▸ API · Referência

Objetos

Todos os objetos do contrato: Scan, Finding, Report, Error, o envelope do webhook…

atualizado em 2 set 2026versão v1

Cada objeto que a API devolve (ou entrega por webhook), com todos os campos. É a mesma definição que gera o OpenAPI — components.schemas. Campos marcados sempre estão em toda resposta; os demais podem faltar.

`Me`

Identidade da chave: a conta, a chave, o que ela pode e o plano em vigor.

Campo	Descrição
`account_id` stringsempre	Id da conta dona da chave.
`key_id` stringsempre	Id da chave — o mesmo que aparece em Configurações → Desenvolvedores. Use no log da integração pra saber qual chave está rodando sem imprimir o segredo.
`scopes` string[]sempre	Escopos da chave, fixados na criação. `scans:readscans:writeapps:read`
`plan` stringsempre	Plano EFETIVO da conta agora — o mesmo que decide cota e recursos. Na prática vem `pro` ou `business`: sem API no plano, a chave nem autentica. `freestarterprobusiness`

Me · exemplo

{
  "account_id": "acc_9f2c1b7e",
  "key_id": "key_3a8d41c6",
  "scopes": [
    "scans:read",
    "scans:write",
    "apps:read"
  ],
  "plan": "pro"
}

`App`

Um app (hostname) monitorado pela conta.

Campo	Descrição
`hostname` stringsempre	Hostname normalizado: minúsculo, sem `www` e sem porta.
`created_at` stringsempre	Quando o app entrou na conta — string ISO 8601 em UTC (`2026-08-27T14:09:24.106Z`).
`last_scan_at` string \| nullsempre	Última ronda contra este app. `null` = nunca escaneado.
`verified` booleansempre	A propriedade do domínio já foi comprovada alguma vez (DNS TXT, arquivo, meta tag ou atestação de provedor). Não reconfere a validade de uma atestação — veja `domain_unverified`.

App · exemplo

{
  "hostname": "app.exemplo.com.br",
  "created_at": "2026-05-14T09:21:44.108Z",
  "last_scan_at": "2026-08-27T14:09:24.106Z",
  "verified": true
}

`AppList`

Lista de apps. Não é paginada: o número de apps é limitado pelo plano.

Campo	Descrição
`data` App[]sempre	Apps da conta, na ordem de cadastro.

`ScanListItem`

Uma ronda no histórico — o resumo que uma automação usa pra decidir.

Campo	Descrição
`id` stringsempre	Id da ronda (`scan_…`).
`hostname` stringsempre	Alvo normalizado.
`status` stringsempre	Estado da ronda. Só leia os números quando for `done`. `queuedrunninganalyzingdonefailedcanceled`
`created_at` string \| nullsempre	Quando a ronda foi criada. É o valor do cursor de paginação.
`finished_at` string \| nullsempre	Quando terminou. `null` enquanto roda.
`risk_score` integersempre	Exposição de 0 a 100 — quanto MAIOR, pior. Vem `0` enquanto a ronda não terminou.
`risk_label` stringsempre	Faixa do número. Vem `SECURE` enquanto a ronda não terminou (é o resumo mínimo, não um veredito). `SECURELOW_RISKMODERATE_RISKHIGH_RISKCRITICAL_RISK`
`critical_count` integersempre	Quantos achados de severidade `critical`.
`blocked` booleansempre	A ronda não conseguiu ver o app (rede bloqueada ou desafio de WAF/anti-bot). O número não representa o app: trate como inconclusivo.

`ScanList`

Página do histórico de rondas, da mais recente pra mais antiga.

Campo	Descrição
`data` ScanListItem[]sempre	As rondas desta página.
`next_before` string \| nullsempre	Cursor da próxima página (o `created_at` do último item). `null` = acabou.

`ScanSummary`

Resumo derivado do relatório. Formato do scanner (camelCase), entregue como ele é.

