# Versionamento e depreciação da API da ExploriGen (versioning and deprecation policy)

Esta página é a promessa pública sobre quando a API REST de ExploriGen muda, quanto aviso você recebe antes, e quanta chamada por minuto ela aceita. Vale para todas as rotas sob https://explorigen.io/api/v1/ e para o sandbox em https://explorigen.io/api/v1/sandbox/. A especificação máquina-a-máquina é o OpenAPI 3.1 em https://explorigen.io/api/openapi.json.

## Versão na URL

A versão é o primeiro segmento depois de `/api`: hoje `v1`, em `/api/v1/...`. Não há versionamento por cabeçalho nem por parâmetro: a URL é a versão, e uma URL que responde hoje responde a mesma forma amanhã.

Mudança compatível (backward compatible) entra na mesma versão, sem aviso prévio: campo novo numa resposta, rota nova, valor novo num campo livre, mensagem de erro reescrita. Um cliente que ignora campo desconhecido não quebra com nenhuma delas.

Mudança incompatível (breaking change) nunca entra na mesma versão: campo removido ou renomeado, tipo de campo alterado, rota removida, status de erro trocado por outro, escopo novo exigido numa rota que já existia. Uma mudança dessas nasce em `/api/v2`, e a `v1` continua respondendo enquanto durar a depreciação.

## Como uma rota é depreciada

Quando uma versão ou uma rota entra em depreciação, o aviso chega por três caminhos ao mesmo tempo, e nenhum deles exige que alguém leia um blog:

- o cabeçalho `Deprecation` (RFC 9745) na resposta da rota depreciada, com a data em que a depreciação foi anunciada;
- o cabeçalho `Sunset` (RFC 8594) na mesma resposta, com a data em que a rota deixa de responder, em formato HTTP-date;
- o campo `deprecacao` no índice em `GET /api`, com a mesma data, e a rota substituta.

Entre o primeiro `Deprecation` e o `Sunset` correspondente há no mínimo **90 dias**. Durante esse prazo a rota depreciada continua respondendo exatamente como antes: depreciar não é degradar.

**Hoje não há nenhuma rota depreciada.** A `v1` é a única versão, e nenhuma resposta desta API carrega `Deprecation` ou `Sunset`. Um agente que encontre um desses cabeçalhos numa resposta nossa está diante de um aviso real, não de um resquício de configuração.

## Cotas e cabeçalhos de cota (rate limit)

Toda resposta da API traz o estado da sua cota, em duas grafias do mesmo fato — os três campos `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset`, e os campos estruturados `RateLimit-Policy` e `RateLimit` do rascunho do IETF (draft-ietf-httpapi-ratelimit-headers). Ler qualquer uma das duas basta; elas nunca discordam.

- Com token (bearer): 120 requisições por 60 s, contadas pelo `registration_id` do próprio token — a política `v1`.
- Sem token — o índice público https://explorigen.io/api e o sandbox https://explorigen.io/api/v1/sandbox/: 60 requisições por 60 s, contadas por endereço de origem, pseudonimizado por hash antes de virar chave — a política `v1-public`.

Acima da cota a resposta é `429` com `error: "rate_limited"`, os mesmos cabeçalhos de cota e um `Retry-After` em segundos. Esperar o `Retry-After` basta: a janela é fixa, e não há punição cumulativa por insistir.

A contagem é aproximada por construção: ela vive num armazenamento de consistência eventual (eventual consistency), e duas requisições simultâneas do mesmo cliente podem ler o mesmo saldo. O propósito da cota é conter varredura, não medir consumo — não há cobrança por chamada, e nenhum plano pago destrava um número maior.

Ler a leitura de prontidão gravada tem um limite próprio, do instrumento e não da API: quando ele está ocupado ou em pausa, a resposta é `429` ou `503` com `Retry-After`, e o corpo diz qual dos dois casos é.

## Repetir sem duplicar (Idempotency-Key)

As duas operações que escrevem — o registro anônimo em `POST /agent/identity` e a troca por access_token em `POST /agent/token` — aceitam o cabeçalho `Idempotency-Key`. Repetir o mesmo pedido com a mesma chave e o mesmo corpo devolve a resposta da primeira vez, marcada com `Idempotency-Replayed: true`, em vez de emitir uma credencial nova. Mesma chave com corpo diferente é `422` com `idempotency_key_reuse`.

A resposta guardada expira junto com o que ela carrega: 24 h no registro (o prazo da `identity_assertion`) e 1 h na troca (o prazo do `access_token`). O relógio é o da primeira emissão — repetir não estica prazo. Erro não é guardado: um pedido que falhou pode ser corrigido e reenviado, com outra chave.

Duas chamadas disparadas ao mesmo tempo com a mesma chave podem passar as duas: o armazenamento tem consistência eventual e não há trava. A garantia cobre o caso real — repetir depois de um erro de rede —, não corrida simultânea. Onde não houver armazenamento, a resposta sai com `Idempotency-Status: unsupported` e a emissão é nova; o cabeçalho nunca é aceito em silêncio.

## Estabilidade do que está fora da v1

Os arquivos de descoberta — https://explorigen.io/api/openapi.json, https://explorigen.io/auth.md, https://explorigen.io/pricing.md, os cartões MCP e o catálogo de APIs — seguem a mesma regra: campo some só em versão nova, e o endereço de cada um é estável. Os servidores MCP em https://explorigen.io/mcp e https://explorigen.io/mcp/docs seguem o versionamento do próprio protocolo; ferramenta removida ou renomeada é tratada como mudança incompatível e recebe os mesmos 90 dias.

## Quando algo quebrar mesmo assim

Escreva para contato@explorigen.io com a URL, o horário aproximado e o corpo da resposta. Não há formulário e não há fila de suporte por plano.

Para agentes e desenvolvedores (developers): https://explorigen.io/agentes