# OKF Index — full API reference

> Generated from the catalog at https://okfindex.com · build `dev`
> 14 endpoints · 8 structures
> Short index: https://okfindex.com/llms.txt · Spec: https://okfindex.com/openapi.json · MCP: https://okfindex.com/mcp

> Full reference. Every route is free; the only write is the submission ping.

## How to read

- Every endpoint lists path, auth, parameters, body, response structure, errors and a call that runs.
- `Pagina<Canal>` is a reference: the fields are under **Structures**, at the end, once.
- `(optional)` on a field means it may be absent; `(may be null)` means it comes with a null value.
- Slice what you need: `https://okfindex.com/llms-full.txt?prefix=/api/` returns only that branch.

## Authentication


## Endpoints

## Discovery

### `GET /agent.json`

Agent card: identity, operator, documentation, the MCP endpoint and the tools it serves. Same document as `/.well-known/agent-card.json`.

- **URL:** `https://okfindex.com/agent.json`
- **Auth:** `none` — not declared

**Response `200`**

`application/json`: `name`, `provider`, `protocol` (`mcp`), `interfaces[]` and `skills[]`.

**Example**

```sh
curl -s https://okfindex.com/agent.json
```

### `GET /okf/:arquivo`

OKF bundle (Open Knowledge Format v0.1): markdown with frontmatter so an agent reads the whole product without parsing HTML.

- **URL:** `https://okfindex.com/okf/:arquivo`
- **Auth:** `none` — not declared

**Path parameters**

- `arquivo` (string, required) — `index.md`, `sobre.md`, `api.md` or `faq.md`. e.g.: `index.md`.

**Response `200`**

`text/markdown`. Start at `/okf/index.md`, which lists the bundle.

**Errors**

- `404` — File outside the bundle.

**Example**

```sh
curl -s https://okfindex.com/okf/index.md
```

### `GET /.well-known/:arquivo`

Machine discovery before the home page: `api-catalog` (RFC 9727, a linkset with the API and the MCP), `security.txt` (RFC 9116), `x402` (payment manifest: network, wallet and the routes that charge) and `mcp-registry-auth` (the official MCP registry key).

- **URL:** `https://okfindex.com/.well-known/:arquivo`
- **Auth:** `none` — not declared

**Path parameters**

- `arquivo` (string, required) — `api-catalog`, `security.txt`, `x402`, `mcp-registry-auth` or `apis.json`. e.g.: `api-catalog`.

**Response `200`**

`application/linkset+json` for the api-catalog; `application/json` for x402 and apis.json; `text/plain` for the other two.

**Errors**

- `404` — Name outside the five published.

**Example**

```sh
curl -s https://okfindex.com/.well-known/api-catalog
```

### `GET /apis.json`

APIs.json (apisjson.org, 0.19): the index APIs.io harvests — the API, the MCP, OpenAPI, guide and OKF bundle in one file. Also at `/.well-known/apis.json`.

- **URL:** `https://okfindex.com/apis.json`
- **Auth:** `none` — not declared

**Response `200`**

`application/json` in the APIs.json 0.19 format: `apis[]` with `baseURL`, `humanURL` and `properties[]`.

**Example**

```sh
curl -s https://okfindex.com/apis.json
```

## Descoberta

### `GET /api/`

Índice auto-descrito: cada rota, o que cobra e como plugar o MCP.

- **URL:** `https://okfindex.com/api/`
- **Auth:** `none` — not declared

**Response `200`**

- `name` (string) — Nome do produto.
- `description` (string) — O que o produto faz.
- `build` (string) — Commit publicado.
- `base_url` (string) — Origem em que esta API está servindo.
- `docs` (object) — Links para llms.txt, OpenAPI, MCP e a UI.
- `endpoints` (object[]) — Catálogo de endpoints.
- `mcp_tools` (string[]) — Tools do MCP.

### `GET /api/health`

Liveness and the build being served.

- **URL:** `https://okfindex.com/api/health`
- **Auth:** `none` — not declared

**Response `200`**

Structure: `Saude`.

- `ok` (bool) — Always `true` when the Worker answers.
- `app` (string) — Display name of the product.
- `build` (string) — Commit published (`dev` outside the CI).

### `POST /mcp`

MCP Streamable HTTP — as tools deste catálogo, despachadas neste mesmo Worker.

- **URL:** `https://okfindex.com/mcp`
- **Auth:** `none` — not declared

**Response `200`**

JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`).

**Example**

```sh
curl -s -XPOST https://okfindex.com/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Index

### `GET /api/bundles`

Paginated search of the index: every live OKF bundle, from GitHub and from live domains.

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/stats` has it.

- **URL:** `https://okfindex.com/api/bundles`
- **Auth:** `none` — not declared

