Reference

Object reference

Every core object in the Fibric API, consolidated on one page: the field tables and a canonical JSON example for each. The per-endpoint pages, Events, Operators, Connectors, Actions & plans, Receipts, Guardrails, Tenants, Webhooks, and API keys, document the operations on these objects; this page is the shape reference you keep open next to them.

Shared conventions, including authentication, pagination, the Idempotency-Key header, and the error envelope, are defined in the API overview. Error codes are catalogued in Errors.

Shared conventions

Every object the API returns follows the same rules:

Typed ids. Every id is an opaque string with a type prefix. Never parse anything beyond the prefix; length and alphabet may change within a major version.
The object field. Every object names its own type, so a consumer can dispatch on object without inspecting the URL it came from. Lists are "object": "list" with the items in data.
Timestamps. All timestamps are RFC 3339 strings in UTC.
Tenancy. The server derives tenant_id and reseller_id from the API key and stamps them onto everything it writes. Objects that expose these fields expose them read-only; nothing in a request body can widen them. See Tenancy & isolation.
Additive evolution. New fields appear within the major version without notice; unknown fields must be ignored. Removals and renames wait for a major version. See API versioning.

Object	`object` value	Id prefix	Endpoint page
Envelope (event)	`event`	`ev_`	Events API
Operator	`operator`	`op_`	Operators API
Connector	`connector`	`cn_`	Connectors API
Capability	none (a value, not a resource)	none	Capabilities
Plan	`execution_plan`	`pl_`	Actions & plans API
Action	`action`	`act_`	Actions & plans API
Receipt	`receipt`	`rc_`	Receipts API
Guardrail	`guardrail_policy`	`grd_`	Guardrails API
Tenant	`tenant`	`t_`	Tenants API
Webhook endpoint	`webhook_endpoint`	`whk_`	Webhooks API
API key	`api_key`	`key_`	API keys

How objects relate

One thread of work touches most of these objects in a fixed order. An event arrives and is stamped with a correlation_id. An operator subscribed to its event_type proposes a plan of actions, each carrying its entity_key and idempotency_key. The executor disposes each action under the matching guardrail rules, and every disposition, applied, blocked, alerted, or deduplicated, appends a receipt. The correlation_id is present on every object in the chain, so any one of them recovers the whole story.

the object graph, one thread of work

event ev_3a91c7            (correlation_id: co_51d2e8)
  └─ plan pl_7c1a          (operator op_8f2a1c, status: proposed)
       ├─ action act_91d0  (order.hold, verdict ALLOW)   ─> receipt rc_5b21 (applied)
       └─ action act_91d1  (order.notify, verdict ALERT) ─> receipt rc_5b22 (awaiting_approval)

connector cn_7d2f4a        fulfills order.hold / order.notify for both actions
guardrail grd_3c90e1       supplied the rules the verdicts cite
webhook_endpoint whk_6b3e0d  delivered plan.proposed and action.needs_approval
api_key key_4e91b2         authenticated the requests; request_id lands on each receipt

Two navigation rules follow. To go forward from a cause, filter by correlation_id: GET /v1/receipts?filters and the Search API both accept it. To go backward from an effect, follow the id fields: a receipt names its action_id, plan_id, event_id, and operator_id directly, so an auditor starting from one receipt needs no search at all.

Envelope (event)

The one canonical event for everything. A commerce webhook, an MQTT temperature reading, a cron tick, and an operator's own output all become the same shape; this is what makes the platform vertical-agnostic. The API's event object is the kernel's EventEnvelope plus the server-assigned read fields. See the event envelope for the concept.