Campo	Descrição
`id` stringsempre	Id da ronda.
`target` stringsempre	URL exata que foi escaneada.
`hostname` stringsempre	Forma normalizada do alvo.
`status` stringsempre	Estado da ronda. `queuedrunninganalyzingdonefailedcanceled`
`score` integersempre	Exposição de 0 a 100 (maior = pior).
`riskLabel` stringsempre	Faixa do score. `SECURELOW_RISKMODERATE_RISKHIGH_RISKCRITICAL_RISK`
`criticalCount` integersempre	Achados `critical`.
`finishedAt` string	Quando terminou.
`durationMs` integersempre	Duração da ronda, em milissegundos.
`blocked` boolean	A ronda não viu o app. Ausente = `false`.
`blockedReason` string	Só com `blocked`. `connection` = não alcançamos o app a partir dos nossos servidores (problema do nosso lado; nada a liberar). `challenge` = o app respondeu com desafio ou 403 de WAF/anti-bot (aí vale liberar a Guarita no seu provedor). `connectionchallenge`

`Scan`

Estado de uma ronda. É o endpoint de polling depois de POST /scans.

Campo	Descrição
`id` stringsempre	Id da ronda.
`hostname` stringsempre	Alvo normalizado — é por ele que a cota de apps é contada.
`target` stringsempre	URL exata que você mandou escanear.
`status` stringsempre	Estado atual. `queuedrunninganalyzingdonefailedcanceled`
`created_at` stringsempre	Quando a ronda foi criada.
`finished_at` string \| nullsempre	Quando terminou. `null` enquanto roda.
`progress` ScanProgress \| nullsempre	Onde a ronda está enquanto roda — a mesma leitura da tela de espera. `null` quando não está rodando (ainda na fila, terminada, falha ou cancelada).
`summary` ScanSummary \| nullsempre	Resumo do resultado. `null` enquanto a ronda não produziu resultado (`queued`, `running`, `analyzing`) e numa ronda `failed` que morreu antes de gerar algo.

Scan · exemplo

{
  "id": "scan_7b3e9a12",
  "hostname": "app.exemplo.com.br",
  "target": "https://app.exemplo.com.br",
  "status": "done",
  "created_at": "2026-08-27T14:02:56.902Z",
  "finished_at": "2026-08-27T14:09:24.106Z",
  "progress": null,
  "summary": {
    "id": "scan_7b3e9a12",
    "target": "https://app.exemplo.com.br",
    "hostname": "app.exemplo.com.br",
    "status": "done",
    "score": 78,
    "riskLabel": "HIGH_RISK",
    "criticalCount": 2,
    "finishedAt": "2026-08-27T14:09:24.106Z",
    "durationMs": 387096,
    "blocked": false
  }
}

`ScanProgress`

Progresso de uma ronda em execução — o mesmo que a tela de espera mostra. Só existe enquanto a ronda roda.

Campo	Descrição
`phase` stringsempre	`running` = rodando as verificações · `analyzing` = na análise com IA. `runninganalyzing`
`done` integersempre	Verificações concluídas (fase `running`).
`total` integersempre	Verificações previstas nesta ronda.
`module` string \| nullsempre	Verificação em andamento (`headers`, `cors`, `supabase`…). `null` quando nenhuma está em andamento.
`with_ai` booleansempre	A análise com IA vem depois das verificações (define quantas etapas faltam).
`updated_at` stringsempre	Última atualização do progresso — string ISO 8601 em UTC (`2026-08-27T14:09:24.106Z`).

ScanProgress · exemplo

{
  "phase": "running",
  "done": 12,
  "total": 40,
  "module": "headers",
  "with_ai": true,
  "updated_at": "2026-08-27T14:04:31.219Z"
}

`ScanCreateRequest`

Corpo de POST /scans. Só target é obrigatório; o resto são as opções da tela, com os mesmos padrões. Booleanos aceitam true/false e as strings "true"/"false".

Campo	Descrição
`target` stringsempre	URL completa do alvo, começando com `http://` ou `https://`.
`ai` booleanpadrão: true	Análise com IA: explica cada achado e entrega o conserto pronto. Consome 1 análise da cota do mês e exige app verificado.
`infra` booleanpadrão: true	Descoberta e sondagem da infraestrutura por trás do app (Supabase, Firebase, clouds). Só leitura.
`authenticated` booleanpadrão: false	Testes autenticados: a Guarita cria um usuário de teste no seu app e checa, por dentro, se dá pra ver dados de outras pessoas. Exige plano com o recurso (Pro+) e app verificado. Pode disparar o e-mail de boas-vindas do seu app.
`aggressive` booleanpadrão: false	Modo agressivo: confirma as brechas explorando de verdade — cria, altera e apaga dados de teste (e limpa depois). Liga sozinho `authenticated` e `infra`. Exige plano com o recurso (Pro+), app verificado e `authorized_intrusive: true`. Prefira um ambiente de teste.
`authorized_intrusive` booleanpadrão: false	Só é lido com `aggressive: true`: a sua confirmação, POR RONDA, de que tem autorização expressa pra testes intrusivos neste alvo — os Termos (§2) exigem. Sem ela, `400 intrusive_unauthorized`.
`lgpd` booleanpadrão: false	Pré-diagnóstico LGPD: consentimento de cookies, rastreadores, política de privacidade, dado pessoal exposto e dados saindo do país. Exige plano com o recurso (Pro+). São sinais técnicos — não é parecer jurídico.
`infra_scope` string[]	Outros endereços SEUS que o app usa (`api.`, `cdn.`…), pra entrarem na sondagem de infra. Array de hostnames ou uma string separada por vírgula. Só o que é seu ou que você tem permissão de testar.

