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

json

{
  "data": [
    {
      "id": "cm5analysis01",
      "type": "streak",
      "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

cURLJavaScriptPython

bash

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

json

{
  "data": {
    "id": "cm5analysis01",
    "type": "streak",
    "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 streak 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 streaks"
      ]
    },
    "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

cURLJavaScriptPython

bash

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	`streak`, `productivity`, `routine`, `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

json

{
  "data": {
    "id": "cm5analysis01",
    "type": "streak",
    "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 streak 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 streaks"
      ]
    },
    "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

cURLJavaScriptPython

bash

curl -X POST https://api.chainabit.com/api/v1/ai/analyses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "streak",
    "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: "streak",
    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": "streak",
        "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, streak health, velocity, and fragmentation	`healthScore`, `signals`, `breakdown`
`continuity`	Identifies chains at risk of streak break, broken streaks, and strong performers	`atRisk`, `broken`, `strong`
`blocker`	Detects stalled chains with zero/declining progress	`stalled`, `declining`
`routine`	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 streaks 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.

AI Analyses ​

Endpoints ​

GET /ai/analyses ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

GET /ai/analyses/:id ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

POST /ai/analyses ​

Request ​

Request Body ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

Chao Analysis Types ​

AI Analyses

Endpoints

GET /ai/analyses

Request

Response

Response Example

Response Fields

Code Examples

GET /ai/analyses/:id

Request

Response

Response Example

Response Fields

Code Examples

POST /ai/analyses

Request

Request Body

Response

Response Example

Response Fields

Code Examples

Chao Analysis Types