AI Analyses

Request and retrieve AI-generated analyses of productivity data, including Chao analysis types for chain health monitoring and actionable insights.

Endpoints

Method	Path	Description	Auth	Rate Limit
GET	/ai/analyses	List analyses	JWT + Entitlement	60/min
GET	/ai/analyses/:id	Get an analysis	JWT + Entitlement	60/min
POST	/ai/analyses	Create an analysis	JWT + Entitlement	10/min

---

GET /ai/analyses

List all analyses for the authenticated user.

Request

• Auth: JWT Bearer token + active AI entitlement required
• Rate limit: 60/min
• No path or query parameters

Response

Response Example

{
  "data": [
    {
      "id": "cm5analysis01",
      "type": "patterns",
      "targetType": "chain",
      "targetId": "cm5chain01",
      "status": "completed",
      "createdAt": "2026-03-17T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Response Fields

Field	Type	Description
id	string	Analysis ID
type	string	Analysis type
targetType	string	Target entity type
targetId	string	Target entity ID
status	string	pending, running, completed, failed
source	string | null	Analysis source (chao, system, manual)
evidence	array | null	Supporting evidence data
chainyId	string | null	Linked Chainy ID
createdAt	string	ISO 8601

Code Examples

cURL

curl https://api.chainabit.com/api/v1/ai/analyses \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const res = await fetch(`${BASE_URL}/ai/analyses`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data, meta } = await res.json();

Python

import requests

res = requests.get(
    f"{BASE_URL}/ai/analyses",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
body = res.json()

---

GET /ai/analyses/:id

Get the full details and result of a specific analysis.

Request

• Auth: JWT Bearer token + active AI entitlement required
• Rate limit: 60/min
• Path params: id — use the id from Create an Analysis's response (data.id) as $ANALYSIS_ID

Response

Response Example

{
  "data": {
    "id": "cm5analysis01",
    "type": "patterns",
    "targetType": "chain",
    "targetId": "cm5chain01",
    "status": "completed",
    "result": {
      "summary": "Your vocabulary practice chain shows strong consistency with 85% completion rate over the past 6 weeks.",
      "insights": [
        "You tend to miss completions on weekends",
        "Your longest completion history was 12 days in February",
        "Morning completions correlate with higher retention scores"
      ],
      "recommendations": [
        "Set a weekend-specific reminder at 10 AM",
        "Consider shorter weekend sessions to maintain run history"
      ]
    },
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Response Fields

Field	Type	Description
id	string	Analysis ID
type	string	Analysis type
targetType	string	Target entity type
targetId	string	Target entity ID
status	string	pending, running, completed, failed
source	string | null	Analysis source (chao, system, manual)
evidence	array | null	Supporting evidence data
chainyId	string | null	Linked Chainy ID
result.summary	string	Summary text
result.insights	string[]	Key insights
result.recommendations	string[]	Action recommendations
createdAt	string	ISO 8601

Code Examples

cURL

curl https://api.chainabit.com/api/v1/ai/analyses/$ANALYSIS_ID \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const analysisId = process.env.ANALYSIS_ID; // id of the analysis to fetch

const res = await fetch(`${BASE_URL}/ai/analyses/${analysisId}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

Python

import os
import requests

analysis_id = os.environ["ANALYSIS_ID"]  # id of the analysis to fetch

res = requests.get(
    f"{BASE_URL}/ai/analyses/{analysis_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

---

POST /ai/analyses

Create a new AI analysis for a target entity.

Request

• Auth: JWT Bearer token + active AI entitlement required
• Rate limit: 10/min
• targetId must be the id of an existing entity matching targetType — e.g. a chain's id from Create Chain, shown below as $CHAIN_ID.

Request Body

Field	Type	Required	Constraints	Description
type	string	Yes	patterns, productivity, execution_timing, time, chainy_health, continuity, blocker, focus, recovery	Analysis type
targetType	string	Yes	chain, chainy, bit	Target entity type
targetId	string	Yes	Valid entity ID	ID of the target entity
dateRange	object	No	ISO 8601 dates	{ from: string, to: string }

Response

Response Example

{
  "data": {
    "id": "cm5analysis01",
    "type": "patterns",
    "targetType": "chain",
    "targetId": "cm5chain01",
    "status": "completed",
    "result": {
      "summary": "Your vocabulary practice chain shows strong consistency with 85% completion rate over the past 6 weeks.",
      "insights": [
        "You tend to miss completions on weekends",
        "Your longest completion history was 12 days in February",
        "Morning completions correlate with higher retention scores"
      ],
      "recommendations": [
        "Set a weekend-specific reminder at 10 AM",
        "Consider shorter weekend sessions to maintain run history"
      ]
    },
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Response Fields

Field	Type	Description
id	string	Analysis ID
type	string	Analysis type
targetType	string	Target entity type
targetId	string	Target entity ID
status	string	pending, running, completed, failed
source	string | null	Analysis source (chao, system, manual)
evidence	array | null	Supporting evidence data
chainyId	string | null	Linked Chainy ID
result.summary	string	Summary text
result.insights	string[]	Key insights
result.recommendations	string[]	Action recommendations
createdAt	string	ISO 8601

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/ai/analyses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "patterns",
    "targetType": "chain",
    "targetId": "'"$CHAIN_ID"'",
    "dateRange": {
      "from": "2026-02-01T00:00:00Z",
      "to": "2026-03-17T23:59:59Z"
    }
  }'

JavaScript

const chainId = process.env.CHAIN_ID; // id of the chain to analyze

const res = await fetch(`${BASE_URL}/ai/analyses`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "patterns",
    targetType: "chain",
    targetId: chainId,
    dateRange: {
      from: "2026-02-01T00:00:00Z",
      to: "2026-03-17T23:59:59Z",
    },
  }),
});
const { data } = await res.json();

Python

import os
import requests

chain_id = os.environ["CHAIN_ID"]  # id of the chain to analyze

res = requests.post(
    f"{BASE_URL}/ai/analyses",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "type": "patterns",
        "targetType": "chain",
        "targetId": chain_id,
        "dateRange": {
            "from": "2026-02-01T00:00:00Z",
            "to": "2026-03-17T23:59:59Z",
        },
    },
)
data = res.json()["data"]

---

Chao Analysis Types

Type	Description	Key Output Fields
chainy_health	Composite health score (0-100) from active chain ratio, completion history health, velocity, and fragmentation	healthScore, signals, breakdown
continuity	Identifies chains at risk of completion history break, broken run history, and strong performers	atRisk, broken, strong
blocker	Detects stalled chains with zero/declining progress	stalled, declining
execution_timing	Time-of-day and day-of-week completion pattern analysis	peakHours, peakDays, patterns
focus	Chain attention distribution, identifies neglected vs over-served chains	distribution, neglected, dominant
recovery	Structured recovery plan for broken run history with prioritized next actions	recoveryPlan (array of {chainTitle, action, recommendation, priority})

Note: Chao analyses may automatically generate pending suggestions (proposals) when actionable findings are detected. These proposals are always created with source: 'chao' and require explicit user approval — Chao never auto-applies changes.