okfindex

Index of the OKF Index API: routes, quota (none) and how to plug the MCP.

{
  "type": "object",
  "properties": {}
}

Search the index of OKF bundles: free text over name, tagline, description and origin; filter by provenance (github|domain), repository, version, language, license, root type or concept count; search root concept text. Paginate with limit/offset. Only `live` bundles. Free text matches the name, the tagline, the description and the origin identifier (`owner/repo:path` or the bundle URL). No `total` on purpose: `GET /api/okf/stats` has it.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free text over name, tagline, description and origin identifier."
    },
    "origin": {
      "type": "string",
      "description": "Provenance: found by the GitHub sweep, or submitted by a domain.",
      "enum": [
        "github",
        "domain"
      ]
    },
    "repo": {
      "type": "string",
      "description": "Only bundles of one repository, `owner/repo` (case-insensitive)."
    },
    "version": {
      "type": "string",
      "description": "Only bundles declaring one of these `okf_version` values; comma-separated, up to 5."
    },
    "language": {
      "type": "string",
      "description": "Only bundles whose repository language is one of these; comma-separated, up to 5 (GitHub bundles)."
    },
    "concept": {
      "type": "string",
      "description": "Text in the indexed root content, including listed concept names and summaries (first 1000 characters); up to 80 characters."
    },
    "concepts": {
      "type": "string",
      "description": "Number of entries listed by the root. Up to 5 comma-separated bands: 0,1-5,6-20,21-100,101+."
    },
    "type": {
      "type": "string",
      "description": "Type declared by the root, not the types of every concept. Up to 5 comma-separated values, 40 characters each."
    },
    "license": {
      "type": "string",
      "description": "Repository license. Up to 5 comma-separated values, 40 characters each."
    },
    "sort": {
      "type": "string",
      "description": "Result order: arrival, last content change, name or repository stars.",
      "enum": [
        "recent",
        "updated",
        "name",
        "stars"
      ],
      "default": "recent"
    },
    "limit": {
      "type": "integer",
      "description": "Bundles per page, at most 100.",
      "default": 24
    },
    "offset": {
      "type": "integer",
      "description": "How many bundles to skip. Use `next_offset` from the previous response; the list ends at 1000.",
      "default": 0
    }
  }
}

One bundle's card: root index.md URL, version, concept count, provenance and repository signal. `live` and `low` (example or fixture bundles kept out of the search) both answer here.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Bundle id, the `id` of every item in the list."
    }
  },
  "required": [
    "id"
  ]
}

Size of the index by provenance and when it last changed.

{
  "type": "object",
  "properties": {}
}

Queue bundle root URLs served by a host you own. IndexNow rules: the key file at https://<host>/<key>.txt has to match, the answer is 202, and nothing of yours is read before the collector checks that file. No account, no payment: ownership is proved by a key file on the host, exactly as IndexNow does it. Host `https://<host>/<key>.txt` containing the key (or point `keyLocation` at another path on the SAME host), then send the bundle URLs. We answer **202**: the key has not been checked yet. Verification and reading happen on our collector, never at the edge — so nothing is published, and no URL of yours is fetched, before the key matches. Re-sending a URL is how you say the bundle changed; it goes back in line to be re-read. At most 100 URLs per request and 200 per host per UTC day. Bundles in public GitHub repositories need no ping: the sweep finds them.

{
  "type": "object",
  "properties": {
    "urlList": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The bundle roots (`index.md` files): https, on `host`, ending in .md — any path, since the spec fixes none."
    },
    "host": {
      "type": "string",
      "description": "The domain that serves the bundles and the key file."
    },
    "key": {
      "type": "string",
      "description": "The IndexNow key: 8 to 128 characters of [a-zA-Z0-9-]."
    },
    "keyLocation": {
      "type": "string",
      "description": "Alternative location of the key file, on the SAME host. Default: `https://<host>/<key>.txt`."
    }
  },
  "required": [
    "host",
    "key",
    "urlList"
  ]
}

Current public prices and free allowances; no charge.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Payment discovery and billing summary; does not create a charge.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}