Field	Type	Description
`id`	string	Unique identifier, prefixed `ev_`. Assigned by the server at ingestion.
`object`	string	Always `event`.
`reseller_id`	string or null	The reseller the tenant belongs to; `null` means Fibric-direct. Present on every envelope, stamped from the key.
`tenant_id`	string	The owning tenant, stamped from the key. Read-only.
`workspace_id`	string or null	The workspace within the tenant, or `null` for tenant-wide events.
`source`	string	What produced the event: a connector id such as `magento`, a gateway such as `bacnet-gw-7`, `cron`, or `operator:<name>` for an operator's own output.
`event_type`	string	Dot-delimited `noun.verb` type, for example `order.updated` or `hvac.zone.fault`. Operators subscribe by glob over this field.
`correlation_id`	string	Threads one piece of work across events, plans, actions, and receipts. Generated if not supplied at ingestion.
`payload`	object	The event body. Shape is source-defined; the convention is an `entity` reference (`{ "kind", "id" }`) plus the source fields.
`agent_id`	string or null	The operator that produced this event, when the source is an operator.
`session_id`	string or null	Groups events belonging to one interactive session, when there is one.
`received_at`	string	RFC 3339 timestamp the server accepted the envelope.
`plan_ids`	string[]	Plans this event caused, populated as operators respond. Empty for events no operator acted on.

json · the event object

{
  "id": "ev_3a91c7",
  "object": "event",
  "reseller_id": null,
  "tenant_id": "t_8f2ac901",
  "workspace_id": null,
  "source": "magento",
  "event_type": "order.updated",
  "correlation_id": "co_51d2e8",
  "payload": {
    "order": "SO-10884",
    "status": "open",
    "ship_by": "2026-07-06",
    "carrier_scanned": false
  },
  "agent_id": null,
  "session_id": null,
  "received_at": "2026-07-02T14:58:01Z",
  "plan_ids": ["pl_7c1a"]
}

Operator

A named AI worker with a goal, a fixed capability allowlist, and the sense-reason-propose loop. An operator never acts directly: it proposes plans, and the deterministic executor disposes them. See Operators for the concept.

Field	Type	Description
`id`	string	Unique identifier, prefixed `op_`.
`object`	string	Always `operator`.
`name`	string	The operator's name within the tenant. It appears on every plan and receipt the operator produces.
`status`	string	`active`, `paused`, or `error`. A paused operator senses nothing and proposes nothing.
`outcome`	string	The goal in plain language. Part of the reviewed contract, not a tunable.
`capabilities`	string[]	The complete allowlist of capabilities the operator may sense or propose through. A plan naming a tool outside this list fails validation.
`guardrails`	object[]	The trust rules bound to this operator: `tool`, `decision` (`ALLOW` / `ALERT` / `BLOCK`), and optional `max_value`. See Guardrail.
`model`	string	A model-router alias such as `router:default`, never a hardcoded vendor model. Resolved per tenant by the router seam.
`schedule`	string or null	Cron expression for scheduled operators; `null` for purely event-driven or on-demand operators.
`created_at`	string	RFC 3339 timestamp of creation.
`last_run`	object or null	Summary of the most recent run: `run_id`, counts of `sensed`, `proposed`, and `applied`, and its timestamp. `null` before the first run.

json · the operator object

{
  "id": "op_8f2a1c",
  "object": "operator",
  "name": "order-risk",
  "status": "active",
  "outcome": "No order misses its promised ship date without a hold and a reason on the record.",
  "capabilities": ["order.read", "order.hold", "order.notify"],
  "guardrails": [
    { "tool": "order.hold", "decision": "ALLOW", "max_value": 500 },
    { "tool": "order.notify", "decision": "ALERT" }
  ],
  "model": "router:default",
  "schedule": "*/15 * * * *",
  "created_at": "2026-06-10T14:21:03Z",
  "last_run": {
    "run_id": "run_5b21",
    "sensed": 42,
    "proposed": 3,
    "applied": 2,
    "at": "2026-07-02T15:02:11Z"
  }
}

Connector

An installed instance of a marketplace listing, bound to one connection's credentials. The connector is where capabilities become concrete: it declares which capabilities it fulfills and which of its tools are side-effecting. See Connectors for the concept and the Connector SDK for authoring.

