# OKF Index — full API reference

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

> Full reference. Public search and submission are free and need no account. Optional accounts use the global platform.

## 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://staging.okfindex.com/llms-full.txt?prefix=/api/` returns only that branch.

## Authentication

- `none` — Public.
- `token` — Operator token `METRICS_TOKEN` as `Authorization: Bearer` (metrics).
- `credito` — Prepaid credit token in `Authorization: Bearer cred_…` (or the `X-Credito` header). Not an account: it is a bearer of balance.
- `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

## Endpoints

## Account

### `GET /api/auth/bootstrap`

Prepare the browser for global sign-in.

Sets a host-only HttpOnly browser cookie. CSRF is bound to the current session. No CORS.

- **URL:** `https://staging.okfindex.com/api/auth/bootstrap`
- **Auth:** `none` — Public.

**Response `200`**

- `csrf` (string) — X-CSRF-Token
- `context` (string) — Opaque view context, also in X-MM-Context; not a credential / contexto opaco da vista, não é credencial.

**Errors**

- `400` — invalid_request
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved

### `GET /api/account/profile`

Read your global profile.

Reads current preferences from the account. Edit them on your account page; products never own a separate profile.

- **URL:** `https://staging.okfindex.com/api/account/profile`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**Response `200`**

{profile:{name,locale,timeZone,theme,revision}}

**Errors**

- `401` — invalid_session
- `503` — auth_unavailable

**Example**

```js
await fetch("https://staging.okfindex.com/api/account/profile", {credentials: "same-origin"}).then(r => r.json());
```

### `GET /api/account/avatar`

Read your global profile photo.

Private WebP, up to 64 KiB, no cache. Change it on your account. No user ID or object URL accepted.

- **URL:** `https://staging.okfindex.com/api/account/avatar`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**Response `200`**

image/webp; Cache-Control: no-store

**Errors**

- `401` — invalid_session
- `404` — not_found: no photo / sem foto
- `503` — auth_unavailable

**Example**

```js
await fetch("https://staging.okfindex.com/api/account/avatar", {credentials: "same-origin"}).then(r => {if (!r.ok) throw new Error("HTTP " + r.status); return r.blob();});
```

### `GET /api/me`

Read the current global account in this product.

- **URL:** `https://staging.okfindex.com/api/me`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**Response `200`**

{user:{identityId,sessionId,productId,audience,authTime,methods,mfaState}}

**Errors**

- `401` — invalid_session
- `503` — auth_unavailable

**Example**

```js
await fetch("https://staging.okfindex.com/api/me", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/auth/logout`

Revoke this product session.

Bootstrap/CSRF must belong to this browser and session. Other product sessions remain active.

- **URL:** `https://staging.okfindex.com/api/auth/logout`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**Response `200`**

- `ok` (bool) — true

**Errors**

- `400` — invalid_request
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved

**Example**

```js
// Execute no console da página do produto / Run in the product page console.
(async () => {
  const origin = "https://staging.okfindex.com";
  const {csrf} = await fetch(origin + "/api/auth/bootstrap").then(r => r.json());
  const r = await fetch(origin + "/api/auth/logout", {
    method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({})
  });
  if (!r.ok) throw new Error("Auth HTTP " + r.status);
  return r.json();
})();
```

### `GET /api/account/keys`

List your API keys in this product.

Never returns the key itself: name, last 4 characters, organization, creation, last use (hourly) and whether it still works.

- **URL:** `https://staging.okfindex.com/api/account/keys`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**Response `200`**

- `keys` (object[]) — `id`, `name`, `organizationId`, `last4`, `createdAt`, `lastUsedAt`, `revokedAt`, `active` (false when revoked or stopped by a password change / ending all sessions).

**Errors**

- `401` — invalid_session
- `503` — auth_unavailable

**Example**

```js
await fetch("https://staging.okfindex.com/api/account/keys", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/account/keys/create`

Create an API key for agents and scripts.

Needs a sign-in in the last 5 minutes; an organization key also needs a second factor in the session and the owner/admin role with this product enabled. At most 10 live keys per account and product. The key (`secret`) is returned ONCE.

- **URL:** `https://staging.okfindex.com/api/account/keys/create`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

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

- `name` (string, required) — Up to 60 characters.
- `organizationId` (string, required) — `null` for an account key.

**Body example**

