API overview

The Fibric REST API drives the loop in code. You ingest what your systems sense. The model proposes execution plans. A deterministic executor vets every action against your policy and runs what it allows. You read a receipt for everything, including refusals. This page covers the conventions shared by every endpoint; each endpoint group has its own reference page, indexed below.

#Base URL

Send every request over HTTPS. The major version is pinned in the path, so an upgrade is never silent.

#Authentication

Authenticate every request with a secret API key in the Authorization header as a Bearer token. Keys are issued per tenant in the Fibric console and carry a fixed set of scopes. Treat a key like a password: it is shown once, it is never logged in a receipt, and it identifies exactly one tenant, so the key enforces the tenancy wall, not anything you pass in the body.

curl https://api.fibric.io/v1/operators \
  -H "Authorization: Bearer sk_live_3f9c2a7b8e1d4f60a2c9"

Scopes are granted per endpoint group and split read from write. Each endpoint's route bar names the scope it requires.

#Versioning

The API is v1.0, stable: the surface documented here is what production tenants run against, and the kernel contract is frozen for the 1.x line. The rules are strict:

• The major version lives in the URL (/v1). Within a major version, changes are additive only: new fields, new endpoints, new enum members. We never remove a field or change a type inside a major version.
• A breaking change ships as a new major, and the previous major is supported for at least twelve months after its successor is stable.
• Optionally pin a dated revision with the Fibric-Version header (for example 2026-06-01) to freeze additive-but-default-changing behavior.
• Treat unknown JSON fields as forward-compatible: parse leniently and ignore what you do not recognize.

#Request & response conventions

Requests and responses are JSON. Send Content-Type: application/json on any request with a body. Timestamps are RFC 3339 in UTC, for example 2026-06-14T09:02:11Z. Booleans are booleans, never "true" strings. Money values are decimal strings with a separate currency field.

Identifiers are opaque, prefixed strings. Never assume a format beyond the prefix:

Marketplace listings use slug ids like cn-magento, distinct from the cn_-prefixed connector instances installing one creates. See the Connectors API.

#Idempotency

Send an Idempotency-Key header on any POST. Retrying with the same key and the same body returns the original result instead of acting twice; the same key with a different body returns 409 idempotency_conflict. Keys are scoped per tenant and route and retained for 24 hours.

curl -X POST https://api.fibric.io/v1/plans/pl_7c1a/approve \
  -H "Authorization: Bearer sk_live_3f9c2a7b8e1d4f60a2c9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approve-pl_7c1a" \
  -d '{"approver": "l.ops@example.com"}'

Beyond the header, side-effecting plan actions carry their own idempotency_key in the body, enforced by the executor itself, and the executor serializes work per entity_key (single-flight). Together these are what make a runaway flood structurally impossible: the same proposal replayed 657 times executes once. Semantics are specified in Errors and the single-flight concept page.

#Pagination

List endpoints are cursor-paginated and return newest first. Pass limit (1–100, default 20) and follow next_cursor until has_more is false. Cursors are opaque and expire; a stale cursor returns 400 invalid_cursor, in which case restart from the first page.

{
  "object": "list",
  "data": [ "…" ],
  "has_more": true,
  "next_cursor": "cur_9f2e8c1b7a"
}

#The object model

Four objects carry the loop, in order. Everything else in the API, operators, connectors, exports, exists to configure or read this chain.

Every object in the chain carries the ids of its ancestors, so you can walk it in either direction: an event lists the plan_ids it produced, a receipt names its event_id, plan_id, and action_id. The correlation_id from the envelope threads through everything.

#Endpoint index

The full surface, grouped by reference page. Each row links to the endpoint's detailed documentation: parameters, curl examples, responses, and error cases.

#Errors

Errors use standard HTTP status codes and one consistent envelope: {"error": {"type", "code", "message", "doc_url", "request_id"}}. Branch on code, which is stable, never on message. The full code table, grouped by status and including the 409 idempotency-conflict and single-flight lock semantics, is on the Errors page.

#Rate limits

Limits are per tenant and per route class; every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset so you can back off before you are throttled. Defaults, burst behavior, 429 handling, and the action allowance quota are on the Rate limits & quotas page.

#Webhooks

Fibric can push to you as well: webhook endpoints receive plan proposals, action dispositions, and connector status changes as they happen, each delivery signed with an HMAC in the Fibric-Signature header. Webhook management endpoints (whk_ ids) are being reworked for the v1 freeze and are documented with your onboarding materials during early access; the delivery payloads are the same objects defined on the group pages above.