# samehand — referência completa da API

> Gerada do catálogo em https://staging.samehand.app · build `dev`
> 27 endpoints · 17 estruturas
> Índice curto: https://staging.samehand.app/llms.txt · Spec: https://staging.samehand.app/openapi.json · MCP: https://staging.samehand.app/mcp

> Referência completa. A voz medida vem do arquivo público do próprio autor.

## Como ler

- Cada endpoint traz caminho, auth, parâmetros, corpo, estrutura da resposta, erros e uma chamada que roda.
- `Pagina<Canal>` é referência: os campos estão em **Estruturas**, no fim, uma vez só.
- `(opcional)` num campo quer dizer que ele pode não vir; `(pode ser null)` quer dizer que vem com valor nulo.
- Fatie o que precisa: `https://staging.samehand.app/llms-full.txt?prefix=/api/` devolve só aquele ramo.

## Autenticação


## Endpoints

## Account

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

Prepare the browser for global sign-in.

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

- **URL:** `https://staging.samehand.app/api/auth/bootstrap`
- **Auth:** `none` — não declarada

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

**Erros**

- `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.samehand.app/api/account/profile`
- **Auth:** `session` — não declarada

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
await fetch("https://staging.samehand.app/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.samehand.app/api/account/avatar`
- **Auth:** `session` — não declarada

**Resposta `200`**

image/webp; Cache-Control: no-store

**Erros**

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

**Exemplo**

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

### `GET /api/me`

Read the current global account in this product.

- **URL:** `https://staging.samehand.app/api/me`
- **Auth:** `session` — não declarada

**Resposta `200`**

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

**Erros**

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

**Exemplo**

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

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

Revoke this product session.

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

- **URL:** `https://staging.samehand.app/api/auth/logout`
- **Auth:** `session` — não declarada

**Resposta `200`**

- `ok` (bool) — true

**Erros**

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

**Exemplo**

```js
// Execute no console da página do produto / Run in the product page console.
(async () => {
  const origin = "https://staging.samehand.app";
  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.samehand.app/api/account/keys`
- **Auth:** `session` — não declarada

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
await fetch("https://staging.samehand.app/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.samehand.app/api/account/keys/create`
- **Auth:** `session` — não declarada

**Corpo** (`application/json`)

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

**Exemplo de corpo**

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

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://staging.samehand.app/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.samehand.app/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.samehand.app/api/account/keys/revoke`
- **Auth:** `session` — não declarada

**Corpo** (`application/json`)

- `id` (string, obrigatório) — The key `id`.

**Exemplo de corpo**

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

**Resposta `200`**

- `ok` (bool) — true

**Erros**

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

**Exemplo**

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

## Discovery

### `GET /agent.json`

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

- **URL:** `https://staging.samehand.app/agent.json`
- **Auth:** `none` — não declarada

**Resposta `200`**

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

**Exemplo**

```sh
curl -s https://staging.samehand.app/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.samehand.app/okf/:arquivo`
- **Auth:** `none` — não declarada

**Parâmetros de caminho**

- `arquivo` (string, obrigatório) — `index.md`, `sobre.md`, `api.md` or `faq.md`. Ex.: `index.md`.

**Resposta `200`**

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

**Erros**

- `404` — File outside the bundle.

**Exemplo**

```sh
curl -s https://staging.samehand.app/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.samehand.app/.well-known/:arquivo`
- **Auth:** `none` — não declarada

**Parâmetros de caminho**

- `arquivo` (string, obrigatório) — `api-catalog`, `security.txt`, `x402`, `mcp-registry-auth` or `apis.json`. Ex.: `api-catalog`.

**Resposta `200`**

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

**Erros**

- `404` — Name outside the five published.

**Exemplo**

```sh
curl -s https://staging.samehand.app/.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.samehand.app/apis.json`
- **Auth:** `none` — não declarada

**Resposta `200`**

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

**Exemplo**

```sh
curl -s https://staging.samehand.app/apis.json
```

## Descoberta

### `GET /api/`

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

- **URL:** `https://staging.samehand.app/api/`
- **Auth:** `none` — não declarada

**Resposta `200`**

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

### `GET /api/health`

Vivacidade, tamanho do banco de exemplos e modelo em uso.

- **URL:** `https://staging.samehand.app/api/health`
- **Auth:** `none` — não declarada

**Resposta `200`**

Estrutura: `Saude`.

- `ok` (bool) — O Worker respondeu.
- `build` (string) — Commit publicado. É por ele que o smoke sabe que o deploy chegou.
- `exemplos` (int) — Quantos textos reais há no banco de exemplos.
- `modelo` (string, pode ser null) — Modelo em uso. Nome é público.
- `protocolo` (string) — `openai` ou `anthropic`.

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/health
```

### `POST /mcp`

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

- **URL:** `https://staging.samehand.app/mcp`
- **Auth:** `none` — não declarada

**Resposta `200`**

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

**Exemplo**

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

### `GET /api/pricing`

Preços vigentes e franquias gratuitas.

- **URL:** `https://staging.samehand.app/api/pricing`
- **Auth:** `none` — não declarada

**Resposta `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**.
- `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.

**Erros**

- `405` — Use GET ou HEAD.

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/pricing
```

### `GET /api/billing`

Descoberta pública de pagamento e crédito pré-pago.

- **URL:** `https://staging.samehand.app/api/billing`
- **Auth:** `none` — não declarada

**Resposta `200`**

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

**Erros**

- `405` — Use GET ou HEAD.

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/billing
```

## Voz

### `GET /api/estilo`

O estilo medido do autor: as marcas dele, em distribuição, com o tamanho da amostra.

- **URL:** `https://staging.samehand.app/api/estilo`
- **Auth:** `none` — não declarada

**Resposta `200`**

Estrutura: `StyleCard`.

- `geradoEm` (string) — Data em que o corpus foi medido.
- `desde` (string) — Recorte: a partir de quando os textos entraram.
- `medidas` (MedidasPorRegistro) — Um bloco de medidas por registro. → ver `MedidasPorRegistro` em **Estruturas**.

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/estilo
```

### `POST /api/rewrite`

Reescreve um texto curto na voz medida do autor, mostrando o que foi cortado.

- **URL:** `https://staging.samehand.app/api/rewrite`
- **Auth:** `credito` — não declarada

**Corpo** (`application/json`)

- `texto` (string) — O que reescrever. Texto de IA ou a ideia crua.
- `contexto` (string) — A conversa ou o assunto. Referência, nunca respondida.
- `registro` (string) — `resposta` (padrão) ou `post`.
- `instrucoes` (string) — Regras do autor sobre a própria voz, uma por linha.
- `estilos` (object[]) — Até 5 `{id, nome, prompt}`. Cada estilo é uma variante — e uma chamada ao modelo.

**Resposta `200`**

Estrutura: `Reescrita`.

- `registro` (string) — `resposta` ou `post` — muda exemplo, tom e comprimento.
- `entrada` (object) — `{achados, palavras}` do texto que entrou.
- `aviso` (string, pode ser null) — Chave de aviso, hoje só `vazio`. Nulo quando não há.
- `variantes` (Variante[]) — Uma por estilo ligado. → ver `Variante` em **Estruturas**.
- `falhas` (FalhaDeEstilo[]) — Estilos que não voltaram. → ver `FalhaDeEstilo` em **Estruturas**.
- `uso` (object) — `{entrada, saida, modelo}` — tokens gastos nesta reescrita.
- `cota` (object) — `{gratis, usado, limite}` da franquia diária deste IP.

**Erros**

- `400` — `texto_vazio` ou `json_invalido`.
- `402` — Franquia do dia esgotada: pague com x402 ou crédito pré-pago.
- `413` — `texto_longo` — o teto é 4000 caracteres.
- `502` — `falha_upstream` — o provedor do modelo não respondeu.
- `503` — `sem_credencial` — o Worker está sem modelo configurado.

**Exemplo**

```sh
curl -s -XPOST https://staging.samehand.app/api/rewrite -H 'content-type: application/json' -d '{"texto":"This is not just a flaw, it is a breach of trust.","registro":"post"}'
```

## Crédito

### `POST /api/credito`

Recarrega crédito pré-pago: paga uma vez com x402 e recebe o token que desconta em qualquer API da casa.

- **URL:** `https://staging.samehand.app/api/credito`
- **Auth:** `none` — não declarada

**Query**

- `usd` (int, obrigatório) — Pacote: 1, 5, 10 ou 25 dólares.

**Resposta `200`**

- `token` (string) — Token portador do saldo (`cred_…`). Mostrado UMA vez — não há como recuperá-lo.
- `saldo_usd` (string) — Saldo creditado.
- `guarde` (string) — Aviso de que o token é o portador do crédito.
- `usar` (string) — Como apresentar o token nas rotas pagas.
- `saldo_em` (string) — Onde consultar saldo e extrato.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25).
- `402` — Sem pagamento — o corpo traz `accepts[]` do x402.

**Exemplo**

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

### `GET /api/credito`

Saldo e extrato do crédito — as últimas movimentações, sem devolver o token.

- **URL:** `https://staging.samehand.app/api/credito`
- **Auth:** `credito` — não declarada

**Resposta `200`**

- `saldo_micros` (int) — Saldo em micro-dólares (1e-6 USD).
- `saldo_usd` (string) — Saldo formatado.
- `criado_em` (string) — Quando o crédito foi aberto.
- `movimentos` (object[]) — Entradas e saídas recentes, com produto e recurso.

**Erros**

- `401` — Sem token ou token desconhecido.

**Exemplo**

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

## 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.samehand.app/api/vitrine`
- **Auth:** `none` — não declarada

**Resposta `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, pode ser null) — When the collector published (ISO 8601).
- `stale` (bool) — `true` when the projection is older than 26 h.
- `nome` (string, opcional) — Product name.
- `desde` (string, opcional, pode ser null) — First day the series covers.
- `fuso` (string, opcional) — Time zone of the days (`UTC`).
- `hoje` (object, opcional) — Today: pages by class (human, AI, bot), API calls by class, machine-surface reads and product usage.
- `dias` (object[], opcional) — Up to 31 days, oldest first: `dia`, `paginas`, `api`, `api_ia`, `maquina`, `visitantes`, `uso`.
- `janelas` (object, opcional) — 7- and 30-day sums (`d7`, `d30`).
- `visitantes` (object, opcional) — Unique visitors at the edge over 7 days.
- `pessoas` (object, opcional, pode ser null) — GA4 when available: users, sessions, countries, devices and who arrived from AI.
- `agentes` (object, opcional) — The AI agents and bots that read the most, 7 days.
- `superficies` (object, opcional) — Reads of OKF, llms, well-known, OpenAPI and MCP over 7 days.
- `mcp` (object, opcional) — MCP calls over 7 days.
- `uso` (object, opcional) — Real product usage per resource: label, today, 7 and 30 days.
- `contas` (object, opcional, pode ser null) — Users and guests.
- `confiabilidade` (object, opcional) — Share of requests without 5xx over 7 days, and the live build.
- `catalogo` (object, opcional, pode ser null) — Size of the catalog, when the product has one.
- `apoio` (object, opcional) — Impressions and clicks per sponsor, when any.

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/vitrine
```

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

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

- **URL:** `https://staging.samehand.app/api/vitrine/operador`
- **Auth:** `none` — não declarada

**Headers**

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

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```sh
curl -s https://staging.samehand.app/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.samehand.app/api/vitrine/painel`
- **Auth:** `none` — não declarada

**Headers**

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

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```sh
curl -s https://staging.samehand.app/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.samehand.app/api/vitrine/cursores`
- **Auth:** `none` — não declarada

**Headers**

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

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```sh
curl -s https://staging.samehand.app/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.samehand.app/api/partners`
- **Auth:** `none` — não declarada

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

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/partners
```

## Operação

### `GET /api/metrics`

Uso e receita do produto, para o painel da casa. Financeiro exige token.

- **URL:** `https://staging.samehand.app/api/metrics`
- **Auth:** `token` — não declarada

**Resposta `200`**

`{app, produto, uso, payments?}`.

**Erros**

- `401` — Token errado.
- `503` — `METRICS_TOKEN` não configurado no Worker — o financeiro não sai sem ele.

**Exemplo**

```sh
curl -s https://staging.samehand.app/api/metrics -H "authorization: Bearer $METRICS_TOKEN"
```

## Estruturas

### `Saude`

Vivacidade e o que está configurado. A credencial nunca aparece aqui.

- `ok` (bool) — O Worker respondeu.
- `build` (string) — Commit publicado. É por ele que o smoke sabe que o deploy chegou.
- `exemplos` (int) — Quantos textos reais há no banco de exemplos.
- `modelo` (string, pode ser null) — Modelo em uso. Nome é público.
- `protocolo` (string) — `openai` ou `anthropic`.

### `StyleCard`

O estilo medido do autor, para ser lido e conferido em vez de caixa-preta.

- `geradoEm` (string) — Data em que o corpus foi medido.
- `desde` (string) — Recorte: a partir de quando os textos entraram.
- `medidas` (MedidasPorRegistro) — Um bloco de medidas por registro. → ver `MedidasPorRegistro` em **Estruturas**.

### `Reescrita`

A resposta de `POST /api/rewrite`: uma variante por estilo, com prova do que saiu.

- `registro` (string) — `resposta` ou `post` — muda exemplo, tom e comprimento.
- `entrada` (object) — `{achados, palavras}` do texto que entrou.
- `aviso` (string, pode ser null) — Chave de aviso, hoje só `vazio`. Nulo quando não há.
- `variantes` (Variante[]) — Uma por estilo ligado. → ver `Variante` em **Estruturas**.
- `falhas` (FalhaDeEstilo[]) — Estilos que não voltaram. → ver `FalhaDeEstilo` em **Estruturas**.
- `uso` (object) — `{entrada, saida, modelo}` — tokens gastos nesta reescrita.
- `cota` (object) — `{gratis, usado, limite}` da franquia diária deste IP.

### `PaymentQuota`

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

### `PaymentX402`

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

- `provider` (string) — Always `x402` — the only billing protocol accepted.
- `mode` (string) — Seller mode: `live` charges for real, `dev` lets calls through unpaid.
- `network` (string) — USDC network: `base` in production, `base-sepolia` in staging.
- `chain_id` (int) — EVM chain ID of the network above, so the wallet signs on the right chain.
- `pay_to` (string, pode ser 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[], opcional) — 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, pode ser null) — Test-USDC faucet; only on base-sepolia.
- `wallets` (object) — Links to wallets that speak x402 (metamask, coinbase, base_app).

