{
  "status": "illustrative — final endpoints and fields confirmed during onboarding",
  "example": true,
  "schema_version": "1.0-example",
  "title": "CDN.MN Domains — illustrative API contract",
  "notice": "Illustrative API contract — final endpoints and fields confirmed during onboarding.",
  "access": "Private access by request: request it from a CDN.MN account (https://app.cdn.mn/app/domains) — the short form, confirmed with an email sign-in code — or email domains@cdn.mn. No public endpoint, key or dataset exists; approved accounts receive theirs in their dashboard.",
  "guide": "https://domains.cdn.mn/agents.md",
  "request": {
    "status": "proposed — approved accounts receive the live endpoint during onboarding",
    "method": "POST",
    "path": "/api/v1/check",
    "headers": {
      "Authorization": "Bearer <scoped token, issued only after access is granted>",
      "Content-Type": "application/json"
    },
    "body": {
      "domains": [
        "registered.example"
      ]
    }
  },
  "response": {
    "schema_version": "1.0-example",
    "example": true,
    "results": [
      {
        "domain": "registered.example",
        "state": "taken",
        "evidence": "registry_registered",
        "match_method": "exact",
        "source_type": "registry_list",
        "dataset_id": "example-registry-demo",
        "snapshot_id": "demo-2026-10-12",
        "as_of": "2026-10-12T00:00:00Z",
        "timestamp_basis": "source_snapshot",
        "ingested_at": "2026-10-12T00:20:00Z",
        "checked_at": "2026-10-12T02:00:00Z",
        "freshness": "fresh",
        "current_availability": "not_checked",
        "bloom_false_positive_probability": null
      }
    ]
  },
  "states": {
    "taken": {
      "label": "Taken in snapshot",
      "meaning": "Exact source membership, or a strong full-length hash match, supports a historical observation.",
      "next_step": "The caller may use its caching policy to deprioritize the name; recheck when current availability matters."
    },
    "possibly_taken": {
      "label": "Possible match",
      "meaning": "A Bloom filter reports possible membership; there is no independent exact confirmation.",
      "next_step": "Confirm before making a definitive taken/unavailable claim."
    },
    "not_in_snapshot": {
      "label": "Not found in this snapshot",
      "meaning": "No match in the specified usable dataset.",
      "next_step": "Check the authoritative registry; this is not an availability guarantee."
    },
    "unknown": {
      "label": "No usable coverage",
      "meaning": "The dataset is missing, unusable, incompatible, unauthorized, or its scope does not cover this query.",
      "next_step": "Use the caller's normal authorized registry workflow."
    }
  },
  "fields": {
    "as_of": "Source snapshot time (ISO 8601, UTC), or null when the source time is unknown. Never a receipt or response time.",
    "timestamp_basis": "\"source_snapshot\" when as_of is the source snapshot time; \"unknown\" when it is null.",
    "ingested_at": "When CDN.MN ingested that snapshot, or null.",
    "checked_at": "When this check ran. Never substituted for as_of.",
    "freshness": "fresh, stale or unknown — computed from the age of as_of against a documented policy (these examples use 36 hours), never from the service being reachable.",
    "evidence": {
      "dns_delegation": "The result rests on DNS-delegation data from a DNS zone snapshot",
      "registry_registered": "The result rests on a registry's registered-name data: a list, hashes, or a Bloom file built from it",
      "none": "No source entry matched: see state for a valid miss (not_in_snapshot) or no usable coverage (unknown)"
    },
    "match_method": {
      "exact": "Exact match in the source list",
      "sha256": "Full-length SHA-256 hash match (negligible collision risk, not zero)",
      "bloom": "Bloom filter: possible membership, not an exact confirmation",
      "none": "No match was made: see state for a valid miss (not_in_snapshot) or no usable coverage (unknown)"
    },
    "current_availability": "Always \"not_checked\": a pre-check never reports whether a name can be registered now.",
    "bloom_false_positive_probability": "The filter's declared target false-positive rate (a number) when match_method is bloom; null otherwise. A filter parameter, not the probability that this answer is wrong."
  },
  "rules": [
    "A Bloom-only positive is possibly_taken, never taken.",
    "evidence names the kind of source, not certainty: certainty comes from state and match_method, so registry_registered with match_method bloom is a possible match only.",
    "Each result in a batch carries its own source and timestamps.",
    "Missing coverage is a normal unknown result; service errors and missing coverage are never converted to not_in_snapshot.",
    "A malformed domain is a validation error, not a membership state.",
    "as_of <= ingested_at <= checked_at whenever they are present.",
    "If independently verified sources conflict, the result is never resolved silently to the convenient answer: it will keep each source's provenance and be marked for authoritative confirmation. The fields that carry that mark and the per-source provenance are proposed and defined during onboarding; this example contract has no field for them yet."
  ],
  "scenarios": [
    {
      "id": "zone-exact",
      "title": "Exact zone match",
      "guidance": "The name was observed as delegated in the DNS zone snapshot. Deprioritize it under your caching policy, and recheck with the registry when current availability matters.",
      "response": {
        "schema_version": "1.0-example",
        "example": true,
        "results": [
          {
            "domain": "delegated.example",
            "state": "taken",
            "evidence": "dns_delegation",
            "match_method": "exact",
            "source_type": "zone_file",
            "dataset_id": "example-zone-demo",
            "snapshot_id": "demo-2026-10-12",
            "as_of": "2026-10-12T00:00:00Z",
            "timestamp_basis": "source_snapshot",
            "ingested_at": "2026-10-12T00:15:00Z",
            "checked_at": "2026-10-12T02:00:00Z",
            "freshness": "fresh",
            "current_availability": "not_checked",
            "bloom_false_positive_probability": null
          }
        ]
      }
    },
    {
      "id": "registry-listed",
      "title": "Registry-listed, not necessarily in DNS",
      "guidance": "The registry's own list shows the name as registered, even though it may not appear in DNS. Deprioritize it under your caching policy, and recheck when current availability matters.",
      "response": {
        "schema_version": "1.0-example",
        "example": true,
        "results": [
          {
            "domain": "registered.example",
            "state": "taken",
            "evidence": "registry_registered",
            "match_method": "exact",
            "source_type": "registry_list",
            "dataset_id": "example-registry-demo",
            "snapshot_id": "demo-2026-10-12",
            "as_of": "2026-10-12T00:00:00Z",
            "timestamp_basis": "source_snapshot",
            "ingested_at": "2026-10-12T00:20:00Z",
            "checked_at": "2026-10-12T02:00:00Z",
            "freshness": "fresh",
            "current_availability": "not_checked",
            "bloom_false_positive_probability": null
          }
        ]
      }
    },
    {
      "id": "bloom-positive",
      "title": "Bloom-only positive",
      "guidance": "A Bloom file reports a possible match, with no exact confirmation for this snapshot. Confirm with the registry before treating the name as taken or unavailable.",
      "response": {
        "schema_version": "1.0-example",
        "example": true,
        "results": [
          {
            "domain": "candidate.example",
            "state": "possibly_taken",
            "evidence": "registry_registered",
            "match_method": "bloom",
            "source_type": "registry_bloom",
            "dataset_id": "example-registry-bloom-demo",
            "snapshot_id": "demo-2026-10-12",
            "as_of": "2026-10-12T00:00:00Z",
            "timestamp_basis": "source_snapshot",
            "ingested_at": "2026-10-12T00:30:00Z",
            "checked_at": "2026-10-12T02:00:00Z",
            "freshness": "fresh",
            "current_availability": "not_checked",
            "bloom_false_positive_probability": 0.000001
          }
        ]
      }
    },
    {
      "id": "no-match",
      "title": "No snapshot match",
      "guidance": "Not found in this DNS zone snapshot. Registered names can be missing from DNS zones, and a name may have been registered since the snapshot. Check the authoritative registry; this is not an availability guarantee.",
      "response": {
        "schema_version": "1.0-example",
        "example": true,
        "results": [
          {
            "domain": "newidea.example",
            "state": "not_in_snapshot",
            "evidence": "none",
            "match_method": "none",
            "source_type": "zone_file",
            "dataset_id": "example-zone-demo",
            "snapshot_id": "demo-2026-10-12",
            "as_of": "2026-10-12T00:00:00Z",
            "timestamp_basis": "source_snapshot",
            "ingested_at": "2026-10-12T00:15:00Z",
            "checked_at": "2026-10-12T02:00:00Z",
            "freshness": "fresh",
            "current_availability": "not_checked",
            "bloom_false_positive_probability": null
          }
        ]
      }
    },
    {
      "id": "old-source",
      "title": "Old source",
      "guidance": "The name was listed as registered in an older registry snapshot, and that snapshot is stale. Recheck with the registry before relying on this observation.",
      "response": {
        "schema_version": "1.0-example",
        "example": true,
        "results": [
          {
            "domain": "oldrecord.example",
            "state": "taken",
            "evidence": "registry_registered",
            "match_method": "sha256",
            "source_type": "registry_hashes",
            "dataset_id": "example-registry-hashes-demo",
            "snapshot_id": "demo-2026-10-01",
            "as_of": "2026-10-01T00:00:00Z",
            "timestamp_basis": "source_snapshot",
            "ingested_at": "2026-10-01T00:40:00Z",
            "checked_at": "2026-10-12T02:00:00Z",
            "freshness": "stale",
            "current_availability": "not_checked",
            "bloom_false_positive_probability": null
          }
        ]
      }
    },
    {
      "id": "unsupported",
      "title": "Unsupported source",
      "guidance": "No usable dataset covers this name, so there is no source snapshot time to show. Use your normal authorized registry workflow.",
      "response": {
        "schema_version": "1.0-example",
        "example": true,
        "results": [
          {
            "domain": "unknown.example",
            "state": "unknown",
            "evidence": "none",
            "match_method": "none",
            "source_type": null,
            "dataset_id": null,
            "snapshot_id": null,
            "as_of": null,
            "timestamp_basis": "unknown",
            "ingested_at": null,
            "checked_at": "2026-10-12T02:00:00Z",
            "freshness": "unknown",
            "current_availability": "not_checked",
            "bloom_false_positive_probability": null
          }
        ]
      }
    }
  ]
}