# Meta Agent Tools — full API reference

> Generated from the catalog at https://staging.agentalog.com · build `359bbfd6`
> 86 endpoints · 47 structures
> Short index: https://staging.agentalog.com/llms.txt · Spec: https://staging.agentalog.com/openapi.json · MCP: https://staging.agentalog.com/mcp

> Community registry of MCP servers, Agent Skills and Claude Code plugins.
> Catalog discovery and ordinary browsing are free. GPTBot, ClaudeBot, CCBot, Meta-ExternalAgent, Amazonbot, AhrefsBot and MJ12bot share a daily allowance of 1,000 reads per crawler family. Further reads require a MAT package: US$1 for 1,000 reads, valid for 30 days, without automatic renewal. Send X-API-Pass on reads. The MAT balance is separate from the company, address and procurement indexes.

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

## Authentication

- `credito` — Prepaid credit token in `Authorization: Bearer cred_…` (or the `X-Credito` header). Not an account: it is a bearer of balance.
- `none` — Public, no credential.
- `guest` — Guest token (`POST /api/guest`) in `X-Guest-Token: mr_…` or `Authorization: Bearer mr_…`. In the browser it also lives in the HttpOnly `guest` cookie, which writes only from this site's exact Origin. A signed-in account (cookie) also works and takes precedence.
- `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.
- `session_ou_x402` — Two doors to the SAME action: a human with the account session (cookie; free, within the quota) or an agent paying x402 (`X-PAYMENT`). A guest token is neither required nor blocks the paid path.
- `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

**Response `200`**

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

**Example**

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

**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.agentalog.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.agentalog.com/.well-known/:arquivo`
- **Auth:** `none` — Public, no credential.

**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.agentalog.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.agentalog.com/apis.json`
- **Auth:** `none` — Public, no credential.

**Response `200`**

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

**Example**

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

### `GET /feed.xml`

RSS 2.0 of the most recently published listings.

- **URL:** `https://staging.agentalog.com/feed.xml`
- **Auth:** `none` — Public, no credential.

**Response `200`**

`application/rss+xml`.

**Example**

```sh
curl -s https://staging.agentalog.com/feed.xml
```

### `GET /feed.json`

JSON Feed 1.1 of the most recently published listings — the same stream as the RSS.

- **URL:** `https://staging.agentalog.com/feed.json`
- **Auth:** `none` — Public, no credential.

**Response `200`**

`application/feed+json`.

**Example**

```sh
curl -s https://staging.agentalog.com/feed.json
```

### `GET /api/`

Self-describing index: the whole API surface, with quota and quickstart.

- **URL:** `https://staging.agentalog.com/api/`
- **Auth:** `none` — Public, no credential.

**Response `200`**

- `name` (string) — Product name.
- `description` (string) — What the registry is and what it is not.
- `auth` (object) — Each authentication mode and how to obtain it.
- `docs` (object) — Links to llms.txt, llms-full.txt, openapi.json, MCP and the UI.
- `endpoints` (object[]) — Every endpoint with method, path, auth, absolute URL and what it returns.
- `quota` (object) — What is free, what costs and how to pay — before you spend a call.
- `mcp` (object) — Address and transport of the MCP server.
- `quickstart` (string[]) — The calls that take you from zero to the first published listing.

### `GET /api/health`

Liveness and the commit deployed right now — it is how the smoke waits for its own deploy.

- **URL:** `https://staging.agentalog.com/api/health`
- **Auth:** `none` — Public, no credential.

**Response `200`**

- `ok` (bool) — Always `true` when the Worker answers.
- `app` (string) — Product name.
- `build` (string) — Deployed commit; CI passes the short SHA on deploy.
- `ts` (string) — Time of the response (UTC, ISO-8601).

### `POST /mcp`

MCP server over HTTP (Streamable HTTP, JSON-RPC 2.0) — plugs into the client with nothing to install.

The tools are the operations of this same catalog; the MCP has no backend of its own. `GET /mcp` returns the server card.

- **URL:** `https://staging.agentalog.com/mcp`
- **Auth:** `none` — Public, no credential.
- Credentials go in the usual headers (X-Guest-Token, Authorization, X-PAYMENT) and are forwarded to the API.
- An exhausted quota comes back as a 402 with accepts[] inside the tool result — pay and repeat.

**Response `200`**

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

**Example**

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

### `GET /api/pricing`

Current prices and free allowances.

- **URL:** `https://staging.agentalog.com/api/pricing`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/pricing
```

## Identity

### `POST /api/guest`

Creates a guest `mr_…` — it is the identity that likes, comments and visits.

Asks for no e-mail. Publishing a listing is what requires an account (or a payment). At most 20 new guests per network per hour; a browser that already has one gets it back from the `guest` cookie.

- **URL:** `https://staging.agentalog.com/api/guest`
- **Auth:** `none` — Public, no credential.

**Response `200`**

- `token` (string) — The guest, prefix `mr_`. Send it in `X-Guest-Token` or as Bearer.

**Errors**

- `429` — More than 20 new guests from the same network in the hour.
- `503` — auth_unavailable

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/guest
```

## Catalog

### `GET /api/listings`

The public mosaic: paginated search of the catalog's listings, the lower-signal tail last.

`live` listings first and the `low` tail (few stars or no clear license) after them in every order — `low=0` leaves the tail out. To walk everything, follow `next`: without `q` it is a cursor (`next_cursor`, keyset on the order's index) and has no ceiling; every listing also has an HTML page at `/l/:id` and the shards of `/sitemap-listings.xml` list them all. `q` runs on a full-text index (FTS5, bm25) kept in the same transaction as every text write. With `q` and `low=0`, `low_count` says how many `low` listings the filter left out — LIKE with a cap of 200. The query is mapped onto kind/topic/transport filters unless `interpret=0`.

- **URL:** `https://staging.agentalog.com/api/listings`
- **Auth:** `none` — Public, no credential.

**Query**

- `q` (string) — Free text over the name, the tagline, the description, the origin identifier and the README excerpt: every word (up to six, 2+ letters, accents ignored) must match; ranked by bm25 with the name weighing most (10), then tagline (5), identifier (3), description (2), README excerpt (1); ties by stars. Kind, topic and transport words become filters. The `low` tail is in the same index. e.g.: `browser testing`.
- `interpret` (string) — `0` disables query understanding and searches the raw string. Values: `0`.
- `kind` (string) — Which kind of resource to fetch. Values: `mcp`, `skill`, `plugin`.
- `category` (string) — Category declared by whoever published.
- `sort` (string) — Result order. Without it, a query is ranked by relevance — bm25 over the full-text index (name 10, tagline 5, identifier 3, description 2, README excerpt 1) multiplied by 1 + 0.05·ln(1 + stars) + 0.1 if pushed in the last 180 days + 0.1 if a README was collected; ties by stars — and a plain listing by arrival. Default: `relevancia when q is set, recent otherwise`. Values: `relevancia`, `recent`, `stars`, `likes`, `visits`, `nome`.
- `low` (string) — `0` leaves the `low` tail out; by default it comes after the `live` listings in every order. Values: `0`.
- `cursor` (string) — Opaque cursor from `next_cursor` of the previous page (orders `recent`, `stars` and `nome`, without `q`). With it, `offset` is ignored. A cursor from another order or a malformed one restarts at the first page.
- `limit` (int) — Listings per page. Default: `24`.
- `offset` (int) — How many listings to skip. No ceiling since 2026-09-13, but the database reads every skipped row: to walk the catalog, follow `next` (cursor) instead. Default: `0`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `PaginaDeAnuncios`.

- `items` (Anuncio[]) — The listings on this page. → see `Anuncio` 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.
- `next_cursor` (string, may be null) — Opaque cursor of the next page for the orders without a text query (`recent`, `stars`, `nome`): pass it back as `cursor`. Each page then reads only its own rows, whatever the depth. `null` when there is no more, or when the order is ranked by `q`, likes or visits (offset applies there).
- `next` (string, may be null) — Absolute URL of the next page, same filters — follow it until it comes back `null` to walk the whole catalog without rebuilding the querystring.
- `low_count` (int) — With `low=0` and `q`: `low` listings left out (cap 200).
- `low_capped` (bool) — `true` when the count hit the cap — there are at least that many.
- `low_included` (bool) — `true` unless `low=0`: the `low` tail comes after `live`.
- `interpretacao` (object, may be null) — Filters deduced from `q` (`kind`, `topico`, `transporte`, `origin`, residual `q`). `null` when understanding is off or there is no query.
- `api` (string) — Absolute URL of this listing.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s 'https://staging.agentalog.com/api/listings?kind=mcp&sort=likes&limit=5'
```

### `GET /api/facets`

The whole catalog's counts by kind, provenance, category and repository state.

Exists to build a filter without sweeping the listings: there are tens of thousands, and asking for the list just to count would be expensive. Also brings `topico_inferido`, deduced from the repositories.

- **URL:** `https://staging.agentalog.com/api/facets`
- **Auth:** `none` — Public, no credential.

**Response `200`**

Structure: `Facetas`.

- `total` (int) — Live listings in the catalog.
- `facetas` (object) — Map of facet → list of `{ v, n }` (value and count): `kind`, `origin`, `category`, `repo_estado`, `transporte`…
- `topico_inferido` (object) — Topics deduced from the repositories, with the count of each.
- `interpretacao` (object, may be null) — Same query understanding as `/api/listings`, so the counts match the list.
- `publicador` (object, optional, may be null) — `{ ns, n, stars }` when the slice has exactly one `ns` — the publisher's live listings and their stars summed, regardless of the other filters (the publisher page header); `null` otherwise. Responses cached before 13/09/2026 may not carry the key yet.
- `api` (string) — Absolute URL of this route.

**Example**

```sh
curl -s https://staging.agentalog.com/api/facets
```

### `GET /v0.1/servers`

MCP subregistry in the Official Registry format (spec v0.1), cursor-paginated.

Only `kind=mcp` and only `live`. It is the route a generic MCP client knows how to read without knowing this product. `GET /v0/servers` is an alias of the same resource, kept for whoever already pointed there — this is the canonical URL.

- **URL:** `https://staging.agentalog.com/v0.1/servers`
- **Auth:** `none` — Public, no credential.

**Query**

- `search` (string) — Free text over the server's name and description.
- `cursor` (string) — Opaque cursor of the next page, from `metadata.next_cursor`.
- `limit` (int) — Servers per page. Default: `30`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `PaginaV01`.

- `servers` (ServidorV01[]) — The servers on this page. → see `ServidorV01` under **Structures**.
- `metadata` (object) — `next_cursor` and `count`, in the spec's format.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s 'https://staging.agentalog.com/v0.1/servers?search=postgres&limit=5'
```

### `GET /api/listings/:id`

One listing's page. The owner sees their own even when pending or hidden.

- **URL:** `https://staging.agentalog.com/api/listings/:id`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Listing ID, from `Anuncio.id`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `Anuncio`.

