Chain Execution Policy API

Configure what Chao (your AI co-pilot) may do autonomously within each Chain's execution lifecycle.

Overview

Every Chain has an execution policy — a JSON object that defines:

• Who executes: none, suggest, draft, or auto-execute
• When: period_start, period_end, both, or none
• What counts as done: free_form, structured_output, or linked_artifact
• Which tools: e.g., ["slack", "github", "google_calendar"]
• Human approval: required or automatic

Chains without a policy (or with agentMode: 'none') behave exactly as before — Chao has no autonomous role.

---

Endpoints

Get Execution Policy

GET /chains/{id}/execution-policy

Request

Path Parameter	Description
id	Chain ID

Headers

Authorization: Bearer <token>

Response

Response 200

{
  "data": {
    "agentMode": "auto-execute",
    "triggerHook": "period_end",
    "evaluationRule": "free_form",
    "allowedTools": ["slack", "github"],
    "approvalRequired": false
  },
  "success": true
}

Code Example

cURL Example

---

Set Execution Policy

PATCH /chains/{id}/execution-policy

Request

Path Parameter	Description
id	Chain ID

Headers

Authorization: Bearer <token>
Content-Type: application/json

Request Body

Field	Type	Required	Values
agentMode	string	Yes	none | suggest | draft | auto-execute
triggerHook	string	Yes	none | period_start | period_end | both
evaluationRule	string	Yes	free_form | structured_output | linked_artifact
allowedTools	string[]	No	Tool integration keys
approvalRequired	boolean	No	Default: false

Request Example — Enable auto-execute

{
  "agentMode": "auto-execute",
  "triggerHook": "period_end",
  "evaluationRule": "free_form",
  "allowedTools": [],
  "approvalRequired": false
}

Response

Response 200

{
  "data": {
    "agentMode": "auto-execute",
    "triggerHook": "period_end",
    "evaluationRule": "free_form",
    "allowedTools": [],
    "approvalRequired": false
  },
  "success": true
}

Code Example

cURL Example

---

Get Bit Tree (Workflow DAG)

Returns the Chain's Bit tree as nodes + edges for rendering or inspection.

GET /chains/{id}/bit-tree

Request

Path Parameter	Description
id	Chain ID

Response

Response 200

{
  "data": {
    "nodes": [
      {
        "id": "bit-001",
        "title": "Collect weekly data",
        "status": "pending",
        "source": "user",
        "parentId": null,
        "rank": 0
      },
      {
        "id": "bit-002",
        "title": "Draft summary",
        "status": "pending",
        "source": "user",
        "parentId": null,
        "rank": 1
      }
    ],
    "edges": [
      {
        "fromBitId": "bit-001",
        "toBitId": "bit-002",
        "relationType": "depends_on"
      }
    ]
  },
  "success": true
}

Code Example

cURL Example

curl -X GET "https://api.chainabit.com/api/v1/chains/abc-123/bit-tree" \
  -H "Authorization: Bearer $TOKEN"

---

Trigger a Workflow Run

Manually create and enqueue a workflow run from the Chain's Bit tree. Useful for testing or on-demand execution.

When the run is queued, it records the exact behavior of every agent its steps will run: the agent's version, instructions, configuration, tools, skills, data access, and connector attachments. If an agent cannot be recorded — for example it is no longer available in the chain's workspace — the trigger is refused with 422 and the message agent_manifest_unavailable.

When an agent step starts, the agent's current behavior is compared with what was recorded. If the agent changed after the run was queued, or is no longer available, the step fails without running and is not retried; trigger a new run to use the agent as it is now. Runs queued before this check existed carry no record, so their agent steps fail the same way and must be triggered again.

POST /chains/{id}/trigger-run

Request

Path Parameter	Description
id	Chain ID

Response

Response 200

{
  "data": {
    "runId": "run-uuid-here",
    "status": "queued"
  },
  "success": true
}

Code Example

cURL Example

curl -X POST "https://api.chainabit.com/api/v1/chains/abc-123/trigger-run" \
  -H "Authorization: Bearer $TOKEN"

---

Hub: Chain Health Signals

Get real-time execution health for all active Chains. Cached for 30 seconds.

GET /chains/health

Request

No path or query parameters.

Response

Response 200

{
  "data": {
    "chains": [
      {
        "chainId": "abc-123",
        "title": "Weekly Report",
        "colorHex": "#10B981",
        "agentSignal": "idle",
        "agentMode": "auto-execute",
        "totalCompletions": 7,
        "currentPeriodCompleted": false,
        "periodEnd": "2026-03-28T23:59:59Z",
        "activeRunId": null
      },
      {
        "chainId": "def-456",
        "title": "Daily Standup",
        "colorHex": "#3B82F6",
        "agentSignal": "running",
        "agentMode": "auto-execute",
        "totalCompletions": 14,
        "currentPeriodCompleted": false,
        "periodEnd": "2026-03-22T23:59:59Z",
        "activeRunId": "run-789"
      }
    ],
    "computedAt": "2026-03-22T10:30:00Z",
    "cacheTtlSeconds": 30
  },
  "success": true
}

Signal Values

Signal	Meaning
idle	No active run. Chain is waiting for the next period trigger or manual action.
running	Chao is actively executing the Bit tree.
awaiting_approval	Chao finished but approvalRequired: true — Chainer must review.
blocked	A workflow step failed and cannot proceed without intervention.

Code Example

cURL Example

curl -X GET "https://api.chainabit.com/api/v1/chains/health" \
  -H "Authorization: Bearer $TOKEN"

---

Bit Source Attribution

Each Bit has a source field indicating who created it:

Source	Meaning
user	Created by the Chainer manually (default)
agent	Created by Chao during autonomous execution
system	Created by Chainabit system processes

This enables audit trails: in the Bit list and Chain detail views, agent-sourced Bits are visually distinguished.

---

Error Responses

Status	Code	Description
400	BAD_REQUEST	Invalid UUID or validation error in request body
403	FORBIDDEN	Feature not enabled in your plan, or limit reached
404	NOT_FOUND	Chain not found or not owned by the authenticated Chainer
500	INTERNAL_SERVER_ERROR	No active AI model available (contact support)