The shapes and rhythms of the Fluenta API.

Response envelope

Every JSON response wraps its payload in a consistent envelope. Successful calls always carry success: true and a typed data field. List endpoints return data as an array; single-resource endpoints return it as an object.

// 200 OK — list shape
{
  "success": true,
  "data": [
    { "id": "...", "title": "...", "ideas_count": 42, ... }
  ]
}

// 200 OK — single shape
{
  "success": true,
  "data": { "id": "...", "status": "complete", "result": {...} }
}

Errors flip success to false and replace data with an error object. Always branch on the HTTP status code first; the envelope is for human-readable detail.

// 402 Payment Required — out of credits
{
  "success": false,
  "error": {
    "code": "credits_exhausted",
    "message": "API key has insufficient credits. 1,200 / 2,000 required."
  }
}

Note: The exact error envelope shape is finalizing — field names like code and message may shift before v1.0. Always check success and the HTTP status before inspecting nested fields.

Pagination

List endpoints accept two query parameters: page (1-indexed) and per_page. Defaults are sensible; hard caps prevent runaway queries.

GET /api/v1/ext/idea-analyses?page=2&per_page=50

Iterate by incrementing page until you receive an empty data array. Cursor-based pagination is on the roadmap for endpoints with large result sets.

Credits & usage

Reads are unlimited. Writes that trigger compute — today, only POST /idea-analyses (the paid X-Ray run) — debit credits from the key’s account.

• 2,000 credits per X-Ray run.
• Free tier includes 2,000 credits at sign-up — one full run, no card required.
• The fluenta_idea_x-ray_sandbox MCP tool is free — useful as a reconnaissance pass before committing credits.
• Check current balance with GET /api/v1/ext/usage.
• When credits run out, write endpoints return 402 with error.code = credits_exhausted. Read endpoints continue to work.

X-Ray async lifecycle

X-Ray runs are asynchronous because they execute 25 live integrations end-to-end — expect ~20 minutes of wall-clock time per run, varying with load. The lifecycle is three steps:

1. Submit. POST /idea-analyses returns 201 with the run id and an initial status. Credits are debited at submission.
2. Poll. GET /idea-analyses/{id}/progress every 30–60s. Returns progress 0–100 and status.
3. Fetch. Once status is complete, GET /idea-analyses/{id} returns the full structured result.

Webhook delivery for X-Ray completion is planned — it will replace the polling loop with a single push. Until then, polling is the only pattern.

Retries & idempotency

Treat HTTP semantics as the source of truth:

• GET endpoints are always safe to retry. No side effects.
• DELETE endpoints (e.g. removing a bookmark) are idempotent — a second call returns the same final state.
• POST endpoints may have side effects. Retry only on 5xx and 429. Never retry on 4xx other than 429.
• For 429, honour the Retry-After header. Implement exponential backoff with jitter starting at 1s, capping at 60s.

Idempotency-Key header support is on the roadmap for POST /idea-analyses so duplicate submits never double-charge credits. Until then, dedupe client-side.

System architecture

Two surfaces — REST and Remote MCP — share one auth, one rate-limit layer, and one core. Whichever surface your client speaks, the same Bearer key, the same scopes, and the same credits apply.