- `id` (string) — Listing ID; it is the key across the whole API.
- `kind` (string) — What this listing is.
- `category` (string, may be null) — Category chosen by whoever published.
- `name` (string) — Display name.
- `tagline` (string, may be null) — One line saying what it is for.
- `body` (string, may be null) — Long description, when whoever published wrote one.
- `url` (string) — Where the resource lives — the MCP endpoint, the SKILL.md or the repository.
- `status` (string) — State in the catalog.
- `origin` (string) — Where the listing came from: `official`, `marketplace`, `directory` or a community submission.
- `origin_id` (string, may be null) — Identifier of the listing at the source.
- `install` (string, may be null) — How to install, when the source says.
- `source` (string, may be null) — Source code URL, when known.
- `transporte` (string, may be null) — MCP transport: `stdio`, `http`, `sse`.
- `ns` (string, may be null) — Server namespace in the official registry.
- `versao` (string, may be null) — Version declared by the source.
- `oficial_status` (string, may be null) — State in the official MCP registry, when applicable.
- `repo_host` (string, may be null) — Where the repository is hosted, e.g. `github`.
- `topico` (string, may be null) — Inferred topic used in search filters, not a publisher declaration. When available, `payload.topico_llm` carries the supporting quote and confidence.
- `linguagem` (string, may be null) — Primary language of the repository, when collected.
- `licenca` (string, may be null) — SPDX license of the repository, when collected.
- `repo_topics` (string, may be null) — Repository topics, separated by spaces.
- `repo_slug` (string, may be null) — owner/name of the repository, when known.
- `stars` (int, may be null) — Repository stars at the last check.
- `forks` (int, may be null) — Repository forks at the last check.
- `prs_abertos` (int, may be null) — Open pull requests at the last check.
- `pushed_at` (string, may be null) — Last push to the repository (UTC).
- `repo_estado` (string, may be null) — How the repository is doing (active, stalled, archived, renamed, gone).
- `likes` (int) — How many people liked it — the like is reversible and counts people.
- `comments` (int) — Public comments on the listing.
- `visits` (int) — Visits counted by the hop; at most 1 per owner per day.
- `created_at` (string) — When it entered the catalog (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `mine` (bool) — `true` when the listing is yours — only then can you edit it.
- `api` (string) — Absolute URL of this listing's page.
- `go` (string) — Hop URL: redirects to `url` and counts the visit.
- `comments_api` (string) — Absolute URL of this listing's comments.
- `readme_api` (string, optional) — Absolute URL of the collected README (`GET`). On list rows and on the listing page, and only when a README was stored: absent means none was collected — do not build the path yourself.
- `historico` (object[], optional) — Listing page only: the repository's last events, as in `/api/listings/:id/history`; absent when there is none yet.
- `readme_fonte` (string, optional) — Where the README came from: `repo` (the GitHub repository's README) or `npm` / `pypi` (the package registry's README, used when the listing has no repository). Present together with `readme_api`.
- `readme_bytes` (int) — Size of the collected README in bytes, on list rows and on the listing page; 0 when none was collected.
- `readme_sha` (string, may be null) — SHA-256 of the collected README. Listing page only.
- `readme_em` (string, may be null) — When the README was stored (UTC). Listing page only.
- `payload` (object, may be null) — Install payload mirrored from the source. Listing page only. When the topic came from the model, `topico_llm` holds `{topico, confianca, trecho, v}`: the label, the confidence (0–1), the literal quote that justified it and the rule version.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `404` — The listing does not exist, or it is not yours and is not live/low.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/listings/ID
```

### `GET /api/listings/:id/readme`

README collected from the listing's repository, served on open.

The text lives in R2 (`mural-coleta`). This call does not write and does not fetch GitHub. Same visibility as the listing page. Call it only when the listing page carries `readme_api`: a page without it has no README collected, and this route answers 404.

- **URL:** `https://staging.agentalog.com/api/listings/:id/readme`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Listing ID, from `Anuncio.id`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `Readme`.

- `markdown` (string) — README text, UTF-8. May be truncated at 200 kB.
- `bytes` (int) — Size as stored.
- `sha` (string) — SHA-256 of the stored object.
- `repo_slug` (string) — owner/name of the repository; empty when the listing has none.
- `fonte` (string) — `repo`, `npm` or `pypi` — the same value as `readme_fonte` on the listing page.
- `truncated` (bool) — `true` when the body was cut at the cap.
- `api` (string) — Absolute URL of this resource.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `404` — The listing does not exist, is not visible, or no README was collected.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/listings/ID/readme
```

### `GET /api/go/:id`

Hop to the listing's URL: redirects and counts the visit.

Counts at most 1 visit per owner per day. The `X-Visit-Counted` header says whether this call counted — it is how the client knows without counting twice.

- **URL:** `https://staging.agentalog.com/api/go/:id`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — ID of the listing to visit. e.g.: `lst_9f3c2b1d7a4e58b0c2d4`.

**Response `200`**

`302` with `Location` to the listing's URL, and the `X-Visit-Counted` header.

**Errors**

- `404` — The listing does not exist or is not live/low.

### `GET /api/volatil`

Fresh download, install and version counters for up to 100 listings.

The catalog stores the values seen at the last real change of a listing; counters and package versions change over time. These values may be cached for up to 15 minutes; `gerado_em` gives their reference date. Listings without a record are simply absent. `GET /api/listings/:id` already applies these values on top of the record.

- **URL:** `https://staging.agentalog.com/api/volatil`
- **Auth:** `none` — Public, no credential.

**Query**

- `ids` (string, required) — Comma-separated listing ids, at most 100.

**Response `200`**

- `itens` (object) — `{id: {downloads?, installs?, version?, pacotes?}}` — `pacotes` maps `registry:identifier` to its version.
- `gerado_em` (string) — When the oldest slice read was generated (UTC).
- `ttl_s` (int) — How long a slice stays in the edge cache.

**Errors**

- `400` — `ids` missing, invalid, or more than 100.

**Example**

```sh
curl -s 'https://staging.agentalog.com/api/volatil?ids=skl_a,skl_b'
```

### `GET /api/listings/:id/history`

Timeline of the listing's repository: the last events (stale, gone, renamed, README or manifest changed).

The listing page carries the same list as `historico`; updates may be cached for up to 15 minutes. An empty list means no change since the series began — the listing still exists. Stale means no push for 12 months. Reading this endpoint does not refresh the record.

- **URL:** `https://staging.agentalog.com/api/listings/:id/history`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Listing ID, from `Anuncio.id`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `Historico`.

- `id` (string) — Listing ID.
- `historico` (object[]) — Newest first, at most 5: `{ em, tipo, de?, para? }` — `tipo` is `abandono` (no push for 12 months), `sumiu`, `renomeado`, `readme_mudou` or `manifesto_mudou`; `de`/`para` only for the state events.
- `gerado_em` (string) — Reference date of this history (UTC).
- `ttl_s` (int) — Edge cache life of the slice, in seconds.
- `api` (string) — Absolute URL of this route.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `404` — The listing does not exist or is not visible.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/listings/ID/history
```

### `GET /api/contadores`

Likes, comments and visits of every listing that has any, read from where they are written.

Counters include visits, likes and comments and may take up to five minutes to reach catalog pages. Only listings with a counter above zero are returned. Smoke traffic never counts. Cached for 60 seconds.

- **URL:** `https://staging.agentalog.com/api/contadores`
- **Auth:** `none` — Public, no credential.

**Response `200`**

Structure: `Contadores`.

- `gerado_em` (string) — When this list was read (ISO 8601).
- `total` (int) — Listings in `itens`.
- `truncado` (bool) — More listings have counters than the 20,000 returned.
- `itens` (object[]) — One entry per listing with any counter: `id`, `likes`, `comments`, `visits`.

**Example**

```sh
curl -s https://staging.agentalog.com/api/contadores
```

### `GET /coleta/readme/:arquivo`

Read a collected README as Markdown by its published object path.

Same MAT read allowance and pass. Prefer /api/listings/:id/readme (also available through MCP) for metadata and the historical R2 fallback. This raw route only serves objects already present on the catalog origin.

- **URL:** `https://staging.agentalog.com/coleta/readme/:arquivo`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `arquivo` (string, required) — Published relative README path, e.g. owner/repository.md.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

README Markdown (text/markdown); a successful basic read is at most 1 MiB.

**Errors**

- `401` — Invalid pass.
- `402` — Read allowance or credit exhausted.
- `404` — README absent.
- `413` — Read too large.
- `503` — Origin unavailable.

**Example**

```sh
curl -s "https://staging.agentalog.com/coleta/readme/owner/repository.md" -H "X-API-Pass: $API_PASS"
```

## Community

### `GET /api/listings/:id/comments`

Public comments on a live listing.

With a credential on the call, each comment of yours comes with `mine: true`.

- **URL:** `https://staging.agentalog.com/api/listings/:id/comments`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — ID of the listing.

**Response `200`**

- `items` (Comentario[]) — The comments, newest first. → see `Comentario` under **Structures**.
- `total` (int) — How many comments the listing has.

**Errors**

- `404` — The listing does not exist or is not live.

**Example**

```sh
curl -s https://staging.agentalog.com/api/listings/ID/comments
```

### `POST /api/listings/:id/comments`

Writes a comment on the listing. Cap of 20 per hour per owner.

- **URL:** `https://staging.agentalog.com/api/listings/:id/comments`
- **Auth:** `guest` — Guest token (`POST /api/guest`) in `X-Guest-Token: mr_…` or `Authorization: Bearer mr_…`. In the browser it also lives in the HttpOnly `guest` cookie, which writes only from this site's exact Origin. A signed-in account (cookie) also works and takes precedence.

**Path parameters**

- `id` (string, required) — ID of the listing to comment on.

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

- `body` (string, required) — The comment text.

**Body example**

```json
{
  "body": "text"
}
```

**Response `200`**

- `ok` (bool) — Always `true` when the comment went in.
- `id` (string) — ID of the created comment.
- `body` (string) — The stored text.

**Errors**

- `400` — Empty or too long text.
- `401` — No credential, or an invalid one. See this endpoint's auth.
- `404` — The listing does not exist.
- `429` — More than 20 comments in the hour.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/listings/ID/comments -H "X-Guest-Token: $MR" -H 'content-type: application/json' -d '{"body":"works well with Claude Code"}'
```

### `DELETE /api/comments/:id`

Deletes a comment of yours. Someone else's comment answers 404, not 403.

The 404 is on purpose: the API does not confirm that a comment with that id exists if it is not yours.

- **URL:** `https://staging.agentalog.com/api/comments/:id`
- **Auth:** `guest` — Guest token (`POST /api/guest`) in `X-Guest-Token: mr_…` or `Authorization: Bearer mr_…`. In the browser it also lives in the HttpOnly `guest` cookie, which writes only from this site's exact Origin. A signed-in account (cookie) also works and takes precedence.

**Path parameters**

- `id` (string, required) — Comment ID, from `Comentario.id`. e.g.: `cm_9f3c2b1d7a4e58b0c2`.

**Response `200`**

- `ok` (bool) — Always `true`.
- `id` (string) — The id that was removed.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.
- `404` — The resource does not exist (or is not yours — the API does not tell the two apart on purpose).

**Example**

```sh
curl -s -XDELETE https://staging.agentalog.com/api/comments/CMT_ID -H "X-Guest-Token: $MR"
```

### `POST /api/listings/:id/like`

Likes the listing. Calling again does not add up: the counter counts people.

- **URL:** `https://staging.agentalog.com/api/listings/:id/like`
- **Auth:** `guest` — Guest token (`POST /api/guest`) in `X-Guest-Token: mr_…` or `Authorization: Bearer mr_…`. In the browser it also lives in the HttpOnly `guest` cookie, which writes only from this site's exact Origin. A signed-in account (cookie) also works and takes precedence.

**Path parameters**

- `id` (string, required) — ID of the listing to like.

**Response `200`**

Structure: `Like`.

- `ok` (bool) — Always `true`.
- `liked` (bool) — Whether YOU are liking it now.
- `likes` (int) — Total people liking the listing.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.
- `404` — The resource does not exist (or is not yours — the API does not tell the two apart on purpose).

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/listings/ID/like -H "X-Guest-Token: $MR"
```

### `DELETE /api/listings/:id/like`

Unlikes and gives the point back to the public counter.

- **URL:** `https://staging.agentalog.com/api/listings/:id/like`
- **Auth:** `guest` — Guest token (`POST /api/guest`) in `X-Guest-Token: mr_…` or `Authorization: Bearer mr_…`. In the browser it also lives in the HttpOnly `guest` cookie, which writes only from this site's exact Origin. A signed-in account (cookie) also works and takes precedence.

**Path parameters**

- `id` (string, required) — ID of the listing to unlike.

**Response `200`**

Structure: `Like`.

- `ok` (bool) — Always `true`.
- `liked` (bool) — Whether YOU are liking it now.
- `likes` (int) — Total people liking the listing.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.
- `404` — The resource does not exist (or is not yours — the API does not tell the two apart on purpose).

**Example**

```sh
curl -s -XDELETE https://staging.agentalog.com/api/listings/ID/like -H "X-Guest-Token: $MR"
```

## Feeds

### `GET /api/feeds`

The feed index: RSS, Atom and JSON feeds, OPML reading lists and sites that only become a feed through a bridge.

Find feeds by text, format, language and availability. Filter and text search run in the SAME full-text query: values inside one parameter are OR'd, different parameters are AND'd. Without `q` the order is by newest in the index (`recentes`) and `next_cursor` is a keyset — follow `next` to walk everything. With `q` the order is relevance and paging is by `offset`. We index and link; the feeds belong to whoever publishes them.

- **URL:** `https://staging.agentalog.com/api/feeds`
- **Auth:** `none` — Public, no credential.

**Query**

- `q` (string) — Free text over the feed name, its description and the domain. Every word must match; accents are ignored. e.g.: `linux`.
- `origem` (string) — Where the record comes from. Comma-separated values are OR'd. Values: `index`, `blogroll`, `bridge`.
- `tipo` (string) — Feed format. Comma-separated values are OR'd. Values: `rss2`, `rss1`, `atom`, `json`, `rss`.
- `midia` (string) — Enclosures the feed carries — this is how you find podcasts and video feeds. Values: `audio`, `video`.
- `comunidade` (string) — Community the publisher belongs to, as the source's bitmask declares it. Values: `fediverse`, `indieweb`, `mastodon`, `friendica`, `wordpress`, `funkwhale`, `blogroll`.
- `recurso` (string) — Namespace seen in the feed: `content` means the whole post travels in the feed, `itunes`/`podcast` mean podcast metadata, `slash` means comment counts. Values: `content`, `itunes`, `podcast`, `media`, `slash`, `wfw`, `georss`.
- `lista` (string) — For OPML lists only: how the list presents itself. Values: `web`, `catalogo`, `planeta`.
- `ano` (string) — Year of the newest item the crawler saw. `0` means the source never dated the content. It is a year, not a moving window: the value never drifts. e.g.: `2026,2025`.
- `saude` (string) — What our own check saw: `ok` answered, `erro` refused or timed out, `sumiu` returned 404/410. A feed not checked yet matches none of them. Values: `ok`, `erro`, `sumiu`. e.g.: `ok`.
- `pais` (string) — ISO-3166 alpha-2 of the IP that serves the host, lowercase or uppercase, resolved in the same check. e.g.: `br,pt`.
- `dominio` (string) — Exact domain — the fastest way to ask whether a site has a feed.
- `idioma` (string) — Language of the site's home page, two or three letters: `pt` matches `pt` and `pt-br`. e.g.: `pt`.
- `imagem` (string) — `1` keeps only feeds whose site has a stored preview image (`imagem` is not empty) — the list that looks like a wall of link cards. Values: `1`.
- `sort` (string) — Result order. `recentes` is insertion in the index (what just arrived). `postando` is the newest post first, read from the feed itself (feeds without a dated post are left out). `frequentes` is most posts in the last 30 days first (same). `densidade` is how much item text discovery found — the closest thing to 'this feed has substance'. `dominio` is A–Z by site. Default: `relevancia with q, recentes otherwise`. Values: `recentes`, `postando`, `frequentes`, `densidade`, `dominio`, `relevancia`.
- `cursor` (string) — Opaque cursor from `next_cursor` (orders `recentes`, `densidade` and `dominio`). A cursor from another order restarts at the first page.
- `limit` (int) — Feeds per page, 1–50. Default: `20`.
- `offset` (int) — Offset, capped at 10000. Ignored when `cursor` is present. Default: `0`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `PaginaDeFeeds`.

- `items` (Feed[]) — The records on this page. → see `Feed` under **Structures**.
- `limit` (int) — Page size applied.
- `offset` (int) — Offset applied.
- `next_cursor` (string, may be null) — Opaque cursor of the next page for the orders without a text query. `null` when there is no more.
- `next_offset` (int, may be null) — Offset of the next page when the order is by relevance.
- `next` (string, may be null) — Absolute URL of the next page, same filters.
- `sort` (string) — Order actually applied.
- `api` (string) — Absolute URL of this collection.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s 'https://staging.agentalog.com/api/feeds?midia=audio&recurso=itunes&limit=5'
```

### `GET /api/feeds/facets`

How many feeds exist in each filter value.

Counts reflect the latest catalog update.

- **URL:** `https://staging.agentalog.com/api/feeds/facets`
- **Auth:** `none` — Public, no credential.

**Response `200`**

Structure: `FacetasDeFeeds`.

- `total` (int) — Records in the index.
- `facetas` (object) — One key per filter (`origem`, `tipo`, `midia`, `comunidade`, `recurso`, `lista`, `ano`), each a list of `{ v, n }`.
- `api` (string) — Absolute URL of this resource.

**Example**

```sh
curl -s https://staging.agentalog.com/api/feeds/facets
```

### `GET /api/feeds/:id`

One feed: address, format, what it carries and where it was found.

The same record the HTML page at `/feeds/<id>` shows. 404 when the id is unknown.

- **URL:** `https://staging.agentalog.com/api/feeds/:id`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Feed id, prefix `fd_`. e.g.: `fd_nytimes_com_1a2b3c4d5e6f7a8b`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `Feed`.

- `id` (string) — Feed id, prefix `fd_`; it is the key across this collection.
- `kind` (string) — What this record is.
- `dominio` (string) — Domain that publishes it, lowercase and without `www.`.
- `url` (string) — The feed address — or the site's, for a record of kind `bridge`.
- `nome` (string) — Feed title as the source published it.
- `descricao` (string) — Feed description; for a reading list, whoever curates it.
- `tipo` (string) — Feed format.
- `audio` (bool) — `true` when the feed carries audio enclosures — a podcast.
- `video` (bool) — `true` when the feed carries video enclosures.
- `comunidade` (int) — Bitmask of the communities the publisher belongs to; 0 when none is known.
- `comunidades` (string[]) — The same communities by name (`wordpress`, `indieweb`, `fediverse`, `mastodon`, `friendica`, `funkwhale`, `blogroll`), so nobody has to decode the bitmask.
- `ano` (int) — Year of the newest item the source saw in this feed; 0 when it published no usable date. It is a freshness hint from discovery, not a live check.
- `recursos` (string[]) — Namespaces seen in the feed, `content` first when the whole post travels in it.
- `densidade` (int) — The source's own text score for the feed (`t`): how much item text discovery found. Bigger means more text travels in the feed — the scale is the source's, and the value is frozen at discovery, not a live metric.
- `itens` (int) — How many feeds an OPML list had when it was read; 0 for a feed.
- `saude` (string) — What OUR own check saw: `ok` answered with an actual feed (an RSS/Atom/RDF root, a JSON Feed, or OPML for a list); `sumiu` returned 404/410 or its domain no longer resolves; `erro` any other failure. A failure only changes this after a second check hours later agrees, and a server that blocks robots (401/403, bot challenge) never turns into `erro`. Empty means not checked yet — which is not the same as failing.
- `pais` (string) — ISO-3166 alpha-2 of the IP that serves the host, resolved during that same check. Empty when it could not be resolved.
- `site_titulo` (string) — Link preview of the publisher's home page, as WhatsApp or X would read it: `og:title`, then `twitter:title`, JSON-LD and `<title>`. Every `site_*` field is empty when the site declares nothing, was not visited yet, disallows our robot in robots.txt, or is confirmed gone (parked, suspended, default server page).
- `site_descricao` (string) — Preview description: `og:description`, then `twitter:description`, JSON-LD and `<meta name=description>`.
- `site_nome` (string) — Site name the page declares (`og:site_name`, `application-name`).
- `site_og` (string) — The preview image URL as declared by the site (`og:image`, then `twitter:image`); https only.
- `site_og_alt` (string) — Alternative text the site declares for that image (`og:image:alt`).
- `site_cor` (string) — The site's `theme-color` as `#rrggbb`; empty when absent or not a plain color.
- `site_idioma` (string) — Language of the home page (`<html lang>`, then `og:locale`): two or three letters, plus the region when the site declares one (`pt-br`, `en-us`).
- `idioma_bandeira` (string) — ISO-3166 alpha-2 (lowercase) of the flag that stands for that language: the declared region, otherwise the language's reference country (`en` → `gb`, `pt` → `br`). Empty for languages without one.
- `icone` (string) — Absolute URL of the site icon served by us (the largest raster icon the home declares, up to 512 px; `/favicon.ico` otherwise), downloaded and checked on our index host. Empty when we have none stored.
- `imagem` (string) — Absolute URL of the preview image served by us, up to 600 KB, downloaded and checked on our index host (PNG, JPEG, GIF, WebP, AVIF, ICO or BMP by its bytes). Empty when the site declares none or we have none stored.
- `ultimo_post` (string) — ISO 8601 date of the newest post, read from the feed itself (RSS `pubDate`, Atom `published`/`updated`, RDF `dc:date`, JSON Feed `date_published`). Empty when not read yet, when the feed dates nothing, or for lists and bridges.
- `posts_24h` (int, may be null) — Posts published in the last 24 hours, counted at request time over the dates we read. `null` when the feed was not read yet — not the same as zero.
- `posts_7d` (int, may be null) — Posts in the last 7 days, same rules as `posts_24h`.
- `posts_30d` (int, may be null) — Posts in the last 30 days, same rules as `posts_24h`.
- `posts_dias` (int[], may be null) — Posts per day over the last 30 days, oldest first and today last (24-hour windows counted from the request time). `null` when the feed was not read yet.
- `posts_no_feed` (int, may be null) — Items the feed carried in what we read. `0` is an empty feed, which is not the same as a feed whose posts carry no date.
- `posts_parcial` (bool) — The feed is longer than what we read (10 MB), so the counts are minimums.
- `atividade_em` (string) — When we last read the feed's posts (ISO 8601). Active feeds are re-read daily.
- `pagina` (string) — Absolute URL of this record's HTML page.
- `api` (string) — Absolute URL of this resource.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `404` — No feed in this index has that id.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/feeds/fd_nytimes_com_1a2b3c4d5e6f7a8b
```

### `GET /api/feeds/:id/items`

The posts of one feed, as our queue read them.

Up to 40 posts, in the order the feed publishes them, WITHOUT the body — the body of one post comes from `/items/:ord`. It is OUR copy, read on our own schedule — not the live feed and not a proxy: the only thing this endpoint accepts is an id from this index, never a URL. `lido_em` says when we read it. Empty list when the feed has not been read yet.

- **URL:** `https://staging.agentalog.com/api/feeds/:id/items`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Feed id, prefix `fd_`. e.g.: `fd_nytimes_com_1a2b3c4d5e6f7a8b`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `PostsDeFeed`.

- `id` (string) — Feed id these posts belong to.
- `itens` (PostDeFeed[]) — Up to 40 posts, in the order the feed publishes them (the archive keeps every post the feed carried). → see `PostDeFeed` under **Structures**.
- `lido_em` (string) — When we read the feed, ISO-8601; empty when it was never read.
- `api` (string) — Absolute URL of this resource.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `404` — No feed in this index has that id. A feed we know but have not read yet answers 200 with an empty `itens` — the two are different answers on purpose.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/feeds/fd_nytimes_com_1a2b3c4d5e6f7a8b/items
```

### `GET /api/feeds/:id/items/:ord`

One post of a feed, with the body — the author's HTML and the same text in Markdown.

Two bodies for the same post, both produced when we READ the feed, never at request time: `conteudo_html` keeps the author's formatting through an allowlist (only known tags and attributes survive; script, style, iframe and event handlers are dropped with their content), and `conteudo` is the same text as Markdown — the shape an agent usually wants. Neither can carry script. 404 when the feed or the position is unknown.

- **URL:** `https://staging.agentalog.com/api/feeds/:id/items/:ord`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Feed id, prefix `fd_`. e.g.: `fd_nytimes_com_1a2b3c4d5e6f7a8b`.
- `ord` (string, required) — Position of the post in the feed; 0 is the newest. e.g.: `0`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `PostDeFeedInteiro`.

- `id` (string) — Feed id this post belongs to.
- `ord` (int) — Position of the post in the feed when we read it; 0 is the newest.
- `titulo` (string) — Post title, plain text.
- `link` (string) — The post on the publisher's site, `http`/`https` only.
- `quando` (string) — Publication date in ISO-8601; empty when the item carried no usable date.
- `autor` (string) — Author as the feed named them, without the e-mail address.
- `resumo` (string) — First lines of the post, plain text.
- `conteudo_html` (string) — The post body as HTML that passed OUR allowlist when we read the feed: only the tags and attributes named in `origem/processa/html-seguro.mjs` survive, links are absolute and open in a new tab, images carry no referrer, and script, style, iframe and embedded media are gone with their content. It keeps the author's formatting — tables, figures with captions, nested lists — and the post's own `audio`/`video` (never autoplaying, nothing fetched before play). A video embed from a known host (YouTube, Vimeo, SoundCloud, Twitch, Dailymotion, Bandcamp, Bilibili, Spotify, Internet Archive) becomes a placeholder `div.mural-md-embed` carrying `data-embed`: the player is only created when the reader clicks it, so the host learns nothing until then.
- `conteudo` (string) — The same body in Markdown, up to half a million characters, cut at a paragraph — the shape an agent usually wants.
- `lido_em` (string) — When we read the feed, ISO-8601.
- `api` (string) — Absolute URL of this resource.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `404` — Unknown feed id, or a position this feed does not have.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/feeds/fd_nytimes_com_1a2b3c4d5e6f7a8b/items/0
```

## MCP indexes

### `GET /api/indices`

The MCP indexes this catalog reads: credit, license, what each measures, counts and the last round.

Each index measures something different — one completes an MCP handshake, another reads the last commit, another only discovers that a resource exists — so `mede` comes with every source and every signal. Collected once a day on our own host, raw data kept, and credited on every response: the data is theirs. `coleta.falhou` says the last round failed; the error text stays private.

- **URL:** `https://staging.agentalog.com/api/indices`
- **Auth:** `none` — Public, no credential.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `ListaDeIndices`.

- `ok` (bool) — Always `true`.
- `indices` (Indice[]) — One per index. → see `Indice` under **Structures**.
- `_links` (object) — `self` and the `sinais` template.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s https://staging.agentalog.com/api/indices
```

### `GET /api/indices/sinais`

What each MCP index says about one listing of this catalog.

A signal belongs to a listing only when it is the SAME object: the name in the official MCP registry, the exact remote endpoint URL or the GitHub `owner/repo`, in that order. A shared domain never matches — two servers on one host are different products. Up to 20 signals, one per index and record.

- **URL:** `https://staging.agentalog.com/api/indices/sinais`
- **Auth:** `none` — Public, no credential.

**Query**

- `listing` (string, required) — Listing id from `/api/listings`. e.g.: `mcp_com_stripe_mcp_b890f1d0`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `SinaisDoRegistro`.

- `ok` (bool) — Always `true`.
- `listing` (string) — The listing id asked for.
- `count` (int) — Signals returned.
- `sinais` (SinalDeIndice[]) — One per index and record, ordered by index. → see `SinalDeIndice` under **Structures**.
- `_links` (object) — `indices`.

**Errors**

- `400` — `listing` is missing.
- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s 'https://staging.agentalog.com/api/indices/sinais?listing=mcp_com_stripe_mcp_b890f1d0'
```

### `GET /api/indices/itens`

Browse the signals, including servers this catalog does not list yet.

Newest change first. `casou=0` is what the indexes know and the catalog does not — the list to look at before submitting a server. Filters are AND'd.

- **URL:** `https://staging.agentalog.com/api/indices/itens`
- **Auth:** `none` — Public, no credential.

**Query**

- `fonte` (string) — Only the signals of this index — `/api/indices` says what each one measures. Values: `wellknown`, `agent_tools`, `nerq`, `truespar`, `neuronto`, `paygent`, `hultra`.
- `estado` (string) — The state in this catalog's words. Values: `vivo`, `fora`, `parado`, `abandonado`, `apagado`, `desconhecido`.
- `casou` (string) — `1` only signals matched to a listing, `0` only unmatched. Values: `0`, `1`.
- `q` (string) — Substring of the name, the URL or the repository. e.g.: `postgres`.
- `limit` (int) — Signals per page, 1–50. Default: `20`.
- `offset` (int) — Offset, capped at 50000. Default: `0`.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `Idempotency-Key` (string) — Optional retry key, up to 80 ASCII characters; same read for five minutes.

**Response `200`**

Structure: `PaginaDeSinais`.

- `ok` (bool) — Always `true`.
- `total` (int) — Signals matching the filters.
- `count` (int) — Signals on this page.
- `items` (SinalDeIndice[]) — Newest change first. → see `SinalDeIndice` under **Structures**.
- `_links` (object) — `self` and `indices`.

**Errors**

- `401` — Invalid MAT pass.
- `402` — Free allowance or MAT credits exhausted; buy a package.
- `409` — Retry conflict or pending read.
- `413` — Basic read exceeds 1 MiB.
- `429` — Temporary reading capacity.
- `503` — Origin or payment verification temporarily unavailable.

**Example**

```sh
curl -s 'https://staging.agentalog.com/api/indices/itens?fonte=truespar&estado=fora&casou=1&limit=5'
```

## Publish

### `POST /api/listings`

Registers an MCP server, a skill or a plugin in the catalog. It comes in as `pending`.

A person reviews it by hand; poll `status_api` (`GET /api/listings/:id/status`, no credential) to learn the decision. Two doors to the same action. Human with a session: free, 1 per day, at most 3 in the queue. Agent (with or without a guest): **402 with `accepts[]`**, $0.10 — pay and repeat. For a skill, the `SKILL.md` URL is enough; the rest is checked. **Validates before charging:** a refused body (400) and an exhausted quota (429) come BEFORE the 402, so no payment settles for a listing already known not to get in. A valid body without payment keeps receiving the 402 with the price.

- **URL:** `https://staging.agentalog.com/api/listings`
- **Auth:** `session_ou_x402` — Two doors to the SAME action: a human with the account session (cookie; free, within the quota) or an agent paying x402 (`X-PAYMENT`). A guest token is neither required nor blocks the paid path.

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

- `kind` (string, required) — What is being registered. Values: `mcp`, `skill`, `plugin`, `okf`.
- `url` (string, required) — MCP endpoint, SKILL.md URL, the plugin's repository or the OKF bundle's `index.md`. For an OKF bundle on a domain you control, `POST /api/okf/ping` is free.
- `name` (string) — Display name; without it, taken from the source.
- `tagline` (string) — One line saying what it is for.
- `body` (string) — Long description, optional.
- `category` (string) — Category so the listing shows up under the right filter.

**Body example**

```json
{
  "kind": "mcp",
  "category": "tools",
  "name": "Name",
  "tagline": "One line",
  "url": "https://example.com/mcp"
}
```

**Response `200`**

- `ok` (bool) — Always `true` when the request went in.
- `id` (string) — ID of the created listing.
- `status` (string) — Always `pending`: everything goes through the queue before turning live.
- `status_api` (string) — Where to poll for the review, with no credential (`GET /api/listings/:id/status`).

**Errors**

- `400` — `kind` or `url` missing, invalid URL, URL that does not answer or refused field.
- `402` — Quota exceeded. The response carries `accepts[]` (x402, USDC on Base): pay and repeat the same call with `X-PAYMENT`.
- `429` — 1 per day, at most 3 pending — applies to both doors, and is checked before charging.
- `502` — The payment settled and the write failed. The body carries `transaction`: keep it and talk to support.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/listings -H "X-PAYMENT: $PAYMENT" -H 'content-type: application/json' -d '{"kind":"mcp","url":"https://example.com/mcp","name":"My MCP"}'
```

### `PATCH /api/listings/:id`

Edits a listing of yours. Changing the URL sends it back to the queue.

The URL is what moderation looks at; swapping it after approval would bypass the queue, so the listing goes back to `pending`.

- **URL:** `https://staging.agentalog.com/api/listings/:id`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**Path parameters**

- `id` (string, required) — ID of the listing to edit.

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

- `name` (string) — New display name.
- `tagline` (string) — New summary line.
- `body` (string) — New long description.
- `category` (string) — New category.
- `url` (string) — New URL — changing this sends the listing back to `pending`.

**Body example**

```json
{
  "tagline": "…"
}
```

**Response `200`**

- `ok` (bool) — Always `true`.
- `id` (string) — ID of the edited listing.
- `status` (string) — State after the edit; back to `pending` if the URL changed.

**Errors**

- `400` — Invalid field in the body.
- `401` — No credential, or an invalid one. See this endpoint's auth.
- `404` — The listing is not yours or does not exist.

**Example**

```js
(async () => {
  const {csrf} = await fetch("https://staging.agentalog.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.agentalog.com/api/listings/ID", {method: "PATCH", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({tagline: "now with SSE support"})});
  return r.json();
})();
```

### `GET /api/me/listings`

The owner's listings in any state, including pending and hidden.

It is the only route that shows what is not live yet — the public mosaic never does.

- **URL:** `https://staging.agentalog.com/api/me/listings`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**Response `200`**

- `items` (Anuncio[]) — The account's listings, in any state. → see `Anuncio` under **Structures**.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.

**Example**

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

### `GET /api/listings/:id/status`

Moderation state of a listing — how the submitter polls for approval, with no credential.

Every submission is born `pending` and a person approves it by hand; this is the receipt you poll after `POST /api/listings` (its response carries this URL as `status_api`). Only the decision comes back, never the unreviewed content: the id (`lst_…`, unguessable) is all it takes, and the page itself keeps its rule — owner only until it is public. Answers are cached for 60 s per point of presence: poll every few minutes, not every second.

- **URL:** `https://staging.agentalog.com/api/listings/:id/status`
- **Auth:** `none` — Public, no credential.

**Path parameters**

- `id` (string, required) — Listing ID, from the `id` of the `POST /api/listings` response.

**Response `200`**

- `id` (string) — Listing ID.
- `status` (string) — Moderation state. `pending` is waiting; `live` and `low` are approved; `hidden` and `blocked` are not published.
- `public` (bool) — `true` when the listing is reachable in the catalog (`live` or `low`).
- `message` (string) — What the state means and what to do next.
- `reason` (string, optional) — Why it was hidden or blocked, when the moderator left a reason. Absent otherwise.
- `api` (string) — The listing's page (`GET /api/listings/:id`): the owner reads it with the token that created it; everybody else once it is public.
- `status_api` (string) — This URL, to poll again.

**Errors**

- `404` — No listing with this id.

**Example**

```sh
curl -s https://staging.agentalog.com/api/listings/ID/status
```

### `POST /api/okf/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. The same queue is served by `POST https://okfindex.com/api/ping`, the index's own home — search, bundle cards and statistics live there.

- **URL:** `https://staging.agentalog.com/api/okf/ping`
- **Auth:** `none` — Public, no credential.

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

- `host` (string, required) — The host that owns the bundles.
- `key` (string, required) — 8 to 128 characters of [a-zA-Z0-9-].
- `keyLocation` (string) — Where the key file lives. Defaults to `https://<host>/<key>.txt`; must be on `host`.
- `urlList` (string[], required) — Bundle `index.md` URLs. https, on `host`, ending in .md. No fixed path: the spec defines no discovery convention.

**Body example**

```json
{
  "host": "example.com",
  "key": "a1b2c3d4e5f60718",
  "urlList": [
    "https://example.com/okf/index.md"
  ]
}
```

**Response `202`**

- `ok` (bool) — The submission was queued.
- `estado` (string) — Always `pendente`: the key has not been checked yet.
- `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.

**Errors**

- `400` — Malformed body, `host`/`key` invalid or `urlList` missing.
- `422` — A URL is not https, is not .md, or does not belong to `host` — `keyLocation` on another host too.
- `429` — This host reached 200 bundles for the UTC day.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/okf/ping -H 'content-type: application/json' -d '{"host":"example.com","key":"a1b2c3d4e5f60718","urlList":["https://example.com/okf/index.md"]}'
```

## Account

### `GET /api/me`

The session's account and, for the admin, the load state.

The account is the global account; `user.id` is its id — the same id that owns the listings, likes and comments made with it, and the guest's after the claim.

- **URL:** `https://staging.agentalog.com/api/me`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**Response `200`**

- `user` (Conta) — The person who owns the session. → see `Conta` under **Structures**.
- `profile` (object) — Global profile: `name`, `locale`, `timeZone`, `theme`, `revision`.
- `admin` (bool) — Whether this account is the `ADMIN_EMAIL`.
- `carga` (Carga, optional) — State of the load sources; admin only. → see `Carga` under **Structures**.

**Errors**

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

**Example**

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

### `GET /api/me/ui`

The owner's screen preferences: search, filter, sort and theme.

Exists so what the person set up survives an F5 and reopening the app on another device. A refresh is not a new screen — see AGENTS-UI.md. A guest has none: without an account there is nobody to give the data back to later, so the guest stays in the browser's `localStorage` only.

- **URL:** `https://staging.agentalog.com/api/me/ui`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**Response `200`**

Structure: `PreferenciasUi`.

- `prefs` (object) — The stored preferences, as the interface wrote them. `{}` when nothing was ever stored.
- `api` (string) — Absolute URL of this route.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.

**Example**

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

### `PUT /api/me/ui`

Stores the owner's screen preferences, replacing the previous ones.

It is PUT and not PATCH on purpose: the client sends the whole screen state, not a delta. Cap of 8 KB — this is a screen preference, not a blob store.

- **URL:** `https://staging.agentalog.com/api/me/ui`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

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

- `prefs` (object, required) — The interface state to keep. Opaque to the server: any JSON within the cap works.

**Body example**

```json
{
  "prefs": {
    "q": "postgres",
    "kind": "mcp",
    "sort": "likes",
    "tema": "escuro"
  }
}
```

**Response `200`**

Structure: `Ok`.

- `ok` (bool) — Always `true` — failure comes as a 4xx/5xx status, not as `ok:false`.

**Errors**

- `400` — Body that is not JSON (`bad_json`) or without the `prefs` key (`prefs`).
- `401` — No credential, or an invalid one. See this endpoint's auth.
- `405` — Method other than GET or PUT on this route.
- `413` — Preferences above the 8 KB cap (`grande`).

**Example**

```js
(async () => {
  const {csrf} = await fetch("https://staging.agentalog.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.agentalog.com/api/me/ui", {method: "PUT", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({prefs: {sort: "likes"}})});
  return r.json();
})();
```

### `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.agentalog.com/api/auth/bootstrap`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/account/profile`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**Response `200`**

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

**Errors**

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

**Example**

```js
await fetch("https://staging.agentalog.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.agentalog.com/api/account/avatar`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**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.agentalog.com/api/account/avatar", {credentials: "same-origin"}).then(r => {if (!r.ok) throw new Error("HTTP " + r.status); return r.blob();});
```

### `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.agentalog.com/api/auth/logout`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**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.agentalog.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.agentalog.com/api/account/keys`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**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.agentalog.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.agentalog.com/api/account/keys/create`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**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.agentalog.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.agentalog.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.agentalog.com/api/account/keys/revoke`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

**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.agentalog.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.agentalog.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();
})();
```

### `POST /api/auth/claim`

Moves what the guest created to the signed-in account: its listings, likes and comments.

Bootstrap/CSRF of this browser required; the page does it right after sign-in. Only what the guest still owns moves, in one transaction, and anything that collides with what the account already has stays with the guest. What the guest bought moves too. An old unsigned token that owns nothing here is refused. Repeating it is harmless (moves zero).

- **URL:** `https://staging.agentalog.com/api/auth/claim`
- **Auth:** `session` — Global account: the HttpOnly session cookie of this domain, set when you sign in at `/conta/global`. Writes need the same Origin and `X-CSRF-Token` from `/api/auth/bootstrap`. A write with the cookie of an ended session answers 401 `session_ended` — sign in again; it never turns into the guest. No bearer token is issued to humans.

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