```json
{
  "name": "agent",
  "organizationId": null
}
```

**Response `200`**

- `key` (object) — `id`, `name`, `organizationId`, `last4`, `createdAt`.
- `secret` (string) — `mmk_…`, shown once.

**Errors**

- `400` — invalid_key_name / invalid_organization
- `401` — invalid_session / reauth_required
- `403` — invalid_origin / invalid_csrf / organization_forbidden / organization_mfa_required
- `409` — key_limit_reached
- `503` — auth_unavailable

**Example**

```js
(async () => {
  const {csrf} = await fetch("https://staging.okfindex.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.okfindex.com/api/account/keys/create", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({name: "agent", organizationId: null})});
  return r.json();
})();
```

### `POST /api/account/keys/revoke`

Revoke one of your API keys.

Stops the key at once. Repeating is harmless.

- **URL:** `https://staging.okfindex.com/api/account/keys/revoke`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

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

- `id` (string, required) — The key `id`.

**Body example**

```json
{
  "id": "…"
}
```

**Response `200`**

- `ok` (bool) — true

**Errors**

- `400` — invalid_key_id
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `404` — key_not_found
- `503` — auth_unavailable

**Example**

```js
(async () => {
  const {csrf} = await fetch("https://staging.okfindex.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.okfindex.com/api/account/keys/revoke", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({id: "…"})});
  return r.json();
})();
```

## 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://staging.okfindex.com/agent.json`
- **Auth:** `none` — Public.

**Response `200`**

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

**Example**

```sh
curl -s https://staging.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://staging.okfindex.com/okf/:arquivo`
- **Auth:** `none` — Public.

**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://staging.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://staging.okfindex.com/.well-known/:arquivo`
- **Auth:** `none` — Public.

**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://staging.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://staging.okfindex.com/apis.json`
- **Auth:** `none` — Public.

**Response `200`**

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

**Example**

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

### `GET /api/pricing`

Current prices and free allowances.

- **URL:** `https://staging.okfindex.com/api/pricing`
- **Auth:** `none` — Public.

**Response `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → see `PaymentQuota` under **Structures**.
- `pricing` (string) — Absolute URL of the current price list.
- `billing` (string) — Absolute URL of payment discovery or the existing billing summary.
- `api_index` (string) — Absolute URL of the API catalog.

**Errors**

- `405` — Use GET or HEAD.

**Example**

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

### `GET /api/billing`

Public payment and prepaid credit discovery.

- **URL:** `https://staging.okfindex.com/api/billing`
- **Auth:** `none` — Public.

**Response `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → see `PaymentQuota` under **Structures**.
- `pricing` (string) — Absolute URL of the current price list.
- `billing` (string) — Absolute URL of payment discovery or the existing billing summary.
- `api_index` (string) — Absolute URL of the API catalog.
- `payment` (PaymentX402) — Public x402 configuration; pay_to=null means not configured. → see `PaymentX402` under **Structures**.
- `credit` (PaymentCredit) — Prepaid credit entry point. Never contains a balance or token. → see `PaymentCredit` under **Structures**.

**Errors**

- `405` — Use GET or HEAD.

**Example**

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

## Descoberta

### `GET /api/`

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

- **URL:** `https://staging.okfindex.com/api/`
- **Auth:** `none` — Public.

**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://staging.okfindex.com/api/health`
- **Auth:** `none` — Public.

**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://staging.okfindex.com/mcp`
- **Auth:** `none` — Public.

**Response `200`**

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

**Example**

```sh
curl -s -XPOST https://staging.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/okf/stats` has it.

- **URL:** `https://staging.okfindex.com/api/bundles`
- **Auth:** `none` — Public.

**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`.
- `concept` (string) — Text in the indexed root content, including listed concept names and summaries (first 1000 characters); up to 80 characters.
- `concepts` (string) — Number of entries listed by the root. Up to 5 comma-separated bands: 0,1-5,6-20,21-100,101+.
- `type` (string) — Type declared by the root, not the types of every concept. Up to 5 comma-separated values, 40 characters each.
- `license` (string) — Repository license. Up to 5 comma-separated values, 40 characters each.
- `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://staging.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://staging.okfindex.com/api/bundles/:id`
- **Auth:** `none` — Public.

**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://staging.okfindex.com/api/bundles/<id>
```

### `GET /api/okf/stats`

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

- **URL:** `https://staging.okfindex.com/api/okf/stats`
- **Auth:** `none` — Public.

