API v1

Seu espaço. Sua API.

O mesmo guia API do painel Business. Todos os endpoints, custos e exemplos, sem entrar.

Conecte seu espaço

Crie um projeto de cliente no painel. Copie seu UUID.
Verifique seu e-mail. Um proprietário ou administrador pode criar uma chave com permissões em API e webhooks.
Guarde a chave em uma variável de ambiente do servidor chamada INDEXTOAST_API_KEY. Nunca a coloque no navegador nem em uma URL.

GET /usage

curl https://api.indextoast.com/v1/business/usage \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY"

GET /projects

curl https://api.indextoast.com/v1/business/projects \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY"

Permissão	Acesso
`usage:read`	GET /usage · GET /projects
`jobs:read`	GET /batches · GET /batches/:id
`jobs:write`	POST /batches/review · POST /batches

As chaves expiram e podem ser revogadas. Alterações de espaço, projetos, chaves, webhooks e faturamento exigem uma sessão autorizada; chaves API não gerenciam pagamentos.

Standard

Envie URLs para indexação Standard. Cada URL única usa 1 ação Standard.

Revise primeiro. Envie uma vez.

A revisão é gratuita. Retorna quantity, duplicates, unitCost, requiredUnits, available, canSubmit e URLs normalizadas. O saldo é verificado ao enviar.

1 · POST /batches/review · jobs:write

curl https://api.indextoast.com/v1/business/batches/review \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "projectId": "YOUR_PROJECT_UUID",
  "name": "Client campaign",
  "operation": "standard",
  "urls": [
    "https://example.com/page-one",
    "https://example.com/page-two"
  ],
  "idempotencyKey": "campaign-standard-001"
}'

2 · POST /batches · jobs:write

curl https://api.indextoast.com/v1/business/batches \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "projectId": "YOUR_PROJECT_UUID",
  "name": "Client campaign",
  "operation": "standard",
  "urls": [
    "https://example.com/page-one",
    "https://example.com/page-two"
  ],
  "idempotencyKey": "campaign-standard-001"
}'

Use de 1 a 1.000 URLs HTTP(S) públicas, um UUID de projeto do espaço, um nome de 1–100 caracteres e uma chave de idempotência de 8–150 caracteres. URLs normalizadas duplicadas são cobradas uma vez.

202 Accepted · response excerpt

{
  "id": "BATCH_UUID",
  "operation": "standard",
  "quantity": 2,
  "status": "queued",
  "successful": 0,
  "failed": 0,
  "results": []
}

202 significa aceito para processamento. Não confirma indexação nem prazo. A capacidade é debitada uma vez na aceitação.

Verificador de indexação

Verifique se as URLs são detectadas no índice de pesquisa. Cada URL única usa 1 ação Standard, incluindo resultados inconclusivos.

Revise primeiro. Envie uma vez.

A revisão é gratuita. Retorna quantity, duplicates, unitCost, requiredUnits, available, canSubmit e URLs normalizadas. O saldo é verificado ao enviar.

1 · POST /batches/review · jobs:write

curl https://api.indextoast.com/v1/business/batches/review \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "projectId": "YOUR_PROJECT_UUID",
  "name": "Client campaign",
  "operation": "check",
  "urls": [
    "https://example.com/page-one",
    "https://example.com/page-two"
  ],
  "idempotencyKey": "campaign-check-001"
}'

2 · POST /batches · jobs:write

curl https://api.indextoast.com/v1/business/batches \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "projectId": "YOUR_PROJECT_UUID",
  "name": "Client campaign",
  "operation": "check",
  "urls": [
    "https://example.com/page-one",
    "https://example.com/page-two"
  ],
  "idempotencyKey": "campaign-check-001"
}'

202 Accepted · response excerpt

{
  "id": "BATCH_UUID",
  "operation": "check",
  "quantity": 2,
  "status": "queued",
  "successful": 0,
  "failed": 0,
  "results": []
}

202 significa aceito para processamento. Não confirma indexação nem prazo. A capacidade é debitada uma vez na aceitação.

Resultados do verificador de indexação

GET /batches/:id · results excerpt

{
  "results": [
    {
      "url": "https://example.com/page-one",
      "result": "indexed"
    },
    {
      "url": "https://example.com/page-two",
      "result": "unknown"
    }
  ]
}

indexed = detectada; not_indexed = não detectada nesta verificação; unknown = inconclusiva. Um lote concluído indica processamento, não um resultado positivo. Leia o resultado de cada URL.

Boost

Boost usa 20 unidades Business compartilhadas por URL única.

Revise primeiro. Envie uma vez.