- `guest_token` (string) — Guest `mr_…`; omitted, the `guest` cookie of this browser.

**Body example**

```json
{}
```

**Response `200`**

- `ok` (bool) — Whether the guest was recognized and moved.
- `claimed` (object) — `product.movidos` (rows moved, per table), `product.apagados` (guest duplicates dropped) and `product.direitos` (purchases moved).

**Errors**

- `400` — invalid_product_claim / invalid_body
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `409` — unknown_guest (em `claimed.reason` / in `claimed.reason`)
- `503` — product_claim_pending / auth_unavailable

**Example**

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

## Billing

### `GET /api/billing`

x402 configuration in force and the agent prices for contact and publishing.

- **URL:** `https://staging.agentalog.com/api/billing`
- **Auth:** `none` — Public, no credential.

**Response `200`**

Structure: `Billing`.

- `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).
- `product` (string) — Name of the product charging.
- `prices` (Precos) — What each paid action costs, in USD. → see `Precos` under **Structures**.

**Example**

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

### `POST /api/contact`

Talks to support: a human solves Turnstile, an agent pays $0.10 in x402.

The first agent message is free; after that the backoff is 60s doubling up to a 1-hour cap, announced in `Retry-After`.

- **URL:** `https://staging.agentalog.com/api/contact`
- **Auth:** `none` — Public, no credential.

