Chaves de API e Limites de Requisições

O aqoon usa chaves de API para autenticar acesso programático à API de busca, servidor MCP e outros endpoints de desenvolvedor. As chaves são prefixadas com aqn_ seguidas de 40 caracteres aleatórios, e são armazenadas no servidor como hashes SHA-256 — o texto em claro é mostrado apenas uma vez no momento da criação.

Para criar e gerenciar suas chaves pela interface, consulte o Guia do Usuário.

Tipos de Chave

Existem dois tipos de chave com diferentes escopos de acesso:

Tipo	Escopo de Acesso	Uso Típico
Acesso total	Todas as coleções pertencentes ou assinadas pelo proprietário da chave	Integração MCP pessoal, scripts de automação, ferramentas internas
Restrita	Apenas coleções explicitamente concedidas à chave	Compartilhamento de acesso de busca com desenvolvedores ou aplicações terceiros

Chaves restritas são o padrão mais seguro ao distribuir acesso. Conceda acesso a coleções específicas pela interface de gerenciamento de chaves ou pelo endpoint /api/v1/keys/{uuid}/collections/.

Níveis de Permissão

Cada concessão de acesso a coleção em uma chave restrita tem um nível de permissão que controla o que o detentor da chave pode fazer com essa coleção:

Permissão	Operações Permitidas
`read`	Pesquisar e recuperar documentos da coleção
`write`	Pesquisar, recuperar e enviar novos documentos para a coleção

A permissão padrão para uma nova concessão é read. Passe "permission": "write" ao conceder acesso se o detentor da chave precisar enviar documentos.

Chaves de acesso total têm permissão de escrita implícita em todas as coleções pertencentes ao proprietário da chave — nenhuma concessão é necessária.

Conceder / Revogar Acesso a Coleções

Use o endpoint /api/v1/keys/{uuid}/collections/ para gerenciar quais coleções uma chave restrita pode acessar, e em qual nível de permissão.

Conceder acesso

POST /api/v1/keys/{uuid}/collections/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json

{
  "collection_id": "collection-uuid",
  "permission": "write"
}

Omita permission (ou passe "read") para conceder acesso somente leitura. Passe "write" para permitir envio de documentos também.

Revogar acesso

DELETE /api/v1/keys/{uuid}/collections/{collection_id}/
Authorization: Bearer aqn_your_api_key

A rotação de chave (gerando um novo segredo para um registro de chave existente) preserva todas as concessões de coleção e seus níveis de permissão. O novo segredo é uma substituição direta — nenhuma nova concessão é necessária.

Permissão de escrita é necessária para usar a API de envio de documentos (POST /api/v1/collections/{id}/documents/). Requisições de uma chave com apenas acesso de leitura serão rejeitadas com HTTP 403.

Expiração da Chave

As chaves podem ser criadas com uma data de expiração (30 dias, 90 dias, 6 meses ou 1 ano) ou configuradas para nunca expirar. Você pode alterar a expiração a qualquer momento na página de detalhes da chave.

Chaves expiradas são automaticamente rejeitadas com um erro 401. Para renovar uma chave, defina uma nova expiração na página de detalhes da chave. Nenhuma nova chave precisa ser criada.

Endpoint de Busca

O endpoint de busca para desenvolvedores aceita um token Bearer e retorna trechos de resultados classificados de todas as coleções acessíveis pela chave:

POST /api/v1/search/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json

{
  "query": "your search query",
  "limit": 5,
  "collection_id": "optional-uuid-to-scope-to-one-collection"
}

Exemplo com cURL:

curl -X POST https://your-instance/api/v1/search/ \
  -H "Authorization: Bearer aqn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "retrieval augmented generation", "limit": 10}'

Consulte a Referência da API para schemas completos de requisição/resposta, opções de filtragem e códigos de erro. Use o Playground de Busca para testar interativamente.

Limitação de Taxa

Cada chave de API é atribuída a um nível de taxa que controla quantas requisições podem ser feitas em três janelas:

Nível	Por Minuto	Por Dia	Por Mês
Gratuito (padrão)	10	1,000	10,000
Básico	60	10,000	100,000
Pro	300	100,000	1,000,000

Os níveis de taxa são gerenciados pelo administrador da sua conta. Os limites são aplicados por conta — todas as chaves de API pertencentes ao mesmo usuário compartilham um único conjunto de contadores. Cada resposta da API inclui os seguintes cabeçalhos para que sua aplicação possa rastrear os limites programaticamente:

Cabeçalho	Descrição
`X-RateLimit-Limit`	Máximo de requisições permitidas na janela atual
`X-RateLimit-Remaining`	Requisições restantes na janela atual
`Retry-After`	Segundos para aguardar antes de tentar novamente (presente apenas em respostas 429)

Quando um limite é excedido, a API retorna HTTP 429 Too Many Requests. Seu cliente deve respeitar o Retry-After e implementar backoff exponencial para resiliência.

Painel de Uso

O painel de uso está disponível na barra lateral do app em Uso da API. Ele fornece:

Métricas resumidas — Total de requisições, contagem de erros e tempo médio de resposta para o período selecionado
Gráfico de volume diário — Requisições e erros plotados ao longo de 7, 30 ou 90 dias
Detalhamento por chave — Contagem de requisições e taxas de erro por chave de API
Log de requisições recentes — Texto da consulta, contagem de resultados, tempo de resposta e status HTTP para requisições individuais

Notificações por Webhook

Configure uma URL de webhook para receber notificações quando o processamento de documentos é concluído. Em vez de polling para status, o aqoon fará um POST com um payload JSON assinado para sua URL quando um documento for indexado ou falhar.

Um webhook por organização — configurado via POST /api/v1/webhooks/
Assinado com HMAC-SHA256 — verifique a autenticidade usando o segredo retornado na criação
Retentativas automáticas — backoff exponencial em erros do servidor (máx. 5 retentativas)
Endpoint de teste — envie um evento de teste via POST /api/v1/webhooks/test/

Consulte a Referência da API — Webhooks para formato completo do payload, verificação de assinatura e exemplos.

Faturamento e Preços

O volume de consultas da API é medido contra sua cota mensal do plano. Três planos estão disponíveis:

Plano	Preço	Consultas Incluídas/Mês	Taxa de Excedente
Gratuito	$0/mês	1,000	—
Starter	$29/mês	10,000	$0.002 por consulta
Pro	$99/mês	100,000	$0.001 por consulta

O faturamento é gerenciado via Stripe. As faturas são geradas automaticamente no final de cada ciclo de faturamento com base nos dados reais de uso. Cobranças de excedente são aplicadas apenas quando você excede a cota incluída do seu plano.