A API, da primeira chave ao primeiro relatório.
Tudo o que o produto serve programaticamente — relatórios, exports CSV, o feed de BI e o servidor MCP — atrás de uma chave com escopo de projeto.
A superfície pública é deliberadamente menor que o produto: é o contrato de serving — reporting, exports, feed de BI e MCP — e nada além. Sua chave lê; nunca escreve. A única superfície de escrita é o conjunto de tools do servidor MCP, atrás da própria plan flag.
Tudo é servido na mesma origem do app, servidor a servidor. Não há CORS: a API é para o seu backend, seu notebook ou seu cliente MCP, não para um navegador em outra origem.
URL base
Todo path REST abaixo pende da base versionada:
https://app.bementioned.ai/api/v1Cada path tem escopo de um projeto. O servidor MCP vive ao lado da base REST — o endereço está no capítulo dele.
API keys
A chave é cunhada por projeto, no app: Settings → API keys. O texto em claro aparece exatamente uma vez, na criação, e só o hash é guardado — copie na hora. Chaves são revogáveis individualmente.
A chave tem escopo do próprio projeto e não o excede: apresentada contra outro projeto, responde 404, como se aquele projeto não existisse. Chaves são principals somente leitura — toda escrita REST responde 403.
Autenticação
Envie a chave em toda requisição, em qualquer um dos dois headers:
curl https://app.bementioned.ai/api/v1/projects/{project_id}/overview \
-H "X-API-Key: bm_your_key_here"Um header Authorization: Bearer com o mesmo valor bm_ é aceito de forma equivalente — o que começa com bm_ é tratado como chave; o resto, como token de sessão.
Limites de requisição
O tráfego autenticado por chave é limitado a 200 requisições por minuto por projeto — um token bucket, então rajadas curtas de até 200 passam. Acima disso a API responde 429 com um header Retry-After em segundos. Requisições rejeitadas nunca debitam do bucket.
Erros
Erros são JSON com um campo detail — uma string, um objeto com código, ou uma lista de validação.
| Status | Significado |
|---|---|
401 | Credencial ausente, desconhecida ou revogada. |
403 | Uma escrita com chave somente leitura, ou um plano sem a flag da feature. |
404 | Nada nesse endereço — inclusive uma chave válida apresentada contra um projeto alheio. |
422 | O body falhou na validação; o detail lista cada campo ofensor. |
429 | Limite de requisições excedido; tente de novo após Retry-After segundos. |
Quando um plano não tem a flag de uma superfície, a API responde 403 e nomeia a flag, para a recusa ser diagnosticável. As flags:
{ "detail": { "code": "plan_flag_missing", "flag": "reporting_api" } }reporting_api · mcp · mcp_write · bi_connector · csv_export · actions · shopping · agent_analytics · deliverables
Capítulos
- Reporting API — as famílias de relatório, o contrato de filtros, export CSV.
- Servidor MCP — conectar um cliente, o roster de tools, escritas.
- BI & webhook — o feed de BI e o webhook de ingest de logs.