**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": "…",
  "email": "a@example.com",
  "message": "…"
}
```

**Response `200`**

Structure: `Ok`.

- `ok` (bool) — Always `true` — failure comes as a 4xx/5xx status, not as `ok:false`.

**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`.

**Example**

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

### `POST /api/visit`

Ping from the interface that increments the day's visits. Agents need not call it.

Smoke does not count: `X-MM-Smoke`, User-Agent `mm-smoke` or `smoke: true` in the body come in as `counted: false`.

- **URL:** `https://staging.agentalog.com/api/visit`
- **Auth:** `none` — Public, no credential.

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

- `p` (string) — Path of the visited page.
- `smoke` (bool) — `true` marks the call as a test and it does not enter the count.

**Body example**

```json
{
  "p": "/"
}
```

**Response `200`**

- `ok` (bool) — Always `true`.
- `counted` (bool) — Whether the visit entered the day's count.
- `reason` (string, optional) — Why it did not count, when `counted` is `false`.

**Example**

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

### `GET /api/metrics`

Metrics of the last 7 days. With the operator token, includes payments.

Without credentials it returns visits, usage and accounts. With `METRICS_TOKEN` as Bearer it adds `payments` — and only on Base mainnet, because staging numbers on a finance panel mislead.

- **URL:** `https://staging.agentalog.com/api/metrics`
- **Auth:** `none` — Public, no credential.

**Headers**