Field	Type	Description
`id`	string	Unique identifier for this installed instance, prefixed `cn_`.
`object`	string	Always `connector`.
`listing`	string	The marketplace listing this instance was installed from, for example `cn-magento`.
`name`	string	Your name for this instance, for example `magento-us-store`. Multiple instances of one listing are distinguished by name.
`kind`	string	`saas`, `hardware`, or `operator`. Operators are connectors too; the kind is metadata, not a different code path.
`transport`	string	How the platform talks to it. `mcp` for all current listings.
`capabilities`	string[]	The capabilities this instance fulfills. Operators bind to these, not to the connector directly.
`tools`	object[]	The tools the connector exposes: `name` plus `side_effect`. Side-effecting tools route through the executor and trust policy; reads do not.
`auth`	object	The auth declaration: `type` (`oauth2`, `api_key`, `basic`, `aws_iam`, `mtls`, or `none`) and a credential `hint`. Secrets are never returned.
`status`	string	`connected`, `degraded`, `error`, or `pending_auth`. Status transitions can be delivered by webhook.
`created_at`	string	RFC 3339 timestamp of installation.
`last_synced_at`	string or null	Timestamp of the most recent successful ingest or probe; `null` before the first.

json · the connector object

{
  "id": "cn_7d2f4a",
  "object": "connector",
  "listing": "cn-magento",
  "name": "magento-us-store",
  "kind": "saas",
  "transport": "mcp",
  "capabilities": ["order.read", "order.hold", "order.notify"],
  "tools": [
    { "name": "order.read",   "side_effect": false },
    { "name": "order.hold",   "side_effect": true },
    { "name": "order.notify", "side_effect": true }
  ],
  "auth": { "type": "api_key", "hint": "mg_****41" },
  "status": "connected",
  "created_at": "2026-06-18T10:02:00Z",
  "last_synced_at": "2026-07-02T14:59:40Z"
}

Capability

A capability is a value, not a resource: a dot-delimited noun.verb string naming one governed ability, such as order.hold or conversation.read. It has no id, no object field, and no endpoint of its own; it is the level of indirection that lets an operator require order.hold without knowing whether Magento or Shopify fulfills it. Swapping the fulfilling connector is configuration, not a redeploy. See Capabilities.

Where it appears	As	Meaning
Operator `capabilities`	string[]	The allowlist: everything the operator may sense or propose through. Enforced at sense time, plan validation, and disposition.
Connector `capabilities`	string[]	What this installed instance fulfills. One connector can fulfill many capabilities; one capability is fulfilled by exactly one bound connector per operator.
`GET /v1/connectors?capability=`	query filter	Which installed connectors fulfill a capability, used when binding.
Guardrail rules	`tool` match	Trust rules match on the tool name, which by convention is the capability the tool implements.

json · a capability binding, inside an operator create

{
  "name": "order-risk",
  "capabilities": ["order.read", "order.hold"],
  "bindings": {
    "order.read": "cn_7d2f4a",
    "order.hold": "cn_7d2f4a"
  }
}

Plan

The kernel's ExecutionPlan: what an operator proposes and the only thing the executor will run. The LLM proposes; the deterministic executor disposes. A plan is validated against the kernel type before it exists as an API object, so every plan you can read was structurally sound. See the Actions & plans API for the approval flow.

Field	Type	Description
`id`	string	Unique identifier, prefixed `pl_`.
`object`	string	Always `execution_plan`.
`operator_id`	string	The operator that proposed the plan.
`event_id`	string or null	The event that triggered the run, or `null` for scheduled and on-demand runs.
`status`	string	`proposed`, `executing`, `disposed`, `vetoed`, or `expired`.
`reasoning`	string or null	The operator's stated reasoning, stored with the plan and shown in review queues.
`actions`	object[]	The proposed actions, each carrying its verdict from the trust evaluation.
`proposed_at`	string	RFC 3339 timestamp of the proposal.
`disposed_at`	string or null	Timestamp the plan reached a final state; `null` while proposed or executing.
`expires_at`	string or null	When an unapproved plan expires. An expired plan is receipted as such and never runs.

json · the plan object

