{
  "schema_version": "anchorfact.api-index.v1",
  "generated": "2026-07-22T07:14:35.144Z",
  "provenance_url": "https://anchorfact.org/provenance.json",
  "name": "AnchorFact Machine API Index",
  "description": "Compact read-only API discovery for AI agents that need the smallest live endpoint before fetching the full OpenAPI contract.",
  "read_only": true,
  "quick_start": {
    "purpose": "Copy one valid primary API request before trying bare endpoint paths.",
    "default_answer_path": "/api/context?q={query}",
    "next_request_after_discovery": {
      "id": "context",
      "path": "/api/context?q={query}&limit=3&format=markdown",
      "required_parameter": "q",
      "method": "GET",
      "url": "https://anchorfact.org/api/context?q={query}&limit=3&format=markdown"
    },
    "minimum_valid_primary_calls": [
      {
        "id": "context",
        "path": "/api/context?q={query}&limit=3&format=markdown",
        "required_parameter": "q",
        "method": "GET",
        "url": "https://anchorfact.org/api/context?q={query}&limit=3&format=markdown"
      },
      {
        "id": "evidence",
        "path": "/api/evidence?q={query}&limit=3&format=markdown",
        "required_parameter": "q",
        "method": "GET",
        "url": "https://anchorfact.org/api/evidence?q={query}&limit=3&format=markdown"
      },
      {
        "id": "cite",
        "path": "/api/cite?id={claim_id}&format=markdown",
        "required_parameter": "id",
        "method": "GET",
        "url": "https://anchorfact.org/api/cite?id={claim_id}&format=markdown"
      },
      {
        "id": "resolve_batch",
        "path": "/api/resolve-batch?ref={claim_id}&ref={source_id}&format=markdown",
        "required_parameter": "ref",
        "method": "GET",
        "url": "https://anchorfact.org/api/resolve-batch?ref={claim_id}&ref={source_id}&format=markdown"
      }
    ],
    "parameter_error_prevention": {
      "bare_primary_paths_return_recoverable_400": true,
      "do_not_call_bare_paths": [
        "/api/context",
        "/api/evidence",
        "/api/cite",
        "/api/source",
        "/api/resolve-batch"
      ],
      "copy_minimum_valid_primary_calls_first": true,
      "recovery_field_on_400": "machine_recovery"
    },
    "example_calls": [
      {
        "id": "context_example",
        "path": "/api/context?q=gaussian%20splatting&limit=3&format=markdown",
        "required_parameter": "q",
        "method": "GET",
        "url": "https://anchorfact.org/api/context?q=gaussian%20splatting&limit=3&format=markdown"
      },
      {
        "id": "evidence_example",
        "path": "/api/evidence?q=RLHF&limit=3&format=markdown",
        "required_parameter": "q",
        "method": "GET",
        "url": "https://anchorfact.org/api/evidence?q=RLHF&limit=3&format=markdown"
      }
    ]
  },
  "ai_adoption_guidance": {
    "primary_api_conversion_target": 0.2,
    "measured_as": "identified AI primary API requests divided by identified AI discovery requests",
    "discovery_entrypoints": [
      "/robots.txt",
      "/llms.txt",
      "/agent.json",
      "/.well-known/anchorfact.json",
      "/api"
    ],
    "primary_api_entrypoints": [
      "/api/context",
      "/api/evidence",
      "/api/cite",
      "/api/resolve-batch"
    ],
    "next_call_after_discovery": "/api/context?q={query}&limit=3&format=markdown",
    "next_request_after_discovery": {
      "id": "context",
      "path": "/api/context?q={query}&limit=3&format=markdown",
      "required_parameter": "q",
      "method": "GET",
      "url": "https://anchorfact.org/api/context?q={query}&limit=3&format=markdown"
    },
    "minimum_valid_primary_calls": [
      {
        "id": "context",
        "path": "/api/context?q={query}&limit=3&format=markdown",
        "required_parameter": "q",
        "method": "GET",
        "url": "https://anchorfact.org/api/context?q={query}&limit=3&format=markdown"
      },
      {
        "id": "evidence",
        "path": "/api/evidence?q={query}&limit=3&format=markdown",
        "required_parameter": "q",
        "method": "GET",
        "url": "https://anchorfact.org/api/evidence?q={query}&limit=3&format=markdown"
      },
      {
        "id": "cite",
        "path": "/api/cite?id={claim_id}&format=markdown",
        "required_parameter": "id",
        "method": "GET",
        "url": "https://anchorfact.org/api/cite?id={claim_id}&format=markdown"
      },
      {
        "id": "resolve_batch",
        "path": "/api/resolve-batch?ref={claim_id}&ref={source_id}&format=markdown",
        "required_parameter": "ref",
        "method": "GET",
        "url": "https://anchorfact.org/api/resolve-batch?ref={claim_id}&ref={source_id}&format=markdown"
      }
    ],
    "parameter_error_prevention": {
      "bare_primary_paths_return_recoverable_400": true,
      "do_not_call_bare_paths": [
        "/api/context",
        "/api/evidence",
        "/api/cite",
        "/api/source",
        "/api/resolve-batch"
      ],
      "copy_minimum_valid_primary_calls_first": true,
      "recovery_field_on_400": "machine_recovery"
    },
    "evidence_query_template": "/api/evidence?q={query}&limit=3&format=markdown",
    "citation_template": "/api/cite?id={claim_id}&format=markdown",
    "crawler_next_step": "After reading /robots.txt, /llms.txt, /agent.json, /.well-known/anchorfact.json, or /api, call /api/context for a real user question instead of downloading large static artifacts.",
    "measurement_signal": "A ratio below 0.2 means discovery is not yet converting into answer assembly or citation retrieval."
  },
  "error_recovery_guidance": {
    "recoverable_400_field": "machine_recovery",
    "default_recovery_path": "/api/context?q={query}&limit=3",
    "default_recovery_url": "https://anchorfact.org/api/context?q={query}&limit=3",
    "observed_recoverable_endpoints": [
      "/api/context",
      "/api/evidence",
      "/api/plan",
      "/api/search",
      "/api/article",
      "/api/claim",
      "/api/source",
      "/api/resolve",
      "/api/resolve-batch",
      "/api/cite"
    ],
    "retry_example_paths": [
      "/api/context?q={query}&limit=3",
      "/api/evidence?q={query}&limit=3",
      "/api/plan?q={query}&limit=3",
      "/api/search?q={query}&limit=5",
      "/api/article?slug={canonical_slug}",
      "/api/claim?id={claim_id}",
      "/api/source?id={source_id}",
      "/api/resolve?ref={claim_id_or_slug_or_source_id}",
      "/api/resolve-batch?ref={claim_id}&ref={source_id}",
      "/api/cite?id={claim_id}"
    ],
    "policy": "If an API request returns a recoverable 400, inspect machine_recovery.next_request first, then use retry_examples for endpoint-specific parameters."
  },
  "readiness_guidance": {
    "status_endpoint": "/api-readiness.json",
    "report_only_until_gates_met": true,
    "default_access_until_ready": "free_no_key_read_only",
    "subscription_ready_requires": [
      "production_integrity_14_day",
      "public_audit_14_day",
      "ai_primary_discovery_ratio_7_day",
      "design_partners"
    ],
    "blocker_evidence_requirements": [
      {
        "id": "production_integrity_14_day",
        "gate_type": "automated_window",
        "status": "not_measured_in_this_report",
        "target": "14 consecutive days production:integrity passing and AI eval 100%",
        "required_days": 14,
        "runtime_input_id": "production_integrity",
        "report_field": "production_health",
        "json_flag": "--production-integrity-json",
        "command": "npm run production:integrity -- --write-json reports/production-integrity.json",
        "history_command": "npm run readiness:history -- --history-dir reports/readiness-history --api-readiness-json reports/api-readiness.json --content-health-json reports/content-health.json --save-current --write reports/readiness-window.md --write-json reports/readiness-window.json",
        "status_when_missing": "not_provided",
        "required_fields": [
          "ok",
          "checks",
          "commit_sha",
          "source_commit_sha"
        ]
      },
      {
        "id": "public_audit_14_day",
        "gate_type": "automated_window",
        "status": "not_measured_in_this_report",
        "target": "14 consecutive days with 0 move_to_draft / repair_sources public audit findings",
        "required_days": 14,
        "runtime_input_id": "content_health",
        "command": "npm run content:health -- --json --write reports/content-health.json",
        "history_command": "npm run readiness:history -- --history-dir reports/readiness-history --api-readiness-json reports/api-readiness.json --content-health-json reports/content-health.json --save-current --write reports/readiness-window.md --write-json reports/readiness-window.json"
      },
      {
        "id": "ai_primary_discovery_ratio_7_day",
        "gate_type": "automated_window",
        "status": "not_measured_in_this_report",
        "target": ">=0.2 primary/discovery ratio for 7 consecutive days",
        "required_days": 7,
        "runtime_input_id": "ai_adoption",
        "report_field": "adoption_signal",
        "json_flag": "--adoption-json",
        "command": "npm run usage:adoption -- --lookback-minutes 1430 --write-json reports/ai-adoption-scorecard.json",
        "history_command": "npm run readiness:history -- --history-dir reports/readiness-history --api-readiness-json reports/api-readiness.json --content-health-json reports/content-health.json --save-current --write reports/readiness-window.md --write-json reports/readiness-window.json",
        "status_when_missing": "not_provided",
        "preferred_measurement_scope": "interactive_ai",
        "required_fields": [
          "identified_ai_primary_to_discovery_ratio",
          "identified_ai_primary_to_discovery_target_status",
          "interactive_ai_primary_to_discovery_ratio",
          "interactive_ai_primary_to_discovery_target_status",
          "crawler_ai_primary_to_discovery_ratio"
        ]
      },
      {
        "id": "design_partners",
        "gate_type": "manual_validation",
        "status": "manual_validation_required",
        "target": ">=3 real external design partners and >=1 paid-intent signal",
        "runtime_input_id": "design_partners",
        "report_field": "design_partner_signal",
        "json_flag": "--design-partners-json",
        "command": "npm run api:readiness -- --design-partners-json reports/design-partners.json",
        "history_command": "npm run readiness:history -- --history-dir reports/readiness-history --api-readiness-json reports/api-readiness.json --content-health-json reports/content-health.json --save-current --write reports/readiness-window.md --write-json reports/readiness-window.json",
        "status_when_missing": "manual_validation_required",
        "manual_validation": true,
        "required_fields": [
          "external_design_partner_count",
          "paid_intent_signal_count"
        ]
      }
    ],
    "start_paid_beta_only_after": "All automated readiness windows pass and external design partner plus paid-intent signals are real.",
    "runtime_signal_contract": {
      "status_endpoint": "/api-readiness.json",
      "static_artifact": true,
      "missing_runtime_status": "not_provided",
      "workflow": ".github/workflows/readiness-scorecard.yml",
      "scorecard_command": "npm run api:readiness -- --adoption-json reports/ai-adoption-scorecard.json --production-integrity-json reports/production-integrity.json --write reports/api-readiness.md --write-json reports/api-readiness.json",
      "history_command": "npm run readiness:history -- --history-dir reports/readiness-history --api-readiness-json reports/api-readiness.json --content-health-json reports/content-health.json --save-current --write reports/readiness-window.md --write-json reports/readiness-window.json",
      "published_static_artifact": "https://anchorfact.org/api-readiness.json",
      "runtime_input_ids": [
        "production_integrity",
        "ai_adoption",
        "design_partners"
      ],
      "preferred_adoption_scope": "interactive_ai",
      "manual_validation_required": [
        "design_partners"
      ]
    }
  },
  "recommended_sequence": [
    "Call /api/context?q={query} first for normal answer assembly, answer_policy, citation-ready claims, content health, fallback guidance, and evidence packs.",
    "Call /api/evidence?q={query} when you need answer-ready evidence packs with mapped claims and sources.",
    "Call /api/plan?q={query} only when coverage is uncertain or you need a fallback decision before requesting evidence.",
    "Call /api/resolve or /api/resolve-batch when you already have AnchorFact claim ids, article slugs, source ids, source URLs, or AnchorFact URLs.",
    "Call /api/cite?id={claim_id} when you need a citation-ready atomic claim.",
    "If you reached /api from /robots.txt, /llms.txt, /agent.json, /.well-known/anchorfact.json, or crawler discovery, make the next request /api/context?q={query}&limit=3&format=markdown for a concrete user question.",
    "Read /api-access/ for the current machine-readable free API access policy, call order, and provenance verification steps.",
    "Verify /provenance.json and /provenance.sig before trusting static artifact hashes or counts."
  ],
  "primary_entrypoints": [
    {
      "id": "context",
      "method": "GET",
      "path": "/api/context",
      "url": "https://anchorfact.org/api/context",
      "minimum_valid_path": "/api/context?q={query}&limit=3&format=markdown",
      "minimum_valid_url": "https://anchorfact.org/api/context?q={query}&limit=3&format=markdown",
      "best_for": [
        "default one-call prompt assembly",
        "answer_policy and citation-ready claims",
        "supported/unsupported routing with fallback guidance"
      ],
      "use_when": [
        "You need one prompt-ready context pack before drafting an answer.",
        "You need an explicit answer_policy.can_answer_with_anchorfact decision."
      ],
      "format_options": [
        "json",
        "markdown"
      ]
    },
    {
      "id": "evidence",
      "method": "GET",
      "path": "/api/evidence",
      "url": "https://anchorfact.org/api/evidence",
      "minimum_valid_path": "/api/evidence?q={query}&limit=3&format=markdown",
      "minimum_valid_url": "https://anchorfact.org/api/evidence?q={query}&limit=3&format=markdown",
      "best_for": [
        "answer-ready evidence packs",
        "public article summaries with mapped claims and sources",
        "compact Markdown context for citation-grounded answers"
      ],
      "use_when": [
        "You already have a factual query and need source-grounded evidence.",
        "You want search hits, claims, sources, and citation exports in one call."
      ],
      "format_options": [
        "json",
        "markdown"
      ]
    },
    {
      "id": "plan",
      "method": "GET",
      "path": "/api/plan",
      "url": "https://anchorfact.org/api/plan",
      "minimum_valid_path": "/api/plan?q={query}&limit=3",
      "minimum_valid_url": "https://anchorfact.org/api/plan?q={query}&limit=3",
      "best_for": [
        "coverage preflight",
        "next-call routing",
        "external-source fallback decisions"
      ],
      "use_when": [
        "You are not sure AnchorFact covers the topic.",
        "The query may be live, local, personalized, or time-sensitive."
      ],
      "format_options": [
        "json"
      ]
    }
  ],
  "endpoints": [
    {
      "id": "plan",
      "method": "GET",
      "path": "/api/plan",
      "url": "https://anchorfact.org/api/plan",
      "query": [
        {
          "name": "q",
          "required": true,
          "description": "Natural-language query."
        },
        {
          "name": "limit",
          "required": false,
          "description": "Maximum article match count; default 3."
        }
      ],
      "description": "Decide whether AnchorFact coverage is plausible and which endpoint to call next.",
      "minimum_valid_paths": [
        "/api/plan?q={query}&limit=3"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "evidence",
      "method": "GET",
      "path": "/api/evidence",
      "url": "https://anchorfact.org/api/evidence",
      "query": [
        {
          "name": "q",
          "required": true,
          "description": "Natural-language query."
        },
        {
          "name": "limit",
          "required": false,
          "description": "Maximum evidence pack count; default 5."
        },
        {
          "name": "format",
          "required": false,
          "description": "json, markdown, or md."
        }
      ],
      "description": "Return one-call public evidence packs with article summaries, claims, sources, and citation exports.",
      "minimum_valid_paths": [
        "/api/evidence?q={query}&limit=3&format=markdown"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "context",
      "method": "GET",
      "path": "/api/context",
      "url": "https://anchorfact.org/api/context",
      "query": [
        {
          "name": "q",
          "required": true,
          "description": "Natural-language query."
        },
        {
          "name": "limit",
          "required": false,
          "description": "Maximum evidence pack count; default 3."
        },
        {
          "name": "format",
          "required": false,
          "description": "json, markdown, or md."
        }
      ],
      "description": "Combine answer policy, citation-ready claims, coverage planning, corpus health, fallback guidance, and public evidence packs for prompt assembly.",
      "minimum_valid_paths": [
        "/api/context?q={query}&limit=3&format=markdown"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "search",
      "method": "GET",
      "path": "/api/search",
      "url": "https://anchorfact.org/api/search",
      "query": [
        {
          "name": "q",
          "required": true,
          "description": "Natural-language query."
        },
        {
          "name": "limit",
          "required": false,
          "description": "Maximum result count; default 5."
        }
      ],
      "description": "Search compact public records by query.",
      "minimum_valid_paths": [
        "/api/search?q={query}&limit=5"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "article",
      "method": "GET",
      "path": "/api/article",
      "url": "https://anchorfact.org/api/article",
      "query": [
        {
          "name": "slug",
          "required": true,
          "description": "Canonical public article slug."
        }
      ],
      "description": "Fetch one public article evidence bundle with claims, sources, and citation exports.",
      "minimum_valid_paths": [
        "/api/article?slug={canonical_slug}"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "claim",
      "method": "GET",
      "path": "/api/claim",
      "url": "https://anchorfact.org/api/claim",
      "query": [
        {
          "name": "id",
          "required": true,
          "description": "Public claim id or shorthand id such as f1."
        }
      ],
      "description": "Dereference one public atomic claim with article and source context.",
      "minimum_valid_paths": [
        "/api/claim?id={claim_id}"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "cite",
      "method": "GET",
      "path": "/api/cite",
      "url": "https://anchorfact.org/api/cite",
      "query": [
        {
          "name": "id",
          "required": true,
          "description": "Public claim id or shorthand id such as f1."
        },
        {
          "name": "format",
          "required": false,
          "description": "json, markdown, or md."
        }
      ],
      "description": "Return a citation-ready public atomic claim.",
      "minimum_valid_paths": [
        "/api/cite?id={claim_id}&format=markdown"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "source",
      "method": "GET",
      "path": "/api/source",
      "url": "https://anchorfact.org/api/source",
      "query": [
        {
          "name": "id",
          "required": false,
          "description": "Source id from /sources.json."
        },
        {
          "name": "url",
          "required": false,
          "description": "Original source URL."
        }
      ],
      "description": "Inspect a public source and mapped claims by source id or original URL.",
      "minimum_valid_paths": [
        "/api/source?id={source_id}",
        "/api/source?url={source_url}"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "resolve",
      "method": "GET",
      "path": "/api/resolve",
      "url": "https://anchorfact.org/api/resolve",
      "query": [
        {
          "name": "ref",
          "required": true,
          "description": "Claim id, article slug, source id, AnchorFact URL, or original source URL."
        }
      ],
      "description": "Resolve one mixed public reference to its matching public payload.",
      "minimum_valid_paths": [
        "/api/resolve?ref={claim_id}"
      ],
      "bare_path_returns_recoverable_400": true
    },
    {
      "id": "resolve_batch",
      "method": "GET",
      "path": "/api/resolve-batch",
      "url": "https://anchorfact.org/api/resolve-batch",
      "query": [
        {
          "name": "ref",
          "required": true,
          "description": "Repeat for each reference."
        },
        {
          "name": "format",
          "required": false,
          "description": "json, markdown, or md."
        }
      ],
      "description": "Resolve up to 20 mixed public references in one request.",
      "minimum_valid_paths": [
        "/api/resolve-batch?ref={claim_id}&ref={source_id}",
        "/api/resolve-batch?ref={claim_id}&ref={source_id}&format=markdown"
      ],
      "bare_path_returns_recoverable_400": true
    }
  ],
  "static_fallbacks": [
    {
      "path": "/index.json",
      "url": "https://anchorfact.org/index.json",
      "media_type": "application/json",
      "description": "Compact root machine directory for preferred entrypoints, trust policy, and signed artifacts."
    },
    {
      "path": "/agent.json",
      "url": "https://anchorfact.org/agent.json",
      "media_type": "application/json",
      "description": "Full AI agent discovery profile and recommended workflow."
    },
    {
      "path": "/api-access/",
      "url": "https://anchorfact.org/api-access/",
      "media_type": "application/json",
      "description": "Machine-readable free API access policy with recommended call order, limits, and provenance verification."
    },
    {
      "path": "/openapi.json",
      "url": "https://anchorfact.org/openapi.json",
      "media_type": "application/json",
      "description": "Full OpenAPI 3.1 machine contract."
    },
    {
      "path": "/artifact-summary.json",
      "url": "https://anchorfact.org/artifact-summary.json",
      "media_type": "application/json",
      "description": "Lightweight size, purpose, cache posture, and recommended alternatives for large static machine artifacts."
    },
    {
      "path": "/artifact-shards.json",
      "url": "https://anchorfact.org/artifact-shards.json",
      "media_type": "application/json",
      "description": "Signed registry of versioned shards for large static artifacts."
    },
    {
      "path": "/api-readiness.json",
      "url": "https://anchorfact.org/api-readiness.json",
      "media_type": "application/json",
      "description": "Subscription-readiness gates, core corpus scorecard, and API citation readiness report."
    },
    {
      "path": "/capabilities.json",
      "url": "https://anchorfact.org/capabilities.json",
      "media_type": "application/json",
      "description": "Task-to-endpoint routing guide."
    },
    {
      "path": "/content-health.json",
      "url": "https://anchorfact.org/content-health.json",
      "media_type": "application/json",
      "description": "Signed corpus health summary for AI trust decisions and source-ready/source acquisition draft repair queues."
    },
    {
      "path": "/coverage.json",
      "url": "https://anchorfact.org/coverage.json",
      "media_type": "application/json",
      "description": "Coverage and limits guide for deciding when to fall back to external primary sources."
    },
    {
      "path": "/examples.json",
      "url": "https://anchorfact.org/examples.json",
      "media_type": "application/json",
      "description": "Executable workflow examples."
    },
    {
      "path": "/evals.json",
      "url": "https://anchorfact.org/evals.json",
      "media_type": "application/json",
      "description": "Executable golden checks for this machine contract."
    },
    {
      "path": "/mcp.json",
      "url": "https://anchorfact.org/mcp.json",
      "media_type": "application/json",
      "description": "Local MCP installation manifest."
    },
    {
      "path": "/provenance.json",
      "url": "https://anchorfact.org/provenance.json",
      "media_type": "application/json",
      "description": "Signed build identity, counts, and static artifact hashes."
    }
  ]
}