Sirveil Exposure

API reference

Dois endpoints faturáveis. Uma tabela de preços. Implemente em uma tarde.

US$ 0,10 por verificação concluída. US$ 0,35 por varredura concluída. US$ 0,00 para qualquer coisa que não pudemos atender — nossas falhas e as de nossos provedores são custo nosso, não seu. Tudo abaixo é legível sem conta.

Versão de pré-visualização — valores fixados no lançamento.

Início rápido

URL base https://ai.sirveil.ai. Autenticação é uma única chave bearer. Sem SDK para instalar, sem dança de OAuth, sem sandbox para solicitar — sua primeira resposta real está a um curl de distância. Pegue uma chave em /scan-api/signup e o medidor começa em zero.

Início rápido

curlPythonNode

Copiar

Uma verificação — uma pessoa, um site que você indica. Feito para

domínios de corretores e busca de pessoas; "não foi possível dizer" é uma resposta real.

Os campos de identidade vão dentro de "identity"; o domínio permanece no nível superior.

curl https://ai.sirveil.ai/api/v1/verify
-H "Authorization: Bearer sk_live_…"
-d '{ "identity": { "firstName":"Jane", "lastName":"Doe", "phone":"5035551212" }, "domain":"examplebroker.com" }'

→ uma resposta estruturada, com suas evidências

