Referência da API v1

A API v1 é a interface que o app Android usa para falar com a console: login, conta, análises, relatórios e envio de traces. Ela foi feita para o app e segue as mesmas regras da console no navegador. Esta página resume o contrato; para mandar um trace por script, siga Enviar traces pela API.

Endereço e formato

• Base: https://app.waitscope.com/api/v1, só por HTTPS. O endereço anterior, https://waitscope.io/api/v1, ainda responde, para o app configurado com ele.
• JSON em UTF-8 nos dois sentidos, menos os downloads e os pedaços de arquivo do envio. Campo desconhecido no corpo é recusado com 400.
• Os caminhos seguem os da console, em português: /analises, /envios, /conta.
• Instantes em RFC 3339 com fuso, como 2026-10-17T13:50:48-03:00. Tempos do trace em microssegundos inteiros, nos campos terminados em _us, e tamanhos em bytes. Quem formata números e datas para exibir é o cliente.
• Sem CORS: a API não atende página de outro site aberta no navegador.

Autenticação

O login tem as duas etapas da console: a senha e depois o código do app autenticador. No fim, a API devolve um token de 43 caracteres, que vai em toda chamada no cabeçalho Authorization: Bearer <token>.

curl -s https://app.waitscope.com/api/v1/sessao \
  -H 'Content-Type: application/json' \
  -d '{"username": "zz-exemplo", "password": "...", "method": "app", "device_name": "zz-script"}'

A resposta traz "etapa": "codigo" e um desafio, que vale 10 minutos. Mande o desafio com o código de 6 dígitos do app, ou com um código de recuperação:

curl -s https://app.waitscope.com/api/v1/sessao/codigo \
  -H 'Content-Type: application/json' \
  -d '{"desafio": "...", "codigo": "123456"}'

A resposta traz o token, a validade em expira_em e os dados da conta, os mesmos de GET /eu.

• O token vale até 90 dias e cai com 30 dias sem uso. DELETE /sessao encerra o token na hora.
• Ele conta no limite de sessões simultâneas da conta, junto com as do navegador, e aparece em Minha conta como “App Android · aparelho”, com o device_name do login.
• O cookie da console não vale na API, e o token não vale na console.
• method é app, o padrão, ou email, este só quando a conta tem e-mail confirmado e o servidor envia e-mail. A recusa traz os meios aceitos em metodos_disponiveis.
• A conta ainda sem verificação em duas etapas recebe "etapa": "cadastro" e um token que só abre o cadastro, por 30 minutos.
• Até você aceitar na console a versão em vigor dos Termos de Serviço e da Política de Privacidade, toda rota responde 403 termos_pendentes, menos GET /eu e DELETE /sessao.

Idioma

As mensagens, o diagnóstico, os cartões do relatório e o catálogo de erros Oracle vêm traduzidos pelo servidor. Com token, no idioma da conta, que PUT /conta/idioma muda. Sem token, pelo cabeçalho Accept-Language: pt, en ou es, e qualquer outro vira pt.

Erros

O erro vem com o status HTTP e um corpo assim:

{"erro": {"codigo": "nao_encontrado", "mensagem": "O endereço pedido não existe."}}

O codigo é estável e serve para o programa decidir o que fazer; a mensagem já vem traduzida, para mostrar a quem usa. Alguns erros trazem campos ao lado de erro: bloqueado_ate, com o cabeçalho Retry-After, tentativas_restantes e metodos_disponiveis.

As rotas da conta e do cadastro usam também senha_atual_incorreta (401), senha_invalida, metodo_indisponivel, email_indisponivel, email_invalido e codigo_expirado (400).

Rotas

Todas as rotas pedem o token, menos GET /versao e as do login. A rota com o id de um recurso de outra conta responde 404 nao_encontrado, sem confirmar que ele existe: nem o administrador vê as análises de outra conta.

Versão

curl -s https://app.waitscope.com/api/v1/versao

Com o app publicado, a resposta traz a versão dele; sem APK publicado, app vem nulo:

{"api":1,"app":{"bytes":...,"codigo":7,"download":"/api/v1/app/apk","minima":...,"pagina":"/app","sha256":"...","versao":"1.2.1"},"servidor":"1.6.0"}

Sessão

Conta

As ações sensíveis (senha, app, e-mail e códigos de recuperação) pedem a senha_atual, com o mesmo bloqueio da console para quem erra.

Análises

Cada análise traz id, name, status (queued, running, done ou error), progress, size_bytes, as datas, o response_time_us, o tipo do trace e a mensagem de erro já traduzida. Não há download do trace nem reprocessamento: o trace não fica no servidor.

curl -s "https://app.waitscope.com/api/v1/analises?limite=20" -H "Authorization: Bearer $TOKEN"

Relatório

relatorio e relatorio.html aceitam ?top=N, de 1 a 300, ou ?todos=1, como Comandos por lista; sem eles, 10. Enquanto a análise não termina, ou se ela terminou com erro, as rotas do relatório respondem 409 conflito. O SQL sai com a máscara de literais da conta. Com uma das opções da máscara ligada, o sql_id das variantes (top_variants) vem vazio e o sql_ids dos textos compartilháveis vem []: o sql_id é calculado a partir do texto com os valores.

Envio

O envio é retomável: o arquivo vai em pedaços de até 8 MiB, um por vez, e depois de uma queda de rede continua de onde parou.

curl -s https://app.waitscope.com/api/v1/envios \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"juntar": false, "arquivos": [{"nome": "exemplo-10046.trc", "tamanho": 1845}]}'

curl -s -X PUT "https://app.waitscope.com/api/v1/envios/$ENVIO/arquivos/0" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Range: bytes 0-1844/1845" \
  --data-binary @exemplo-10046.trc

O exemplo manda o trace sintético, de 1.845 bytes, num pedaço só; $ENVIO é o id devolvido pelo POST /envios. Com "juntar": true, os arquivos viram uma coleta, analisada como um trace só. O envio pertence ao token que o abriu e some com 24 horas sem pedaço novo ou quando a sessão do token termina.

Limites

• Limite de pedidos por endereço IP e bloqueio progressivo do login depois de 5 erros de senha ou de código. Quem passa do limite recebe 429.
• Os limites da conta (tamanho por envio, análises na fila e análises guardadas) vêm em GET /eu, no campo limits. Passou do tamanho: 413 grande_demais. Fila ou análises guardadas no limite: 429 limite.
• Um envio em andamento por usuário, em pedaços de até 8 MiB. O envio parado some em 24 horas.
• Até 200 análises por página na lista, até 200 ids na exclusão em lote e até 500 itens por consulta de mudanças.
• Token por até 90 dias, ou 30 dias sem uso; token de cadastro por 30 minutos; desafio da segunda etapa por 10 minutos.

Para onde ir depois

• Enviar traces pela API: o passo a passo do envio por script.
• Enviar traces pelo app Android: o app que usa esta API.
• Limites e envio repetido: os limites de tamanho e o que acontece com o arquivo enviado de novo.
• Retenção, exclusão e privacidade dos dados: o que fica guardado e quem vê.