**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_type` (Faceta[]) — Declared root types, up to 12; roots need not declare a type. → see `Faceta` under **Structures**.
- `by_concepts` (Faceta[]) — Root entry counts in bands 0, 1-5, 6-20, 21-100, 101+. → see `Faceta` under **Structures**.
- `by_license` (Faceta[]) — Repository licenses, up to 12; absent license is unknown. → 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://staging.okfindex.com/api/okf/stats
```

### `GET /api/stats`

Counts and facets for the OKF Index home.

- **URL:** `https://staging.okfindex.com/api/stats`
- **Auth:** `none` — Public.

**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_type` (Faceta[]) — Declared root types, up to 12; roots need not declare a type. → see `Faceta` under **Structures**.
- `by_concepts` (Faceta[]) — Root entry counts in bands 0, 1-5, 6-20, 21-100, 101+. → see `Faceta` under **Structures**.
- `by_license` (Faceta[]) — Repository licenses, up to 12; absent license is unknown. → 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://staging.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://staging.okfindex.com/api/ping`
- **Auth:** `none` — Public.

**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://staging.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://staging.okfindex.com/api/visit`
- **Auth:** `none` — Public.

**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://staging.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://staging.okfindex.com/api/metrics`
- **Auth:** `token` — Operator token `METRICS_TOKEN` as `Authorization: Bearer` (metrics).

**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://staging.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://staging.okfindex.com/api/erro-cliente`
- **Auth:** `none` — Public.

**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://staging.okfindex.com/api/erro-cliente -H 'content-type: application/json' -d '{"code":"UI-APP-001","phase":"carregar_lista","path":"/","message":"lista 500"}'
```

### `POST /api/pagamento/aberto`

The interface reports a visible payment prompt. Agents must not call this route.

An empty same-origin report, sent automatically when a payment prompt becomes visible. It starts no payment, grants no access and receives no identity or credentials. It writes no database row per report. Counts events, not unique people. The private operator dashboard separates API payment requests and browser payment views per UTC day; the two counts may overlap.

- **URL:** `https://staging.okfindex.com/api/pagamento/aberto`
- **Auth:** `none` — Public.

**Headers**

- `Origin` (string, required) — The page origin, identical to this route's origin.
- `Sec-Fetch-Site` (string, required) — `same-origin`, set by the browser.
- `X-MM-Payment-View` (string, required) — `1`, set by the shared component.

**Response `202`**

202 with no body when accepted; 204 when ignored. Always no-store.

## Public stats

### `GET /api/vitrine`

The product's public numbers: traffic, agents, usage and reliability, no money.

Projection published hourly by the house collector, rounded to two significant digits; `null` is a missing measurement, never zero. 15-minute cache with ETag (`If-None-Match` → 304). There is no way to send numbers through this route: publishing belongs to the collector, with its own token.

- **URL:** `https://staging.okfindex.com/api/vitrine`
- **Auth:** `none` — Public.

**Response `200`**

- `v` (int) — Contract version (1).
- `produto` (string) — Product id.
- `publicado` (bool) — `false` before the collector's first publication; then only these five keys come.
- `atualizado_em` (string, may be null) — When the collector published (ISO 8601).
- `stale` (bool) — `true` when the projection is older than 26 h.
- `nome` (string, optional) — Product name.
- `desde` (string, optional, may be null) — First day the series covers.
- `fuso` (string, optional) — Time zone of the days (`UTC`).
- `hoje` (object, optional) — Today: pages by class (human, AI, bot), API calls by class, machine-surface reads and product usage.
- `dias` (object[], optional) — Up to 31 days, oldest first: `dia`, `paginas`, `api`, `api_ia`, `maquina`, `visitantes`, `uso`.
- `janelas` (object, optional) — 7- and 30-day sums (`d7`, `d30`).
- `visitantes` (object, optional) — Unique visitors at the edge over 7 days.
- `pessoas` (object, optional, may be null) — GA4 when available: users, sessions, countries, devices and who arrived from AI.
- `agentes` (object, optional) — The AI agents and bots that read the most, 7 days.
- `superficies` (object, optional) — Reads of OKF, llms, well-known, OpenAPI and MCP over 7 days.
- `mcp` (object, optional) — MCP calls over 7 days.
- `uso` (object, optional) — Real product usage per resource: label, today, 7 and 30 days.
- `contas` (object, optional, may be null) — Users and guests.
- `confiabilidade` (object, optional) — Share of requests without 5xx over 7 days, and the live build.
- `catalogo` (object, optional, may be null) — Size of the catalog, when the product has one.
- `apoio` (object, optional) — Impressions and clicks per sponsor, when any.