`ScanCreated`

Resposta 202 de POST /scans: a ronda foi aceita e enfileirada.

Campo	Descrição
`id` stringsempre	Id da ronda nova. Use em `GET /scans/{id}`.
`status` stringsempre	Estado inicial (`running`). `queuedrunninganalyzingdonefailedcanceled`

ScanCreated · exemplo

{
  "id": "scan_e11a03d9",
  "status": "running"
}

`ScanCanceled`

Resposta de POST /scans/{id}/cancel: o estado da ronda depois do pedido.

Campo	Descrição
`id` stringsempre	Id da ronda.
`status` stringsempre	`canceled` quando a ronda foi interrompida agora. Se já tinha terminado, vem o estado final que ela tinha (`done`, `failed` ou `canceled`). `queuedrunninganalyzingdonefailedcanceled`
`finished_at` string \| nullsempre	Quando a ronda parou.

ScanCanceled · exemplo

{
  "id": "scan_7b3e9a12",
  "status": "canceled",
  "finished_at": "2026-09-02T12:00:00.000Z"
}

`Report`

O relatório completo de uma ronda — o mesmo documento que o painel mostra e o PDF imprime. Formato do scanner, versionado por schemaVersion: camelCase na estrutura e snake_case dentro de ai.

Campo	Descrição
`schemaVersion` stringsempre	Versão do formato do relatório.
`scan` ReportScansempre	Metadados da execução.
`findings` Finding[]sempre	Os achados, do mais grave pro menos grave.
`ai` AiAssessmentsempre	Análise da IA. Numa ronda básica (`ai: false`), bloqueada ou parcial, vem com o `risk_score` calculado e os demais blocos vazios.
`infra` InfraInventorysempre	Inventário de infraestrutura observado (provedores, ativos, credenciais).
`strengths` string[]	O que o app já acerta — boas práticas comprovadas na ronda.
`lgpd` LgpdReadiness	Pré-diagnóstico LGPD. Só quando a ronda incluiu os módulos LGPD (`lgpd: true` em `POST /scans`, ou a opção da tela).

`ReportScan`

Metadados da execução da ronda.

Campo	Descrição
`id` stringsempre	Id da ronda.
`target` stringsempre	URL escaneada.
`hostname` stringsempre	Alvo normalizado.
`stack` string[]	Stack detectada (ex.: `["Lovable", "Supabase", "Vercel"]`).
`status` stringsempre	Estado. `queuedrunninganalyzingdonefailedcanceled`
`startedAt` string	Início da execução.
`finishedAt` string	Fim da execução.
`durationMs` integersempre	Duração em milissegundos.
`modulesRun` integersempre	Quantas verificações rodaram (descontando as puladas).
`passive` boolean	Ronda PASSIVA: só os checks observacionais, porque o domínio não estava verificado (ou excedia a cota de apps verificados do plano).
`blocked` boolean	A ronda não conseguiu ver o app. A IA é pulada e a cota NÃO é consumida.
`blockedReason` string	Motivo do bloqueio (só com `blocked`): `connection` ou `challenge`. `connectionchallenge`
`incomplete` boolean	O tempo esgotou e a ronda terminou PARCIAL (alguns módulos não rodaram). A IA é pulada e a cota não é consumida.

`Finding`

Um achado da ronda, com a camada leiga e o conserto (quando o plano destrava).

