# samehand — referência completa da API

> Gerada do catálogo em https://samehand.app · build `425670a3`
> 56 endpoints · 19 estruturas
> Índice curto: https://samehand.app/llms.txt · Spec: https://samehand.app/openapi.json · MCP: https://samehand.app/mcp

> Referência completa. Perfil pessoal privado, demonstração pública e reescrita com comparação.

## Serviços grátis e pagos

- [Franquias e preços vigentes](https://samehand.app/api/pricing)
- [Meios e condições de pagamento](https://samehand.app/api/billing)
- [Primeira chamada e recuperação de pagamento](https://samehand.app/skill.md)


## 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://samehand.app/llms-full.txt?prefix=/api/` devolve só aquele ramo.

## Autenticação

- `none` — Público.
- `token` — Token de operador `METRICS_TOKEN` em `Authorization: Bearer` (métricas).
- `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.
- `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

## Endpoints

## Account

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

Prepare the browser for global sign-in.

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

- **URL:** `https://samehand.app/api/auth/bootstrap`
- **Auth:** `none` — Público.

**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://samehand.app/api/account/profile`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
await fetch("https://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://samehand.app/api/account/avatar`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**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://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.

The product SDK also returns profile and administration. administration is {href} for the platform owner signed in with a passkey, authenticator or recovery code, otherwise null. The server derives this field from the authenticated account. authTime is the sign-in time of a browser session; it is null for an API key or OAuth token.

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

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
await fetch("https://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://samehand.app/api/auth/logout`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**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://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://samehand.app/api/account/keys`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**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://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 within the last 2 hours; 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://samehand.app/api/account/keys/create`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

**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://samehand.app/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://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://samehand.app/api/account/keys/revoke`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

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

### `GET /api/account/apps`

List the apps connected to your account in this product.

The MCP clients you signed in with (OAuth), such as claude.ai or ChatGPT. Never returns a token.

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

**Resposta `200`**

- `apps` (object[]) — Up to 50: `id`, `nome` (the app; its host when it identifies itself by a metadata document), `criadoEm`, `usadoEm` (hourly, or null).

**Erros**

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

**Exemplo**

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

### `POST /api/account/apps/revoke`

Disconnect an app from your account.

Stops the app's access at once; it asks you to sign in again. Repeating is harmless.

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

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

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

**Exemplo de corpo**

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

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_app_id
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `404` — app_not_found
- `503` — auth_unavailable

**Exemplo**

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

### `GET /api/account/callouts`

List the notices that you closed in this product.

The keys of the notices that stay closed for your account, on every device, such as the explanation of an area.

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

**Resposta `200`**

- `callouts` (string[]) — Up to 200 keys, in alphabetical order.

**Erros**

- `401` — invalid_session
- `403` — product_required
- `503` — auth_unavailable

**Exemplo**

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

### `POST /api/account/callouts/dismiss`

Close a notice for good.

The notice does not open again for your account in this product. Repeating is harmless.

- **URL:** `https://samehand.app/api/account/callouts/dismiss`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

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

- `key` (string, obrigatório) — The notice key: letters, digits and `_.:-`, up to 80.

**Exemplo de corpo**

```json
{
  "key": "financeiro_expense"
}
```

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_callout
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `409` — too_many_callouts
- `503` — auth_unavailable

**Exemplo**

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

### `POST /api/account/callouts/reopen`

Open a closed notice again.

Undoes the close: the notice shows again for your account in this product. A product also keeps an on/off choice here, as the hidden values of Finance. Repeating is harmless.

- **URL:** `https://samehand.app/api/account/callouts/reopen`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

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

- `key` (string, obrigatório) — The notice key: letters, digits and `_.:-`, up to 80.

**Exemplo de corpo**

```json
{
  "key": "financeiro_expense"
}
```

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_callout
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable

**Exemplo**

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

### `POST /api/auth/wallet/agent/start`

Start the wallet credential of an agent without an account.

No account: the wallet proves it is hers by signing the message (EIP-4361). Signing does not pay or transfer anything. The message names this product and lasts 5 minutes. Before you sign, compare the message with the URL that you called. The domain on the first line must be the host of that URL. URI must be its origin. If one is different, do not sign. Sign it with personal_sign and send it to /api/auth/wallet/agent/token.

- **URL:** `https://samehand.app/api/auth/wallet/agent/start`
- **Auth:** `none` — Público.

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

- `address` (string, obrigatório) — 0x…, a carteira (EOA ou contrato na Base)

**Exemplo de corpo**

```json
{
  "address": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23"
}
```

**Resposta `200`**

- `message` (string) — EIP-4361
- `issuedAt` (number) — segundos / seconds
- `expiresIn` (number) — 300

**Erros**

- `400` — invalid_wallet_address
- `503` — auth_unavailable

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/auth/wallet/agent/start -H 'content-type: application/json' -d '{"address":"0x2c7536E3605D9C16a7a3D7b1898e529396a65c23"}'
```

### `POST /api/auth/wallet/agent/token`

Get the wallet credential (mmw_…) of this product.

The wallet's signature of the start message, checked here (own key) or on Base (contract, EIP-1271/6492). The credential lasts 30 days: send `Authorization: Bearer mmw_…` to the routes that accept the wallet as owner (owner `x402:<address>`). Once the wallet is linked to an account, what it did here moves to the account when the person signs in.

- **URL:** `https://samehand.app/api/auth/wallet/agent/token`
- **Auth:** `none` — Público.

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

- `address` (string, obrigatório) — 0x…, a mesma carteira do start / the same wallet as in start
- `issuedAt` (number, obrigatório) — o issuedAt do start / start's issuedAt
- `signature` (string, obrigatório) — personal_sign (0x…)

**Exemplo de corpo**

```json
{
  "address": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "issuedAt": 1791400000,
  "signature": "0x…"
}
```

**Resposta `200`**

- `token` (string) — mmw_…
- `owner` (string) — x402:0x…
- `expiresAt` (number) — segundos / seconds

**Erros**

- `400` — invalid_body
- `401` — invalid_wallet
- `429` — wallet_limited
- `503` — wallet_unavailable / auth_unavailable

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/auth/wallet/agent/token -H 'content-type: application/json' -d '{"address":"0x2c7536E3605D9C16a7a3D7b1898e529396a65c23","issuedAt":1791400000,"signature":"0x…"}'
```

## Installed app

### `POST /api/auth/pwa/install`

Prepare a personal app installation.

Requires recent sign-in, exact Origin and browser CSRF. Returns a private signed PIN and a no-store manifest address. At most 10 active installations per account and product.

- **URL:** `https://samehand.app/api/auth/pwa/install`
- **Auth:** `session` — Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.

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

- `path` (string, obrigatório) — Same-origin task path, up to 1600 characters.
- `state` (object, obrigatório) — Up to 30 allowlisted preference keys and string values.
- `manifest` (object, obrigatório) — Public app name and same-origin icons.

**Resposta `200`**

{pin,path,manifest}

**Erros**

- `400` — invalid_installation_path / invalid_installation_state / invalid_installation_manifest
- `401` — invalid_session / reauth_required
- `409` — installation_not_created
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://samehand.app/api/auth/bootstrap").then(r => r.json());
  const manifest = await fetch(document.querySelector('link[rel="manifest"]').href).then(r => r.json());
  const r = await fetch("https://samehand.app/api/auth/pwa/install", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({path: location.pathname + location.search, state: {}, manifest})});
  return r.json();
})();
```

### `POST /api/auth/pwa/restore`

Restore an installed app.

Requires the signed PIN, exact Origin and browser CSRF. Verifies host, product, account status, security version and installation revocation. Keeps the original authentication time. Sensitive actions still require recent sign-in.

- **URL:** `https://samehand.app/api/auth/pwa/restore`
- **Auth:** `none` — Público.

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

- `pin` (string, obrigatório) — Private signed installation credential.

**Resposta `200`**

{ok:true,state,path,manifest}; HttpOnly session cookies

**Erros**

- `401` — invalid_installation
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable

**Exemplo**

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

### `GET /api/auth/pwa/manifest`

Read the private installation manifest.

Requires the installation cookie and its manifest key. Private, no-store. The start URL keeps the PIN in the fragment.

- **URL:** `https://samehand.app/api/auth/pwa/manifest`
- **Auth:** `none` — Público.

**Query**

- `key` (string, obrigatório) — Key in the manifest address that the install or restore call returned.

**Resposta `200`**

application/manifest+json

**Erros**

- `401` — invalid_installation

**Exemplo**

```js
await fetch("https://samehand.app/api/auth/pwa/manifest?key=…", {credentials: "same-origin"}).then(r => 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://samehand.app/agent.json`
- **Auth:** `none` — Público.

**Resposta `200`**

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

**Exemplo**

```sh
curl -s https://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://samehand.app/okf/:arquivo`
- **Auth:** `none` — Público.

**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://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://samehand.app/.well-known/:arquivo`
- **Auth:** `none` — Público.

**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://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://samehand.app/apis.json`
- **Auth:** `none` — Público.

**Resposta `200`**

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

**Exemplo**

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

## Descoberta

### `GET /api/`

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

- **URL:** `https://samehand.app/api/`
- **Auth:** `none` — Público.

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

Saúde do processo, número de exemplos e disponibilidade da configuração de reescrita.

- **URL:** `https://samehand.app/api/health`
- **Auth:** `none` — Público.

**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.
- `reescrita_disponivel` (bool) — A configuração permite aceitar uma reescrita. Não testa o provedor nem revela a chave.
- `protocolo` (string) — `openai` ou `anthropic`.

**Exemplo**

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

### `POST /mcp`

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

- **URL:** `https://samehand.app/mcp`
- **Auth:** `none` — Público.

**Resposta `200`**

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

**Exemplo**

```sh
curl -s -XPOST https://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://samehand.app/api/pricing`
- **Auth:** `none` — Público.

**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://samehand.app/api/pricing
```

### `GET /api/billing`

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

- **URL:** `https://samehand.app/api/billing`
- **Auth:** `none` — Público.

**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://samehand.app/api/billing
```

## Voz

### `GET /api/estilo`

Estatísticas do perfil de escrita atual, com o tamanho das amostras de um único autor.

- **URL:** `https://samehand.app/api/estilo`
- **Auth:** `none` — Público.

**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://samehand.app/api/estilo
```

### `POST /api/rewrite`

Reescreve um texto curto com o perfil atual. Compara as palavras removidas e adicionadas.

**Resultados prontos e quando usar**

Reutilize o perfil salvo e veja as palavras alteradas. Você não precisa montar o contexto e a comparação a cada rascunho.

Confira /api/health, leia seu perfil autorizado e envie voz:pessoal com perfilVersao. Em preservar, indique trechos literais do rascunho. Experimente na franquia gratuita e revise sentido e estilo.
Além da franquia, crédito ou pagamento por chamada compra mais reescritas. Use quando o perfil salvo e a comparação ajudarem na tarefa.
O modelo recebe rascunho e contexto selecionado. Variantes sem um trecho protegido são recusadas; se nenhuma restar, o pedido não cobra. Preservar trechos não verifica os demais fatos nem a intenção. Estilos extras exigem gerações extras.

- **URL:** `https://samehand.app/api/rewrite`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.

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

- `texto` (string) — Rascunho ou ideia a reescrever. Até 4000 caracteres. Ex.: `Please review this draft.`.
- `contexto` (string) — Informações de referência. Até 4000 caracteres. O modelo não busca links.
- `registro` (string) — `resposta` (padrão) ou `post`.
- `voz` (string) — pessoal: your account profile; neutra: no examples; demonstracao: public demo (legacy default).
- `perfilVersao` (string) — Current revision from GET /api/profile. Required when voz is pessoal.
- `preservar` (string[]) — Literal names, amounts, dates or other strings from texto that every returned variant must retain exactly. Invalid entries are refused before billing. Variants that change them are not returned; if all fail, no charge.
- `instrucoes` (string) — Regras do autor sobre a própria voz, uma por linha.
- `idioma` (string) — Língua das versões, em código ISO 639-1 (`en`, `pt`, `ja`…). Sem ele, a do texto.
- `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.
- `voz` (object) — Selected tipo and perfilVersao. The revision is non-null only for the authenticated personal profile.
- `preservados` (string[]) — Literal strings checked in every returned variant. This does not verify other facts or intent.
- `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}` of the signed-in account's daily allowance.

**Erros**

- `400` — `texto_vazio`, `json_invalido` or `preservar_invalido` (not an array of nonempty strings present in texto).
- `401` — Invalid account credential. Sign in again or use a valid personal API key.
- `402` — No account or daily allowance used up: pay with x402 or prepaid credit.
- `403` — The account request failed its origin or CSRF check.
- `413` — `texto_longo` — o teto é 4000 caracteres.
- `502` — `falha_upstream` — o provedor do modelo não respondeu.
- `503` — `sem_credencial` — reescrita sem modelo configurado. Não cobra nem chama o provedor.

**Exemplo**

```sh
curl -s -XPOST https://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

### `GET /api/credito/x402/saude`

Saúde do verificador x402: pendências, falta de hash e falha ou parada da conciliação.

- **URL:** `https://samehand.app/api/credito/x402/saude`
- **Auth:** `none` — Público.

**Resposta `200`**

- `verificado_em` (string) — Hora da leitura, em UTC.
- `ativo` (boolean) — Verificador configurado no processo. → ver `boolean` em **Estruturas**.
- `tarefas` (object[]) — Falhas com id e motivo, sem dados do pagador. Contagem limitada indica +.

**Erros**

- `503` — Verificador indisponível neste processo.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/x402/saude
```

### `GET /api/credito/barrados/saude`

Quem pagou e foi barrado neste site nas últimas 24 horas: a casa pediu pagamento a quem tinha saldo ou plano, ou cobrou e não entregou.

- **URL:** `https://samehand.app/api/credito/barrados/saude`
- **Auth:** `none` — Público.

**Resposta `200`**

- `verificado_em` (string) — Hora da leitura, em UTC.
- `ativo` (boolean) — A leitura funcionou. → ver `boolean` em **Estruturas**.
- `total` (int) — Quantas ocorrências diferentes houve.
- `tarefas` (object[]) — Até 8 ocorrências, com classe, rota, vezes e última hora, sem dados de quem pagou.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/barrados/saude
```

### `GET /api/credito/conta`

O saldo da conta da sessão: a soma das compras dela neste ambiente, em todo produto, sem precisar do código. Com movimentos=1, o extrato da conta.

- **URL:** `https://samehand.app/api/credito/conta`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.

**Query**

- `movimentos` (string) — `1`: consulta só o extrato paginado da conta, sem saldo.
- `de` (string) — Início inclusivo em UTC ISO 8601 com milissegundos. Padrão: 1970-01-01T00:00:00.000Z.
- `ate` (string) — Fim exclusivo em UTC ISO 8601 com milissegundos. Padrão: agora. Conserve o valor entre páginas.
- `antes` (string) — Cursor `proximo` da página anterior. Só com movimentos=1.
- `limite` (int) — 1 a 50 movimentos por página; padrão 20. Só com movimentos=1.

**Resposta `200`**

- `saldo_micros` (int) — O saldo em milionésimos de dólar.
- `saldo_usd` (string) — O saldo em dólar, formatado.
- `referencia_usd` (string) — O saldo logo depois da última recarga, somado nas carteiras com saldo: a base do que resta.
- `cotacao_brl_por_usd` (number) — A cotação do real que a tela usa para mostrar o saldo.
- `movimentos` (object[]) — Só com movimentos=1: id, em, valor_usd, saldo_usd, motivo, produto e recurso, do mais novo.
- `proximo` (string) — Só com movimentos=1: cursor da próxima página ou null.

**Erros**

- `400` — Período, limite ou cursor inválido.
- `401` — Sem sessão.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/conta -H 'Cookie: <sessão>'
```

### `POST /api/credito/conta`

Liga à conta da sessão o crédito comprado sem conta, inclusive em USDC, com o plano de consultas pago por ele. Depois disso, o saldo vale nos produtos do crédito da casa com `X-Credito: conta`, somado ao das outras compras da conta.

- **URL:** `https://samehand.app/api/credito/conta`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.

**Resposta `200`**

- `ok` (boolean) — A ligação foi conferida. → ver `boolean` em **Estruturas**.
- `ligadas` (int) — Compras ligadas agora. Zero quando a compra já tem conta.
- `da_conta` (boolean) — O saldo deste código já vem no saldo da conta. → ver `boolean` em **Estruturas**.

**Erros**

- `401` — Sem sessão ou sem o código de crédito.

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/credito/conta -H 'Authorization: Bearer cred_…' -H 'Cookie: <sessão>'
```

### `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://samehand.app/api/credito`
- **Auth:** `none` — Público.

**Query**

- `usd` (number, obrigatório) — Pacote: 0.1, 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.
- `usar_com_outra_credencial` (string) — O header `X-Credito`, para quando o `Authorization` já leva outra credencial.
- `saldo_em` (string) — Onde consultar saldo e extrato.
- `onde_gastar` (object) — `precos`: as ações pagas e os preços deste produto (`/api/pricing`); `produtos`: o APIs.json com os outros produtos da casa.

**Erros**

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

**Exemplo**

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

### `GET /api/credito`

Saldo e extrato com cred_…; com mmw_…, saldo da carteira e até 20 pagamentos em recuperação.

Sem token, responde 401 e aponta o manifesto x402 no cabeçalho Link. Com a cobrança configurada, o corpo inclui accepts[] com os mesmos termos da menor recarga por POST. O GET não cobra nem abre crédito.

- **URL:** `https://samehand.app/api/credito`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.

**Query**

- `movimentos` (string) — `1`: consulta só o histórico paginado, sem saldo.
- `de` (string) — Início inclusivo em UTC ISO 8601 com milissegundos. Padrão: 1970-01-01T00:00:00.000Z.
- `ate` (string) — Fim exclusivo em UTC ISO 8601 com milissegundos. Padrão: agora. Conserve o valor entre páginas.
- `antes` (string) — Cursor `proximo` da página anterior. Só com movimentos=1.
- `limite` (int) — 1 a 50 movimentos por página; padrão 20. Só com movimentos=1.

**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.
- `wallet` (string) — Só com mmw_…: endereço autenticado da carteira.
- `payments` (object[]) — Só com mmw_…: até 20 pagamentos, com id, produto, rede, tx_hash, micros, estado e criado_ms. creditado indica saldo recuperado.
- `proximo` (string|null) — Só com movimentos=1: cursor da próxima página ou null; movimentos inclui id, em, valor_usd, saldo_usd, motivo, produto e recurso. → ver `string|null` em **Estruturas**.
- `onde_gastar` (object) — `precos`: as ações pagas e os preços deste produto; `produtos`: o APIs.json com os outros produtos da casa.

**Erros**

- `400` — Período, limite ou cursor inválido.
- `401` — Sem token ou token desconhecido.

**Exemplo**

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

### `GET /api/credito/pix`

Crédito por Pix: a chave, o câmbio fixo, os pacotes em reais e o que o comprovante aceita.

- **URL:** `https://samehand.app/api/credito/pix`
- **Auth:** `none` — Público.

**Resposta `200`**

- `chave` (string) — A chave Pix que recebe o pagamento.
- `brl_por_usd` (number) — Câmbio fixo usado nos pacotes.
- `pacotes` (object[]) — Os pacotes (3, 5, 10 ou 25 dólares), cada um com `brl_centavos` e `copia_e_cola` (o Pix copia e cola do valor, o mesmo texto do QR: o app do banco já vem com o valor).
- `comprovante` (object) — Tipos aceitos (foto ou PDF) e o tamanho máximo, em bytes.
- `liberacao` (string) — `manual`: o dono confere o Pix e libera.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/pix
```

### `POST /api/credito/pix`

Pede crédito pago por Pix: multipart com `usd`, `comprovante` (foto ou PDF até 2 MB) e `email`; o resto é opcional.

O código de crédito sai na resposta e passa a valer quando o dono confere o Pix e libera (manual, em geral no mesmo dia). O `email` é obrigatório: é por ele que o dono fala com a pessoa. Opcionais: `nome`, `pagina` (a página de onde pediu, até 2.000 caracteres) e o que a pessoa comprava quando recebeu o 402 — `recurso` (até 2.000), `descricao` (até 300) e `preco_usd` (decimal, ex. `0.50`); e `navegador_id` (UUID que liga os pedidos do mesmo navegador). Tudo o que chega fica registrado no pedido — o comprovante inclusive —, com a conta logada (conferida pelo cookie da sessão), a rede e o navegador de quem pediu.

- **URL:** `https://samehand.app/api/credito/pix`
- **Auth:** `none` — Público.

**Resposta `200`**

- `id` (string) — Id do pedido, para acompanhar.
- `estado` (string) — `pendente` até a decisão.
- `credito` (string) — O token `cred_…`, mostrado UMA vez; vale depois da liberação.
- `estado_em` (string) — Onde acompanhar o pedido.

**Erros**

- `400` — Pacote fora da lista (3, 5, 10 ou 25), sem comprovante ou sem e-mail válido.
- `413` — Comprovante acima de 2 MB.
- `415` — Comprovante que não é foto (JPEG, PNG, WebP) nem PDF.
- `429` — A rede já mandou os pedidos do dia.
- `502` — O e-mail ao dono não saiu: o pedido fica registrado como `falhou`; mande de novo.
- `503` — Fila de conferência cheia, ou Pix indisponível neste app.

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/credito/pix -F usd=5 -F email=voce@empresa.com.br -F comprovante=@pix.pdf
```

### `GET /api/credito/pix/:id`

Estado de um pedido de crédito por Pix: `pendente`, `liberado`, `recusado` ou `falhou`.

- **URL:** `https://samehand.app/api/credito/pix/:id`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id do pedido (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pendente`, `liberado`, `recusado` ou `falhou` (o e-mail ao dono não saiu; mande de novo).
- `usd` (int) — O pacote pedido.
- `decidido_em` (string) — Quando o dono decidiu, ou `null`.

**Erros**

- `404` — Pedido desconhecido.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/pix/0123456789abcdef0123456789abcdef
```

### `POST /api/credito/asaas/:id/cancelar`

Cancela uma cobrança pendente ao fechar o pagamento.

Exige o bilhete `cancelamento` devolvido na criação. Uma cobrança antiga de crédito aceita seu token em `credito`. Só atua no produto e ambiente de origem. Não estorna pagamentos nem remove o histórico. 202 indica cancelamento em andamento; a vigia retoma falhas externas.

- **URL:** `https://samehand.app/api/credito/asaas/:id/cancelar`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id da cobrança (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `id` (string) — Id da cobrança.
- `estado` (string) — `cancelando`, `vencido` ou o estado final já confirmado.

**Erros**

- `404` — Cobrança ou bilhete inválido, produto ou ambiente diferente.

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/credito/asaas/0123456789abcdef0123456789abcdef/cancelar -H 'content-type: application/json' -d '{"cancelamento":"<bilhete>"}'
```

### `GET /api/credito/asaas`

Pix automático: se está disponível neste app, os pacotes em reais e o saldo que o produto vende.

- **URL:** `https://samehand.app/api/credito/asaas`
- **Auth:** `none` — Público.

**Resposta `200`**

- `disponivel` (boolean) — `false` quando o app não tem o Asaas configurado (use o Pix com comprovante). → ver `boolean` em **Estruturas**.
- `pacotes` (object[]) — Os pacotes de crédito (3, 5, 10 ou 25 dólares), com `brl_centavos`.
- `exatos` (object[]) — Preços declarados pelo app, com `usd` e `brl_centavos`. Só aparecem a partir de R$ 5,00 e até R$ 10.000.
- `saldo` (object) — Quando o produto vende saldo em reais: a faixa e se a conta logada pode comprar.
- `precisa_documento` (boolean) — Se o CPF ou CNPJ de quem paga ainda é pedido. → ver `boolean` em **Estruturas**.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/asaas
```

### `POST /api/credito/asaas`

Gera um Pix dinâmico: JSON com `oferta` (`pacote` com `usd`, ou `saldo` com `centavos`) e o pagador.

O pagamento libera sozinho o que se comprou: o pacote vira o token `cred_…` que já vem na resposta; o saldo cai na organização da conta logada. Na primeira compra vão `documento` (CPF ou CNPJ, que segue para o gateway e não fica guardado aqui) e `nome`; `email`, `pagina` e `navegador_id` são opcionais e ficam registrados. Com `forma: "cartao_boleto"`, a cobrança é livre: a resposta traz `pagamento_em`, a página do gateway onde se paga com cartão, boleto ou Pix (vence em três dias). Com `forma: "cartao"` e o `cartao` (`titular`, `numero`, `mes`, `ano`, `cvv`, `documento`, `email`, `cep`, `numero_endereco`, `telefone`), a cobrança é paga no cartão no mesmo pedido: 200 com `estado: "pago"`, 202 com `conferir` enquanto o emissor analisa, 422 quando o cartão é recusado; o cartão não fica guardado. O `usd` deve ser um valor de `pacotes` ou `exatos` do GET. O servidor define os centavos e recusa valores não declarados.

- **URL:** `https://samehand.app/api/credito/asaas`
- **Auth:** `none` — Público.

**Resposta `200`**

- `id` (string) — Id da cobrança, para acompanhar.
- `credito` (string) — No pacote: o token `cred_…`, mostrado UMA vez; vale quando o pagamento cair.
- `forma` (string) — `pix` (o padrão), `cartao` ou `cartao_boleto`.
- `pix` (object) — `copia_e_cola`, `imagem` (QR em PNG, data URI) e `expira_em`; só na forma `pix`.
- `pagamento_em` (string) — Na forma `cartao_boleto`: a página de pagamento do gateway.
- `estado` (string) — Na forma `cartao`: `pago`, ou `pendente` com `conferir`.
- `estado_em` (string) — Onde acompanhar o pagamento.
- `cancelamento` (string) — Bilhete para cancelar a cobrança pendente de Pix ou boleto.

**Erros**

- `400` — Crédito fora de `pacotes` e `exatos`, valor fora da faixa, CPF/CNPJ, nome ou e-mail inválido, dado do cartão inválido (`cartao_dados`, com o `campo`), ou o gateway recusou o pagador (`pagador_recusado`, com a razão em `detalhe`).
- `422` — Cartão recusado (`cartao_recusado`, com o `campo` quando o gateway diz qual); troque em `POST /api/credito/asaas/:id/cartao`.
- `429` — Limite de 3 tentativas por minuto ou 10 por dia, por conta ou rede, ou limite do cartão.
- `502` — O gateway não gerou o Pix; tente de novo.
- `503` — Pix automático indisponível neste app, o gateway ocupado (`asaas_ocupado`, espere `retry_after_s`), ou cobranças demais de quem não entrou esperando pagamento.

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/credito/asaas -H 'content-type: application/json' -d '{"oferta":"pacote","usd":5,"documento":"000.000.000-00","nome":"Ana"}'
```

### `GET /api/credito/asaas/:id`

Estado de uma cobrança Pix automática: `pendente`, `pago`, `vencido`, `estornado` ou `falhou`.

- **URL:** `https://samehand.app/api/credito/asaas/:id`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id da cobrança (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pago` libera o token do pacote ou o saldo; o Pix pago depois do vencimento vale.
- `pago_em` (string) — Quando o pagamento foi confirmado, ou `null`.

**Erros**

- `404` — Cobrança desconhecida.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/asaas/0123456789abcdef0123456789abcdef
```

### `POST /api/credito/asaas/:id/cartao`

Paga com outro cartão a cobrança de cartão cujo cartão foi recusado: a mesma cobrança, sem cobrar duas vezes.

JSON com o `cartao` (os mesmos campos do `POST /api/credito/asaas`) e, sem conta, o `navegador_id` que criou a cobrança. Só a cobrança de cartão que espera pagamento, de quem a criou, e até cinco tentativas por cobrança.

- **URL:** `https://samehand.app/api/credito/asaas/:id/cartao`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id da cobrança (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pago`, ou `pendente` com `conferir` enquanto o emissor analisa.
- `estado_em` (string) — Onde acompanhar o pagamento.

**Erros**

- `400` — Dado do cartão inválido (`cartao_dados`, com o `campo`).
- `404` — Cobrança desconhecida, de outra pessoa ou que não é de cartão.
- `409` — A cobrança já venceu ou foi encerrada; comece o pagamento de novo.
- `422` — Cartão recusado (`cartao_recusado`).
- `429` — Passou das tentativas de cartão desta cobrança ou do dia.

**Exemplo**

```sh
curl -s -XPOST https://samehand.app/api/credito/asaas/0123456789abcdef0123456789abcdef/cartao -H 'content-type: application/json' -d '{"cartao":{…}}'
```

### `GET /api/credito/asaas/saude`

A saúde do Pix e das assinaturas ativas deste app: falhas com motivo, para o painel.

- **URL:** `https://samehand.app/api/credito/asaas/saude`
- **Auth:** `none` — Público.

**Resposta `200`**

- `ativo` (boolean) — `false` quando o Asaas e as assinaturas estão desligados. → ver `boolean` em **Estruturas**.
- `tarefas` (object[]) — Cada problema: `id`, `falhando` e `motivo`. Inclui Pix e, quando ativas, recuperação, fila e orçamento das assinaturas. Não consulta o provedor.

**Exemplo**

```sh
curl -s https://samehand.app/api/credito/asaas/saude
```

## 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://samehand.app/api/vitrine`
- **Auth:** `none` — Público.

**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) — Traffic time zone. Audience periods state their time zone in `pessoas.medicao`.
- `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 browsers with recorded interaction over 7 days.
- `pessoas` (object, opcional, pode ser null) — First-party measurement of browsers confirmed by interaction: unique browsers, sessions and pages over 7 and 30 days, segments and coverage. `null` means no measurement. Browsers are not verified people.
- `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) — Measured sponsors: 1-second exposures and native clicks per page in confirmed sessions, 7-day CTR, observed days and coverage. Empty means no history, not zero CTR.

