The API, from first key to first report.

The public surface is deliberately smaller than the product: it is the serving contract — reporting, exports, the BI feed and MCP — and nothing else. Your key reads; it never writes. The one write surface is the MCP server’s tool set, gated by its own plan flag.

Everything is served same-origin with the app, server-to-server. There is no CORS: the API is for your backend, your notebook or your MCP client, not for a browser on another origin.

Base URL

Every REST path below hangs off the versioned base:

https://app.bementioned.ai/api/v1

Every path is scoped to one project. The MCP server lives beside the REST base — its address is in its own chapter.

API keys

A key is minted per project, in the app: Settings → API keys. The plaintext is shown exactly once at creation and only a hash is stored — copy it then. Keys are individually revocable.

A key is scoped to its project and cannot exceed it: presented against another project it answers 404, as if that project did not exist. Keys are read-only principals — every REST write answers 403.

Authenticate

Send the key on every request, in either header:

curl https://app.bementioned.ai/api/v1/projects/{project_id}/overview \
  -H "X-API-Key: bm_your_key_here"

An Authorization: Bearer header carrying the same bm_ value is accepted equivalently — anything starting with bm_ is treated as a key, anything else as a session token.

Rate limits

Key-authed traffic is limited to 200 requests per minute per project — a token bucket, so short bursts up to 200 pass. Beyond it the API answers 429 with a Retry-After header in seconds. Rejected requests are never debited from the bucket.

Errors

Errors are JSON with a detail field — a string, a coded object, or a validation list.

Status	Meaning
401	Missing, unknown or revoked credential.
403	A write with a read-only key, or a plan that lacks the feature’s flag.
404	Nothing at that address — including a valid key presented against a foreign project.
422	The body failed validation; the detail lists each offending field.
429	Rate limit exceeded; retry after Retry-After seconds.

When a plan lacks a surface’s flag, the API answers 403 and names the flag, so the refusal is diagnosable. The flags:

{ "detail": { "code": "plan_flag_missing", "flag": "reporting_api" } }

reporting_api · mcp · mcp_write · bi_connector · csv_export · actions · shopping · agent_analytics · deliverables

Chapters

• Reporting API — the report families, the filter contract, CSV export.
• MCP server — connect a client, the tool roster, writes.
• BI & webhook — the BI feed and the log-ingest webhook.