**Query**

- `q` (string) — Free text over name, tagline, description and origin identifier. e.g.: `agent`.
- `origin` (string) — Provenance: found by the GitHub sweep, or submitted by a domain. Values: `github`, `domain`.
- `repo` (string) — Only bundles of one repository, `owner/repo` (case-insensitive). e.g.: `fastendpoints/fastendpoints`.
- `version` (string) — Only bundles declaring one of these `okf_version` values; comma-separated, up to 5. e.g.: `0.1,0.2`.
- `language` (string) — Only bundles whose repository language is one of these; comma-separated, up to 5 (GitHub bundles). e.g.: `TypeScript,Go`.
- `sort` (string) — Result order: arrival, last content change, name or repository stars. Default: `recent`. Values: `recent`, `updated`, `name`, `stars`.
- `limit` (int) — Bundles per page, at most 100. Default: `24`.
- `offset` (int) — How many bundles to skip. Use `next_offset` from the previous response; the list ends at 1000. Default: `0`.

**Response `200`**

Structure: `PaginaDeBundles`.

- `items` (Bundle[]) — The bundles on this page. → see `Bundle` under **Structures**.
- `limit` (int) — Page size applied.
- `offset` (int) — Offset applied.
- `next_offset` (int, may be null) — Offset of the next page; `null` when there is no more (or past the 1000 cap).
- `next` (string, may be null) — Absolute URL of the next page, same filters; follow it until it comes back `null`.

**Example**

```sh
curl -s 'https://okfindex.com/api/bundles?q=agent&sort=stars&limit=5'
```

### `GET /api/bundles/:id`

One bundle's card, by id.

`live` and `low` (example or fixture bundles kept out of the search) both answer here.

- **URL:** `https://okfindex.com/api/bundles/:id`
- **Auth:** `none` — not declared

**Path parameters**

- `id` (string, required) — Bundle id, the `id` of every item in the list. e.g.: `okf-fastendpoints`.

**Response `200`**

Structure: `Bundle`.

- `id` (string) — Bundle id; the key across the whole API.
- `name` (string) — Title of the root `index.md`; `owner/repo · dir` when it has none or the title is a listing heading (`Files`, `Index`).
- `tagline` (string) — One line from the frontmatter `description`; empty when the author gave none.
- `description` (string) — Body of the root `index.md`, capped at 1000 characters.
- `okf_version` (string) — The `okf_version` the bundle declares (0.1 and 0.2 coexist).
- `concepts` (int) — How many linked entries the root index lists.
- `concept_list` (Concept[]) — The entries the root lists, in order, up to 24 — read from the indexed body, so a very long root is cut. → see `Concept` under **Structures**.
- `type` (string) — The `type` declared in the root frontmatter, when any.
- `index_url` (string) — The root `index.md`, raw — what you hand to an agent.
- `page_url` (string) — The page a human opens: the file on GitHub, or the bundle URL on its site.
- `source` (BundleSource) — Provenance and location of the bundle. → see `BundleSource` under **Structures**.
- `repo` (RepoSignal, may be null) — Repository signal; `null` for bundles served by a domain. → see `RepoSignal` under **Structures**.
- `indexed_at` (string) — When the bundle entered the index, `YYYY-MM-DD HH:MM:SS` UTC.
- `updated_at` (string) — When its indexed content last changed, `YYYY-MM-DD HH:MM:SS` UTC.
- `api` (string) — Absolute URL of this bundle's card.

**Errors**

- `404` — No bundle with that id, or it is not public.

**Example**

```sh
curl -s https://okfindex.com/api/bundles/<id>
```

### `GET /api/stats`

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

- **URL:** `https://okfindex.com/api/stats`
- **Auth:** `none` — not declared

**Response `200`**

Structure: `IndexStats`.

- `total` (int) — Live bundles in the index.
- `by_origin` (object) — `{github, domain}`: live bundles found by the sweep and submitted by domains.
- `by_version` (Faceta[]) — Live bundles per declared `okf_version`, most common first (up to 12). → see `Faceta` under **Structures**.
- `by_language` (Faceta[]) — Live bundles per repository language, most common first (up to 12); domain bundles have none. → see `Faceta` under **Structures**.
- `last_update` (string, may be null) — Newest `updated_at` among live bundles, `YYYY-MM-DD HH:MM:SS` UTC.

**Example**

```sh
curl -s https://okfindex.com/api/stats
```

## Publish

### `POST /api/ping`

Submits OKF bundles from a domain you control, using the IndexNow protocol.

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.

- **URL:** `https://okfindex.com/api/ping`
- **Auth:** `none` — not declared

**Body** (`application/json`)

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

**Body example**