- `Authorization` (string) — `Bearer <METRICS_TOKEN>` to include the finance block.

**Response `200`**

Structure: `Metricas`.

- `app` (string) — Product name.
- `today` (string) — Reference day (UTC, YYYY-MM-DD).
- `today_visits` (int) — Visits counted today.
- `today_contacts` (int, optional) — Contact messages received today. Only with `METRICS_TOKEN`: contact does not leave without a token.
- `days` (object[]) — One record per day of the window, with the counts of each metric.
- `usage` (object) — Usage per product resource — here, listings created through the surface (origin community); the registry's own catalog load does not count as usage.
- `accounts` (object) — Total guests and accounts.
- `financeiro` (object, optional) — Aggregate of the day: `hoje_usd`, `hoje_count`, `rede`. Only with `METRICS_TOKEN`: money does not leave without a token; the full series is `payments`.
- `payments` (object, optional) — Finance summary; only with METRICS_TOKEN.

**Example**

```sh
curl -s https://staging.agentalog.com/api/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

## Operations

### `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.agentalog.com/api/erro-cliente`
- **Auth:** `none` — Public, no credential.

**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.agentalog.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.agentalog.com/api/pagamento/aberto`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/vitrine`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/vitrine
```

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

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

- **URL:** `https://staging.agentalog.com/api/vitrine/operador`
- **Auth:** `none` — Public, no credential.

**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.agentalog.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.agentalog.com/api/vitrine/painel`
- **Auth:** `none` — Public, no credential.

**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.agentalog.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.agentalog.com/api/vitrine/cursores`
- **Auth:** `none` — Public, no credential.

**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.agentalog.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.agentalog.com/api/partners`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/partners
```

## 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.agentalog.com/api/bundles`
- **Auth:** `none` — Public, no credential.

**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.agentalog.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.agentalog.com/api/bundles/:id`
- **Auth:** `none` — Public, no credential.

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

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

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

- **URL:** `https://staging.agentalog.com/api/okf/stats`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/okf/stats
```

## Operation

### `POST /api/admin/volatil`

Publishes one group of updated counters.

CARGA_TOKEN only. One slice = 1/256 of the ids (by hash), whole; submit only slices whose content changed. Nothing here touches the catalog database — that is the point.

- **URL:** `https://staging.agentalog.com/api/admin/volatil`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `fatia` (string, required) — Two hex digits; every id in `itens` must hash to it.
- `gerado_em` (string, required) — UTC instant the slice was built.
- `itens` (object, required) — `{id: record}`, at most 5000 ids and 1 MB.

**Body example**

```json
{
  "fatia": "0a",
  "gerado_em": "2026-09-08 12:00:00",
  "itens": {
    "skl_a": {
      "downloads": 138,
      "version": "1.1"
    }
  }
}
```

**Response `200`**

- `ok` (bool) — Stored.
- `fatia` (string) — The slice stored.
- `itens` (int) — Records in it.

**Errors**

- `400` — Malformed slice, id outside the slice, or above the ceilings.
- `401` — CARGA_TOKEN required.
- `503` — Object storage not configured.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/volatil -H "Authorization: Bearer $CARGA_TOKEN" -d @fatia.json
```

### `POST /api/admin/sitemap`

Receives one shard of the listings sitemap (or its manifest) for publication.

CARGA_TOKEN only. Submit catalog shards (up to 50,000 listings each, ordered by id) and sends only the shard whose content changed, then the manifest (how many shards, when). The Worker serves `/sitemap-listings.xml` (index) and `/sitemap-listings-N.xml` (shard) from that storage, with cache at the edge; the catalog database is never read for it.

- **URL:** `https://staging.agentalog.com/api/admin/sitemap`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `parte` (int) — Shard number, 1-based (at most 200). Omit when sending the manifest.
- `gerado_em` (string) — UTC instant the shard was built.
- `urls` (object[]) — `{id, lastmod?}` per listing, at most 50,000; `lastmod` is the listing's `updated_at`.
- `manifesto` (object) — `{partes, gerado_em}` — sent once after the shards; replaces the previous manifest.

**Body example**

```json
{
  "parte": 1,
  "gerado_em": "2026-09-13 12:00:00",
  "urls": [
    {
      "id": "mcp_x",
      "lastmod": "2026-09-10 08:00:00"
    }
  ]
}
```

**Response `200`**

- `ok` (bool) — Stored.
- `parte` (int, optional) — The shard stored (absent for the manifest).
- `urls` (int, optional) — Listings in it (absent for the manifest).
- `manifesto` (object, optional) — The manifest stored (absent for a shard).

**Errors**

- `400` — Malformed shard or manifest, invalid id, or above the ceilings.
- `401` — CARGA_TOKEN required.
- `503` — Object storage not configured.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/sitemap -H "Authorization: Bearer $CARGA_TOKEN" -d @parte-1.json
```

### `GET /api/fila`

The public snapshot of the enrichment queue: how much of the catalog has been checked.

It is public because it is about the catalog's health, not about anyone: aggregate numbers only, no identifiable listing.

- **URL:** `https://staging.agentalog.com/api/fila`
- **Auth:** `none` — Public, no credential.

**Response `200`**

Structure: `EstadoFila`.

- `ok` (bool) — Always `true` when there is a snapshot.
- `fila` (RetratoFila) — The queue's numbers. → see `RetratoFila` under **Structures**.

**Example**

```sh
curl -s https://staging.agentalog.com/api/fila
```

### `POST /api/admin/fila`

The enrichment robot pushes the snapshot of its own queue here.

Robot credential only: this does not write to the catalog, so there is no reason to accept admin.

- **URL:** `https://staging.agentalog.com/api/admin/fila`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `fila` (object, required) — The queue snapshot: totals, states and reasons.

**Body example**

```json
{
  "fila": {
    "total": 20182,
    "concluidos": 11675
  }
}
```

**Response `200`**

Structure: `Ok`.

- `ok` (bool) — Always `true` — failure comes as a 4xx/5xx status, not as `ok:false`.

**Errors**

- `400` — Body without `fila`.
- `401` — No credential, or an invalid one. See this endpoint's auth.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/fila -H "Authorization: Bearer $TOKEN_ROBO" -H 'content-type: application/json' -d '{"fila":{}}'
```

### `POST /api/admin/repos`

The enricher writes here what it found out about a repository: stars, forks, state.

Accepts the enricher's credential OR the admin's — the robot has its own, with less privilege, and the admin gets in to operate by hand without depending on the robot. The Worker collects nothing: it only stores what was already checked outside it.

- **URL:** `https://staging.agentalog.com/api/admin/repos`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `itens` (object[], required) — Up to 500 checked repositories with repo_slug, stars, forks, PRs, pushed_at and state. Optional listing_ids is an array of up to 50 listing IDs (1–160 letters, digits, underscore or hyphen); only matching listings of that repository are updated. An empty array stores only the repository fact. Omit it only for legacy fanout, still subject to the daily budget.

**Body example**

```json
{
  "itens": [
    {
      "repo_slug": "x/y",
      "stars": 120,
      "repo_estado": "ativo"
    }
  ]
}
```

**Response `200`**

Structure: `Ok`.

- `ok` (bool) — Always `true` — failure comes as a 4xx/5xx status, not as `ok:false`.

**Errors**

- `400` — Body without `itens` or malformed item.
- `401` — Neither the enricher's nor the admin's credential.
- `429` — Daily publication budget exhausted; retain pending facts.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/repos -H "Authorization: Bearer $TOKEN_ROBO" -H 'content-type: application/json' -d '{"itens":[]}'
```

### `GET /api/admin/listings`

The moderation queue. Without a filter, brings what is pending.

Accepts `ADMIN_TOKEN` as Bearer or the `ADMIN_EMAIL` session.

- **URL:** `https://staging.agentalog.com/api/admin/listings`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

**Query**

- `status` (string) — Which state to list. Default: `pending`. Values: `pending`, `live`, `hidden`, `blocked`.

**Response `200`**

- `items` (Anuncio[]) — The listings in that state. → see `Anuncio` under **Structures**.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.

**Example**

```sh
curl -s 'https://staging.agentalog.com/api/admin/listings?status=pending' -H "Authorization: Bearer $ADMIN_TOKEN"
```

### `POST /api/admin/listings/:id`

Decides the fate of a listing in the queue: approve, hide or block.

A submitter with an account gets one e-mail per decision (the decision, the reason and the page or the receipt); repeating the same state sends nothing. A guest or agent owner has no e-mail and polls `GET /api/listings/:id/status`.

- **URL:** `https://staging.agentalog.com/api/admin/listings/:id`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

**Path parameters**

- `id` (string, required) — ID of the listing to moderate.

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

- `action` (string, required) — What to do with the listing. Values: `approve`, `hide`, `block`.
- `reason` (string) — Why, for whoever submitted: it comes back in `GET /api/listings/:id/status`. Required for `block`, optional for `hide`, ignored for `approve` (which clears an earlier reason). Up to 300 characters.
- `fix` (object) — Corrections applied together with `approve`, any of `name`, `tagline`, `body`, `category`, with the same validation as a submission. `url` and `kind` are refused: a new URL is what sends a listing back to the queue.

**Body example**

```json
{
  "action": "hide",
  "reason": "The URL has answered 404 since yesterday."
}
```

**Response `200`**

- `ok` (bool) — Always `true`.
- `status` (string) — The state the listing ended up in.
- `reason` (string) — The reason stored with the decision; empty when none.

**Errors**

- `400` — `action` outside the list; `reason` missing on `block` or above 300 characters; `fix` outside `approve`; `fix_url` (URL or kind inside the fix); or the refused field of the fix (`name`, `tagline`, `category`, `golpe`).
- `401` — No credential, or an invalid one. See this endpoint's auth.
- `404` — The resource does not exist (or is not yours — the API does not tell the two apart on purpose).

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/listings/ID -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' -d '{"action":"approve"}'
```

### `GET /api/admin/carga`

State of the catalog's load sources: last batch, count and failures.

Accepts `ADMIN_TOKEN` as Bearer or the `ADMIN_EMAIL` session.

- **URL:** `https://staging.agentalog.com/api/admin/carga`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

**Query**

- `fonte` (string) — Restricts to one source, e.g. `official_mcp`.

**Response `200`**

Structure: `Carga`.

- `fontes` (object[]) — Each source with its last batch and the count it brought.
- `falhas` (object[]) — Import failures not yet marked as seen.
- `runs` (object[]) — The recent runs, newest first.
- `orcamento` (object) — Today's publication budget (UTC day): `total`, `catalogo` (the catalog slice) and `okf` (the OKF slice), each with `usados` (rows actually written, as D1 counts them: row, key and every index entry, reconciled after each batch), `reservado` (the estimate charged before writing; `reservado / usados` is how inflated the estimate is) and `teto`; `classes` (catalogo, okf, fatos, readmes, fts) with today's `itens`, `reservado`, `linhas` (rows the database actually wrote) and `media` (real rows per item over the last days, the number the estimate now uses; null without history); plus `dia`.

**Errors**

- `401` — No credential, or an invalid one. See this endpoint's auth.

**Example**

```sh
curl -s https://staging.agentalog.com/api/admin/carga -H "Authorization: Bearer $ADMIN_TOKEN"
```

### `POST /api/admin/carga`

Requests an update or marks a failure alert as seen.

run/reset enqueue a request for the next scheduled operation. They do not run synchronously.

- **URL:** `https://staging.agentalog.com/api/admin/carga`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `action` (string, required) — What to do with the source. Values: `run`, `visto`, `reset`.
- `fonte` (string) — Which source to load or mark, e.g. `official_mcp`.

**Body example**

```json
{
  "action": "run",
  "fonte": "official_mcp"
}
```

**Response `200`**

Structure: `Ok`.

- `ok` (bool) — Always `true` — failure comes as a 4xx/5xx status, not as `ok:false`.

**Errors**

- `400` — `action` outside the list or unknown source.
- `401` — No credential, or an invalid one. See this endpoint's auth.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/carga -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' -d '{"action":"run","fonte":"official_mcp"}'
```

### `GET /api/admin/okf/pendentes`

Reads the queue of OKF bundles submitted through `POST /api/okf/ping`.

CARGA_TOKEN only. Up to 50 submissions, oldest first. The edge never fetches a key file or a bundle: submissions require key verification before reading the submitter's host — otherwise a stranger could make us fetch arbitrary URLs.

- **URL:** `https://staging.agentalog.com/api/admin/okf/pendentes`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

**Response `200`**

- `pendentes` (object[]) — {bundle_url, host, chave, chave_url} still waiting for key verification.
- `lote` (int) — Batch ceiling; a full page may have more pending items.

**Errors**

- `401` — CARGA_TOKEN required.

**Example**

```sh
curl -s https://staging.agentalog.com/api/admin/okf/pendentes -H "Authorization: Bearer $CARGA_TOKEN"
```

### `POST /api/admin/okf/pendentes`

Records verification of submitted bundles.

CARGA_TOKEN only. Changes the QUEUE, never the catalog: an approved bundle reaches the mosaic through the normal catalog difference, because two doors writing listings would be two truths. A network failure is not a verdict — the submission stays pending and comes back next round.

- **URL:** `https://staging.agentalog.com/api/admin/okf/pendentes`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `resultados` (object[], required) — {bundle_url, estado: verificado|recusado, motivo}. At most 50; `motivo` is chave|bundle|okf_version.

**Body example**

```json
{
  "resultados": [
    {
      "bundle_url": "https://example.com/okf/index.md",
      "estado": "verificado"
    }
  ]
}
```

**Response `200`**

- `ok` (bool) — The batch was applied.
- `marcados` (int) — How many queue rows were touched.

**Errors**

