Rankmio JSON-API

Die drei Endpoints

• GET /api/v1/projects — Discovery: listet alle Projekte, die der Key sehen darf (id, domain, name, created_at). Für Agenten, die dein Projekt-Setup noch nicht kennen.
• GET /api/v1/projects/{id} — Meta und verfügbare Blöcke: welche der 12 Datenblöcke haben Daten, Datensatz-Count und geschätzte Bytes pro Block. Ideal, um vor dem Export gezielt zu entscheiden, welche Blöcke sinnvoll sind.
• GET /api/v1/projects/{id}/export?blocks=… — der eigentliche Snapshot in exakt derselben Struktur wie der Browser-JSON-Download. Blöcke werden per Query-Parameter selektiert; ohne Parameter kommen alle.

Die ersten beiden Endpoints sind kostenlos, der Export folgt der gleichen Kostenlogik wie der Browser-Download.

Auth und Missbrauchsschutz

Jeder Aufruf trägt den Bearer-Token im Authorization-Header. Serverseitig prüft eine Middleware Token, IP-Whitelist (optional pro Key) und Projekt-Whitelist (optional pro Key). Rate-Limit gilt pro Key: 60 Requests pro Minute, 1000 pro Tag. Zusätzlich hat jeder Key ein tägliches Credit-Limit (Default 200 Credits pro Key pro Tag) — ein Missbrauchs-Anker, damit ein geleakter Token das Guthaben nicht leer machen kann. Response-Header X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Day und X-Charge-Used-Cr geben jeder Pipeline eine ehrliche Selbst-Auskunft ohne separaten Status-Call.

Typischer Agent-Flow

Ein Coding-Agent, der Rankmio noch nicht kennt, arbeitet in drei Schritten: (1) GET /projects aufrufen, in der Liste nach der gewünschten Domain filtern und die Projekt-ID merken. (2) GET /projects/{id} aufrufen, prüfen welche Blöcke Daten haben und wie groß sie sind. (3) GET /projects/{id}/export?blocks=… aufrufen und den Snapshot in den Chat-Kontext, ein Slash-Command oder eine CI-Pipeline geben. Die ersten zwei Schritte sind kostenlos, nur der Export bucht Credits ab.

Fehler-Codes nach HTTP-Konvention

• 401 unauthorized — Bearer-Token fehlt, ist ungültig oder wurde widerrufen.
• 402 insufficient credits — Guthaben reicht nicht für den Export.
• 403 forbidden — IP-Whitelist oder Projekt-Whitelist des Keys greift.
• 404 project not found — Projekt gehört dir nicht oder existiert nicht.
• 429 rate limit oder charge cap exceeded — Rate-Limit oder Tages-Credit-Limit erreicht, plus Retry-After-Header.

Jeder Aufruf (auch Fehler) wird intern in api_key_usage protokolliert — für Audit-Nachvollziehbarkeit.