Campo	Descrição
`id` stringsempre	Id do achado DENTRO desta ronda. Renumera entre rondas — pra casar achados entre rondas use `module` + `title`.
`module` stringsempre	Verificação que produziu o achado (`secrets`, `cors`, `headers`, `supabase`…).
`title` stringsempre	Título técnico. Estável entre rondas (é a chave de identidade do achado).
`severity` stringsempre	Gravidade. `criticalhighmediumlowinfo`
`cvss` numbersempre	Pontuação CVSS.
`description` stringsempre	O que foi encontrado, em detalhe.
`evidence` stringsempre	A prova observada: requisição, resposta, trecho do bundle. Valores sensíveis vêm encurtados com `…` — a ronda não guarda o segredo inteiro.
`recommendation` stringsempre	Recomendação curta do scanner (não é o conserto pronto).
`confidence` string	`confirmed` = provado por observação ativa · `firm` = detecção determinística · `tentative` = heurística que pede confirmação. Ausente = `firm`. `confirmedfirmtentative`
`good` boolean	Achado POSITIVO: uma boa prática comprovada, não um problema.
`links` string[]	Ids de achados relacionados — hoje, os elos de uma cadeia de ataque (`module: "chain"`).
`friendly` FindingFriendly	A versão em português de gente.
`fix` FindingFix	O conserto pronto. Ausente quando retido pelo plano — aí vem `fixWithheld: true`.
`fixWithheld` boolean	O conserto existe, mas não está nesta resposta (plano sem análise com IA). Diz "foi retido", pra não parecer que a ronda não analisou.
`fixSample` boolean	Este é o achado-AMOSTRA da conta: o conserto veio inteiro mesmo sem plano. Uma por conta, não por ronda.
`fixFromCatalog` boolean	O conserto veio do catálogo determinístico, não da IA (ronda básica).

`FindingFriendly`

O achado em linguagem de produto.

Campo	Descrição
`headline` stringsempre	Título pra pessoa (sem jargão).
`whatItIs` stringsempre	O que é.
`whyItMatters` stringsempre	Por que importa.
`urgency` stringsempre	Urgência: agora · em breve · quando der. `nowsoonlater`

`FindingFix`

O conserto pronto pra colar numa IA de código (ou o passo manual, conforme kind).

Campo	Descrição
`prompt` stringsempre	Texto autossuficiente: problema + onde + o que fazer + como validar. É o que se copia e cola no chat da ferramenta.
`kind` string	Tipo de ação: `code` (cola numa IA de código) · `dns` (registro no painel de DNS) · `infra` (console do provedor) · `action` (ação manual) · `confirm` (como confirmar um achado `tentative` antes de mexer) · `chain` (feche qualquer elo da cadeia). `codednsinfraactionconfirmchain`
`code` string	Exemplo DIDÁTICO de como a correção costuma ficar. Não é o conserto do seu projeto — quem adapta é a IA, a partir do `prompt`.
`targets` string[]	Ferramentas pras quais o prompt foi escrito (`lovable`, `cursor`, `v0`, `bolt`…).

`AiAssessment`

Análise da IA sobre a ronda. Os blocos abaixo têm formato livre (são a saída do modelo) — leia risk_score e remediation_plan, que são estáveis.

Campo	Descrição
`executive_summary` stringsempre	Resumo executivo em português.
`risk_score` RiskScoresempre	Exposição consolidada (0–100 + faixa).
`remediation_plan` RemediationItem[]sempre	Plano de correção priorizado.
`infra_inventory` InfraInventoryEntry[]sempre	Inventário de infra na leitura da IA.
`finding_verifications` FindingVerification[]	Achados que a IA verificou ativamente, com veredito.
`risk_scenarios` object[]sempre	Cenários de ataque (formato livre).
`owasp_mapping` object[]sempre	Mapeamento OWASP (formato livre).
`additional_insights` object[]sempre	Observações extras (formato livre).
`cross_infra_chains` object[]sempre	Cadeias entre provedores (formato livre).
`discovered_vulnerabilities` object[]sempre	Vulnerabilidades descobertas pela IA (formato livre).

`RiskScore`

Exposição consolidada da ronda.

Campo	Descrição
`score` integersempre	0 = tranquilo · 100 = muito exposto. Faixas: seguro (0–14) · baixo (15–39) · médio (40–69) · alto (70–100).
`label` stringsempre	Faixa do score. `SECURELOW_RISKMODERATE_RISKHIGH_RISKCRITICAL_RISK`
`justification` stringsempre	Por que esse número.

`RemediationItem`

Um passo do plano de correção.

