Um só contrato para as suas casas

O contrato legível por máquina

GET /api/v1/openapi.json devolve um documento OpenAPI 3.1 com exatamente o que esta implantação oferece: cada caminho, esquema, permissão exigida e resposta, além dos eventos de webhook. Ele é gerado a partir do catálogo de operações em execução, o mesmo que produz as ferramentas MCP, então REST e MCP nunca se distanciam.

curl -s "https://<seu host>/api/v1/openapi.json"

A superfície cobre casas e rascunhos, revisões e publicações, posts, o catálogo de modelos, importações, portfólios e execuções em lote, domínios e planos de DNS, encaminhamento de e-mail, configurações de inscrição e contato, fontes sociais, análises, promoções, cobrança, membros da equipe e webhooks. GET /workspaces/{id}/capabilities diz quais estão ativos, simulados ou aguardando credenciais no seu espaço.

Repetições são deliberadas

• Toda mutação precisa de um cabeçalho Idempotency-Key de 16 a 128 caracteres. Repetir uma requisição com a mesma chave e o mesmo corpo devolve o resultado original com Idempotent-Replayed: true. A mesma chave com outro corpo dá 409 idempotency_key_reused.
• Edições de uma casa precisam de If-Match com o ETag da sua última leitura. Um valor desatualizado dá 412 revision_conflict e nada muda.
• Publicar exige o revision_id e o expected_digest exatos que você leu, assim você publica o que conferiu.

Trabalho demorado vira um trabalho

Publicação, execuções em lote e outras operações lentas respondem 202 com um trabalho. Consulte GET /workspaces/{id}/jobs/{job_id} no máximo a cada next_poll_after_seconds, ou assine os webhooks job.updated. Aceito não é concluído: leia o state, as contagens e o error do trabalho antes de dar algo como feito.

Erros são detalhes de problema

Os erros usam application/problem+json com um code estável, um title traduzido, o request_id e retryable. Decida pelo code, nunca pelo texto do título.

{
  "type": "https://<seu host>/problems/insufficient_scope",
  "title": "Este token não inclui a permissão necessária para esta ação.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

Listas e limites

• Listagens aceitam limit (até 100) e um cursor da página anterior.
• Cada token de espaço pode fazer 120 leituras e 30 escritas por minuto. Acima do limite você recebe 429 com um cabeçalho Retry-After.
• Preserve campos desconhecidos nas respostas: campos novos podem aparecer sem mudança de versão.