Actions & plans API

An ExecutionPlan is what the model proposes; the deterministic executor is what disposes it. This page documents reading proposed plans with the trust verdict on every action, approving or vetoing a plan, listing disposed actions, and undoing a reversible one. The model never executes anything through this API, and neither do you: every side effect passes through the executor's policy gate, single-flight lock, and idempotency dedup.

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.

#The plan object

A plan wraps the kernel's ExecutionPlan, its optional reasoning and its actions[], with API metadata and the verdict the trust policy produced for each action. Action fields match PlannedAction in packages/kernel/src/trust.ts: connector, tool, args, optional value, entity_key, and idempotency_key.

Verdicts a plan's actions can carry, and the disposition DEDUP that appears once an action has been disposed:

{
  "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" }
    },
    {
      "id": "act_91d1",
      "connector": "cn_7d2f4a",
      "tool": "order.notify",
      "args": { "order": "SO-10884", "to": "owner" },
      "entity_key": "order:SO-10884",
      "idempotency_key": "order-risk:SO-10884:notify",
      "verdict": { "decision": "ALERT", "tier": 2, "rule": "tool:order.notify" }
    }
  ],
  "proposed_at": "2026-07-02T15:02:09Z",
  "disposed_at": null,
  "expires_at": "2026-07-05T15:02:09Z"
}

Returns plans for the tenant, newest first, cursor-paginated. Filter to status=proposed to build an approval queue.

curl "https://api.fibric.io/v1/plans?status=proposed&operator_id=op_8f2a1c" \
  -H "Authorization: Bearer $FIBRIC_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "pl_7c1a",
      "object": "execution_plan",
      "operator_id": "op_8f2a1c",
      "event_id": "ev_3a91c7",
      "status": "proposed",
      "action_count": 2,
      "proposed_at": "2026-07-02T15:02:09Z",
      "expires_at": "2026-07-05T15:02:09Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List responses summarize each plan with action_count; retrieve a single plan for full actions and verdicts.

Returns the full plan object, including the model's reasoning and the verdict on every action. Inspect this before approving; the verdicts you see are the verdicts the executor will enforce.

curl https://api.fibric.io/v1/plans/pl_7c1a \
  -H "Authorization: Bearer $FIBRIC_KEY"

Returns the plan object. A cross-tenant id reads as 404 not_found.

The human escalation path: asks the executor to run a plan that is waiting in proposed. Approval is a request to run, not a bypass. The executor re-evaluates every action against the guardrails at execution time, enforces single-flight per entity_key, dedupes on each idempotency_key, and writes a receipt per action. An action whose verdict is BLOCK stays blocked with your approval on the record.

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

{
  "id": "pl_7c1a",
  "object": "execution_plan",
  "status": "executed",
  "approver": "ops@acme.com",
  "results": [
    { "action_id": "act_91d0", "disposition": "ALLOW", "ok": true, "receipt_id": "rc_5b21" },
    { "action_id": "act_91d1", "disposition": "ALERT", "ok": true, "receipt_id": "rc_5b22" }
  ],
  "disposed_at": "2026-07-02T15:04:41Z"
}

Error cases:

Refuses a proposed plan. Nothing in a vetoed plan ever runs, and the veto, with who and why, is written to the audit trail. The operator sees the veto as feedback on its next run over the same entity.

curl -X POST https://api.fibric.io/v1/plans/pl_7c1a/veto \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer already contacted; hold would double-message" }'

{
  "id": "pl_7c1a",
  "object": "execution_plan",
  "status": "vetoed",
  "vetoed_by": "ops@acme.com",
  "veto_reason": "customer already contacted; hold would double-message",
  "disposed_at": "2026-07-02T15:06:12Z"
}

#The action object

Once a plan is disposed, each of its actions becomes an addressable record of what the executor did with it. The disposition is the kernel's ActionDisposition: a trust decision, or DEDUP when the idempotency key had already been applied.

Returns disposed actions for the tenant, newest first, cursor-paginated.

curl "https://api.fibric.io/v1/actions?entity=order:SO-10884&disposition=ALLOW" \
  -H "Authorization: Bearer $FIBRIC_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "act_91d0",
      "object": "action",
      "plan_id": "pl_7c1a",
      "connector": "cn_7d2f4a",
      "tool": "order.hold",
      "entity_key": "order:SO-10884",
      "idempotency_key": "order-risk:SO-10884:hold",
      "disposition": "ALLOW",
      "ok": true,
      "receipt_id": "rc_5b21",
      "undoable": true,
      "undone": false,
      "disposed_at": "2026-07-02T15:04:41Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Runs the tool's declared compensating inverse, for example releasing a hold that order.hold placed. The undo is itself an action: it takes the same single-flight lock on the entity_key, carries its own idempotency key derived from the original, and writes its own receipt. The original action's record is never altered; undone flips to true and both receipts stand.

curl -X POST https://api.fibric.io/v1/actions/act_91d0/undo \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "shipment confirmed; releasing the hold" }'

{
  "id": "act_91d0",
  "object": "action",
  "undone": true,
  "undo_action_id": "act_9a44",
  "undo_receipt_id": "rc_5c07",
  "undone_at": "2026-07-02T17:40:02Z"
}

Error cases:

#Single-flight and idempotency semantics

Two kernel primitives shape every write on this page. Both are visible in packages/kernel/src/executor.ts and explained in Single-flight & idempotency.

• Single-flight per entity. The executor serializes side effects per entity_key. Inside the executor this is a wait, not a failure; at the API boundary, a request that would need a lock held by longer-running work returns 409 with code entity_locked and a Retry-After header. Retry the same request unchanged; when the lock is free, it disposes normally.
• Idempotency per side effect. Every side-effecting action carries an idempotency_key. A key the executor has already applied disposes as DEDUP: acknowledged, skipped, receipted, never applied twice. This is the property that makes a runaway flood, such as the 657-message incident that shaped the kernel, structurally impossible.