{
  "id": "pl_7c1a",
  "object": "execution_plan",
  "operator_id": "op_8f2a1c",
  "event_id": "ev_3a91c7",
  "status": "proposed",
  "reasoning": "SO-10884 is paid, unfulfilled, and two days from its promise with no carrier scan. Hold it and tell the owner.",
  "actions": [
    {
      "id": "act_91d0",
      "connector": "cn_7d2f4a",
      "tool": "order.hold",
      "args": { "order": "SO-10884", "reason": "will miss promised ship date" },
      "value": 184.5,
      "entity_key": "order:SO-10884",
      "idempotency_key": "order-risk:SO-10884:hold",
      "verdict": { "decision": "ALLOW", "tier": 1, "rule": "tool:order.hold max_value:500" }
    }
  ],
  "proposed_at": "2026-07-02T15:02:09Z",
  "disposed_at": null,
  "expires_at": "2026-07-05T15:02:09Z"
}

Action

One side effect inside a plan, from proposal through disposition. The proposal fields are the kernel's PlannedAction, and the disposition is the kernel's ActionDisposition: a trust decision (ALLOW, ALERT, BLOCK) or DEDUP when the idempotency key had already been applied. The two keys are the kernel primitives that make a runaway flood structurally impossible; see Single-flight & idempotency.

Field	Type	Description
`id`	string	Unique identifier, prefixed `act_`. Stable from proposal through disposition.
`object`	string	Always `action`.
`plan_id`	string	The plan this action belonged to.
`connector`	string	The connector instance the tool routes through.
`tool`	string	The tool the action invokes, for example `order.hold`.
`args`	object	The validated arguments, unchanged from the proposal.
`value`	number, optional	The monetary or physical magnitude, when the tool has one; evaluated against `max_value` guardrail rules.
`entity_key`	string	Single-flight key, conventionally `kind:id`. The executor serializes all side effects sharing the key.
`idempotency_key`	string	Dedup key, conventionally `operator:entity:action`. A key already applied disposes as `DEDUP`.
`verdict`	object	The trust evaluation: `decision`, `tier`, and the `rule` that matched.
`disposition`	string	`ALLOW`, `ALERT`, `BLOCK`, or `DEDUP`.
`ok`	boolean	Whether the disposition completed without error. A `BLOCK` is `ok: false` with `error: "blocked by trust policy"`.
`error`	string or null	Error detail when `ok` is `false`.
`receipt_id`	string	The immutable receipt written for this action, refusals included.
`undoable`	boolean	`true` when the tool declares a compensating inverse and the action applied successfully.
`undone`	boolean	`true` after a successful undo.
`disposed_at`	string	RFC 3339 timestamp of the disposition.

json · the action object

{
  "id": "act_91d0",
  "object": "action",
  "plan_id": "pl_7c1a",
  "connector": "cn_7d2f4a",
  "tool": "order.hold",
  "args": { "order": "SO-10884", "reason": "will miss promised ship date" },
  "value": 184.5,
  "entity_key": "order:SO-10884",
  "idempotency_key": "order-risk:SO-10884:hold",
  "verdict": { "decision": "ALLOW", "tier": 1, "rule": "tool:order.hold max_value:500" },
  "disposition": "ALLOW",
  "ok": true,
  "error": null,
  "receipt_id": "rc_5b21",
  "undoable": true,
  "undone": false,
  "disposed_at": "2026-07-02T15:04:41Z"
}

Receipt

The immutable record of one disposition: the proposal exactly as the operator made it, the policy decision, the keys, who approved, and the outcome. Receipts are append-only; there is no write scope for them because only the kernel appends. Refusals and dedups are receipted with the same fidelity as applied actions. See Receipts & audit.

Field	Type	Description
`id`	string	Unique identifier, prefixed `rc_`.
`object`	string	Always `receipt`.
`reseller_id`	string or null	Stamped from the tenant, on every row.
`tenant_id`	string	The owning tenant.
`operator_id`	string	The operator whose plan produced this disposition.
`operator`	string	The operator's name at disposition time, denormalized for readable exports.
`event_id`	string or null	The triggering event, threading the receipt back to its cause.
`plan_id`	string	The plan the action belonged to.
`action_id`	string	The action this receipt records.
`connector`	string	The connector instance the action routed through.
`tool`	string	The tool invoked, or refused.
`entity_key`	string	The single-flight key the disposition held.
`idempotency_key`	string	The dedup key the disposition checked.
`verdict`	object	The trust evaluation: `decision`, `tier`, and the matching `rule`.
`outcome`	string	`applied`, `blocked`, `deduplicated`, `failed`, or `awaiting_approval`.
`approver`	string or null	Who approved an `ALERT` action; `null` for unattended dispositions.
`request_id`	string	The API request that caused the disposition, for correlation with your own logs.
`at`	string	RFC 3339 timestamp of the disposition.

