Skip to main content
Uma API HTTP, versionada em /v1, JSON na entrada e JSON na saída.
Os exemplos deste guia usam $API para essa base. O playground de cada página de endpoint já aponta para lá.

​
Requisições

Content-Type: application/json em qualquer coisa com corpo. Os corpos têm teto de 1 MiB; um corpo grande demais falha no leitor em vez de ser bufferizado em memória antes. Credenciais viajam em Authorization: Bearer:
Nada mais é aceito. Nenhum parâmetro de query — cairia em logs de acesso e no histórico do navegador. Nenhum cookie — esta API não é autenticada por cookie, e é também por isso que o CORS nunca precisa de credenciais. A exceção é a chave publicável, que viaja no corpo dos endpoints que a aceitam, ao lado dos dados de que esses endpoints já precisam. Veja Autenticação.

​
A organização ativa

Rotas autenticadas por sessão agem sobre uma organização. Qual delas vem de um header:
Ele identifica; não autoriza. O JOIN do vínculo é o que autoriza, então um código do qual você não é membro não resolve nada. Omitido, responde a organização padrão da sessão.

​
Respostas

Sucesso é um 2xx com corpo JSON, exceto 204, que não tem nenhum.
202 não é “na fila”. Em forgot-password, signup e nos fluxos de magic link ele significa “aceito, e a resposta seria a mesma de qualquer jeito” — a API não revela se um endereço tem conta.
Erros são sempre o mesmo envelope:
Ramifique em code. Veja Erros.

​
Timestamps

RFC 3339, UTC:
Um timestamp anulável vem como null, nunca como string vazia ou data zero.

​
Identificadores

UUIDs, com duas exceções:
  • código público da organização — org_<32 hex>, o que vai nas URLs e no header X-Organization-Id;
  • prefixos de credencial — uk_sk_, uk_pk_, uk_st_, uk_ct_, e as famílias de token de uso único.
O UUID interno da organização nunca sai da API nas superfícies que o painel usa.

​
Paginação

Leituras de coleção aceitam limit e offset:
O teto é deliberado: suficiente para uma tela, pequeno o bastante para ninguém baixar a audiência inteira sem querer.
Valores fora da faixa não são erro — eles voltam para o padrão. Não conte com um 400 para pegar um tamanho de página inválido.

​
Ambientes

Na superfície de máquina, o ambiente é o da chave, resolvido a partir da linha armazenada em toda requisição. Não existe parâmetro para ele. Na superfície do painel, as leituras aceitam ?environment=live|test, com padrão live. Os dois estão cobertos em Ambientes.

​
Rate limits

Endpoints públicos e de credencial são limitados por IP; o boot é adicionalmente limitado por chave publicável. Veja Rate limits.

​
As superfícies

Plano de staff

uk_st_…. Login, conta, organizações, membros, papéis, chaves, e a visão do painel sobre contatos.

Superfície de máquina

uk_sk_…. /v1/me e /v1/contacts — o seu backend falando sobre os seus próprios usuários.

Plano de clientes

Chave publicável no corpo. /v1/boot e /v1/contact-auth/*, chamados das suas páginas.

Superfície de contato

uk_ct_…. /v1/contact/me — um dos seus usuários lendo o próprio registro.