**Exemplo**

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

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

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

- **URL:** `https://samehand.app/api/vitrine/operador`
- **Auth:** `none` — Público.

**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://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://samehand.app/api/vitrine/painel`
- **Auth:** `none` — Público.

**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://samehand.app/api/vitrine/painel -H "Authorization: Bearer $METRICS_TOKEN"
```

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

Per-product cursors: `borda`, `borda5xx` (5xx only), and `cli`. Operator token only.

- **URL:** `https://samehand.app/api/vitrine/cursores`
- **Auth:** `none` — Público.

**Headers**

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

**Resposta `200`**

JSON: `{ [product]: { borda?: ISO, borda5xx?: 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://samehand.app/api/vitrine/cursores -H "Authorization: Bearer $METRICS_TOKEN"
```

## Partnership

### `GET /api/partners`

Fixed-price advertising: placements, duration, public numbers and checkout. Partnerships and custom campaigns use negotiation.

Four packages priced in USD per week, as a one-off purchase or weekly card subscription. Lists real channels, current sponsors and public numbers. Purchase through POST /api/partners. Negotiation and partnerships use the contact form. Cached for up to 1 hour; with a linked order, 1 minute.

- **URL:** `https://samehand.app/api/partners`
- **Auth:** `none` — Público.

**Resposta `200`**

