API
Endereço base: https://senaste.ai/api/v1. Todos os caminhos abaixo vêm depois dele. Envie o cabeçalho Authorization: Bearer uxp_.... Crie uma chave na sua conta. O limite é de 60 requisições por minuto; cada resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos até o próximo minuto), e uma resposta 429 inclui Retry-After.
Toda a API com a estrutura de cada resposta, em OpenAPI 3.1 para geradores de código e Postman: https://senaste.ai/api/v1/openapi.json
De um site novo a um relatório
KEY=uxp_...
# 1. adicione o site; a resposta contém o id e "verification"
curl -X POST https://senaste.ai/api/v1/sites -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"url":"https://example.com/pricing","task":"Find the price of the Pro plan","personas":["impulse","price"],"generate":2}'
# 2. coloque uma prova no site (TXT DNS, o arquivo ou a meta tag), depois
curl -X POST https://senaste.ai/api/v1/sites/SITE_ID/verify -H "Authorization: Bearer $KEY"
# 3. estime o custo do teste sem iniciá-lo, depois inicie-o
curl -X POST https://senaste.ai/api/v1/runs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"site":"SITE_ID","steps":20,"dry_run":true}'
curl -X POST https://senaste.ai/api/v1/runs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: deploy-1234" \
-d '{"site":"SITE_ID","steps":20,"concurrency":3,"callback_url":"https://example.com/hooks/senaste"}'
# 4. acompanhe-o ou aguarde o callback
curl https://senaste.ai/api/v1/runs/RUN_ID -H "Authorization: Bearer $KEY"
Omita personas em um teste para enviar todas as personas habilitadas no painel. Uma resposta para POST /runs:
{"id":"rmhb2x1k4f9a0c3d1","site":"s1a2b3c4d5e6","domain":"example.com","status":"queued","personas":8,"steps":20,
"credits":8,"refunded":0,"charged":8,"created":"2026-11-09T10:00:00.000Z","started":null,"finished":null,
"queue":{"position":1,"ahead_yours":0,"ahead_others":0,"start_in_s":0,"done_in_s":190},
"callback":{"url":"https://example.com/hooks/senaste","status":null},"warnings":[],"callback_secret":"..."}
Enquanto executa, GET /runs/{id} tem progress:
"progress":{"phase":"walking","percent":41,"personas_done":3,"personas_total":8,"steps_done":71,"steps_total":160,"eta_s":190,
"personas":[{"persona":"p01","name":"Impulse buyer","step":20,"state":"done","outcome":"gave_up"},
{"persona":"p02","name":"Price-first evaluator","step":7,"state":"walking"}]}Quando um teste termina: callback_url
Um teste iniciado com callback_url (https, um endereço público) envia um POST para esse endereço quando termina: done, failed, cancelled ou interrupted. O corpo é {"event":"run.finished","run":{...}} com o status, a pontuação e as contagens; os resultados vêm de GET /runs/{id}. Cabeçalhos: X-Senaste-Event, X-Senaste-Timestamp (segundos Unix) e X-Senaste-Signature: sha256=…, o HMAC-SHA256 de timestamp + "." + body com a chave callback_secret, que só aparece na resposta ao POST /runs. Responda com 2xx; caso contrário, há nova tentativa após 10 e 60 segundos. Redirecionamentos não são seguidos.
// Node.js
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.headers['x-senaste-timestamp'] + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-senaste-signature']));Métodos
| Método | Caminho | O que faz |
|---|---|---|
| GET | /balance | Saldo de créditos |
| GET | /sites | Seus sites, seus ids e painéis |
| POST | /sites | Adicione um site: url, task (até 500 caracteres), personas (chaves da biblioteca de GET /personas) e/ou generate (quantas a IA escreve a partir da página inicial, até um minuto), report_lang, audience. A resposta tem verification: o registro DNS, o arquivo e a meta tag, qualquer um dos quais comprova o domínio. |
| GET | /sites/{id} | Um site com seu painel e, até ser verificado, verification |
| POST | /sites/{id}/verify | Procure a comprovação agora. 200 com o site quando encontrado (e referral quando este pagou ou não pagou um bônus de indicação), 422 not_verified quando ainda não. |
| GET | /personas | A biblioteca de personas |
| GET | /runs | Seus testes, mais recentes primeiro, uma página por vez: ?limit= de 1 a 100 (50 por padrão). Quando next não for nulo, use-o em ?before= para a próxima página. |
| POST | /runs | Iniciar um teste: steps de 3 a 30, concurrency de 1 a 4. A resposta tem warnings: forms quando uma tarefa pede para enviar um formulário, comprar ou fazer cadastro (o teste retém os formulários), offsite quando indica outro domínio. "dry_run":true executa todas as verificações e responde 200 com credits, balance e would_start, sem iniciar nada. O cabeçalho Idempotency-Key torna uma nova tentativa segura: a mesma chave dentro de 24 horas retorna o teste que iniciou (200, Idempotent-Replayed: true). callback_url está descrito acima. |
| GET | /runs/{id} | Status e resultados por persona. summary indica quantas personas navegaram pelo site e quantas falhas ocorreram no teste; esse resultado tem failure com a etapa, a etapa e o endereço.
Cada resultado tem steps (o elemento usado e effect, o que o navegador fez) e goal_check: as partes da tarefa e se as telas mostram cada uma. Uma persona que diz ter alcançado o objetivo, mas cujas telas mostram apenas parte da tarefa, tem o resultado partly_reached. groups agrupa anotações de várias personas sobre um mesmo problema; o id de uma anotação é persona:index. http lista erros HTTP com o tipo de recurso, se foi carregamento de página, a página e a etapa. Uma execução em fila tem queue (posição, execuções à frente da sua e de outras contas, segundos até iniciar e até ficar pronta); uma em execução tem progress; uma concluída tem waited_s e ran_s. Uma etapa que digitou tem value, o que o campo continha depois. notes_dropped lista as anotações que a verificação deixou de lado, com o motivo. Um erro de servidor em http também tem at (UTC), url, retry (mais uma solicitação 2 s depois), hindered e os cabeçalhos de resposta pelos quais um proprietário do site pode encontrá-la em seus logs. |
| POST | /runs/{id}/cancel | Cancelar, créditos não utilizados são devolvidos |
Erros
Formato: {"error":{"code":"...","message":"..."}}. Um valor fora do intervalo também indica o campo e seus limites: {"error":{"code":"invalid_steps","message":"...","field":"steps","min":3,"max":30,"got":40}}
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_steps, invalid_concurrency | Etapas ou concorrência fora do intervalo; nada foi iniciado e nenhum crédito foi gasto |
| 400 | invalid_limit, invalid_cursor | Uma página da lista de testes solicitada com limite ou before inválido |
| 400 | no_personas | Nenhuma persona selecionada, ou um id não está neste site |
| 400 | invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachable | Um novo site com campo incorreto; nada foi adicionado |
| 400 | invalid_dry_run, invalid_idempotency_key, invalid_callback_url | dry_run, Idempotency-Key ou callback_url incorretos; nada foi iniciado |
| 400 | not_test_host | O modo de pagamento de teste precisa de uma página inicial em um host de teste |
| 401 | unauthorized | Chave ausente ou inválida |
| 402 | insufficient_credits | Créditos insuficientes |
| 403 | domain_not_verified | Domínio não verificado |
| 404 | not_found | Nada disso na sua conta |
| 409 | too_many_runs | Muitos testes na fila |
| 409 | site_exists, too_many_sites | O domínio já está na sua conta, ou a conta tem 20 sites |
| 422 | not_verified | Nenhuma prova do domínio encontrada ainda |
| 502 | generation_failed | O modelo não conseguiu criar personas; tente novamente ou escolha da biblioteca |
| 429 | rate_limited | Limite de solicitações excedido |
O que um teste faz no seu site
Apenas solicitações GET para o domínio verificado. Os formulários não são enviados e os campos de senha e cartão permanecem vazios, então um teste nunca se registra, entra ou paga. A exceção é o modo de pagamento de teste, que você ativa para um host de teste. As anotações vêm de um modelo; verifique-as antes de agir.