Run Your First AI Session

In this tutorial you will create an AI conversation session, send messages, stream responses in real time using Server-Sent Events (SSE), and execute AI feature runs.

Prerequisites

A Chainabit account with a valid access token
curl available in your terminal
A plan that includes AI credits (check your balance at /wallet/balance)

Set your environment variables:

bash

export TOKEN="your-access-token"

Step 1: Check Available AI Providers

Before starting a session, check which AI providers your plan gives you access to:

bash

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

Response includes an isAccessible flag per provider:

json

{
  "data": [
    {
      "key": "google",
      "displayName": "Google",
      "isActive": true,
      "isAccessible": true
    },
    {
      "key": "openai",
      "displayName": "OpenAI",
      "isActive": true,
      "isAccessible": true
    },
    {
      "key": "anthropic",
      "displayName": "Anthropic",
      "isActive": true,
      "isAccessible": false
    }
  ]
}

isAccessible: true means your plan grants access to that provider. Use a provider key (e.g. openai) when sending messages.

Free plan: only google is accessible. Paid plans unlock additional providers.

Step 2: Create a New AI Session

A session holds a conversation thread:

bash

curl -s -X POST "https://api.chainabit.com/api/v1/ai/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Fitness coaching" }'

Response:

json

{
  "data": {
    "id": "session_01HQS...",
    "title": "Fitness coaching",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Save the session ID:

bash

export SESSION_ID="session_01HQS..."

Step 3: Send a Message

Post a message to the session. Optionally pass a provider and effortMode to control which AI is used:

bash

curl -s -X POST "https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I want to build a morning routine. I have 45 minutes before work. What activities should I include?",
    "provider": "openai",
    "effortMode": "thinking"
  }'

Field	Values	Description
`provider`	`google`, `openai`, `anthropic`, `mistral`	Provider to use. Defaults to `google`. Requires plan access.
`effortMode`	`basic`, `thinking`, `pro`	Model tier. `basic` = fast, `thinking` = balanced, `pro` = most capable.

Both fields are optional — omitting them uses your plan's default (Google, basic).

Response:

json

{
  "data": {
    "id": "msg_01HQT...",
    "sessionId": "session_01HQS...",
    "role": "user",
    "content": "I want to build a morning routine. I have 45 minutes before work. What activities should I include?",
    "createdAt": "2026-03-17T10:01:00.000Z"
  }
}

Save the message ID to stream the AI response:

bash

export MESSAGE_ID="msg_01HQT..."

Step 4: Stream the AI Response via SSE

Connect to the SSE streaming endpoint to receive the AI response in real time. Use curl -N to disable buffering:

bash

curl -N "https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/messages/$MESSAGE_ID/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

SSE Event Format

The server sends events in the standard SSE format. Each event has a type and a JSON data payload:

event: message.delta
data: {"eventId":1,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":"Great question! Here's a"}}

event: message.delta
data: {"eventId":2,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":" structured 45-minute morning routine"}}

event: message.delta
data: {"eventId":3,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":" that balances exercise, mindfulness, and preparation:\n\n"}}

event: message.delta
data: {"eventId":4,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":"1. **Wake up + hydrate** (2 min)\n"}}

event: message.delta
data: {"eventId":5,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":"2. **Stretching** (5 min)\n"}}

event: message.delta
data: {"eventId":6,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":"3. **Bodyweight workout** (20 min)\n"}}

event: message.delta
data: {"eventId":7,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":"4. **Shower** (10 min)\n"}}

event: message.delta
data: {"eventId":8,"type":"message.delta","runId":"run_01HQU...","payload":{"delta":"5. **Journaling** (8 min)\n"}}

event: message.completed
data: {"eventId":9,"type":"message.completed","runId":"run_01HQU...","payload":{"messageId":"msg_01HQU...","content":"Great question! Here's a structured 45-minute morning routine..."}}

Event Types

Event	Description
`message.delta`	A chunk of the response content
`message.completed`	Streamed assistant content is complete
`tool.*`	Tool-card, progress, approval, and result events
`run.error` / `run.failed`	An error occurred during generation
`run.settlement.completed`	Run is fully settled and terminal

Step 5: List Conversation History

Retrieve the full conversation thread for a session:

bash

curl -s "https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN"

Response:

json

{
  "data": [
    {
      "id": "msg_01HQT...",
      "role": "user",
      "content": "I want to build a morning routine. I have 45 minutes before work. What activities should I include?",
      "createdAt": "2026-03-17T10:01:00.000Z"
    },
    {
      "id": "msg_01HQU...",
      "role": "assistant",
      "content": "Great question! Here's a structured 45-minute morning routine...",
      "createdAt": "2026-03-17T10:01:05.000Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

Step 6: Create an AI Run

AI runs execute a specific feature against your data. For example, generate a weekly activity summary:

bash

curl -s -X POST "https://api.chainabit.com/api/v1/ai/runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "featureKey": "weekly-activity-summary",
    "input": {
      "chainyId": "chainy_01HQXYZ...",
      "weekOf": "2026-03-10"
    }
  }'

Response:

json

{
  "data": {
    "id": "run_01HQV...",
    "featureKey": "weekly-activity-summary",
    "status": "running",
    "createdAt": "2026-03-17T10:05:00.000Z"
  }
}

Save the run ID:

bash

export RUN_ID="run_01HQV..."

Step 7: Stream Run Output

Stream the AI run output the same way you stream messages:

bash

curl -N "https://api.chainabit.com/api/v1/ai/runs/$RUN_ID/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Output:

event: run.started
data: {"eventId":1,"type":"run.started","runId":"run_01HQV...","payload":{"runId":"run_01HQV..."}}

event: message.delta
data: {"eventId":2,"type":"message.delta","runId":"run_01HQV...","payload":{"delta":"## Weekly Summary: March 10-16\n\n"}}

event: message.delta
data: {"eventId":3,"type":"message.delta","runId":"run_01HQV...","payload":{"delta":"**Workout Chain:** 5/7 days completed (71%)\n"}}

event: message.delta
data: {"eventId":4,"type":"message.delta","runId":"run_01HQV...","payload":{"delta":"**Nutrition Chain:** 6/7 days completed (86%)\n"}}

event: message.delta
data: {"eventId":5,"type":"message.delta","runId":"run_01HQV...","payload":{"delta":"\n### Highlights\n- Longest streak this week: Running (7 days)\n"}}

event: message.completed
data: {"eventId":6,"type":"message.completed","runId":"run_01HQV...","payload":{"content":"## Weekly Summary: March 10-16\n\n..."}}

event: run.settlement.completed
data: {"eventId":7,"type":"run.settlement.completed","runId":"run_01HQV...","payload":{"status":"completed"}}

Handling Connection Drops

SSE connections can drop due to network issues. To handle reconnection:

Track the last event you received
When the connection drops, reconnect to the same endpoint
The server will resume from where it left off if the generation is still in progress

bash

# If the connection drops, simply reconnect:
curl -N "https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/messages/$MESSAGE_ID/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

If you receive run.settlement.completed, run.failed, or run.error, the stream is terminal and no reconnection is needed.

Summary

In this tutorial you:

Listed available AI models on your plan
Created an AI session for a conversation thread
Sent a message and captured its ID
Streamed the AI response via SSE in real time
Retrieved the full conversation history
Created an AI run for a specific feature
Streamed the run output with the same SSE pattern

Next Steps

How to Stream AI Responses for advanced streaming patterns and JavaScript examples
Create an AI Agent to build a reusable agent that can run sessions for you
API Reference for the complete AI endpoints documentation

Run Your First AI Session ​

Prerequisites ​

Step 1: Check Available AI Providers ​

Step 2: Create a New AI Session ​

Step 3: Send a Message ​

Step 4: Stream the AI Response via SSE ​

SSE Event Format ​

Event Types ​

Step 5: List Conversation History ​

Step 6: Create an AI Run ​

Step 7: Stream Run Output ​

Handling Connection Drops ​

Summary ​

Next Steps ​

Run Your First AI Session

Prerequisites

Step 1: Check Available AI Providers

Step 2: Create a New AI Session

Step 3: Send a Message

Step 4: Stream the AI Response via SSE

SSE Event Format

Event Types

Step 5: List Conversation History

Step 6: Create an AI Run

Step 7: Stream Run Output

Handling Connection Drops

Summary

Next Steps