- `status` (string) — `preco_fechado`: priced spaces can be purchased; other offers require negotiation.
- `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[]) — Package channels: id, nome, onde, formato, medicao and disponivel. Legacy monthly price is null in the weekly catalogue.
- `packages` (object[]) — Four packages: id, nome, assinatura, preco_usd_semana, espacos, canais and allowed periods in exposicao[{dias,preco}].
- `house_bundle` (object) — Unavailable in the weekly catalogue: `{disponivel:false}`.
- `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) — Shared payment through the purchase POST. Wallet fields remain for compatibility; do not send a manual payment before the quote.
- `contact` (object) — `email`, `form_url`, `api_url` (`POST /api/contact`, free: one message every 10 s per network), `campos` (required), `campos_proposta` (the optional proposal fields, each with its accepted values), `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://samehand.app/api/partners
```

### `POST /api/partners`

Buy a weekly ad package and submit the artwork for review.

The server prices the selected package and number of weeks. One-off: shared 402 quote and payment, no renewal. modalidade=assinatura: signed-in account, same-origin CSRF, native card payment and explicit weekly renewal acceptance. Read the current BRL offer at /api/credito/assinaturas/ofertas. Cancel future charges in the account. modalidade=recibo returns only that account's paid campaign receipt. Payment precedes content approval; ad display starts on publication. Reuse the id, token and content for retries. The quote does not save artwork or reserve inventory. Custom campaigns and free partnerships use POST /api/contact.