```json
{
  "urlList": [
    "https://kb.example.org/knowledge/index.md"
  ],
  "host": "kb.example.org",
  "key": "okf-2026-09-08-k3y"
}
```

**Response `202`**

- `ok` (bool) — The submission was queued.
- `estado` (string) — Always `pendente`: the key has not been checked yet.
- `host` (string) — The host as normalized (lowercase).
- `recebidos` (int) — How many distinct URLs entered the queue.
- `chave_em` (string) — Where we will look for the key file. Check it if you are unsure.
- `mensagem` (string) — What happens next, in one sentence.
- `api_index` (string) — Absolute URL of this API's index.

**Errors**

- `400` — Body is not JSON, `host` is not a domain, `key` is out of shape, or `urlList` is missing/empty/over 100.
- `422` — Some URL is not https, does not end in .md or lives on another host; `keyLocation` off-host too.
- `429` — The host already submitted 200 bundles this UTC day.

**Example**

```sh
curl -s -XPOST https://okfindex.com/api/ping -H 'content-type: application/json' -d '{"urlList":["https://kb.example.org/knowledge/index.md"],"host":"kb.example.org","key":"okf-2026-09-08-k3y"}'
```

## Operations

### `POST /api/visit`

One ping per page view from the interface; it feeds the index's own visit counter.

Counted under the index's metric (`okf_visit`), apart from the Meta Agent Tools counter that shares the database. Test traffic is left out: `X-MM-Smoke`, User-Agent `mm-smoke` or `smoke: true`.

- **URL:** `https://okfindex.com/api/visit`
- **Auth:** `none` — not declared

**Body** (`application/json`)

- `smoke` (bool) — `true` flags a test call, which is acknowledged but not counted.
- `p` (string) — Path of the page that was opened (informative).

**Body example**

```json
{
  "p": "/",
  "smoke": false
}
```

**Response `200`**

- `counted` (bool) — `false` for test traffic, `true` when the day's counter moved.
- `ok` (bool) — Always `true`; the route never refuses a ping.

**Example**

```sh
curl -s -XPOST https://okfindex.com/api/visit -H 'content-type: application/json' -d '{"p":"/","smoke":false}'
```

### `GET /api/metrics`

Usage of the index for the house dashboard: bundles indexed, visits and MCP calls per day.

Anonymous calls get the usage block only. Send `METRICS_TOKEN` as Bearer and the finance block is added — all zeros, because nothing here is charged.

- **URL:** `https://okfindex.com/api/metrics`
- **Auth:** `token` — not declared

**Headers**

- `Authorization` (string) — Optional `Bearer <METRICS_TOKEN>`; unlocks the zeroed finance block.

**Response `200`**

`{app, today, today_visits, days[], usage: {okf, mcp}, accounts, payments?}`.

**Errors**

- `401` — Token present but wrong.
- `503` — Token present, but the Worker has no `METRICS_TOKEN` to compare.

**Example**

```sh
curl -s "https://okfindex.com/api/metrics" -H "authorization: Bearer $METRICS_TOKEN"
```

### `POST /api/erro-cliente`

Browser error report, sent by the interface itself. Agents need not call it.

The interface reports on its own JS errors, unhandled rejections, scripts/CSS that failed to load and CSP blocks — once per session — and the app reports handled failures through `window.mmErro.relata`. The server validates the envelope, redacts credentials, e-mails and phone numbers, merges repeats of the same failure per minute and records an operational event; nothing is written to a database. It keeps no IP, cookie, query string or full User-Agent. Always answers 204, even for an invalid report.

- **URL:** `https://okfindex.com/api/erro-cliente`
- **Auth:** `none` — not declared

**Body** (`application/json`)

- `code` (string, required) — Failure code, `UI-` + letters/digits (`UI-JS-001` global error, `UI-PROMESSA-001`, `UI-RECURSO-001`, `UI-CSP-001`, `UI-APP-001` app report).
- `phase` (string, required) — Where it broke, lowercase: `global`, `promessa`, `script`, `load_list`…
- `path` (string) — Path of the open page, without query.
- `message` (string) — Error message, up to 2000 characters.
- `stack` (string) — Stack trace, up to 12000 characters.
- `source` (string) — Originating script; only its path is kept.
- `line` (int) — Line in the originating script.
- `column` (int) — Column in the originating script.
- `visivel` (bool) — Whether the tab was visible when it broke.

**Body example**

```json
{
  "code": "UI-APP-001",
  "phase": "carregar_lista",
  "path": "/",
  "message": "lista 500"
}
```

**Response `200`**

204 with no body, always — an invalid, repeated or over-cap report also gets 204.

**Example**