### `PaymentCredit`

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

### `MedidasPorRegistro`

As medidas separadas por registro: ele escreve diferente respondendo e postando.

- `resposta` (Medidas) — As marcas dele quando responde alguém. → ver `Medidas` em **Estruturas**.
- `post` (Medidas) — As marcas dele quando posta do zero. → ver `Medidas` em **Estruturas**.

### `Variante`

Uma versão do texto na voz do autor, com o próprio recibo.

- `estilo` (Estilo) — Qual estilo gerou esta versão. → ver `Estilo` em **Estruturas**.
- `texto` (string) — A reescrita. É isto que se copia.
- `passou` (bool) — Se o lint não achou erro nesta variante.
- `achados` (Achado[]) — O que o lint ainda encontra nela. → ver `Achado` em **Estruturas**.
- `palavras` (int) — Quantas palavras a variante tem.
- `tirado` (string[]) — O que a entrada reprovava e esta variante não reprova.
- `palavrasAMenos` (int) — Quantas palavras a menos que a entrada.
- `diff` (Diff) — O corte, palavra a palavra. → ver `Diff` em **Estruturas**.

### `FalhaDeEstilo`

Estilo que não voltou. Aparece como falha, nunca como cartão que sumiu.

- `estilo` (Estilo) — Qual estilo falhou. → ver `Estilo` em **Estruturas**.
- `motivo` (string) — Causa: erro do provedor, ou `vazio (length)`.