- **URL:** `https://samehand.app/api/partners`
- **Auth:** `none` — Público.

**Query**

- `0` (string) — Omit for one-off payment; assinatura uses native weekly card billing; recibo reads the account's campaign receipt.

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

- `id` (string, obrigatório) — Fresh random order id: 32 lowercase hexadecimal characters. Reuse for retries.
- `token` (string, obrigatório) — Private random order capability: 64 lowercase hexadecimal characters. Keep it for recovery.
- `espaco` (string[]) — Legacy paid-order retry only. New purchases select a package.
- `pacote` (string, obrigatório) — One of the four package ids in GET /api/partners packages.
- `duracao` (int, obrigatório) — Days from the package exposure list. Weekly subscriptions require 7.
- `assinatura` (object) — Only with modalidade=assinatura: the native subscription body with recurso=publicidade:ORDER_ID, simulado, cartao and explicit renewal aceite. The authenticated account must own the campaign.
- `pedido` (string) — Only with modalidade=recibo: the campaign id owned by the signed-in account.
- `nome` (string, obrigatório) — Brand or product, up to 80 characters.
- `email` (string, obrigatório) — Contact email.
- `url` (string, obrigatório) — HTTPS destination URL.
- `frase` (string, obrigatório) — Ad copy, up to 100 characters.
- `arte` (string, obrigatório) — Base64 image bytes, without a data URL prefix. PNG, JPEG or WebP, up to 2 MB.
- `direitos` (bool, obrigatório) — true confirms the right to use the image and content.