json · the receipt object

{
  "id": "rc_5b21",
  "object": "receipt",
  "reseller_id": null,
  "tenant_id": "t_8f2ac901",
  "operator_id": "op_8f2a1c",
  "operator": "order-risk",
  "event_id": "ev_3a91c7",
  "plan_id": "pl_7c1a",
  "action_id": "act_91d0",
  "connector": "cn_7d2f4a",
  "tool": "order.hold",
  "entity_key": "order:SO-10884",
  "idempotency_key": "order-risk:SO-10884:hold",
  "verdict": { "decision": "ALLOW", "tier": 1, "rule": "tool:order.hold max_value:500" },
  "outcome": "applied",
  "approver": null,
  "request_id": "req_9b3e21f0",
  "at": "2026-07-02T15:04:41Z"
}

Guardrail

A named, versioned trust policy: the deterministic half of the loop. Rules match on connector and tool, optionally constrain by value, and yield a decision. Evaluation is default-closed: no matching rule is BLOCK, a matching rule with a failed constraint is BLOCK, and among passing matches ALERT wins over ALLOW. See the Guardrails API and Trust tiers.

Field	Type	Description
`id`	string	Unique identifier, prefixed `grd_`.
`object`	string	Always `guardrail_policy`.
`name`	string	The policy's name within the tenant.
`description`	string or null	What the policy is for, in plain language.
`status`	string	`active` or `disabled`. A disabled policy contributes no rules, which under default-closed evaluation means less is allowed, never more.
`version`	integer	Monotonic version, incremented on every rules change. Receipts record the version that evaluated them.
`rules`	object[]	The rules, evaluated as a set. Each rule: optional `connector` and `tool` matchers (absent means any), optional `max_value` constraint, and a `decision` of `ALLOW`, `ALERT`, or `BLOCK`.
`created_at`	string	RFC 3339 timestamp of creation.
`updated_at`	string	Timestamp of the most recent change.

json · the guardrail policy object

{
  "id": "grd_3c90e1",
  "object": "guardrail_policy",
  "name": "refund-ceiling",
  "description": "Refunds auto-run to $250; larger refunds page a human.",
  "status": "active",
  "version": 3,
  "rules": [
    { "tool": "order.refund", "decision": "ALLOW", "max_value": 250 },
    { "tool": "order.refund", "decision": "ALERT" }
  ],
  "created_at": "2026-05-14T10:00:00Z",
  "updated_at": "2026-06-30T16:42:12Z"
}

Tenant

The isolation boundary. Every envelope, plan, action, and receipt carries the tenant's id, and a key belongs to exactly one tenant; another tenant's ids read as 404 not_found, not 403. Workspaces subdivide a tenant for scoping keys and organizing operators. See Tenancy & isolation and the Tenants API.

Field	Type	Description
`id`	string	Unique identifier, prefixed `t_`.
`object`	string	Always `tenant`.
`name`	string	Display name.
`slug`	string	URL-safe identifier, unique across the platform.
`reseller_id`	string or null	The reseller the tenant belongs to; `null` means Fibric-direct.
`plan`	string	The billing plan, for example `early_access` or `team`.
`workspaces`	object[]	The tenant's workspaces: `id` (prefixed `ws_`), `name`, `created_at`. Keys may be pinned to one workspace; see tenant and workspace scoping.
`created_at`	string	RFC 3339 timestamp of creation.

json · the tenant object

