REST-API-Referenz

Nutzen Sie den Host, der zur Website des Arbeitsbereichs gehört. Schlüssel von followerx.de gelten nur auf api.followerx.de.

https://api.followerx.de/v1

Legen Sie einen Schlüssel im Dashboard unter Konto → API-Schlüssel an oder per POST /v1/api-keys. Senden Sie ihn als Bearer-Token. Live-Schlüssel beginnen mit fx_live_, Testschlüssel mit fx_test_. Testschlüssel bewegen keine echten Tokens und öffnen keine Live-Jobs.

Scopes

account:read
account:write
catalog:read
profiles:read
profiles:write
jobs:read
jobs:write
deliverables:read
invoices:read
webhooks:read
webhooks:write

Die Pfadversion ist v1. Die Kalenderversion 2026-09-11 senden Sie als FollowerX-Version. Ohne Header gilt das aktuelle stabile Verhalten. Breaking Changes erhalten eine neue Kalenderversion und mindestens 90 Tage Vorlauf.

Fehler sind JSON mit error.code, error.message und einer request_id. Validierungsfehler ergänzen error.errors[] mit path und reason.

{
  "request_id": "req_4f2c1a",
  "error": {
    "code": "insufficient_tokens",
    "message": "This quote needs 100 tokens; 42 are available."
  }
}

Leseanfragen: 120 pro Minute und Schlüssel. Writes: 30 pro Minute. Burst-Header folgen dem IETF-RateLimit-Entwurf: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. 429 enthält Retry-After.

POST und PATCH akzeptieren Idempotency-Key (UUID). Wiederholungen mit gleichem Schlüssel und Body liefern 24 Stunden die Originalantwort. Ein anderer Body mit demselben Schlüssel liefert 409.

Listenendpunkte nehmen limit (1–100, Standard 25) und starting_after. Antworten enthalten has_more und next_cursor.

SKUs und Token-Preise entsprechen der öffentlichen Leistungsseite. Creator-Honorare werden separat zum Selbstkostenpreis abgerechnet und sind keine Katalog-SKU. Express ist ein +50-%-Aufschlag auf geeignete SKUs, angefragt als rush: true am Job.

Ein Job ist eine Arbeitsanfrage gegen eine SKU. Das Anlegen gibt keine Tokens aus. Das Studio liefert ein Angebot; die Annahme reserviert Tokens. Die Abnahme der Lieferung zieht sie ein. Wird eine veröffentlichte Durchlaufzeit ohne vereinbarten Grund verfehlt, gehen reservierte Tokens zurück aufs Guthaben.

Beispiel

curl https://api.followerx.de/v1/jobs \
  -X POST \
  -H "Authorization: Bearer $FOLLOWERX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c1d2e3f-4a5b-6789-abcd-ef0123456789" \
  -d '{
    "sku": "copy_hook_pack",
    "title": "Hooks for the April launch",
    "platform": "instagram",
    "brief": "Twenty hooks for a product launch. Tone: direct, no hype.",
    "rush": false
  }'

{
  "id": "job_8k2m1q",
  "object": "job",
  "sku": "copy_hook_pack",
  "service_line": "content",
  "title": "Hooks for the April launch",
  "status": "requested",
  "tokens_quoted": null,
  "tokens_reserved": 0,
  "rush": false,
  "profile_id": null,
  "platform": "instagram",
  "brief": "Twenty hooks for a product launch. Tone: direct, no hype.",
  "deliverable_ids": [],
  "created_at": "2026-09-11T21:00:00.000Z",
  "updated_at": "2026-09-11T21:00:00.000Z"
}

Guthaben liegt auf Kontoebene und kann für jede Marke, jedes Profil oder jede Leistungslinie eingesetzt werden. Tokens verfallen nicht. Käufe laufen über den gehosteten Checkout; die API kann ihn öffnen und danach das Kontobuch lesen.

{
  "object": "balance",
  "available": 420,
  "reserved": 50,
  "lifetime_purchased": 1560,
  "currency": "EUR",
  "expires": false
}

API und MCP verkaufen und melden keine gekauften Follower, Likes oder Views. Analytics-Endpunkte liefern nur Arbeit, die Sie gegen den veröffentlichten Katalog angefragt haben.

Zustellungen sind POST-JSON mit X-FollowerX-Timestamp und X-FollowerX-Signature: sha256=<Hex von HMAC-SHA-256(secret, timestamp + '.' + raw body)>. Zeitstempel älter als 5 Minuten ablehnen. Wir wiederholen 24 Stunden mit exponentiellem Backoff.

account.updated
balance.updated
job.created
job.quoted
job.started
job.in_review
job.completed
job.cancelled
deliverable.ready
invoice.issued
invoice.paid

{
  "id": "evt_91ab",
  "object": "event",
  "type": "job.quoted",
  "created_at": "2026-09-11T21:12:00.000Z",
  "data": {
    "id": "job_8k2m1q",
    "status": "quoted",
    "tokens_quoted": 50,
    "sku": "copy_hook_pack"
  }
}