API overview

This page specifies the proposed Fibric REST contract. It is not a public callable API today. The target flow ingests events, separates model proposals from deterministic policy checks, and records supported dispositions; external outcomes still require connector-specific verification.

#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

This page sketches a proposed v1 contract. There is no public stable API or production-tenant compatibility commitment today. The target rules are:

• The proposed major version lives in the URL (/v1), with additive-change discipline as a design goal.
• Any compatibility, deprecation, and prior-major support window would be published with the service and agreed contractually.
• 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

The proposed contract accepts an Idempotency-Key on POST. A recognized stable key and matching body would return the stored service-boundary result; a changed body would conflict. The retention value is a reference default, not a public commitment, and downstream outcomes still require verification.

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"}'

In the target contract, side-effecting plan actions carry an idempotency_key and the executor serializes work per entity_key. Stable keys can suppress recognized retries inside that boundary. They reduce runaway risk but do not guarantee connector or downstream behavior; see Single-flight & idempotency.

#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

The proposed API includes signed webhook deliveries for plan proposals, action dispositions, and connector status changes. These endpoints and whk_ objects are target-contract examples, not a public service; deployment-specific webhook behavior is documented during managed onboarding.