A revisão é gratuita. Retorna quantity, duplicates, unitCost, requiredUnits, available, canSubmit e URLs normalizadas. O saldo é verificado ao enviar.

1 · POST /batches/review · jobs:write

curl https://api.indextoast.com/v1/business/batches/review \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "projectId": "YOUR_PROJECT_UUID",
  "name": "Client campaign",
  "operation": "boost",
  "urls": [
    "https://example.com/page-one",
    "https://example.com/page-two"
  ],
  "idempotencyKey": "campaign-boost-001"
}'

2 · POST /batches · jobs:write

curl https://api.indextoast.com/v1/business/batches \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "projectId": "YOUR_PROJECT_UUID",
  "name": "Client campaign",
  "operation": "boost",
  "urls": [
    "https://example.com/page-one",
    "https://example.com/page-two"
  ],
  "idempotencyKey": "campaign-boost-001"
}'

202 Accepted · response excerpt

{
  "id": "BATCH_UUID",
  "operation": "boost",
  "quantity": 2,
  "status": "queued",
  "successful": 0,
  "failed": 0,
  "results": []
}

202 significa aceito para processamento. Não confirma indexação nem prazo. A capacidade é debitada uma vez na aceitação.

Use unidades Business mensais ou pré-pagas para Boost. Não há uma franquia Boost separada.

Acompanhar lotes

GET /batches/:id · jobs:read

curl https://api.indextoast.com/v1/business/batches/BATCH_UUID \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY"

GET /batches · jobs:read

curl https://api.indextoast.com/v1/business/batches?page=1 \
  -H "Authorization: Bearer $INDEXTOAST_API_KEY"

As listas contêm 20 lotes por página. Consulte hasMore antes de pedir a próxima. Consultas de status são gratuitas; use espera progressiva ou um webhook.

Estados de processamento

queued → submitting → submitted / processing → completed
                                             ↘ failed / unknown

failed ou unknown exige revisão. Contate o suporte com o ID antes de criar um substituto; uma chave nova pode debitar capacidade novamente. Tentativas de processamento usam a reserva original.

Verificar assinaturas de webhooks

Configure um endpoint HTTPS em API e webhooks. Guarde o segredo exibido uma vez. Receba eventos batch.finished assinados e deduplique por ID.

Cabeçalho de assinatura

x-indextoast-signature: t=TIMESTAMP,v1=HEX

HMAC-SHA256(secret, timestamp + "." + rawBody)

Verifique o corpo original com comparação em tempo constante antes de processar.
Rejeite timestamps a mais de cinco minutos do relógio do servidor, incluindo futuros.
Guarde o ID antes de responder 2xx. As tentativas são limitadas; reconcilie eventos ausentes consultando o status.

Uso e faturamento

Serviço	Custo por URL única	Saldo
Standard	1 ação	Standard
Verificador de indexação	1 ação	Standard
Boost	20 unidades	Standard

Enviar 100 URLs Standard e verificar cada uma usa 200 unidades. Boost para 100 URLs usa 2.000 unidades; verificar cada uma acrescenta 100, totalizando 2.100.

GET /usage · response excerpt

{
  "plan": "agency",
  "included": 10000,
  "purchased": 0,
  "standardAvailable": 10000,
  "boostAvailable": 500,
  "unitCosts": {
    "standard": 1,
    "check": 1,
    "boost": 20
  },
  "monthlyActionLimit": null,
  "acceptedThisMonth": 0,
  "periodEnd": "2026-11-08T00:00:00.000Z"
}

Ações incluídas são usadas antes das compradas. Renovam no período pago sem acumular; saldos pré-pagos não expiram. Saldos Regular e Business são separados.

O limite mensal conta todas as operações aceitas no mês UTC. Vazio usa limites de saldo; 0 pausa novos trabalhos. É um limite de ações, não um orçamento monetário.

Erros e tentativas

Repita um envio com timeout usando o mesmo conteúdo e chave. O lote existente retorna sem novo débito. Se enviar o cabeçalho opcional Idempotency-Key, ele deve coincidir com o corpo.

HTTP	Significado / próximo passo
400 / 422	Entrada inválida. Corrija o conteúdo antes de repetir.
401 / 403	Verifique a chave, permissões e e-mail verificado.
404	O projeto ou lote não está disponível neste espaço.
409	`STANDARD_BALANCE_REQUIRED · SPENDING_LIMIT · IDEMPOTENCY_CONFLICT`
429 / 5xx	Respeite Retry-After quando informado. Repita com espera exponencial e a mesma chave.

Limite API: 120 solicitações por minuto por IP, compartilhado entre rotas. Validação, revisão e consultas não gastam ações. Um resultado pago do verificador pode ser inconclusivo.

Contatar suportehello@indextoast.com