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 /productivity/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

curl -X GET "https://api.chainabit.com/productivity/chains/abc-123/execution-policy" \
  -H "Authorization: Bearer $TOKEN"

---

Set Execution Policy

PATCH /productivity/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

curl -X PATCH "https://api.chainabit.com/productivity/chains/abc-123/execution-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentMode": "auto-execute",
    "triggerHook": "period_end",
    "evaluationRule": "free_form",
    "allowedTools": [],
    "approvalRequired": false
  }'

---

Get Bit Tree (Workflow DAG)

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

GET /productivity/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/productivity/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.

POST /productivity/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/productivity/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 /productivity/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",
        "currentStreak": 7,
        "currentPeriodCompleted": false,
        "periodEnd": "2026-03-28T23:59:59Z",
        "activeRunId": null
      },
      {
        "chainId": "def-456",
        "title": "Daily Standup",
        "colorHex": "#3B82F6",
        "agentSignal": "running",
        "agentMode": "auto-execute",
        "currentStreak": 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/productivity/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)