**Example**

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

### `GET /api/vitrine/operador`

The product's full document on the operator panel — operator token only.

- **URL:** `https://staging.okfindex.com/api/vitrine/operador`
- **Auth:** `none` — Public.

**Headers**

- `Authorization` (string, required) — `Bearer <METRICS_TOKEN>` — the operator class.

**Response `200`**

- `produto` (string) — Product id.
- `atualizado_em` (string, may be null) — When the collector published.
- `operador` (object, may be null) — The collector's full document, with what the public projection leaves out.

**Errors**

- `401` — No token, wrong token or a token of another class.
- `503` — Worker without `METRICS_TOKEN` or without the control plane.

**Example**

```sh
curl -s https://staging.okfindex.com/api/vitrine/operador -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/vitrine/painel`

The whole house panel, in the shape the gm reads — operator token only.

- **URL:** `https://staging.okfindex.com/api/vitrine/painel`
- **Auth:** `none` — Public.

**Headers**

- `Authorization` (string, required) — `Bearer <METRICS_TOKEN>` — the operator class.

**Response `200`**

- `apps` (object[]) — One operator document per product, ordered by id.
- `updated` (string, optional) — When the collector closed the round.
- `totals` (object, optional) — House totals.

**Errors**

- `401` — No token, wrong token or a token of another class.
- `503` — Worker without `METRICS_TOKEN` or without the control plane.

**Example**

```sh
curl -s https://staging.okfindex.com/api/vitrine/painel -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/vitrine/cursores`

The resolved-error cursor per product (`borda`, `cli`) — operator token only.

- **URL:** `https://staging.okfindex.com/api/vitrine/cursores`
- **Auth:** `none` — Public.

**Headers**

- `Authorization` (string, required) — `Bearer <METRICS_TOKEN>` — the operator class.

**Response `200`**

JSON: `{ [product]: { borda?: ISO, cli?: ISO } }`; empty is `{}`.

**Errors**

- `401` — No token, wrong token or a token of another class.
- `503` — Worker without `METRICS_TOKEN` or without the control plane.

**Example**

```sh
curl -s https://staging.okfindex.com/api/vitrine/cursores -H "Authorization: Bearer $METRICS_TOKEN"
```

## Partnership

### `GET /api/partners`

Partnership, sponsorship and advertising: the product's placements with a suggested price, the public numbers next to them and how to propose.

Information on request, no activation: placements from the house catalogue priced in USD per 30 days (90 and 365 days discounted), sponsors in effect, an excerpt of `/api/vitrine`, the house wallet (USDC on Base) and the contact path — bank deposit, PIX or invoice are arranged in the reply. Cached for 1 hour.

- **URL:** `https://staging.okfindex.com/api/partners`
- **Auth:** `none` — Public.

**Response `200`**