**Resposta `200`**

- `id` (string) — Order id.
- `estado` (string) — revisao: paid and awaiting content approval.
- `recibo` (string) — Verified payment receipt.

**Erros**

- `400` — Invalid order or artwork.
- `402` — Payment required.
- `409` — Space occupied or order changed.
- `503` — Checkout unavailable.

**Exemplo**

```sh
curl -X POST 'https://samehand.app/api/partners' -H 'content-type: application/json' -H 'Idempotency-Key: ORDER_ID' --data-binary @campaign.json
```

## Contact

### `POST /api/contact`

Write to the people behind the product — free, for people and agents alike.

One route for a question and for a sponsorship, partnership or ad proposal (`tipo`, with the placements of `GET /api/partners`). No captcha, no account, no payment. One message every 10 seconds per network: one that arrives sooner waits its turn and then goes out — no error. The message reaches the team by e-mail, with `email` as the reply address. For voice, send multipart/form-data: `dados` is this JSON (up to 32 KiB), and `audio` is one WebM, Ogg or M4A audio file (up to 2 MB). Audio can replace message. The browser records up to two minutes. Audio is attached to the owner's e-mail.

- **URL:** `https://samehand.app/api/contact`
- **Auth:** `none` — Público.

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

- `name` (string, obrigatório) — What to call the person writing.
- `email` (string, obrigatório) — Where to reply.
- `message` (string, obrigatório) — What you want to say.
- `whatsapp` (string) — Optional reply number with country code, such as +5561999999999.
- `prefer_whatsapp` (bool) — Request a WhatsApp reply. Requires whatsapp.
- `tipo` (string) — Proposal: `patrocinio`, `parceria`, `anuncio` or `consultoria`. Turns on the fields below.
- `empresa` (string) — Who is proposing, when it is a company.
- `site` (string) — Website of who is proposing.
- `orcamento` (string) — Advertising: `ate_100`, `100_500`, `500_2000`, `2000_mais` or `a_combinar`. Consulting, in US dollars: `ate_2000`, `2000_5000`, `5000_10000`, `10000_mais` or `nao_sei`.
- `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`.
- `projeto` (string) — Consulting: the kind of project (`llm_privado`, `voz`, `dados_sensiveis`, `gpu`, `integracao` or `outro`).
- `prazo` (string) — Consulting: when to start (`agora`, `1_mes`, `1_3_meses` or `explorando`).
- `formato` (string) — Consulting: `projeto` (per scope), `mensal` (monthly) or `assessoria` (advisory).
- `pais` (string) — Consulting: the country of the person asking.
- `fuso` (string) — Consulting: the IANA time zone, such as `America/New_York`.
- `horarios` (string[]) — Consulting: up to 3 times for the call, `YYYY-MM-DDTHH:MM` in that time zone.