Campo	Descrição
`priority` integersempre	Ordem (1 = primeiro).
`finding_ids` string[]sempre	Achados que este passo fecha.
`action` stringsempre	O que fazer.
`effort` stringsempre	Esforço estimado. `quick_winmoderatesignificantmajor_refactor`
`impact_if_not_fixed` stringsempre	O que acontece se não fizer.
`scoreImpact` integer	Quantos pontos de exposição este passo derruba.

`InfraInventoryEntry`

Um ativo de infra na leitura da IA.

Campo	Descrição
`provider` stringsempre	Provedor (`supabase`, `aws`, `vercel`…).
`asset` stringsempre	O ativo (host, bucket, função).
`kind` stringsempre	Tipo do ativo.
`exposure` stringsempre	Como ele está exposto. `publicauthenticatedcredential_leakedinternal`
`notes` stringsempre	Observações.

`FindingVerification`

Veredito da IA sobre um achado que ela testou ativamente.

Campo	Descrição
`ref_id` stringsempre	Id do achado verificado.
`verdict` stringsempre	`confirmed` = exploração observada · `refuted` = testado e não se sustenta (alarme falso). `confirmedrefuted`
`evidence` stringsempre	A prova observada.

`InfraInventory`

Inventário de infraestrutura observado pelo scanner.

Campo	Descrição
`assets` InfraAsset[]sempre	Ativos descobertos.
`credentials` InfraCredential[]sempre	Credenciais encontradas (valores sensíveis encurtados).
`providers` string[]sempre	Provedores detectados.
`scopeHosts` string[]sempre	Hosts que entraram no escopo da ronda.
`notes` string[]sempre	Observações.

`InfraAsset`

Um ativo de infraestrutura (projeto BaaS, bucket, função, banco…).

Campo	Descrição
`id` stringsempre	Id do ativo dentro da ronda.
`provider` stringsempre	Provedor.
`kind` stringsempre	Tipo. `baas_projectobject_storageserverless_fnauthdatabaseapicdn_host`
`endpoint` stringsempre	Endereço do ativo.
`identifier` string	Identificador no provedor (id do projeto, nome do bucket).
`credentials` InfraCredential[]sempre	Credenciais ligadas a este ativo.
`evidence` stringsempre	Onde foi observado.
`relatedTo` string[]sempre	Ids de ativos relacionados.

`InfraCredential`

Uma credencial observada.

Campo	Descrição
`kind` stringsempre	Tipo da credencial. `anon_keyservice_rolepublishableapi_keyaccess_keyjwtconnection_stringpresigned_url`
`provider` stringsempre	Provedor.
`value` stringsempre	Valor observado — encurtado quando sensível.
`source` stringsempre	Onde foi encontrada.
`sensitive` booleansempre	É segredo (não deveria estar público).

`LgpdReadiness`

Pré-diagnóstico técnico de indicadores LGPD. NÃO é parecer jurídico nem atesta conformidade.

Campo	Descrição
`score` integersempre	Prontidão indicativa (maior = menos indícios de não-conformidade).
`label` stringsempre	Faixa da prontidão.
`categories` object[]sempre	Pontuação por categoria (transparência, consentimento, segurança…).
`findingCount` integersempre	Quantos achados têm relação com a LGPD.
`disclaimer` stringsempre	O aviso obrigatório: pré-diagnóstico automatizado, não substitui revisão por encarregado/advogado.

`Error`

Todo erro tem a mesma forma. Trate pelo error; mostre a message.

Campo	Descrição
`error` stringsempre	Código estável, feito pro seu código ler.
`message` stringsempre	Texto em português, feito pra uma pessoa ler no log.

Error · exemplo

{
  "error": "unauthorized",
  "message": "Chave de API ausente ou inválida. Envie `Authorization: Bearer gsk_...` — crie a sua em Configurações > Desenvolvedores."
}

`WebhookEnvelope`

O corpo de todo POST de webhook.

Campo	Descrição
`id` stringsempre	Id do EVENTO (`evt_` + UUID). Estável entre reentregas — é por ele que se deduplica.
`event` stringsempre	Qual evento. `scan.completedscan.failedfinding.opened`
`createdAt` stringsempre	Quando o evento aconteceu — string ISO 8601 em UTC (`2026-08-27T14:09:24.106Z`).
`data` objectsempre	Carga específica do evento (veja cada um).

Achou algo errado ou faltando? help@guarita.dev — com o x-request-id, se for sobre uma resposta.