Rankmio JSON API

The three endpoints

• GET /api/v1/projects — discovery: lists all projects the key is allowed to see (id, domain, name, created_at). For agents that do not yet know your project setup.
• GET /api/v1/projects/{id} — meta data and available blocks: which of the 12 data blocks hold data, the record count and the estimated bytes per block. Ideal for deciding, before the export, which blocks are worth requesting.
• GET /api/v1/projects/{id}/export?blocks=… — the actual snapshot, in exactly the same structure as the browser JSON download. Blocks are selected via query parameter; without a parameter, all of them are returned.

The first two endpoints are free of charge; the export follows the same cost logic as the browser download.

Authentication and abuse protection

Every call carries the bearer token in the Authorization header. Server-side, a middleware checks the token, the IP whitelist (optional per key) and the project whitelist (optional per key). The rate limit applies per key: 60 requests per minute, 1,000 per day. In addition, every key has a daily credit limit (default 200 credits per key per day) — an anchor against abuse, so that a leaked token cannot drain the balance. The response headers X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Day and X-Charge-Used-Cr give every pipeline an honest self-report without a separate status call.

A typical agent flow

A coding agent that does not yet know Rankmio works in three steps: (1) call GET /projects, filter the list for the desired domain and note the project ID. (2) Call GET /projects/{id} and check which blocks hold data and how large they are. (3) Call GET /projects/{id}/export?blocks=… and pass the snapshot into the chat context, a slash command or a CI pipeline. The first two steps are free of charge; only the export deducts credits.

Error codes following HTTP convention

• 401 unauthorized — the bearer token is missing, invalid or has been revoked.
• 402 insufficient credits — the balance is not sufficient for the export.
• 403 forbidden — the key's IP whitelist or project whitelist applies.
• 404 project not found — the project does not belong to you or does not exist.
• 429 rate limit or charge cap exceeded — the rate limit or the daily credit limit has been reached, plus a Retry-After header.

Every call (including errors) is logged internally in api_key_usage — for audit traceability.