**Exemplo de corpo**

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

**Resposta `200`**

- `ok` (bool) — Always `true` when the message was accepted.

**Erros**

- `400` — Validation: `code` names the field.
- `503` — Contact is not configured on this server.

**Exemplo**

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

## Operação

### `GET /api/metrics`

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

- **URL:** `https://samehand.app/api/metrics`
- **Auth:** `token` — Token de operador `METRICS_TOKEN` em `Authorization: Bearer` (métricas).

**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://samehand.app/api/metrics -H "authorization: Bearer $METRICS_TOKEN"
```

## Writing profile

### `GET /api/profile`

Read your private writing examples and preferences.

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

**Resposta `200`**

Estrutura: `WritingProfileState`.

- `perfil` (WritingProfile, pode ser null) — The authenticated person's private writing profile. → ver `WritingProfile` em **Estruturas**.
- `versao` (string, pode ser null) — Revision from GET /api/profile. Null for a new profile.

**Erros**

- `400` — Invalid examples, preferences, version, or missing authorship confirmation.
- `401` — A personal account session, API key, or OAuth token is required.
- `403` — Cookie writes require the same origin and the account CSRF header.
- `409` — The profile changed. Read it again before saving, deleting, or rewriting.
- `413` — The JSON body exceeds 32 KiB.
- `503` — The writing profile is unavailable.

**Exemplo**

```sh
curl -s https://samehand.app/api/profile -H 'Authorization: Bearer YOUR_PERSONAL_API_KEY'
```

### `PUT /api/profile`

Save your own writing examples and preferences.

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

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

- `perfil` (WritingProfile) — Your examples and preferences.
- `versao` (string) — Revision from GET /api/profile. Null for a new profile.
- `textosProprios` (bool) — Must be true. You wrote the supplied examples.

**Resposta `200`**

Estrutura: `WritingProfileState`.

- `perfil` (WritingProfile, pode ser null) — The authenticated person's private writing profile. → ver `WritingProfile` em **Estruturas**.
- `versao` (string, pode ser null) — Revision from GET /api/profile. Null for a new profile.

**Erros**

- `400` — Invalid examples, preferences, version, or missing authorship confirmation.
- `401` — A personal account session, API key, or OAuth token is required.
- `403` — Cookie writes require the same origin and the account CSRF header.
- `409` — The profile changed. Read it again before saving, deleting, or rewriting.
- `413` — The JSON body exceeds 32 KiB.
- `503` — The writing profile is unavailable.

**Exemplo**

```sh
curl -s https://samehand.app/api/profile -H 'Authorization: Bearer YOUR_PERSONAL_API_KEY' -X PUT -H 'Content-Type: application/json' -d '{"perfil":{"exemplos":["here is how I usually write"],"instrucoes":"","corrigirGramatica":false},"versao":null,"textosProprios":true}'
```

### `DELETE /api/profile`

Delete your private writing profile. Drafts, history, account and credit remain.

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

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

- `versao` (string) — Revision from GET /api/profile. Null for a new profile.

**Resposta `200`**

Estrutura: `WritingProfileState`.

- `perfil` (WritingProfile, pode ser null) — The authenticated person's private writing profile. → ver `WritingProfile` em **Estruturas**.
- `versao` (string, pode ser null) — Revision from GET /api/profile. Null for a new profile.

**Erros**

- `400` — Invalid examples, preferences, version, or missing authorship confirmation.
- `401` — A personal account session, API key, or OAuth token is required.
- `403` — Cookie writes require the same origin and the account CSRF header.
- `409` — The profile changed. Read it again before saving, deleting, or rewriting.
- `413` — The JSON body exceeds 32 KiB.
- `503` — The writing profile is unavailable.

**Exemplo**

```sh
curl -s https://samehand.app/api/profile -H 'Authorization: Bearer YOUR_PERSONAL_API_KEY' -X DELETE -H 'Content-Type: application/json' -d '{"versao":"REVISION_FROM_GET"}'
```

### `POST /api/profile/preview`

Suggest editable preferences from your examples. No model call and no save.

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

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

- `exemplos` (string[]) — 1–12 own texts, up to 1500 characters each and 6000 total.
- `instrucoes` (string) — Editable style preferences, up to 2000 characters.
- `corrigirGramatica` (bool) — Correct spelling and grammar only when true.
- `idioma` (string) — Language of suggestions: en (default) or pt.

**Resposta `200`**

Estrutura: `WritingProfile`.

- `exemplos` (string[]) — 1–12 own texts, up to 1500 characters each and 6000 total.
- `instrucoes` (string) — Editable style preferences, up to 2000 characters.
- `corrigirGramatica` (bool) — Correct spelling and grammar only when true.

**Erros**

- `400` — Invalid examples, preferences, version, or missing authorship confirmation.
- `401` — A personal account session, API key, or OAuth token is required.
- `403` — Cookie writes require the same origin and the account CSRF header.
- `409` — The profile changed. Read it again before saving, deleting, or rewriting.
- `413` — The JSON body exceeds 32 KiB.
- `503` — The writing profile is unavailable.

**Exemplo**

```sh
curl -s https://samehand.app/api/profile/preview -H 'Authorization: Bearer YOUR_PERSONAL_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"exemplos":["here is how I usually write"],"instrucoes":"","corrigirGramatica":false}'
```

## 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.
- `reescrita_disponivel` (bool) — A configuração permite aceitar uma reescrita. Não testa o provedor nem revela a chave.
- `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.
- `voz` (object) — Selected tipo and perfilVersao. The revision is non-null only for the authenticated personal profile.
- `preservados` (string[]) — Literal strings checked in every returned variant. This does not verify other facts or intent.
- `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}` of the signed-in account's daily allowance.