- `status` (string) — `sob_consulta`: information and proposal, no activation and no charge.
- `produto` (string) — Product name.
- `idioma` (string) — Language of the texts (the product's).
- `titulo` (string) — Title of the offer.
- `descricao` (string) — One sentence about the offer.
- `publico` (string) — Who uses the product — the audience a sponsor reaches.
- `modalidades` (object[]) — `{ id, nome }`: patrocinio, parceria, anuncio.
- `placements` (object[]) — The product's placements: `id`, `nome`, `onde`, `formato`, `exclusivo`, `medicao`, `price_usd_30d` (suggested; `null` is on request), `exposure[{ dias, price_usd }]` for 30, 90 and 365 days, `disponivel`.
- `house_bundle` (object) — The house bundle: footer and agent mention across the ten products, discounted.
- `parcerias` (string[]) — Partnership ideas the product is open to discuss.
- `current_sponsors` (object[]) — Sponsors in effect: `id`, `nome`, `url`, `frase`, `espacos`, `ate`.
- `stats` (object) — Excerpt of the public numbers (`hoje`, `janelas`, `agentes`, `confiabilidade`) and the `link` to `/api/vitrine`; `publicado: false` before the first publication.
- `payment` (object) — How to pay: `rede`, `chain_id`, `ativo`, `pay_to`, `eip681` (the house wallet, when declared), `alternativas` and the `nota` — bank deposit, PIX or invoice in the reply.
- `contact` (object) — `email`, `form_url`, `api_url` (`POST /api/contact` where the handler exists), `campos` (required), `campos_proposta` (the optional proposal fields, each with its accepted values), `price_agent_usd`, `message_template`, `instructions`.
- `politica` (object) — Placement label, refused sectors, prepayment, deadlines.
- `_links` (object) — `self`, `stats`, `page` (`null` until the page exists), `contact`, `casa` (the same path on the ten products).

**Example**

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

## Contact

### `POST /api/contact`

Talks to the people behind the index: a human solves Turnstile, an agent pays $0.10 in x402 or prepaid credit.

Without a captcha in the body the request is treated as an agent: 402 until paid — x402 (`X-PAYMENT`) or prepaid credit (`Authorization: Bearer cred_…`, bought at `POST /api/credito`, the same token in every product of the house). The first agent message is free; after that the backoff is 60s doubling up to a 1-hour cap, announced in `Retry-After`. A partnership proposal goes through this same route with `tipo`.

- **URL:** `https://staging.okfindex.com/api/contact`
- **Auth:** `none` — Public.

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

- `name` (string, required) — What to call the person writing.
- `email` (string, required) — Where to reply.
- `message` (string, required) — What you want to say.
- `form_ts` (int) — When the form was opened; the anti-robot of the human path, and only it requires this.
- `cf_turnstile_response` (string) — Turnstile response; present only on the human path.
- `tipo` (string) — Proposal: `patrocinio`, `parceria` or `anuncio`. Turns on the fields below.
- `empresa` (string) — Who is proposing, when it is a company.
- `site` (string) — Website of who is proposing.
- `orcamento` (string) — `ate_100`, `100_500`, `500_2000`, `2000_mais` or `a_combinar`.
- `espaco` (string[]) — Placement ids from `GET /api/partners`, up to 6.
- `duracao` (string) — Exposure in days: `30`, `90` or `365`.
- `pagamento` (string) — `usdc`, `deposito` or `a_combinar`.

**Body example**

```json
{
  "name": "Agent",
  "email": "agent@example.com",
  "message": "hello from an agent"
}
```

**Response `200`**

- `ok` (bool) — Always `true` when the message was accepted.
- `path` (string) — Which path it came through: human with captcha or paid agent.

**Errors**

- `400` — Required field missing.
- `402` — Quota exceeded. The response carries `accepts[]` (x402, USDC on Base): pay and repeat the same call with `X-PAYMENT`.
- `429` — Agent backoff: wait for `Retry-After`.
- `503` — Mail or captcha not configured on the Worker; nothing was charged.

**Example**

```sh
curl -s -XPOST https://staging.okfindex.com/api/contact -H "X-PAYMENT: $PAYMENT" -H 'content-type: application/json' -d '{"name":"Agent","email":"agent@example.com","message":"hello from an agent"}'
```

## Credit

### `POST /api/credito`

Top up prepaid credit: pay once with x402 and get the token that debits on any API of the house.

- **URL:** `https://staging.okfindex.com/api/credito`
- **Auth:** `none` — Public.

**Query**

- `usd` (int, required) — Package: 1, 5, 10 ou 25 dollars.

**Response `200`**

- `token` (string) — Bearer token for the balance (`cred_…`). Shown ONCE — it cannot be recovered.
- `saldo_usd` (string) — Credited balance.
- `guarde` (string) — Warning that the token is the bearer of the credit.
- `usar` (string) — How to present the token on paid routes.
- `saldo_em` (string) — Where to check balance and statement.

**Errors**

- `400` — Package outside the list (1, 5, 10 ou 25).
- `402` — Unpaid — the body carries the x402 `accepts[]`.

**Example**

```sh
curl -s -XPOST 'https://staging.okfindex.com/api/credito?usd=10'
```

### `GET /api/credito`

Credit balance and statement — the latest movements, without returning the token.

- **URL:** `https://staging.okfindex.com/api/credito`
- **Auth:** `credito` — Prepaid credit token in `Authorization: Bearer cred_…` (or the `X-Credito` header). Not an account: it is a bearer of balance.

**Response `200`**

- `saldo_micros` (int) — Balance in micro-dollars (1e-6 USD).
- `saldo_usd` (string) — Formatted balance.
- `criado_em` (string) — When the credit was opened.
- `movimentos` (object[]) — Recent credits and debits, with product and resource.

**Errors**

- `401` — No token, or unknown token.

**Example**

```sh
curl -s https://staging.okfindex.com/api/credito -H 'Authorization: Bearer cred_…'
```

## 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/okf/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_type` (Faceta[]) — Declared root types, up to 12; roots need not declare a type. → see `Faceta` under **Structures**.
- `by_concepts` (Faceta[]) — Root entry counts in bands 0, 1-5, 6-20, 21-100, 101+. → see `Faceta` under **Structures**.
- `by_license` (Faceta[]) — Repository licenses, up to 12; absent license is unknown. → 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.

### `PaymentQuota`

- `free` (PaymentFree[]) — Free allowances and their windows. → see `PaymentFree` under **Structures**.
- `paid` (PaymentPrice[]) — List prices in USD. The operation's 402 is the payable quote. → see `PaymentPrice` under **Structures**.
- `how_to_pay` (string) — Payment instructions and availability restrictions.
- `live` (string, may be null) — Authoritative product quota endpoint.
- `free_now` (string[], optional) — SKUs temporarily free despite their list price.
- `trial` (PaymentTrial, optional) — Registration trial, when offered. → see `PaymentTrial` under **Structures**.

### `PaymentX402`

x402 payment configuration in force. Comes from `planPublic` and is the same across the products.

- `provider` (string) — Always `x402` — the only billing protocol accepted.
- `mode` (string) — Seller mode: `live` charges for real, `dev` lets calls through unpaid.
- `network` (string) — USDC network: `base` in production, `base-sepolia` in staging.
- `chain_id` (int) — EVM chain ID of the network above, so the wallet signs on the right chain.
- `pay_to` (string, may be null) — Address that receives the payment.
- `homolog` (bool) — Staging seam on: the loop can be closed without spending USDC.
- `dev` (bool) — Development mode: the 402 is simulated.
- `dev_gate` (bool) — A homologation credential is configured; this grants no access.
- `gratis` (string[], optional) — Temporarily free SKUs.
- `facilitator` (string) — URL of the facilitator that verifies and settles the payment.
- `asset` (string) — Accepted currency — always `USDC`.
- `asset_address` (string) — USDC contract on the network above.
- `faucet` (string, may be null) — Test-USDC faucet; only on base-sepolia.
- `wallets` (object) — Links to wallets that speak x402 (metamask, coinbase, base_app).

### `PaymentCredit`

- `url` (string) — POST to purchase credit; GET with X-Credito to inspect its balance.
- `header` (string) — Header for a previously issued credit token: X-Credito.

### `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 stored facet value or the concept-count band.
- `n` (int) — Live bundles with that value.

### `PaymentFree`

- `o_que` (string) — Operation or allowance.
- `limite` (string) — Allowance and eligibility.
- `janela` (string, may be null) — Reset window, when applicable.

### `PaymentPrice`

- `o_que` (string) — Operation and billing unit.
- `price_usd` (number) — Current list price in USD.

### `PaymentTrial`

- `days` (int) — Trial duration in days.
- `how` (string) — Eligibility and activation steps.


## Public data archives

Browse addresses and procurement by location, then open the records you need. Up to 20 items per page, in formats ready for people and agents. Check coverage and the reference date before using a result. Access options are shown by each product.

- [Postal codes and addresses](https://api.pontofato.com/enderecos/index.json): Find addresses by location, with coordinates and a 2022 reference date. Not a current postal-code certification. State → municipality → locality → street → addresses. [HTML](https://api.pontofato.com/enderecos/) · [llms.txt](https://api.pontofato.com/enderecos/llms.txt) · [OKF](https://api.pontofato.com/enderecos/okf/index.md)
- [Public procurement](https://api.editalmd.com/licitacoes/index.json): Find public procurement by location and date. View documents and reading options in EditalMD. Procedure → state → year → month → day → municipality → purchases. [HTML](https://api.editalmd.com/licitacoes/) · [llms.txt](https://api.editalmd.com/licitacoes/llms.txt) · [OKF](https://api.editalmd.com/licitacoes/okf/index.md)