- `400` — Missing `resultados`, more than 50, or an unknown state.
- `401` — CARGA_TOKEN required.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/okf/pendentes -H "Authorization: Bearer $CARGA_TOKEN" -H 'content-type: application/json' -d '{"resultados":[]}'
```

### `POST /api/admin/feeds`

Applies prepared feed-index differences for publication.

Requires CARGA_TOKEN. Maximum 100 items and 2 MB. A daily budget slice of its own stops publication with 429 (`alvo: "feeds"`) without holding the catalog back; unconfirmed items remain pending.

- **URL:** `https://staging.agentalog.com/api/admin/feeds`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `itens` (object[], required) — Each delta has id, novo, and either valores (changed columns only) or remove:true.
- `contagens` (object[]) — Optional `{ chave, n }` list with the count per facet value, computed on the collector.

**Body example**

```json
{
  "itens": []
}
```

**Response `200`**

- `ok` (bool) — The complete batch was accepted.
- `aceitos` (int) — Accepted items, including idempotent retries.
- `recusados` (int) — Zero on success; invalid batches fail in full.

**Errors**

- `400` — Invalid delta or facet count.
- `401` — CARGA_TOKEN required.
- `413` — More than 100 items or a body over 2 MB.
- `429` — Daily feed slice exhausted; retain pending items.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/feeds -H "Authorization: Bearer $CARGA_TOKEN" -d @lote.json
```

### `POST /api/admin/catalogo`

Applies prepared catalog differences for publication.

Requires CARGA_TOKEN. Imported sources only; no SQL, community records or user fields. Maximum 25 items and 2 MB. An atomic daily budget stops publication with 429; retain unconfirmed differences.

- **URL:** `https://staging.agentalog.com/api/admin/catalogo`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `itens` (object[], required) — Each delta has id, origin, origin_id, novo, valores (changed catalog columns only), optional prepared pacotes and owner for new rows.

**Body example**

```json
{
  "itens": []
}
```

**Response `200`**

- `ok` (bool) — The complete batch was accepted.
- `aceitos` (int) — Accepted items, including idempotent retries.
- `recusados` (int) — Zero on success; invalid batches fail in full.

**Errors**

- `400` — Invalid delta.
- `401` — CARGA_TOKEN required.
- `409` — Identity differs from destination.
- `413` — Batch or body too large.
- `429` — Daily publication budget exhausted; `alvo` names the slice that ran out (`catalogo` or `okf`, each with its own cap).

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/catalogo -H "Authorization: Bearer $CARGA_TOKEN" -H 'content-type: application/json' -d '{"itens":[]}'
```

### `POST /api/admin/readmes`

Stores documentation for listings without a repository.

Requires CARGA_TOKEN. The listing exposes the document with attribution. Unchanged text is not written again. Maximum 20 items and 2 MB.

- **URL:** `https://staging.agentalog.com/api/admin/readmes`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `itens` (object[], required) — {listing_id, fonte: npm|pypi, readme} — README of 1 to 200,000 characters; no repeated listing_id.

**Body example**

```json
{
  "itens": [
    {
      "listing_id": "mcp_x",
      "fonte": "npm",
      "readme": "# X"
    }
  ]
}
```

**Response `200`**

- `ok` (bool) — The batch was processed.
- `aceitos` (int) — READMEs stored (new or changed).
- `iguais` (int) — Unchanged READMEs: nothing written.
- `recusados` (string[]) — listing_ids unknown to the catalog; the rest of the batch is applied.

**Errors**

- `400` — Malformed item.
- `401` — CARGA_TOKEN required.
- `413` — More than 20 items or body over 2 MB.
- `429` — Daily publication budget exhausted; retain pending documents.
- `503` — R2 not configured: nothing indexed.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/readmes -H "Authorization: Bearer $CARGA_TOKEN" -H 'content-type: application/json' -d '{"itens":[]}'
```

### `POST /api/admin/fts`

Indexes one page of live listings into the full-text search index.

Requires CARGA_TOKEN. Pages by rowid: `apos` is the last rowid already indexed, `limite` the page size (≤ 500). Each page reserves 5 write units per listing in the daily catalog budget before writing; 429 means try tomorrow. An empty page marks the index ready (`fts:pronto`) and the search switches from LIKE to the index.

- **URL:** `https://staging.agentalog.com/api/admin/fts`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `apos` (int, required) — Last rowid already indexed; 0 to start.
- `limite` (int) — Page size, 1–500 (default 500).

**Body example**

```json
{
  "apos": 0,
  "limite": 500
}
```

**Response `200`**

- `ok` (bool) — The page was processed.
- `indexados` (int) — Listings written to the index in this page.
- `ultimo` (int) — Last rowid indexed — send it back as `apos`.
- `pronto` (bool) — `true` when there was nothing left: the index covers the catalog.

**Errors**

- `400` — Invalid page.
- `401` — CARGA_TOKEN required.
- `429` — Daily catalog budget exhausted.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/fts -H "Authorization: Bearer $CARGA_TOKEN" -H 'content-type: application/json' -d '{"apos":0,"limite":500}'
```

### `GET /api/admin/carga/c3`

Reads pending operator commands and an indexed community delta.

CARGA_TOKEN only. Up to 100 community rows ordered by (updated_at,id), older than one minute. Imported catalog rows are never read. A full page advances to its last row; a short page advances to ate with empty apos.

- **URL:** `https://staging.agentalog.com/api/admin/carga/c3`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

**Query**

- `desde` (string, required) — UTC cursor, YYYY-MM-DD HH:mm:ss.
- `apos` (string) — ID after the last received row; empty for a new time boundary.

**Response `200`**

- `pedidos` (object[]) — Commands {fonte,id,acao}; restricted to the operation service.
- `comunidade` (object[]) — Changed {id,source,status,updated_at} records.
- `ate` (string) — Exclusive UTC upper bound of the feed.

**Errors**

- `400` — Invalid cursor.
- `401` — CARGA_TOKEN required.

**Example**

```sh
curl -sG https://staging.agentalog.com/api/admin/carga/c3 --data-urlencode "desde=2026-09-06 00:00:00" -H "Authorization: Bearer $CARGA_TOKEN"
```

### `POST /api/admin/carga/c3`

Publishes source status and acknowledges operator commands completed by the operation service.

CARGA_TOKEN only. Up to 12 statuses and acknowledgements. A retry with the same run ID does not rewrite status; an old acknowledgement cannot erase a newer command.

- **URL:** `https://staging.agentalog.com/api/admin/carga/c3`
- **Auth:** `token` — Operator token `ADMIN_TOKEN` or `METRICS_TOKEN` as Bearer. The load routes also accept the enricher's credential, which has less privilege — see each endpoint.

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

- `estados` (object[], required) — Source run summaries: fonte,id,status,cursor,updated_since,erro,pages,imported,skipped,more,started_at,finished_at.
- `aceites` (object[], required) — Completed command {fonte,id} pairs.

**Body example**

```json
{
  "estados": [],
  "aceites": []
}
```

**Response `200`**

- `ok` (bool) — Accepted.
- `estados` (int) — Accepted statuses.
- `aceites` (int) — Accepted command acknowledgements.

**Errors**

- `400` — Invalid status or acknowledgement.
- `401` — CARGA_TOKEN required.
- `429` — Daily budget exhausted.

**Example**

```sh
curl -s -XPOST https://staging.agentalog.com/api/admin/carga/c3 -H "Authorization: Bearer $CARGA_TOKEN" -H 'content-type: application/json' -d '{"estados":[],"aceites":[]}'
```

## 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.agentalog.com/api/credito`
- **Auth:** `none` — Public, no credential.

**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.agentalog.com/api/credito?usd=10'
```

### `GET /api/credito`

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

- **URL:** `https://staging.agentalog.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.agentalog.com/api/credito -H 'Authorization: Bearer cred_…'
```

## API access

### `GET /api/acesso`

Discover the monthly data package or inspect a private purchase.

Catalog discovery and ordinary browsing are free. GPTBot, ClaudeBot, CCBot, Meta-ExternalAgent, Amazonbot, AhrefsBot and MJ12bot share a daily allowance of 1,000 reads per crawler family. Further reads require a MAT package: US$1 for 1,000 reads, valid for 30 days, without automatic renewal. Send X-API-Pass on reads. The MAT balance is separate from the company, address and procurement indexes.

- **URL:** `https://staging.agentalog.com/api/acesso`
- **Auth:** `none` — Public, no credential.

**Headers**

- `X-API-Pass` (string) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.

**Response `200`**

Structure: `ApiAccess`.

- `offer` (ApiAccessOffer) — Current offer and payment instructions. → see `ApiAccessOffer` under **Structures**.
- `enabled` (bool, optional) — Present in public discovery; false means no purchases.
- `id` (string, optional) — Purchase ID; not a credential.
- `status` (string, optional) — paid, unpaid or pending.
- `granted_credits` (int, optional) — Original grant, not remaining usage.
- `expires_at` (string, optional, may be null) — ISO expiry, 30 days after purchase.
- `receipt` (string, optional, may be null) — Confirmed payment receipt.
- `via` (string, optional, may be null) — x402, credito or gated homolog.
- `message` (string, optional) — Next action in the requested language.

**Errors**

- `400` — Invalid pass.
- `404` — Unknown purchase or wrong owner.
- `503` — Purchases disabled.

**Example**

```sh
curl -s https://staging.agentalog.com/api/acesso
```

### `POST /api/acesso`

Buy 1000 basic data reads for US$1, valid for 30 days.

Catalog discovery and ordinary browsing are free. GPTBot, ClaudeBot, CCBot, Meta-ExternalAgent, Amazonbot, AhrefsBot and MJ12bot share a daily allowance of 1,000 reads per crawler family. Further reads require a MAT package: US$1 for 1,000 reads, valid for 30 days, without automatic renewal. Send X-API-Pass on reads. The MAT balance is separate from the company, address and procurement indexes.

- **URL:** `https://staging.agentalog.com/api/acesso`
- **Auth:** `none` — Public, no credential.

**Headers**

- `X-API-Pass` (string, required) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.
- `X-Credito` (string) — Existing prepaid credit token; alternative to x402.
- `Authorization` (string) — Bearer cred_… alternative to X-Credito.
- `X-PAYMENT` (string) — Signed x402 authorization from the 402 quote, maximum 16 KiB.
- `PAYMENT-SIGNATURE` (string) — Alternative name for X-PAYMENT.
- `X-API-Transaction` (string) — Confirmed Base transaction hash for reconciliation with the original pass and signed payment. Never creates another charge.

**Response `200`**

Structure: `ApiAccess`.

- `offer` (ApiAccessOffer) — Current offer and payment instructions. → see `ApiAccessOffer` under **Structures**.
- `enabled` (bool, optional) — Present in public discovery; false means no purchases.
- `id` (string, optional) — Purchase ID; not a credential.
- `status` (string, optional) — paid, unpaid or pending.
- `granted_credits` (int, optional) — Original grant, not remaining usage.
- `expires_at` (string, optional, may be null) — ISO expiry, 30 days after purchase.
- `receipt` (string, optional, may be null) — Confirmed payment receipt.
- `via` (string, optional, may be null) — x402, credito or gated homolog.
- `message` (string, optional) — Next action in the requested language.

**Errors**

- `400` — Missing or invalid pass/payment.
- `401` — Invalid prepaid credit.
- `402` — Payment required: x402 accepts[] and prepaid-credit instructions.
- `409` — Payment pending; retain the same pass and do not pay again.
- `429` — Purchase attempt limit; respect Retry-After.
- `503` — Payment unavailable or pending reconciliation.

**Example**

```sh
curl -s -X POST "https://staging.agentalog.com/api/acesso" -H "X-API-Pass: $API_PASS"
```

### `GET /api/uso`

Read the remaining MAT balance without consuming credit.

- **URL:** `https://staging.agentalog.com/api/uso`
- **Auth:** `none` — Public, no credential.

**Headers**

- `X-API-Pass` (string, required) — MAT-only private pass: mat_<32 random hex>_<64 random hex>. Generate and save before buying.

**Response `200`**

Structure: `MatUsage`.

- `id` (string) — Package ID.
- `credits` (int) — Original 1,000-read grant.
- `used` (int) — Reads consumed.
- `remaining` (int) — Reads remaining.
- `expires_at` (string) — ISO expiry.
- `active` (bool) — Has credit and has not expired.

**Errors**

- `401` — Missing or invalid pass.
- `402` — Purchase pending or expired.
- `503` — Origin unavailable.

**Example**

```sh
curl -s "https://staging.agentalog.com/api/uso" -H "X-API-Pass: $API_PASS"
```

## Structures

### `PaginaDeAnuncios`

A page of the public mosaic. No `total`: the catalog has tens of thousands of listings and counting everything on each search would be expensive without changing any decision.

- `items` (Anuncio[]) — The listings on this page. → see `Anuncio` 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.
- `next_cursor` (string, may be null) — Opaque cursor of the next page for the orders without a text query (`recent`, `stars`, `nome`): pass it back as `cursor`. Each page then reads only its own rows, whatever the depth. `null` when there is no more, or when the order is ranked by `q`, likes or visits (offset applies there).
- `next` (string, may be null) — Absolute URL of the next page, same filters — follow it until it comes back `null` to walk the whole catalog without rebuilding the querystring.
- `low_count` (int) — With `low=0` and `q`: `low` listings left out (cap 200).
- `low_capped` (bool) — `true` when the count hit the cap — there are at least that many.
- `low_included` (bool) — `true` unless `low=0`: the `low` tail comes after `live`.
- `interpretacao` (object, may be null) — Filters deduced from `q` (`kind`, `topico`, `transporte`, `origin`, residual `q`). `null` when understanding is off or there is no query.
- `api` (string) — Absolute URL of this listing.