```sh
curl -s -XPOST https://okfindex.com/api/erro-cliente -H 'content-type: application/json' -d '{"code":"UI-APP-001","phase":"carregar_lista","path":"/","message":"lista 500"}'
```

## Structures

### `Saude`

Liveness of the Worker and the build it is serving.

- `ok` (bool) — Always `true` when the Worker answers.
- `app` (string) — Display name of the product.
- `build` (string) — Commit published (`dev` outside the CI).

### `PaginaDeBundles`

A page of the index. No `total`: counting on every search would cost a scan without changing any decision — `GET /api/stats` has the totals.

- `items` (Bundle[]) — The bundles on this page. → see `Bundle` under **Structures**.
- `limit` (int) — Page size applied.
- `offset` (int) — Offset applied.
- `next_offset` (int, may be null) — Offset of the next page; `null` when there is no more (or past the 1000 cap).
- `next` (string, may be null) — Absolute URL of the next page, same filters; follow it until it comes back `null`.

### `Bundle`

One OKF bundle: a markdown tree whose root `index.md` carries `okf_version`.

- `id` (string) — Bundle id; the key across the whole API.
- `name` (string) — Title of the root `index.md`; `owner/repo · dir` when it has none or the title is a listing heading (`Files`, `Index`).
- `tagline` (string) — One line from the frontmatter `description`; empty when the author gave none.
- `description` (string) — Body of the root `index.md`, capped at 1000 characters.
- `okf_version` (string) — The `okf_version` the bundle declares (0.1 and 0.2 coexist).
- `concepts` (int) — How many linked entries the root index lists.
- `concept_list` (Concept[]) — The entries the root lists, in order, up to 24 — read from the indexed body, so a very long root is cut. → see `Concept` under **Structures**.
- `type` (string) — The `type` declared in the root frontmatter, when any.
- `index_url` (string) — The root `index.md`, raw — what you hand to an agent.
- `page_url` (string) — The page a human opens: the file on GitHub, or the bundle URL on its site.
- `source` (BundleSource) — Provenance and location of the bundle. → see `BundleSource` under **Structures**.
- `repo` (RepoSignal, may be null) — Repository signal; `null` for bundles served by a domain. → see `RepoSignal` under **Structures**.
- `indexed_at` (string) — When the bundle entered the index, `YYYY-MM-DD HH:MM:SS` UTC.
- `updated_at` (string) — When its indexed content last changed, `YYYY-MM-DD HH:MM:SS` UTC.
- `api` (string) — Absolute URL of this bundle's card.

### `IndexStats`

Size of the index by provenance, the facets a search can filter by, and when it last changed.

- `total` (int) — Live bundles in the index.
- `by_origin` (object) — `{github, domain}`: live bundles found by the sweep and submitted by domains.
- `by_version` (Faceta[]) — Live bundles per declared `okf_version`, most common first (up to 12). → see `Faceta` under **Structures**.
- `by_language` (Faceta[]) — Live bundles per repository language, most common first (up to 12); domain bundles have none. → see `Faceta` under **Structures**.
- `last_update` (string, may be null) — Newest `updated_at` among live bundles, `YYYY-MM-DD HH:MM:SS` UTC.

### `Concept`

One entry the root `index.md` lists: a concept file or a subdirectory of the bundle.

- `name` (string) — Link text as written in the root index.
- `url` (string) — Absolute URL of the entry, resolved against the root; a directory link gets its `index.md`.
- `summary` (string) — Text after the link on the same line; empty when the index has none.

### `BundleSource`

Where a bundle comes from and how it entered the index.

- `origin` (string) — Provenance of the bundle.
- `via` (string) — How it got in: the GitHub sweep or an IndexNow ping.
- `url` (string) — The repository (GitHub) or the site root (domain).
- `host` (string) — Hostname of `url`; empty when it cannot be parsed.
- `repo` (string, may be null) — `owner/repo` in lowercase, GitHub bundles only.
- `dir` (string) — Directory of the bundle inside the repository (empty at the root).
- `path` (string) — Path of the root `index.md` inside the repository.

### `RepoSignal`

Repository signal collected by the enricher — GitHub bundles only.

- `stars` (int) — Stargazers at the last collection.
- `forks` (int) — Forks at the last collection.
- `pushed_at` (string, may be null) — Last push seen, `YYYY-MM-DD HH:MM:SS` UTC.
- `state` (string, may be null) — Repository state as classified by the enricher (active, stalled, archived, gone).
- `language` (string, may be null) — Primary language reported by GitHub.
- `license` (string, may be null) — License identifier reported by GitHub.

### `Faceta`

One value of a facet and how many live bundles carry it.

- `v` (string) — The value as stored: an `okf_version` or a repository language.
- `n` (int) — Live bundles with that value.