### `WritingProfileState`

- `perfil` (WritingProfile, pode ser null) — The authenticated person's private writing profile. → ver `WritingProfile` em **Estruturas**.
- `versao` (string, pode ser null) — Revision from GET /api/profile. Null for a new profile.

### `WritingProfile`

- `exemplos` (string[]) — 1–12 own texts, up to 1500 characters each and 6000 total.
- `instrucoes` (string) — Editable style preferences, up to 2000 characters.
- `corrigirGramatica` (bool) — Correct spelling and grammar only when true.

### `PaymentQuota`

- `free` (PaymentFree[]) — Free allowances and their windows. → ver `PaymentFree` em **Estruturas**.
- `paid` (PaymentPrice[]) — List prices in USD or in the stated currency; account-only offers are marked. 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.
- `charged_now` (string[], opcional) — SKUs charged at their list price even when free_now has `*`.
- `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.
- `alternavel` (bool) — Dev only: a request with `X-MM-Pagamento: real` pays for real instead of in test mode.
- `gratis` (string[], opcional) — Temporarily free SKUs.
- `cobrados` (string[], opcional) — SKUs charged even when `gratis` has `*`.
- `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)`.
- `ausentes` (string[], opcional) — Literal protected strings missing from a refused variant (protected_text_changed).

### `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, opcional) — Current list price in USD.
- `price` (string, opcional) — Price with its currency or billing unit.
- `so_conta` (bool, opcional) — Only a signed-in account can buy this offer.

### `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. Cada página HTML abre o app do produto com os dados públicos já renderizados. UF → município → bairro/localidade → rua → endereços. [HTML](https://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. Cada página HTML abre o app do produto com os dados públicos já renderizados. Modalidade → UF → ano → mês → dia → município → compras. [HTML](https://editalmd.com/licitacoes/) · [llms.txt](https://api.editalmd.com/licitacoes/llms.txt) · [OKF](https://api.editalmd.com/licitacoes/okf/index.md)