### `Facetas`

The whole catalog's breakdowns, to build a filter without sweeping the listings.

- `total` (int) — Live listings in the catalog.
- `facetas` (object) — Map of facet → list of `{ v, n }` (value and count): `kind`, `origin`, `category`, `repo_estado`, `transporte`…
- `topico_inferido` (object) — Topics deduced from the repositories, with the count of each.
- `interpretacao` (object, may be null) — Same query understanding as `/api/listings`, so the counts match the list.
- `publicador` (object, optional, may be null) — `{ ns, n, stars }` when the slice has exactly one `ns` — the publisher's live listings and their stars summed, regardless of the other filters (the publisher page header); `null` otherwise. Responses cached before 13/09/2026 may not carry the key yet.
- `api` (string) — Absolute URL of this route.

### `PaginaV01`

The subregistry page, cursor-paginated as the v0.1 spec requires.

- `servers` (ServidorV01[]) — The servers on this page. → see `ServidorV01` under **Structures**.
- `metadata` (object) — `next_cursor` and `count`, in the spec's format.

### `Anuncio`

A catalog listing: MCP server, Agent Skill or Claude Code plugin.

- `id` (string) — Listing ID; it is the key across the whole API.
- `kind` (string) — What this listing is.
- `category` (string, may be null) — Category chosen by whoever published.
- `name` (string) — Display name.
- `tagline` (string, may be null) — One line saying what it is for.
- `body` (string, may be null) — Long description, when whoever published wrote one.
- `url` (string) — Where the resource lives — the MCP endpoint, the SKILL.md or the repository.
- `status` (string) — State in the catalog.
- `origin` (string) — Where the listing came from: `official`, `marketplace`, `directory` or a community submission.
- `origin_id` (string, may be null) — Identifier of the listing at the source.
- `install` (string, may be null) — How to install, when the source says.
- `source` (string, may be null) — Source code URL, when known.
- `transporte` (string, may be null) — MCP transport: `stdio`, `http`, `sse`.
- `ns` (string, may be null) — Server namespace in the official registry.
- `versao` (string, may be null) — Version declared by the source.
- `oficial_status` (string, may be null) — State in the official MCP registry, when applicable.
- `repo_host` (string, may be null) — Where the repository is hosted, e.g. `github`.
- `topico` (string, may be null) — Inferred topic used in search filters, not a publisher declaration. When available, `payload.topico_llm` carries the supporting quote and confidence.
- `linguagem` (string, may be null) — Primary language of the repository, when collected.
- `licenca` (string, may be null) — SPDX license of the repository, when collected.
- `repo_topics` (string, may be null) — Repository topics, separated by spaces.
- `repo_slug` (string, may be null) — owner/name of the repository, when known.
- `stars` (int, may be null) — Repository stars at the last check.
- `forks` (int, may be null) — Repository forks at the last check.
- `prs_abertos` (int, may be null) — Open pull requests at the last check.
- `pushed_at` (string, may be null) — Last push to the repository (UTC).
- `repo_estado` (string, may be null) — How the repository is doing (active, stalled, archived, renamed, gone).
- `likes` (int) — How many people liked it — the like is reversible and counts people.
- `comments` (int) — Public comments on the listing.
- `visits` (int) — Visits counted by the hop; at most 1 per owner per day.
- `created_at` (string) — When it entered the catalog (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `mine` (bool) — `true` when the listing is yours — only then can you edit it.
- `api` (string) — Absolute URL of this listing's page.
- `go` (string) — Hop URL: redirects to `url` and counts the visit.
- `comments_api` (string) — Absolute URL of this listing's comments.
- `readme_api` (string, optional) — Absolute URL of the collected README (`GET`). On list rows and on the listing page, and only when a README was stored: absent means none was collected — do not build the path yourself.
- `historico` (object[], optional) — Listing page only: the repository's last events, as in `/api/listings/:id/history`; absent when there is none yet.
- `readme_fonte` (string, optional) — Where the README came from: `repo` (the GitHub repository's README) or `npm` / `pypi` (the package registry's README, used when the listing has no repository). Present together with `readme_api`.
- `readme_bytes` (int) — Size of the collected README in bytes, on list rows and on the listing page; 0 when none was collected.
- `readme_sha` (string, may be null) — SHA-256 of the collected README. Listing page only.
- `readme_em` (string, may be null) — When the README was stored (UTC). Listing page only.
- `payload` (object, may be null) — Install payload mirrored from the source. Listing page only. When the topic came from the model, `topico_llm` holds `{topico, confianca, trecho, v}`: the label, the confidence (0–1), the literal quote that justified it and the rule version.

### `Readme`

The available README for the listing, with its attribution and reference date. Reading does not refresh it.

- `markdown` (string) — README text, UTF-8. May be truncated at 200 kB.
- `bytes` (int) — Size as stored.
- `sha` (string) — SHA-256 of the stored object.
- `repo_slug` (string) — owner/name of the repository; empty when the listing has none.
- `fonte` (string) — `repo`, `npm` or `pypi` — the same value as `readme_fonte` on the listing page.
- `truncated` (bool) — `true` when the body was cut at the cap.
- `api` (string) — Absolute URL of this resource.

### `Comentario`

A public comment on a listing.

- `id` (string) — Comment ID, for deleting.
- `body` (string) — The comment text.
- `author` (string, may be null) — Nickname of whoever wrote it.
- `created_at` (string) — When it was written (UTC).
- `mine` (bool) — `true` if it is yours — only you can delete it.

### `Like`

The state of the like after the call. Turning it on and off return the same shape.

- `ok` (bool) — Always `true`.
- `liked` (bool) — Whether YOU are liking it now.
- `likes` (int) — Total people liking the listing.

### `PaginaDeFeeds`

A page of the feed index. No `total`: the total per filter value lives in `/api/feeds/facets`, already counted.

- `items` (Feed[]) — The records on this page. → see `Feed` under **Structures**.
- `limit` (int) — Page size applied.
- `offset` (int) — Offset applied.
- `next_cursor` (string, may be null) — Opaque cursor of the next page for the orders without a text query. `null` when there is no more.
- `next_offset` (int, may be null) — Offset of the next page when the order is by relevance.
- `next` (string, may be null) — Absolute URL of the next page, same filters.
- `sort` (string) — Order actually applied.
- `api` (string) — Absolute URL of this collection.

### `FacetasDeFeeds`

How many records exist in each filter value, pre-computed on the collector.

- `total` (int) — Records in the index.
- `facetas` (object) — One key per filter (`origem`, `tipo`, `midia`, `comunidade`, `recurso`, `lista`, `ano`), each a list of `{ v, n }`.
- `api` (string) — Absolute URL of this resource.

### `Feed`

A record in the feed index: an RSS/Atom/JSON feed, an OPML reading list, or a site that only becomes a feed through a bridge.

- `id` (string) — Feed id, prefix `fd_`; it is the key across this collection.
- `kind` (string) — What this record is.
- `dominio` (string) — Domain that publishes it, lowercase and without `www.`.
- `url` (string) — The feed address — or the site's, for a record of kind `bridge`.
- `nome` (string) — Feed title as the source published it.
- `descricao` (string) — Feed description; for a reading list, whoever curates it.
- `tipo` (string) — Feed format.
- `audio` (bool) — `true` when the feed carries audio enclosures — a podcast.
- `video` (bool) — `true` when the feed carries video enclosures.
- `comunidade` (int) — Bitmask of the communities the publisher belongs to; 0 when none is known.
- `comunidades` (string[]) — The same communities by name (`wordpress`, `indieweb`, `fediverse`, `mastodon`, `friendica`, `funkwhale`, `blogroll`), so nobody has to decode the bitmask.
- `ano` (int) — Year of the newest item the source saw in this feed; 0 when it published no usable date. It is a freshness hint from discovery, not a live check.
- `recursos` (string[]) — Namespaces seen in the feed, `content` first when the whole post travels in it.
- `densidade` (int) — The source's own text score for the feed (`t`): how much item text discovery found. Bigger means more text travels in the feed — the scale is the source's, and the value is frozen at discovery, not a live metric.
- `itens` (int) — How many feeds an OPML list had when it was read; 0 for a feed.
- `saude` (string) — What OUR own check saw: `ok` answered with an actual feed (an RSS/Atom/RDF root, a JSON Feed, or OPML for a list); `sumiu` returned 404/410 or its domain no longer resolves; `erro` any other failure. A failure only changes this after a second check hours later agrees, and a server that blocks robots (401/403, bot challenge) never turns into `erro`. Empty means not checked yet — which is not the same as failing.
- `pais` (string) — ISO-3166 alpha-2 of the IP that serves the host, resolved during that same check. Empty when it could not be resolved.
- `site_titulo` (string) — Link preview of the publisher's home page, as WhatsApp or X would read it: `og:title`, then `twitter:title`, JSON-LD and `<title>`. Every `site_*` field is empty when the site declares nothing, was not visited yet, disallows our robot in robots.txt, or is confirmed gone (parked, suspended, default server page).
- `site_descricao` (string) — Preview description: `og:description`, then `twitter:description`, JSON-LD and `<meta name=description>`.
- `site_nome` (string) — Site name the page declares (`og:site_name`, `application-name`).
- `site_og` (string) — The preview image URL as declared by the site (`og:image`, then `twitter:image`); https only.
- `site_og_alt` (string) — Alternative text the site declares for that image (`og:image:alt`).
- `site_cor` (string) — The site's `theme-color` as `#rrggbb`; empty when absent or not a plain color.
- `site_idioma` (string) — Language of the home page (`<html lang>`, then `og:locale`): two or three letters, plus the region when the site declares one (`pt-br`, `en-us`).
- `idioma_bandeira` (string) — ISO-3166 alpha-2 (lowercase) of the flag that stands for that language: the declared region, otherwise the language's reference country (`en` → `gb`, `pt` → `br`). Empty for languages without one.
- `icone` (string) — Absolute URL of the site icon served by us (the largest raster icon the home declares, up to 512 px; `/favicon.ico` otherwise), downloaded and checked on our index host. Empty when we have none stored.
- `imagem` (string) — Absolute URL of the preview image served by us, up to 600 KB, downloaded and checked on our index host (PNG, JPEG, GIF, WebP, AVIF, ICO or BMP by its bytes). Empty when the site declares none or we have none stored.
- `ultimo_post` (string) — ISO 8601 date of the newest post, read from the feed itself (RSS `pubDate`, Atom `published`/`updated`, RDF `dc:date`, JSON Feed `date_published`). Empty when not read yet, when the feed dates nothing, or for lists and bridges.
- `posts_24h` (int, may be null) — Posts published in the last 24 hours, counted at request time over the dates we read. `null` when the feed was not read yet — not the same as zero.
- `posts_7d` (int, may be null) — Posts in the last 7 days, same rules as `posts_24h`.
- `posts_30d` (int, may be null) — Posts in the last 30 days, same rules as `posts_24h`.
- `posts_dias` (int[], may be null) — Posts per day over the last 30 days, oldest first and today last (24-hour windows counted from the request time). `null` when the feed was not read yet.
- `posts_no_feed` (int, may be null) — Items the feed carried in what we read. `0` is an empty feed, which is not the same as a feed whose posts carry no date.
- `posts_parcial` (bool) — The feed is longer than what we read (10 MB), so the counts are minimums.
- `atividade_em` (string) — When we last read the feed's posts (ISO 8601). Active feeds are re-read daily.
- `pagina` (string) — Absolute URL of this record's HTML page.
- `api` (string) — Absolute URL of this resource.

### `PostsDeFeed`

The posts of one feed, as our queue read them — our copy, not the live feed.

- `id` (string) — Feed id these posts belong to.
- `itens` (PostDeFeed[]) — Up to 40 posts, in the order the feed publishes them (the archive keeps every post the feed carried). → see `PostDeFeed` under **Structures**.
- `lido_em` (string) — When we read the feed, ISO-8601; empty when it was never read.
- `api` (string) — Absolute URL of this resource.

### `PostDeFeedInteiro`

One post with its body, as `/api/feeds/{id}/items/{ord}` returns it.

- `id` (string) — Feed id this post belongs to.
- `ord` (int) — Position of the post in the feed when we read it; 0 is the newest.
- `titulo` (string) — Post title, plain text.
- `link` (string) — The post on the publisher's site, `http`/`https` only.
- `quando` (string) — Publication date in ISO-8601; empty when the item carried no usable date.
- `autor` (string) — Author as the feed named them, without the e-mail address.
- `resumo` (string) — First lines of the post, plain text.
- `conteudo_html` (string) — The post body as HTML that passed OUR allowlist when we read the feed: only the tags and attributes named in `origem/processa/html-seguro.mjs` survive, links are absolute and open in a new tab, images carry no referrer, and script, style, iframe and embedded media are gone with their content. It keeps the author's formatting — tables, figures with captions, nested lists — and the post's own `audio`/`video` (never autoplaying, nothing fetched before play). A video embed from a known host (YouTube, Vimeo, SoundCloud, Twitch, Dailymotion, Bandcamp, Bilibili, Spotify, Internet Archive) becomes a placeholder `div.mural-md-embed` carrying `data-embed`: the player is only created when the reader clicks it, so the host learns nothing until then.
- `conteudo` (string) — The same body in Markdown, up to half a million characters, cut at a paragraph — the shape an agent usually wants.
- `lido_em` (string) — When we read the feed, ISO-8601.
- `api` (string) — Absolute URL of this resource.

### `ListaDeIndices`

The indexes, their credit and their last round.

- `ok` (bool) — Always `true`.
- `indices` (Indice[]) — One per index. → see `Indice` under **Structures**.
- `_links` (object) — `self` and the `sinais` template.

### `SinaisDoRegistro`

The signals of one listing.

- `ok` (bool) — Always `true`.
- `listing` (string) — The listing id asked for.
- `count` (int) — Signals returned.
- `sinais` (SinalDeIndice[]) — One per index and record, ordered by index. → see `SinalDeIndice` under **Structures**.
- `_links` (object) — `indices`.

### `PaginaDeSinais`

A page of signals.

- `ok` (bool) — Always `true`.
- `total` (int) — Signals matching the filters.
- `count` (int) — Signals on this page.
- `items` (SinalDeIndice[]) — Newest change first. → see `SinalDeIndice` under **Structures**.
- `_links` (object) — `self` and `indices`.

### `Conta`

The person behind the session.

- `id` (string) — ID of the account.
- `email` (string) — E-mail confirmed by code.

### `Carga`

The state of the catalog's load sources — where the listings come from and when they came.

- `fontes` (object[]) — Each source with its last batch and the count it brought.
- `falhas` (object[]) — Import failures not yet marked as seen.
- `runs` (object[]) — The recent runs, newest first.
- `orcamento` (object) — Today's publication budget (UTC day): `total`, `catalogo` (the catalog slice) and `okf` (the OKF slice), each with `usados` (rows actually written, as D1 counts them: row, key and every index entry, reconciled after each batch), `reservado` (the estimate charged before writing; `reservado / usados` is how inflated the estimate is) and `teto`; `classes` (catalogo, okf, fatos, readmes, fts) with today's `itens`, `reservado`, `linhas` (rows the database actually wrote) and `media` (real rows per item over the last days, the number the estimate now uses; null without history); plus `dia`.

### `PreferenciasUi`

What the person set up on the screen and needs to survive an F5: filter selection, active tab and open item tabs. The content is OPAQUE — the server does not interpret the JSON, it only stores and returns it, so the screen can change fields without a database migration.

- `prefs` (object) — The stored preferences, as the interface wrote them. `{}` when nothing was ever stored.
- `api` (string) — Absolute URL of this route.

### `Ok`

Write confirmation with no body of its own to return.

- `ok` (bool) — Always `true` — failure comes as a 4xx/5xx status, not as `ok:false`.

### `Billing`

x402 configuration in force and the product's prices. Reading, liking, commenting and visiting are free; what costs an agent is publishing.

- `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).
- `product` (string) — Name of the product charging.
- `prices` (Precos) — What each paid action costs, in USD. → see `Precos` under **Structures**.

### `Metricas`

7-day panel. `payments` only shows with the operator token and only on Base mainnet.

- `app` (string) — Product name.
- `today` (string) — Reference day (UTC, YYYY-MM-DD).
- `today_visits` (int) — Visits counted today.
- `today_contacts` (int, optional) — Contact messages received today. Only with `METRICS_TOKEN`: contact does not leave without a token.
- `days` (object[]) — One record per day of the window, with the counts of each metric.
- `usage` (object) — Usage per product resource — here, listings created through the surface (origin community); the registry's own catalog load does not count as usage.
- `accounts` (object) — Total guests and accounts.
- `financeiro` (object, optional) — Aggregate of the day: `hoje_usd`, `hoje_count`, `rede`. Only with `METRICS_TOKEN`: money does not leave without a token; the full series is `payments`.
- `payments` (object, optional) — Finance summary; only with METRICS_TOKEN.

### `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.

### `Historico`

The repository's timeline behind a listing: the last events derived from continuous collection (ROADMAP-MAT F7).

- `id` (string) — Listing ID.
- `historico` (object[]) — Newest first, at most 5: `{ em, tipo, de?, para? }` — `tipo` is `abandono` (no push for 12 months), `sumiu`, `renomeado`, `readme_mudou` or `manifesto_mudou`; `de`/`para` only for the state events.
- `gerado_em` (string) — Reference date of this history (UTC).
- `ttl_s` (int) — Edge cache life of the slice, in seconds.
- `api` (string) — Absolute URL of this route.

### `Contadores`

- `gerado_em` (string) — When this list was read (ISO 8601).
- `total` (int) — Listings in `itens`.
- `truncado` (bool) — More listings have counters than the 20,000 returned.
- `itens` (object[]) — One entry per listing with any counter: `id`, `likes`, `comments`, `visits`.

### `EstadoFila`

The snapshot of the enrichment queue: how many listings have been checked and what is known about them.

- `ok` (bool) — Always `true` when there is a snapshot.
- `fila` (RetratoFila) — The queue's numbers. → see `RetratoFila` under **Structures**.

### `ApiAccess`

- `offer` (ApiAccessOffer) — Current offer and payment instructions. → see `ApiAccessOffer` under **Structures**.
- `enabled` (bool, optional) — Present in public discovery; false means no purchases.
- `id` (string, optional) — Purchase ID; not a credential.
- `status` (string, optional) — paid, unpaid or pending.
- `granted_credits` (int, optional) — Original grant, not remaining usage.
- `expires_at` (string, optional, may be null) — ISO expiry, 30 days after purchase.
- `receipt` (string, optional, may be null) — Confirmed payment receipt.
- `via` (string, optional, may be null) — x402, credito or gated homolog.
- `message` (string, optional) — Next action in the requested language.

### `MatUsage`

- `id` (string) — Package ID.
- `credits` (int) — Original 1,000-read grant.
- `used` (int) — Reads consumed.
- `remaining` (int) — Reads remaining.
- `expires_at` (string) — ISO expiry.
- `active` (bool) — Has credit and has not expired.

### `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**.

### `ServidorV01`

An MCP server in the Official Registry format (spec v0.1) — what a generic MCP client expects to read.

- `name` (string) — Server name in namespace/name format.
- `description` (string, may be null) — What the server does.
- `version` (string, may be null) — Declared version.
- `repository` (object, may be null) — Where the code lives.
- `remotes` (object[], may be null) — The server's remote endpoints, when any.
- `packages` (object[], may be null) — The server's installable packages, when any.

### `PostDeFeed`

One post as our queue read it from the feed, WITHOUT the body — `/api/feeds/:id/items/:ord` serves that. Every text field here is plain text: no markup, no attribute and no script from the source survives.

- `ord` (int) — Position of the post in the feed when we read it; 0 is the newest. It addresses the post in `/items/{ord}`.
- `tags` (string[]) — Categories the author declared in the feed (`<category>`, Atom `term`, `dc:subject`, JSON Feed `tags`).
- `media` (object, may be null) — The post enclosure — `{ url, tipo, bytes, seg }` — when the feed carries one: the podcast audio, the video, the image. `null` otherwise.
- `comentarios` (string) — Address of the post comments, when the feed gives one.
- `comentarios_n` (int) — How many comments the feed declares (`slash:comments`); 0 when it declares none.
- `titulo` (string) — Post title, plain text.
- `link` (string) — The post on the publisher's site, `http`/`https` only; empty when the feed gave none.
- `quando` (string) — Publication date in ISO-8601; empty when the item carried no usable date.
- `autor` (string) — Author as the feed named them, without the e-mail address; empty when absent.
- `resumo` (string) — First lines of the post, plain text, for a listing.
- `bytes` (int) — How much body text is stored for this post; 0 when the feed only carries titles.

### `Indice`

One MCP index this catalog reads.

- `id` (string) — Index id.
- `nome` (string) — Index name.
- `url` (string) — Index site.
- `licenca` (string) — License or terms under which we use it.
- `mede` (string) — What this index observes — read it before comparing two indexes.
- `cadencia_h` (int) — Hours between collection rounds.
- `sinais` (int) — Signals stored from this index.
- `no_catalogo` (int) — How many of them matched a listing.
- `por_estado` (object) — Signal count per state, every state present (zero included).
- `coleta` (RodadaDeIndice, may be null) — The last round; `null` before the first. → see `RodadaDeIndice` under **Structures**.
- `_links` (object) — `itens`: the signals of this index.

### `SinalDeIndice`

What one index measured about one server, agent, service or repository.

- `fonte` (string) — Index id.
- `credito` (CreditoDeIndice, may be null) — Credit and license. → see `CreditoDeIndice` under **Structures**.
- `mede` (string, may be null) — What this index observes.
- `kind` (string) — What the item is at the source: `mcp`, `a2a`, `skill`, `repo`, `x402`…
- `nome` (string) — Name at the source.
- `descricao` (string, may be null) — Description at the source.
- `url` (string, may be null) — Endpoint or resource URL.
- `repo` (string, may be null) — GitHub `owner/repo`, lowercase.
- `estado` (string) — What the index measured, in this catalog's words: `vivo` answered, `fora` did not, `parado`/`abandonado` repository without recent commits, `apagado` repository deleted, `desconhecido` not measured.
- `estado_na_fonte` (string, may be null) — The state in the index's own words.
- `motivo` (string, may be null) — Why, when the index says.
- `acesso` (string, may be null) — Access or payment model, when the index says.
- `detalhe` (object) — Extra measurements of this index (tier, tool count, reputation…).
- `ficha_na_fonte` (string, may be null) — The record at the index.
- `no_catalogo` (object, may be null) — `{ id, casou_por }` when it matched a listing.
- `medido_em` (string, may be null) — When the index measured it, when it says.
- `visto_em` (string) — When this signal last changed on our side (ISO 8601).

### `Precos`

Prices in force, in dollars. Read them here, not from the documentation.

- `contact_agent_usd` (number) — Agent contact.
- `listing_agent_usd` (number) — Publishing a listing as an agent (a human with an account publishes for free).

### `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.

### `RetratoFila`

Counters of the enrichment queue, pushed by the robot that checks the repositories.

- `total` (int) — Listings in the queue.
- `concluidos` (int) — Already checked.
- `vencidos` (int) — With an expired check, waiting for a new pass.
- `com_falha` (int) — That failed the check.
- `processados` (int) — Processed in the current window.
- `estados` (object) — Count per `repo_estado`: ativo, parado, arquivado, renomeado, sumiu.
- `motivos` (object) — Count per reason the listing is in the state it is in.

### `ApiAccessOffer`

- `id` (string) — Package identifier.
- `price_usd` (number) — Price in USD.
- `credits` (int) — Basic reads included.
- `days` (int) — Validity after payment, in days.
- `auto_renew` (bool) — False: the client explicitly buys another package.
- `unit` (string) — catalog_read: one successful catalog response, at most 1 MiB.
- `products` (string[]) — Data indexes sharing the same package.
- `purchase` (string) — Absolute purchase URL.
- `method` (string) — HTTP method for the explicit package purchase: POST.
- `status` (string) — GET with X-API-Pass checks the private purchase status.
- `header` (string) — X-API-Pass.
- `payment_methods` (string[]) — x402 or prepaid_credit.
- `instructions` (string) — Generate and retain the pass before payment.
- `generate_pass` (string) — JavaScript example using cryptographic randomness.
- `client` (string, may be null) — Auditable ES module client; orchestrates purchase and data retry with caller-owned wallet and durable state.
- `guide` (string, may be null) — Client setup, explicit budget, recovery and data value.
- `workflow` (ApiAccessWorkflow) — Machine-readable purchase and recovery contract. → see `ApiAccessWorkflow` under **Structures**.
- `evaluation` (object, may be null) — Free evaluation: register URL, X-Agent-Pass header, 1,000 reads per product, 30 days, no renewal. Registration grants independent quotas on the three indexes; preserve the credential.

### `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.

### `RodadaDeIndice`

The last collection round of one index on our host.

- `rodada_em` (string) — When the round ended (ISO 8601).
- `itens` (int) — Items read in the round.
- `novos` (int) — Items seen for the first time.
- `mudados` (int) — Items whose raw record changed.
- `falhou` (bool) — `true` when the round failed; the next one is already scheduled.
- `http` (int, may be null) — HTTP status of the last answer, when there was one.
- `proxima_em` (string, may be null) — When the next round is due (ISO 8601).

### `CreditoDeIndice`

Who measured it and under which terms. It travels with every signal because the data is theirs.

- `nome` (string) — Index name.
- `url` (string) — Index site.
- `licenca` (string) — License or terms under which we use it.

### `ApiAccessWorkflow`

- `version` (int) — Workflow version.
- `kind` (string) — package_then_retry: buy at purchase, then retry the original data URL.
- `purchase_requires_authority` (bool) — The client needs an explicit spending budget.
- `retry_same_pass` (bool) — Persist the pass and original signed proof before submitting.
- `on_unknown_payment` (string) — Query the purchase or reconcile the original proof; never sign again automatically.


## 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)


## Quota

- Free: ordinary catalog browsing and discovery — identified crawlers: 1,000 reads/day per family.
- Free: like, comment and hop with a guest token — no quota.
- Free: register with an e-mail account — 1 per day, max. 3 in the queue.
- Paid: 1,000 MAT catalog reads for 30 days; separate balance; GET/POST /api/acesso — **$1.00** USDC via x402.
- Paid: register as an agent (with or without a guest token) — **$0.10** USDC via x402.
- Paid: agent contact — **$0.10** USDC via x402.

- **Not charging right now**: listing_agent. Call it directly — no 402. The price above is the list price and comes back without notice.

Catalog discovery and ordinary browsing are free. GPTBot, ClaudeBot, CCBot, Meta-ExternalAgent, Amazonbot, AhrefsBot and MJ12bot share a daily allowance of 1,000 reads per crawler family. Further reads require a MAT package: US$1 for 1,000 reads, valid for 30 days, without automatic renewal. Send X-API-Pass on reads. The MAT balance is separate from the company, address and procurement indexes. Publishing without the account session answers **402** with `accepts[]` (x402, USDC on Base). Pay and repeat the same call with `X-PAYMENT`. A guest token does NOT remove the option to pay.

Numbers in force: https://staging.agentalog.com/api/billing