### `PaymentFree`

- `o_que` (string) — Operation or allowance.
- `limite` (string) — Allowance and eligibility.
- `janela` (string, pode ser 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.

### `Medidas`

As marcas do autor num registro, medidas no arquivo dele. Distribuição, não regra.

- `amostras` (int) — Quantos textos entraram na medida.
- `palavrasMediana` (int) — Mediana de palavras do registro.
- `comecaMinuscula` (number) — Fração que começa em minúscula.
- `quebraDeLinha` (number) — Fração com quebra de linha.
- `reticencias` (number) — Fração com reticências.
- `pergunta` (number) — Fração que faz pergunta.
- `caps` (number) — Fração com CAPS de ênfase.
- `semPontoFinal` (number) — Fração que não fecha com ponto.
- `travessao` (number) — Fração com travessão.
- `pontoEVirgula` (number) — Fração com ponto e vírgula.
- `emoji` (number) — Fração com emoji.

### `Estilo`

O estilo de saída que gerou esta variante.

- `id` (string) — Identificador do estilo.
- `nome` (string) — Nome de exibição, vazio quando não há estilo.

### `Achado`

Uma marca de texto de IA que o lint encontrou. Determinístico, sem modelo.

- `id` (string) — Identificador estável: `travessao`, `vocab-llm`, `nao-so-mas`…
- `rotulo` (string) — Nome legível do achado.
- `gravidade` (string) — `erro` reprova a variante; `aviso` só sinaliza.

### `Diff`

O corte, mostrado em vez de afirmado. Comparação por palavra, normalizada.

- `pedacos` (Pedaco[]) — Os trechos em ordem de leitura. → ver `Pedaco` em **Estruturas**.
- `mudou` (number) — Fração de palavras que mudaram, de 0 a 1.
- `util` (bool) — `false` quando a reescrita ficou distante demais para o corte ensinar algo.

### `Pedaco`

Um trecho do diff por palavra entre a entrada e a variante.

- `op` (string) — `igual`, `saiu` (estava na entrada) ou `entrou` (é da variante).
- `texto` (string) — O texto do trecho, como aparece na tela.


## Acervos públicos de dados

Explore endereços e compras por lugar e abra os registros de que precisa. Até 20 itens por página, em formatos prontos para pessoas e agentes. Confira a cobertura e a data de referência antes de usar um resultado. Cada produto informa suas opções de acesso.

- [CEPs e endereços](https://api.pontofato.com/enderecos/index.json): Encontre endereços por lugar, com coordenadas e referência de 2022. Não certifica CEP vigente. UF → município → bairro/localidade → rua → endereços. [HTML](https://api.pontofato.com/enderecos/) · [llms.txt](https://api.pontofato.com/enderecos/llms.txt) · [OKF](https://api.pontofato.com/enderecos/okf/index.md)
- [Editais e compras públicas](https://api.editalmd.com/licitacoes/index.json): Encontre compras públicas por lugar e período. Consulte documentos e opções de leitura no EditalMD. Modalidade → UF → ano → mês → dia → município → compras. [HTML](https://api.editalmd.com/licitacoes/) · [llms.txt](https://api.editalmd.com/licitacoes/llms.txt) · [OKF](https://api.editalmd.com/licitacoes/okf/index.md)