REST API reference

Use the host that matches the site the workspace belongs to. Keys issued on followerx.de only work on api.followerx.de.

https://api.followerx.ae/v1

Create a key in the dashboard under Account → API keys, or POST /v1/api-keys. Send it as a Bearer token. Live keys start with fx_live_, test keys with fx_test_. Test keys never move real tokens or open 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

The path version is v1. The calendar version 2026-09-11 is sent as FollowerX-Version. Omit the header to get the latest stable behaviour. Breaking changes get a new calendar version and at least 90 days notice.

Errors are JSON with error.code, error.message and a request_id. Validation failures add error.errors[] with path and reason.

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

Read requests: 120 per minute per key. Writes: 30 per minute. Burst headers follow the IETF RateLimit draft: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. 429 includes Retry-After.

POST and PATCH accept Idempotency-Key (UUID). Replays with the same key and body return the original response for 24 hours. A different body with the same key returns 409.

List endpoints take limit (1–100, default 25) and starting_after. Responses include has_more and next_cursor.

SKUs and token prices match the public services page. Creator fees are billed separately at cost and are not a catalogue SKU. Rush is a +50% surcharge on eligible SKUs, requested as rush: true on the job.

A job is a work request against one SKU. Creating it does not spend tokens. The studio returns a quote; accepting it reserves tokens. Approving the deliverable captures them. If a published turnaround is missed without an agreed reason, reserved tokens return to the balance.

Example

curl https://api.followerx.ae/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"
}

Balances sit at account level and can be spent on any brand, profile or service line. Tokens do not expire. Purchases happen on the hosted checkout; the API can open that checkout and can read the ledger afterwards.

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

The API and MCP do not sell or report purchased followers, likes or views. Analytics endpoints return only work you requested against the published catalogue.

Deliveries are POST JSON with X-FollowerX-Timestamp and X-FollowerX-Signature: sha256=<hex of HMAC-SHA-256(secret, timestamp + '.' + raw body)>. Reject timestamps older than 5 minutes. We retry for 24 hours with exponential 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"
  }
}