Start a Chao Session

This guide walks you through fetching Chao context for a Chainy and starting a Chao-powered coaching session.

Prerequisites

• A Chainabit account with a valid access token
• An active AI entitlement on your plan
• At least one Chainy already created in your account
• curl available in your terminal (or use the JavaScript/Python examples)

---

Step 1: Find your Chainy ID

You need the UUID of the Chainy you want to coach. Retrieve your Chainies from the Productivity API:

cURL

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

JavaScript

const res = await fetch(`${BASE_URL}/productivity/chainies`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();
const chainyId = data[0].id; // pick your target Chainy

Python

import requests

res = requests.get(
    f"{BASE_URL}/productivity/chainies",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
chainy_id = res.json()["data"][0]["id"]

Note the id field — this is your chainyId.

---

Step 2: Fetch Chao context

Before starting a session, confirm the Chao context resolves for your Chainy. This also verifies your entitlement and that the Chainy belongs to your account.

cURL

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

JavaScript

const res = await fetch(
  `${BASE_URL}/ai/chao/context?chainyId=${chainyId}`,
  { headers: { Authorization: `Bearer ${TOKEN}` } },
);
const { data } = await res.json();
console.log(`Memories: ${data.memories.length}`);
console.log(`Chains in snapshot: ${data.productivitySnapshot.chains.length}`);

Python

import requests

res = requests.get(
    f"{BASE_URL}/ai/chao/context",
    params={"chainyId": chainy_id},
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]
print(f"Memories: {len(data['memories'])}")
print(f"Chains: {len(data['productivitySnapshot']['chains'])}")

A successful response returns memories and a productivity snapshot. If you receive a 404, the Chainy ID is invalid or does not belong to your account.

---

Step 3: Create a Chao session

Create an AI session with assistantType: "chao" and bind it to your Chainy:

cURL

curl -X POST "https://api.chainabit.com/api/v1/ai/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Chainy Coach",
    "assistantType": "chao",
    "primaryContextType": "chainy",
    "primaryContextId": "'"$CHAINY_ID"'"
  }'

JavaScript

const res = await fetch(`${BASE_URL}/ai/sessions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "My Chainy Coach",
    assistantType: "chao",
    primaryContextType: "chainy",
    primaryContextId: chainyId,
  }),
});
const { data: session } = await res.json();
const sessionId = session.id;

Python

import requests

res = requests.post(
    f"{BASE_URL}/ai/sessions",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "title": "My Chainy Coach",
        "assistantType": "chao",
        "primaryContextType": "chainy",
        "primaryContextId": chainy_id,
    },
)
session_id = res.json()["data"]["id"]

Field	Value	Description
assistantType	"chao"	Activates the Chao behavioral advisor
primaryContextType	"chainy"	Scopes the session to a specific Chainy
primaryContextId	your Chainy UUID	Binds Chao context to this Chainy
mode	"approval" / "auto" / "plan"	Controls how write tools execute (see Session Modes); defaults to "approval"

---

Step 4: Send your first message

Send a message to the session. Chao automatically injects the resolved context:

cURL

curl -X POST "https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "How am I doing with my Morning Run chain?"}'

JavaScript

const res = await fetch(`${BASE_URL}/ai/sessions/${sessionId}/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "How am I doing with my Morning Run chain?" }),
});
const { data: message } = await res.json();

Python

import requests

res = requests.post(
    f"{BASE_URL}/ai/sessions/{session_id}/messages",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={"content": "How am I doing with my Morning Run chain?"},
)

To receive the AI response as a stream, see Stream AI Responses.

---

Next Steps

• Chao Context Reference — full endpoint schema and error codes
• Chao Context Model — how context is assembled and why
• Sessions Reference — manage session lifecycle
• Stream AI Responses — receive Chao responses via SSE