{
  "id": "t_8f2ac901",
  "object": "tenant",
  "name": "Acme Fulfillment",
  "slug": "acme-fulfillment",
  "reseller_id": null,
  "plan": "early_access",
  "workspaces": [
    { "id": "ws_2d81f0", "name": "us-store", "created_at": "2026-05-01T10:00:00Z" },
    { "id": "ws_9a44c2", "name": "eu-store", "created_at": "2026-06-12T09:30:00Z" }
  ],
  "created_at": "2026-04-01T12:00:00Z"
}

Webhook endpoint

A registered HTTPS destination for signed deliveries: plan proposals, action dispositions, connector status changes, and receipts, pushed as they happen. Deliveries wrap the full API objects defined on this page, so a consumer rarely needs a follow-up fetch. Signature verification, the retry schedule, and the delivery object are covered in the Webhooks API.

Field	Type	Description
`id`	string	Unique identifier, prefixed `whk_`.
`object`	string	Always `webhook_endpoint`.
`url`	string	The HTTPS destination. Plain HTTP is rejected at creation.
`types`	string[]	Subscribed delivery types, for example `plan.proposed` or `action.needs_approval`.
`status`	string	`active`, `disabled` (by you), or `suspended` (by Fibric, after sustained delivery failure).
`secret`	string	Signing secret, prefixed `whsec_`. Returned in full at creation and rotation only; reads return a hint. Used to verify `Fibric-Signature`.
`created_at`	string	RFC 3339 timestamp of creation.
`last_delivery_at`	string or null	Timestamp of the most recent delivery attempt, successful or not.

json · the webhook endpoint object

{
  "id": "whk_6b3e0d",
  "object": "webhook_endpoint",
  "url": "https://ops.example.com/fibric/webhook",
  "types": ["plan.proposed", "action.needs_approval", "connector.status_changed"],
  "status": "active",
  "secret": "whsec_5f2e8a1c9b0d7e4f6a3b",
  "created_at": "2026-07-02T15:30:00Z",
  "last_delivery_at": null
}

API key

The credential every request authenticates with. A key proves identity, names the one tenant it can touch, and carries the scopes that decide what it can do there. The full secret is returned exactly once, at creation; the object stores only a display hint. Key anatomy, roles, and rotation are covered in Authentication and the API keys reference.

Field	Type	Description
`id`	string	Unique identifier, prefixed `key_`. This is the id you revoke; it is not the secret.
`object`	string	Always `api_key`.
`name`	string	Your label for the workload holding the key, for example `ingest-gateway`.
`mode`	string	`live` or `test`. The secret's prefix (`sk_live_` / `sk_test_`) matches. Test keys operate on an isolated test partition.
`role`	string or null	The role preset the key was created from (`read_only`, `ingest`, `operate`, `admin`), or `null` for hand-assembled scopes. The expanded scopes are stored on the key; later role changes never alter existing keys.
`scopes`	string[]	The granted scopes, for example `events:write`. The grant is the union; there is no implicit escalation.
`workspace_id`	string or null	Workspace pin. A pinned key behaves as if the tenant contained only that workspace; `null` sees the whole tenant.
`hint`	string	Display hint for the secret, for example `sk_live_…41f7`. The full secret is never readable after creation.
`status`	string	`active` or `revoked`. Revocation is immediate and permanent.
`last_used_at`	string or null	Timestamp of the most recent authenticated request; `null` if never used.
`created_at`	string	RFC 3339 timestamp of creation.
`revoked_at`	string or null	Timestamp of revocation; `null` while active.

json · the API key object

{
  "id": "key_4e91b2",
  "object": "api_key",
  "name": "ingest-gateway",
  "mode": "live",
  "role": "ingest",
  "scopes": ["events:write"],
  "workspace_id": null,
  "hint": "sk_live_…41f7",
  "status": "active",
  "last_used_at": "2026-07-02T15:11:02Z",
  "created_at": "2026-05-20T09:00:00Z",
  "revoked_at": null
}

Object reference

#Shared conventions

#How objects relate

#Envelope (event)

#Operator

#Connector

#Capability

#Plan

#Action

#Receipt

#Guardrail

#Tenant

#Webhook endpoint

#API key