Chao Context

Reference for the Chao Context API. Chao is Chainabit's Chainy-native behavioral advisor; this endpoint assembles the resolved context that powers personalized coaching sessions.

See also

• How-to: Start a Chao Session
• Explanation: Chao Context Model
• Reference: Sessions

Endpoints

Method	Path	Description	Auth	Rate Limit
GET	/ai/chao/context	Get resolved Chao context	JWT + Entitlement	30/min

---

GET /ai/chao/context

Description

Retrieve the resolved Chao context. Behavior depends on whether chainyId is provided:

• With chainyId — returns Chainy-scoped memories and chain productivity data for that specific goal system.
• Without chainyId — returns general mode context: account-wide memories, near-term bits (tasks), and active chainies (goal systems with their vision).

Authentication: JWT Bearer token + active AI entitlement required. Rate limit: 30/min

Request

Query Parameters

Parameter	Type	Required	Description
chainyId	string (UUID)	No	The Chainy to resolve context for. Must belong to the authenticated account. If omitted, general mode is returned.

Response

Response — Chainy Mode

Returned when chainyId is provided.

{
  "data": {
    "mode": "chainy",
    "chainyId": "550e8400-e29b-41d4-a716-446655440000",
    "memories": [
      {
        "content": "User prefers morning workouts before 8 AM.",
        "type": "preference",
        "scope": "chainy",
        "importance": 85,
        "origin": "inferred",
        "confidence": "high"
      }
    ],
    "productivitySnapshot": {
      "chains": [
        {
          "title": "Morning Run",
          "currentStreak": 12,
          "longestStreak": 30,
          "totalCompletions": 156,
          "status": "active"
        }
      ],
      "recentCompletions": [
        {
          "chainTitle": "Morning Run",
          "completedAt": "2026-03-20T07:30:00.000Z"
        }
      ]
    }
  }
}

Response — General Mode

Returned when chainyId is omitted. Chao surfaces near-term tasks and active goal systems across the full account.

{
  "data": {
    "mode": "general",
    "memories": [
      {
        "content": "User prefers concise, action-oriented advice.",
        "type": "preference",
        "scope": "account",
        "importance": 70,
        "origin": "inferred",
        "confidence": "high"
      }
    ],
    "bits": [
      {
        "id": "a1b2c3d4-...",
        "title": "Write unit tests",
        "description": "Cover edge cases for the auth module.",
        "priority": "p2",
        "scheduledFor": "2026-03-31",
        "score": 47
      }
    ],
    "chainies": [
      {
        "id": "550e8400-...",
        "title": "Morning Athlete",
        "description": "Build a consistent morning exercise routine to feel energized daily.",
        "status": "active"
      }
    ]
  }
}

Response Fields — Chainy Mode

Field	Type	Description
mode	string	Always "chainy"
chainyId	string	The Chainy UUID this context was resolved for
memories	object[]	Chainy-scoped memory entries
memories[].content	string	Human-readable memory content
memories[].type	string	Memory type: preference, behavioral_pattern, goal, observation
memories[].scope	string	Memory scope: chainy, account, workspace
memories[].importance	number	Importance score (0–100)
memories[].origin	string	How the memory was created: inferred, explicit, system
memories[].confidence	string	Confidence level: high, medium, low
productivitySnapshot.chains[].title	string	Chain title
productivitySnapshot.chains[].currentStreak	number	Current active streak
productivitySnapshot.chains[].longestStreak	number	All-time longest streak
productivitySnapshot.chains[].totalCompletions	number	Total completions
productivitySnapshot.chains[].status	string	Chain status: active, paused, archived
productivitySnapshot.recentCompletions[].chainTitle	string	Title of the completed chain
productivitySnapshot.recentCompletions[].completedAt	string	ISO 8601 completion timestamp

Response Fields — General Mode

Field	Type	Description
mode	string	Always "general"
memories	object[]	Account-wide memory entries (same shape as chainy mode)
bits	object[]	Near-term tasks scored by date proximity and priority (max 10)
bits[].id	string	Bit UUID
bits[].title	string	Task title
bits[].description	string | null	Short task description
bits[].priority	string	Priority: p1, p2, p3, p4
bits[].scheduledFor	string | null	ISO date the bit is scheduled for
bits[].score	number	Computed relevance score (higher = more urgent)
chainies	object[]	Active goal systems (max 5)
chainies[].id	string	Chainy UUID
chainies[].title	string	Goal system title
chainies[].description	string | null	Goal system vision or description
chainies[].status	string	Always "active" in this response

Error Responses

Status	Code	Description
400	BAD_REQUEST	chainyId was provided but is not a valid UUID
401	UNAUTHORIZED	Missing or invalid JWT token
403	FORBIDDEN	No active AI entitlement
404	NOT_FOUND	Chainy not found or does not belong to the authenticated account

Code Examples

In Chainy mode, chainyId must be the id of an existing Chainy — e.g. from Create Chainy, shown below as $CHAINY_ID.

cURL — Chainy mode

curl "https://api.chainabit.com/api/v1/ai/chao/context?chainyId=$CHAINY_ID" \
  -H "Authorization: Bearer $TOKEN"

cURL — General mode

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

JavaScript

const chainyId = process.env.CHAINY_ID; // id of the Chainy to resolve context for

// Chainy-scoped mode
const chainyRes = await fetch(
  `${BASE_URL}/ai/chao/context?chainyId=${chainyId}`,
  { headers: { Authorization: `Bearer ${TOKEN}` } },
);

// General mode
const generalRes = await fetch(
  `${BASE_URL}/ai/chao/context`,
  { headers: { Authorization: `Bearer ${TOKEN}` } },
);

Python

import os
import requests

chainy_id = os.environ["CHAINY_ID"]  # id of the Chainy to resolve context for

# Chainy-scoped mode
chainy_res = requests.get(
    f"{BASE_URL}/ai/chao/context",
    params={"chainyId": chainy_id},
    headers={"Authorization": f"Bearer {TOKEN}"},
)

# General mode
general_res = requests.get(
    f"{BASE_URL}/ai/chao/context",
    headers={"Authorization": f"Bearer {TOKEN}"},
)