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étodoCaminhoO que faz
GET/balanceSaldo de créditos
GET/sitesSeus sites, seus ids e painéis
POST/sitesAdicione 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}/verifyProcure 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/personasA biblioteca de personas
GET/runsSeus 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/runsIniciar 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}/cancelCancelar, 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}}

HTTPCódigoSignificado
400invalid_steps, invalid_concurrencyEtapas ou concorrência fora do intervalo; nada foi iniciado e nenhum crédito foi gasto
400invalid_limit, invalid_cursorUma página da lista de testes solicitada com limite ou before inválido
400no_personasNenhuma persona selecionada, ou um id não está neste site
400invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachableUm novo site com campo incorreto; nada foi adicionado
400invalid_dry_run, invalid_idempotency_key, invalid_callback_urldry_run, Idempotency-Key ou callback_url incorretos; nada foi iniciado
400not_test_hostO modo de pagamento de teste precisa de uma página inicial em um host de teste
401unauthorizedChave ausente ou inválida
402insufficient_creditsCréditos insuficientes
403domain_not_verifiedDomínio não verificado
404not_foundNada disso na sua conta
409too_many_runsMuitos testes na fila
409site_exists, too_many_sitesO domínio já está na sua conta, ou a conta tem 20 sites
422not_verifiedNenhuma prova do domínio encontrada ainda
502generation_failedO modelo não conseguiu criar personas; tente novamente ou escolha da biblioteca
429rate_limitedLimite 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.