{ "state": "indexed", "domain": "examplebroker.com", "evidence": [ … ], "dropped_fields": [], "billed": "$0.10" // chamadas com falha: $0.00 }

pip install requests — essa é toda a história do SDK

import requests

r = requests.post("https://ai.sirveil.ai/api/v1/verify", headers={"Authorization": "Bearer sk_live_…"}, json={"identity": {"firstName": "Jane", "lastName": "Doe", "phone": "5035551212"}, "domain": "examplebroker.com"})

print(r.json()["state"]) # indexed | not_indexed | indeterminate

// sem SDK para instalar — fetch é o cliente const r = await fetch("https://ai.sirveil.ai/api/v1/verify", { method: "POST", headers: { Authorization: "Bearer sk_live_…" }, body: JSON.stringify({ identity: { firstName: "Jane", lastName: "Doe", phone: "5035551212" }, domain: "examplebroker.com" }) }); const result = await r.json(); console.log(result.state); // indexed | not_indexed | indeterminate

Essa chamada cobrou dez centavos. Se tivesse falhado, não teria cobrado nada. Essa é toda a relação comercial — o resto desta página é detalhe.

Autenticação

Toda requisição carrega um cabeçalho. As chaves têm o formato sk_live_… e vêm de /scan-api/signup — minutos, não reuniões. A chave é a conta: ela identifica você, mede seu uso, e é só isso que ela faz.

CabeçalhoCopiar

Authorization: Bearer sk_live_…

• Mantenha no lado do servidor. Uma chave bearer em JavaScript de navegador é uma chave bearer que você publicou. Faça proxy das chamadas pelo seu backend.
• Rotacione livremente. Emita uma nova chave, mova o tráfego, revogue a antiga — o medidor segue a conta, não a chave.
• Chave ausente ou inválida → 401, cobrado $0,00, como todo erro.

Construindo uma boa requisição

Ambos os endpoints aceitam a mesma forma de identidade: um objeto JSON identity contendo tudo o que sabemos sobre o sujeito. Apenas identity.firstName e identity.lastName são obrigatórios — mas o nome só abre a porta. O que torna a resposta digna de pagamento é um identificador forte junto com ele. Uma requisição com nome e telefone é uma experiência de produto materialmente diferente de uma requisição apenas com nome.

Qual identificador enviar primeiro

Classificamos os identificadores por quão bem eles realmente recuperam em nossas próprias execuções contra nossa própria amostra — não por quão seletivos parecem no papel. A classificação abaixo é a ordem que a busca realmente valoriza, em ambos os endpoints:

Classificação	Identificador	Por que está nessa posição
1º	telefone	Páginas de perfil de corretores são indexadas por números de telefone. O melhor campo para enviar.
2º	e-mail	Quase único na web aberta. Um forte segundo se você não tiver telefone.
3º	streetAddress1 + cidade/estado	Forte — páginas de corretores também são indexadas por endereço — mas é o campo que as pessoas mais relutam em fornecer na primeira passagem.
—	apenas nome	O plano B. Funciona, mas é o caso fraco — veja os avisos de piso em cada endpoint.

Por que telefone supera e-mail aqui. Em uma busca web geral, um endereço de e-mail é o identificador mais seletivo — uma consulta de e-mail puro é quase única em toda a internet. Mas quando a consulta é limitada a um único domínio de corretor, essa classificação se inverte: páginas de perfil de corretores são construídas em torno de números de telefone e endereços, e muitas vezes nem imprimem um e-mail. Então a busca lidera deliberadamente com telefone, contra a ordem mais óbvia. A ordenação veio de nossas próprias execuções — não publicamos nenhuma figura de precisão para o Serviço, e esta não é uma.

• city + state são a defesa mais barata contra colapso de homônimos. Para qualquer nome comum, são a diferença entre uma resposta sobre uma pessoa e uma resposta sobre quatro.
• streetAddress1 é recomendado, não mínimo — envie quando tiver, mas não deixe que isso fique entre você e sua primeira chamada.
• usernames estende a busca por uma grande lista de sites públicos. Só é executado em um identificador que você declara — nunca adivinhamos um para você.

Campos que não podemos usar: dropped_fields

Um campo que não podemos usar — um número de telefone malformado, uma data de nascimento não analisável — é descartado e nomeado no array dropped_fields na resposta. Isso nunca falha a requisição inteira, e nunca é silenciosamente ignorado: um campo silenciosamente ignorado significaria que você pagou preço cheio por uma busca mais fraca sem como descobrir. Nomear o campo descartado é como você descobre.

Dica de integração: registre dropped_fields durante sua implementação. É a maneira mais rápida de detectar uma incompatibilidade de formatação entre seu modelo de dados e o nosso — e transforma um vago ticket de "os resultados parecem fracos" em uma correção de uma linha do seu lado.

POST/api/v1/verify

A verificação — uma pessoa, um domínio que você indica. Síncrona. Mediana de 890 ms, p95 de 1.463 ms (benchmarks).

Pergunte se uma pessoa está indexada em um único site. Domínios de corretores e busca de pessoas retornam veredictos decidíveis; sites com login obrigatório ou noindex retornam um honesto indeterminate em vez de um falso "não". Toda resposta chega com suas evidências.

Corpo da requisição

Os campos de identidade viajam dentro de um objeto identity; domain permanece no nível superior. Este é o corpo que recomendamos enviar — quatro campos, liderado por telefone:

Recomendado — 4 camposCopiar

{ "identity": { "firstName": "Jane", "lastName": "Doe", "phone": "5035551212" }, "domain": "examplebroker.com" }

O telefone é o identificador de maior classificação neste endpoint — páginas de perfil de corretores são indexadas por números de telefone — então esta forma produz uma consulta ancorada por identificador em vez do fallback apenas com nome (veja Construindo uma boa requisição). Sem telefone? Substitua por email. Nem um nem outro? streetAddress1 mais city.

Mínimo — 3 campos (o piso, não a recomendação)Copiar

{ "identity": { "firstName": "Jane", "lastName": "Doe" }, "domain": "examplebroker.com" }

O piso funciona, mas não lidere com ele. Uma requisição apenas com nome executa a busca mais fraca possível a preço cheio, e é a requisição mais provável de responder indeterminate — uma chamada tecnicamente bem-sucedida que parece uma falha. Envie um identificador forte junto com o nome.

Campo	Tipo	Obrigatório	Notas
identity.firstName	string	obrigatório	Nome de batismo do sujeito, como um corretor o listaria.
identity.lastName	string	obrigatório	Sobrenome do sujeito.
identity.phone	string	opcional	Identificador de maior classificação aqui. Fornecer telefone ou e-mail é o que transforma um fallback apenas com nome em uma busca ancorada por identificador.
identity.email	string	opcional	Segundo na classificação. Quase único na web aberta; menos em páginas de corretores, que raramente imprimem um.
identity.city	string	opcional	Com o estado, a defesa mais barata contra colapso de homônimos em nomes comuns.
identity.state	string	opcional	Estado dos EUA com duas letras, ex.: "OR".
identity.streetAddress1	string	opcional	Recomendado, não mínimo — a terceira forma de identificador, forte quando fornecido.
identity.dateOfBirth	string	opcional	Ajuda a confirmar uma correspondência. Valores não analisáveis são descartados e nomeados em dropped_fields.
identity.employer	string	opcional	Desambiguação extra quando corretores listam um.
identity.usernames	array	opcional	Estende a busca por sites públicos — apenas para identificadores que você declara; nunca adivinhamos um.
domain	string	obrigatório	Nível superior, ao lado de identity. O site a verificar, hostname puro — ex.: examplebroker.com. Qualquer site público é aceito exceto uma classe (veja domain_excluded em Erros); a decidibilidade depende da classe (veja Status).

Por que o nome é obrigatório. Não existem consultas apenas com telefone ou apenas com e-mail — nunca, em nenhum nível. O nome é a âncora contra a qual cada registro candidato é pontuado; sem ele, nada decide se o registro que encontramos é a pessoa certa. Outros fornecedores retornarão uma correspondência por número de telefone sem nunca dizer quão confiantes estão de que é a pessoa certa. Nós não faremos isso. Um identificador forte junto com o nome é o que torna o resultado digno de pagamento.

Resposta

200 OKCopy

{ "state": "indexed", // indexed | not_indexed | indeterminate "domain": "examplebroker.com", "evidence": [ { "source": "https://examplebroker.com/profile/jane-doe-tx-1982", "query": ""Jane Doe" site:examplebroker.com", "observed_at": "2026-08-16T14:02:11Z" } ], "dropped_fields": [], // any unusable inputs, named — never silently ignored "billed": "$0.10" // failed calls: $0.00 }

dropped_fields lista quaisquer campos de identidade que não pudemos usar — um telefone malformado, uma data de nascimento impossível de interpretar — descartados e nomeados em vez de falhar a solicitação ou desaparecer silenciosamente. Veja Construindo uma boa solicitação.

Cobrança: $0,10 por verificação concluída — e indeterminate é uma verificação concluída, porque "a busca pública não consegue ver" é uma resposta real. Uma chamada que não pudemos atender — por culpa nossa ou de um fornecedor upstream — cobra $0,00. Uma chamada que é concluída cobra, inclusive se seu cliente parou de esperar por ela.

POST/api/v1/scan

A varredura completa — uma pessoa, doze domínios consultados, todos os 548 reconciliados. Síncrona por padrão. Mediana de 154 s, mais lenta em 203 s (n=5; nossas execuções em nossos dados, não uma garantia).

Uma varredura consulta um conjunto fixo de doze domínios de busca de pessoas; os resultados são classificados em relação ao Registro — atualmente 548 domínios, derivados do registro de corretores de dados da Califórnia, um registro público que você pode auditar, além de um conjunto prioritário selecionado — e a cobertura é reportada sobre ele. O Registro não é a lista de consulta, e uma varredura não consulta todos os domínios nele. O que os $0,35 fixos compram é doze domínios consultados e todos os 548 reconciliados — os que alcançamos e, pelo nome, os que não alcançamos.

É um POST síncrono simples e comum. Você chama, a linha permanece aberta, o relatório concluído volta no corpo. Sem job para monitorar, sem callback para hospedar, nada para ativar — é simplesmente o que acontece. A única coisa a saber: leva cerca de dois minutos e meio, e a execução mais lenta que medimos foi de 203 segundos, então defina o timeout do seu cliente acima disso. Se sua stack odeia conexões longas, há um header para isso — veja abaixo.

Corpo da solicitação

Mesma forma que uma verificação: campos de identidade dentro de um objeto identity. Este é o corpo que recomendamos para uma varredura — seis campos:

Recomendado — 6 camposCopy

{ "identity": { "firstName": "Jane", "lastName": "Doe", "phone": "5035551212", "email": "jane.doe@example.com", "city": "Portland", "state": "OR" } }

Cada campo merece seu lugar: o nome passa pelo portão; telefone e email são o que a busca liderada por identificador realmente usa; cidade e estado são a defesa mais barata contra o colapso de homônimos — em um nome comum, a diferença entre um relatório sobre uma pessoa e um relatório sobre quatro. Detalhes em Construindo uma boa solicitação.

Mínimo — 2 campos (o piso, não a recomendação)Copy

{ "identity": { "firstName": "Jane", "lastName": "Doe" } }

O piso funciona, mas não comece com ele. Uma varredura apenas com nome custa os mesmos $0,35 que qualquer outra e executa a busca mais fraca possível — preço cheio para a configuração com menor probabilidade de encontrar o que existe, e a mais propensa a responder indeterminate onde uma solicitação mais forte teria decidido. Envie um identificador forte junto com o nome.

Campo	Tipo	Obrigatório	Notas
identity.firstName	string	obrigatório	Nome de batismo do sujeito.
identity.lastName	string	obrigatório	Sobrenome do sujeito.
identity.phone	string	opcional	Identificador de maior prioridade. Fornecer telefone ou email é o que transforma uma varredura apenas com nome em uma ancorada por identificador.
identity.email	string	opcional	Segundo identificador em prioridade; quase único na web aberta.
identity.city	string	opcional	Com o estado, defende contra o colapso de homônimos em nomes comuns.
identity.state	string	opcional	Estado dos EUA com duas letras, ex.: "OR".
identity.streetAddress1	string	opcional	Recomendado, não mínimo — o terceiro formato de identificador; páginas de perfil de corretores são indexadas por endereço.
identity.dateOfBirth	string	opcional	Ajuda a confirmar uma correspondência. Valores impossíveis de interpretar são descartados e nomeados em dropped_fields.
identity.employer	string	opcional	Desambiguação extra quando os corretores listam um.
identity.usernames	array	opcional	Estende a varredura por uma grande lista de sites públicos — apenas para identificadores que você declara; nunca adivinhamos um.
webhook_url	string	opcional	Nível superior, ao lado de identity. Ainda não ativo — a superfície de entrega está especificada, não implementada; veja Webhooks. Quando for lançado, aplica-se apenas a chamadas Prefer: respond-async, já que uma chamada síncrona já entregou o relatório a você.

Resposta — o padrão

Nada para ativar. O relatório concluído é o corpo da resposta.

200 OK · o relatório completoCopy

{ "job_id": "job_9f2c…", "status": "complete", "summary": { "indexed": 5, "not_indexed": 7, "indeterminate": 0 }, "coverage": { … }, // all 548 reconciled — see Statuses & evidence "results": [ … ], "billed": "$0.35" }

Não quer manter a linha aberta? Prefer: respond-async

Um header, e pegamos o job e entregamos um ticket para você:

Solicitação · adesão assíncronaCopy

curl https://ai.sirveil.ai/api/v1/scan
-H "Authorization: Bearer sk_live_…"
-H "Prefer: respond-async"
-d '{ "identity": { "firstName":"Jane", "lastName":"Doe", "phone":"5035551212" } }'

202 Accepted · somente assíncronoCopy

{ "job_id": "job_9f2c…", "status": "queued" }

Depois, consulte GET /api/v1/jobs/:job_id quantas vezes quiser — a consulta é gratuita. (Um campo webhook_url existe na forma, mas webhooks ainda não foram implementados — não projete em torno disso hoje.) Assíncrono muda quando a resposta chega, não o que ela diz nem o que custa. Mesmo relatório, mesmos $0,35.

Cobrança: $0,35 por varredura concluída, cobrada quando a varredura termina — não quando começa. Uma varredura que não pudemos atender cobra $0,00, em qualquer modo — mas uma varredura que conclui cobra mesmo se seu cliente desistiu de esperar. Veja a armadilha abaixo.

Uma armadilha, e é a que o padrão síncrono cria. Uma varredura que roda até o fim é uma resposta concluída, e cobra esteja você ainda na linha para recebê-la ou não. Desligue aos 120 segundos em uma execução que termina aos 154 e o trabalho foi feito, o medidor diz isso, e você nunca viu o relatório. Duas maneiras de não pagar por uma resposta que você não leu: defina o timeout acima de 203 segundos, ou envie Prefer: respond-async e colete do job. Melhor ouvir isso aqui do que de uma fatura.

GET/api/v1/jobs/:job_id

Colete uma varredura assíncrona — o relatório concluído, ou o progresso dela.

Você só precisa disso se enviou Prefer: respond-async; uma varredura padrão já entregou o relatório a você. Enquanto uma varredura assíncrona roda, status é queued ou running. Quando muda para complete, o relatório completo está no corpo, cada entrada com seu veredito e suas evidências. Buscar um job é gratuito — consulte o quanto quiser.

Resposta

200 OK · completoCopy

{ "job_id": "job_9f2c…", "status": "complete", // queued | running | complete | failed "summary": { "indexed": 5, "not_indexed": 7, "indeterminate": 0 // verdicts for the domains actually queried }, "coverage": { … }, // and the rest of the registry, named — see Statuses "results": [ { "domain": "examplebroker.com", "state": "indexed", "evidence": [ … ] }, { "domain": "quietbroker.example", "state": "not_indexed", "evidence": [ … ] } // … one entry per domain queried, each with its source ], "billed": "$0.35" // a failed job: $0.00 }

Cobrança: os $0,35 pertencem à varredura, não à busca. GET /api/v1/jobs/:id em si é gratuito em qualquer frequência de consulta.

GET/api/v1/whoami

Sua chave, seu plano, seus limites — gratuito, e não consome cota.

Entregue sua chave bearer e ele informa a qual conta a chave pertence, em qual plano essa conta está, e o limite de taxa, a permissão restante e o teto que se aplicam a você. É a resposta real para "quais são meus limites?" — melhor do que qualquer coisa que possamos imprimir em uma página, porque um número impresso pode ficar desatualizado para sua conta e este não pode.

Também é a primeira chamada certa em qualquer integração: prova que a chave funciona antes de você gastar um centavo. Uma chave errada ou revogada retorna 401 aqui por $0,00, em vez de na sua primeira chamada cobrável.

200 OKCopy

curl https://ai.sirveil.ai/api/v1/whoami
-H "Authorization: Bearer sk_live_…"

→ quem você é e o que se aplica a você

{ "plan": "developer", "rate_limit_per_minute": …, "quota_remaining": …, // units: a check is 1, a sweep is 100 "spend_ceiling" // our supplier-cost guard, not a cap on your bill: … }

ConfirmarOs nomes exatos dos campos estão sendo fixados com a engenharia antes do lançamento. Os quatro fatos — conta, plano, limites, restante — são o conteúdo comprometido; leia a resposta ao vivo como fonte da verdade em vez deste exemplo.

Cobrança: gratuito. Sem cobrança, sem unidade de cota, em qualquer frequência de consulta. Não vamos medir você por perguntar quanto ainda tem.

POST/api/v1/mcppreview

Uma superfície de Model Context Protocol para agentes — uma ferramenta somente leitura hoje.

Integrando isso a um agente em vez de uma aplicação? Este endpoint fala MCP sobre a mesma chave bearer. Ele expõe uma única ferramenta somente leitura — não a API inteira — e nada nas respostas muda: mesmos vereditos, mesmas evidências, mesmos três estados. Ele cobra exatamente como o endpoint subjacente. Uma verificação feita via MCP é uma verificação de $0,10 e uma unidade. Estamos dizendo isso aqui em vez de deixar você descobrir na fatura, porque um agente em loop gasta dinheiro real na velocidade da máquina. Leia seu saldo restante de volta de GET /api/v1/whoami antes de apontar um para isso.

PréviaA superfície MCP não é congelada em versão: nomes de ferramentas e esquemas podem avançar em relação aos endpoints que eles encapsulam, e o processo de mudança de quebra ainda não cobre isso. Mudanças chegam em /scan-api/changelog.

Status e evidências

Cada veredito é uma de três strings. Não há uma quarta, e não há "provavelmente".

indexed

A busca pública pode ver uma página para este assunto neste domínio. O array de evidências diz exatamente onde e como.

not_indexed

Ausente do índice de busca para este domínio — o que não é o mesmo que ausente do site, e não vamos fingir que é. Retornado apenas quando a forma de consulta por nome foi executada e voltou vazia.

indeterminate

Não existe um sim/não honesto. Quatro maneiras de chegar aqui: a identidade era somente nome; o texto da página não continha o nome completo declarado; a confiança caiu abaixo do limite de lançamento; ou o domínio é protegido por login ou noindex.

Um nome sozinho nunca pode retornar indexed. Uma correspondência de nome sozinha não pode distinguir esta pessoa de todos os outros que compartilham o nome, então ela cai em indeterminate toda vez. Envie um telefone se tiver um — a seletividade segue telefone → e-mail → endereço → nome, que é invertido em relação à busca web geral de propósito: um perfil de corretor com escopo site: é chaveado por telefone e endereço e frequentemente não imprime nenhum e-mail.

A decidibilidade depende da classe, e dizemos em qual classe você está. Domínios de corretores de dados e busca de pessoas retornam vereditos decidíveis, porque ser publicamente encontrável é o modelo de negócios deles. Sites protegidos por login ou noindex retornam indeterminate — se a busca pública não pode ver a página do assunto, nós também não podemos, e nem o estranho com quem você está preocupado. Um indeterminate que calculamos é uma resposta completa e cobrada; uma chamada que não pudemos atender cobra $0,00. E se nosso provedor de busca cair, você recebe indeterminate com outcome: unserved e uma conta de nada — nós pagamos por essa tentativa, não você.

**Negativos são o produto — e também é assumir o que não alcançamos.**Uma varredura consulta um conjunto fixo e priorizado de domínios de busca de pessoas e, em seguida, relata um resultado para cada domínio no registro em quatro categorias: indexed, not_indexed, indeterminate e não alcançado — nomeado, até o limite por resposta (never_queried_truncated informa quando a lista foi cortada). Os "nãos" datados permitem que você diga a um cliente "você está limpo aqui" e prove isso. As lacunas nomeadas são o que permitem que eles acreditem no resto. Publicamos o que perdemos, o que, pelo que sabemos, nos torna os únicos que fazem isso.

O bloco de cobertura

Toda varredura retorna um objeto de cobertura ao lado dos resultados. Nada se esconde em um erro de arredondamento:

coverageCopy

{ "expected": 548, "queried_hit": 5, "queried_empty": 7, "queried_failed": 0, "never_queried": 536, "never_queried_domains": [ "..." ], // nomeado, limitado a 100 por resposta "never_queried_truncated": true }

ConfirmarOs números das categorias acima são formas ilustrativas, não uma execução real. Uma distribuição ao vivo vai aqui assim que a engenharia entregar uma — preferimos mostrar um espaço reservado que rotulamos do que um número que inventamos.

Toda resposta carrega seus próprios limites, no corpo. Uma string contract.limitation é enviada dentro de toda resposta de verificação dizendo o que o endpoint realmente fez: leu um índice de busca, não buscou a página. Está no payload, não em uma nota de rodapé que você teria que procurar.

Toda resposta é reproduzível — incluindo as que deram errado. Cada uma carrega pipeline_version, linkage_weights_version e calibration_version, em 400s e 500s, bem como em sucessos. Deliberadamente: um registro que carimba apenas suas vitórias tem um buraco exatamente onde estão as perdas.

Confiança e vinculação são diagnósticos, não determinações. Onde confidence, calibrated_probability ou linkage por campo retornam, eles explicam como um veredito foi alcançado. Não os trate como uma medida de precisão, e por favor não mostre um deles a um assunto como uma pontuação.

O array de evidências

Cada resultado mostra seu trabalho: de onde veio, o que perguntamos e quando olhamos. Verificamos o que a busca pública pode ver, porque é isso que um abusador ou um estranho pode ver.

**Os dois endpoints não alcançam os mesmos lugares, e não vamos misturá-los.**Uma verificação alcança exatamente um terceiro — o provedor de busca — e não faz chamadas de modelo. Apenas consultas públicas, sem logins, sem portas dos fundos. Uma varredura vai mais longe: além do provedor de busca, pode consultar fontes de enriquecimento de identidade, violações e logs de stealer, e registros judiciais, além de páginas públicas de nome de usuário onde você forneceu um handle, e usa inferência de modelo para julgar e formular resultados. Algumas dessas são dados de assinatura comercial, não páginas web públicas. Nenhum endpoint jamais faz login em nada ou contorna um controle de acesso. O relato completo está em Aviso de Privacidade da API §5.

Entrada de evidênciaCopy

{ "source": "https://examplebroker.com/profile/jane-doe-tx-1982", // URL pública que vimos "query": ""Jane Doe" site:examplebroker.com", // a consulta que executamos "observed_at": "2026-08-16T14:02:11Z" // quando olhamos (UTC) }

PréviaOs três campos acima — URL de origem, consulta usada, timestamp de observação — são a forma comprometida; nomes exatos de campos são fixados no lançamento.

O que mantemos

Seção curta, porque não há muito o que manter. A identidade que você envia é usada para responder à chamada que você fez, e esse é todo o trabalho que ela faz.

• Uma chamada síncrona não grava nada sobre o assunto no armazenamento. O caminho de verificação é protegido em código contra gravações no banco de dados.
• Uma exceção, e é o cache. O texto da consulta normalizada — que contém o identificador — fica na memória em uma instância por cerca de 15 minutos, particionado por conta e nunca gravado em disco. O mesmo cache que torna uma resposta repetida consistente, e o mesmo que cobra integralmente. Preferimos nomeá-lo do que deixar "não persiste nada" fazer um trabalho que não pode fazer.
• Um trabalho assíncrono mantém a identidade que você enviou e o relatório concluído por 24 horas para que você tenha tempo de coletá-lo, e então o corpo armazenado é anulado. Essa janela é o preço de não manter uma conexão aberta.
• A linha de medição é mantida indefinidamente — conta, chave, endpoint, timestamp, status, latência, unidades cobradas, resultado, identificador de execução. Sem corpos de solicitação, sem corpos de resposta. Uma fatura que você pode auditar tem que sobreviver aos dados a partir dos quais foi calculada; ela não precisa contê-los.
• Não vendemos ou compartilhamos seus identificadores ou sua saída, e não treinamos modelos neles.

Estes são comportamentos atuais, não o limite externo. O Aviso de Privacidade da API é o documento governante, e §7 é a autoridade sobre retenção. É explícito que a linha de atividade por chamada não tem expiração definida hoje — uma decisão não resolvida, não uma projetada, e diz isso nessas palavras. O que está acima é o que o sistema faz hoje. Onde os dois diferem, o Aviso governa.

Erros

Erros são JSON, dizem o que deu errado em palavras, e nunca cobram. Uma forma, em todos os lugares:

Corpo de erroCopy

{ "error": { "type": "identity_incomplete", "message": "identity.firstName e identity.lastName são obrigatórios — o nome é a âncora contra a qual cada correspondência é pontuada.", "doc_url": "https://sirveil.ai/scan-api/docs#errors" } }

Status	Significado	Cobrado
400	Solicitação malformada — JSON quebrado, campo obrigatório ausente. Tipos nomeados abaixo.	$0,00 — nunca
401	Chave de API ausente, revogada ou errada.	$0,00 — nunca
402	spend_ceiling_reached — um teto de nível de conta está em vigor. Ele protege nosso custo de fornecedor, não um limite na sua conta. Veja Limites de taxa.	$0,00 — nunca
403	tenant_suspended — a conta está suspensa; ou domain_excluded — você nomeou um domínio na classe de reconhecimento facial e identificação biométrica, a única recusa que não é dispensável.	$0,00 — nunca
404	Sem rota, ou sem job_id na sua conta.	$0,00 — nunca
410	result_expired — você consultou um trabalho assíncrono após sua janela de 24 horas. Uma resposta explícita, não um silêncio que você teria que interpretar.	$0,00 — nunca
422	JSON válido, valores inutilizáveis — por exemplo, um domínio que não é um hostname.	$0,00 — nunca
429	rate_limited — muitas solicitações por minuto. Recue, respeite Retry-After, continue.	$0,00 — nunca
429	quota_exceeded — a cota de unidades do mês está gasta. Mesmo status, problema diferente: esperar não vai corrigir este.	$0,00 — nunca
500	Culpa nossa. Seguro tentar novamente; se persistir, nos avise. /scan-api/status é apenas informativo — não é uma métrica de disponibilidade, não é um compromisso de nível de serviço (Termos da API §11).	$0,00 — nunca
503	search_unavailable — uma fonte de recuperação está fora do ar. Em uma verificação, você pode, em vez disso, receber um indeterminate honesto com um resultado não atendido.	$0,00 — nunca
503	async_not_available — você enviou Prefer: respond-async em uma implantação onde async não está disponível. Nada é cobrado.	$0,00 — nunca
503	capacity_reached — um guarda diário de toda a plataforma. Não é você, não é sua integração. Tente mais tarde.	$0,00 — nunca

Tipos de erro nomeados

Tipo	Status	O que significa
identity_incomplete	400	A requisição está sem um nome. A mensagem real da API: "identity.firstName e identity.lastName são obrigatórios — o nome é a âncora contra a qual cada correspondência é pontuada." Ambos os endpoints a retornam.
invalid_domain	400	Somente POST /api/v1/verify: o domínio de nível superior está ausente ou não é um hostname simples utilizável. Não há lista de permissões — qualquer hostname público é aceito, exceto a classe excluída abaixo — mas precisa ser um hostname.
rate_limited	429	Chamadas demais por minuto. Retry-After informa quanto tempo esperar. Esperar resolve.
quota_exceeded	429	A cota de unidades do mês acabou. Esperar não resolve — a cota é redefinida no início do próximo mês UTC, ou peça para aumentarmos.
spend_ceiling_reached	402	Um teto no nível da conta está em vigor e novas chamadas são recusadas até que seja elevado. Ele mede o custo do nosso fornecedor, não um limite na sua fatura. Não é uma cobrança; nada é faturado. Vendo isso em uso normal? support@sirveil.ai e nós elevamos — preferimos ajustar um número a perder seu tráfego.
capacity_reached	503	Uma proteção diária em toda a plataforma. Nada errado com sua chave ou sua requisição.
tenant_suspended	403	A conta está suspensa. A suspensão é regida pelos Termos da API; se você está vendo isso e não sabe o motivo, support@sirveil.ai informará.
domain_excluded	403	Você indicou um domínio na classe de reconhecimento facial e identificação biométrica — um serviço cuja função principal é identificar uma pessoa a partir de uma imagem ou de um modelo biométrico. Recusado antes de qualquer consulta ser montada e antes de qualquer cobrança. É um controle no código, em ambos os endpoints, e não é dispensável — nem por nós, nem por qualquer preço.

Cada um destes é recusado antes de qualquer busca ser executada — nenhum trabalho é feito, nada é cobrado, e o custo registrado é null, não zero. Uma requisição recusada não nos custou nada para responder, e não vamos afirmar uma medição que nunca fizemos.

A coluna de cobrança não é uma nota de cortesia — é o modelo de preços. Você é cobrado por resposta concluída, e um erro não é uma resposta. Problemas de infraestrutura são custo nosso, não seu.

Limites de taxa

Generosos por padrão, aumentados mediante solicitação. Os limites são definidos para acomodar tráfego normal de integração — consultar GET /api/v1/jobs/:id enquanto uma varredura roda, com certeza incluído. Eles são aplicados com base no melhor esforço e podemos ajustá-los, então leia os seus em whoami em vez de supor. Quatro limites podem dizer não, verificados em ordem para que você sempre receba a resposta mais específica disponível. Todos os quatro cobram $0,00.

• Limite de taxa — 429 rate_limited, com um cabeçalho Retry-After. Respeite-o e você está bem.
• Cota de unidades, quando sua conta tem uma — 429 quota_exceeded. Uma verificação custa 1 unidade, uma varredura custa 100, em um mês civil UTC. Contas do marketplace são provisionadas sem limite de unidades.
• Teto da conta — 402 spend_ceiling_reached. Chamadas são recusadas, não cobradas. Peça e nós elevamos. Uma coisa que não é: o teto é medido contra o nosso custo de fornecedor para sua conta, não contra sua fatura. Não é proteção de gastos e não vamos fingir que é — a única coisa que limita uma fatura medida é o número de chamadas que sua integração faz.
• Capacidade da plataforma — 503 capacity_reached. Uma proteção diária em toda a plataforma. Rara, e não é uma falha na sua integração.

Leia seus próprios limites, de graça, quando quiser. GET /api/v1/whoami retorna o plano, o limite de taxa, a cota restante e o teto que se aplicam à sua conta. Não custa nada e não consome cota, o que o torna uma resposta melhor do que qualquer número impresso em uma página — um número impresso pode estar desatualizado para você, e esse não pode.

Não há uma escada de planos para consultar o seu — whoami é a resposta, e é grátis. Rodando quente de propósito? Limites elevados e preços por volume: support@sirveil.ai.

Semântica de cobrança

Um medidor e uma fatura mensal. Esse é todo o aparato.

• Puramente pós-pago. Cada resposta concluída incrementa o medidor: $0,10 por verificação, $0,35 por varredura. No fim do mês, você é faturado pelo que o medidor registrou. Sem pacotes, sem créditos, sem assinaturas, sem mínimos.
• Zero chamadas, zero dólares. Um mês tranquilo não gera cobrança nem fatura. Nada é pré-pago, então nada pode expirar e nenhum dinheiro seu fica em nossos livros.
• Medição no marketplace. O Serviço está disponível para compra através do AWS Marketplace — essa é a lista completa hoje (Termos da API, Seção 3.1) — e o uso entra na sua fatura AWS existente através do medidor do marketplace. Um canal mencionado em um artefato, mas não listado nos Termos, não é uma oferta. Para uma compra no Marketplace, o preço publicado na listagem no momento da chamada é o preço daquela chamada.
• Mudanças na tabela de preços levam pelo menos 30 dias de aviso e nunca se aplicam retroativamente. Volume comprometido recebe ofertas privadas abaixo das taxas publicadas — support@sirveil.ai.
• Erros cobram $0,00 — veja Erros. A matemática completa está em /for-business#math.
• Um acerto de cache cobra integralmente. Faça a mesma pergunta duas vezes em uma janela curta e você pode receber a mesma resposta por consistência — e cobra e consome cota exatamente como uma chamada nova. O cache torna uma resposta repetida consistente, não gratuita. Preferimos dizer isso aqui do que você descobrir em uma fatura.
• Uma resposta não atendida não cobra nada. Se nosso provedor de busca estiver fora do ar, você recebe indeterminate com outcome: unserved e cobrança zero. Nós pagamos por essa tentativa; você não.
• Uma recusa registra custo como null, não zero. Nada foi gasto e nada foi medido, e não vamos afirmar uma medição que nunca fizemos.

Versionamento e descontinuação

/api/v1 é a superfície estável: os endpoints, campos de requisição, status e envelope de erro nesta página. Adicionamos campos sem aviso — analise com tolerância e ignore o que você não reconhece. Não removemos nem reaproveitamos nada sob /api/v1 sem um processo de mudança disruptiva:

• Pelo menos 30 dias de aviso antes que uma mudança disruptiva entre em vigor. Esse é o compromisso que publicamos e mantemos, e na prática buscamos dar muito mais tempo. Os Termos da API regem o acordo em si.
• Anunciado em /scan-api/changelog primeiro, antes de qualquer outro canal.
• Uma mudança disruptiva é lançada como /api/v2; /api/v1 continua respondendo durante o período de aviso.
• Qualquer coisa marcada como preview ou ainda não construída nesta página fica fora desse processo até ser marcada como estável. É para isso que serve o rótulo.

Onde esta página e o contrato discordam, o contrato vence. Estes documentos descrevem como a API se comporta e nós os mantemos honestos; os Termos da API, o Aviso de Privacidade da API e a Política de Uso Aceitável são o que realmente nos vincula. Nada nesta página é uma garantia — preferimos dizer isso claramente do que deixar uma frase bonita nos documentos ser lida como tal.

Webhooks ainda não construídos

Ainda não construído**Este ainda não existe.**Está especificado e na lista de construção, não lançado — então não projete uma integração em torno dele hoje. O formato abaixo é o que será, e chega em /scan-api/changelog quando for real. Consultar funciona agora, e é grátis.

Quando for lançado: passe webhook_url em uma varredura assíncrona e nós enviamos o relatório concluído para você em vez de fazer você consultar. As entregas são assinadas com HMAC-SHA256 sobre o corpo bruto, no cabeçalho X-Sirveil-Signature — verifique antes de confiar no payload.

Entrega (rascunho)Copiar

POST https://yourapp.example/hooks/sirveil X-Sirveil-Signature: sha256=6b4f… // HMAC-SHA256 do corpo bruto Content-Type: application/json

{ "job_id": "job_9f2c…", "status": "complete", "summary": { … }, "results": [ … ] }

Consultar GET /api/v1/jobs/:id funciona hoje e continua funcionando — webhooks são uma conveniência, não uma dependência.

Para onde ir agora

Veja os recibos

890 ms mediana / 1.463 ms p95 verificações (n=18, cache frio), 154 s mediana / 203 s varreduras mais lentas (n=5) — nossas execuções em nossos dados, execuções lentas com certeza incluídas. Medições, não compromissos.

Benchmarks →

Faça a matemática

O medidor interativo: controles deslizantes, uma fatura de exemplo e toda a tabela de preços em uma página.

Preços →

Obtenha uma chave

Minutos, não reuniões. O medidor começa em zero e permanece lá até você chamar.

Inscreva-se →

{"@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [{"@type": "ListItem", "position": 1, "name": "Home", "item": "https://sirveil.ai"}, {"@type": "ListItem", "position": 2, "name": "Sirveil for Business \u2014 Scan API", "item": "https://sirveil.ai/for-business"}, {"@type": "ListItem", "position": 3, "name": "API Docs", "item": "https://sirveil.ai/scan-api/docs"}]}