Manage AI Twins

In this tutorial you will create an AI digital twin, add memories to personalize it, trigger actions, and perform full CRUD operations. A twin is a personalized AI entity that learns from your data and can act on your behalf.

Prerequisites

• A Chainabit account with a valid access token
• curl available in your terminal
• A plan that includes AI credits

Set your environment variables:

export TOKEN="your-access-token"

---

Twin Architecture

---

Step 1: Create an AI Twin

Create a new digital twin with a persona:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/agents/twins" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Productivity Coach",
    "persona": "A focused, encouraging productivity coach that helps maintain daily routines.",
    "modelId": "model_01HQ..."
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/twins`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Productivity Coach',
    persona:
      'A focused, encouraging productivity coach that helps maintain daily routines.',
    modelId: 'model_01HQ...',
  }),
});
const data = await res.json();
console.log(data);

Python

import requests

res = requests.post(
    f"{BASE}/agents/twins",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Productivity Coach",
        "persona": "A focused, encouraging productivity coach that helps maintain daily routines.",
        "modelId": "model_01HQ...",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "twin_01HQA...",
    "name": "Productivity Coach",
    "persona": "A focused, encouraging productivity coach that helps maintain daily routines.",
    "status": "active",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Save the twin ID:

export TWIN_ID="twin_01HQA..."

---

Step 2: Add Memories

Memories give your twin context about your preferences and patterns:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/agents/twins/$TWIN_ID/memories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "preference",
    "content": "User prefers morning workouts between 6:00 and 7:00 AM.",
    "importance": "high"
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/twins/${TWIN_ID}/memories`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'preference',
    content:
      'User prefers morning workouts between 6:00 and 7:00 AM.',
    importance: 'high',
  }),
});
const data = await res.json();
console.log(data);

Python

res = requests.post(
    f"{BASE}/agents/twins/{TWIN_ID}/memories",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "type": "preference",
        "content": "User prefers morning workouts between 6:00 and 7:00 AM.",
        "importance": "high",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "mem_01HQB...",
    "twinId": "twin_01HQA...",
    "type": "preference",
    "content": "User prefers morning workouts between 6:00 and 7:00 AM.",
    "importance": "high",
    "createdAt": "2026-03-17T10:01:00.000Z"
  }
}

---

Step 3: Trigger an Action

Ask the twin to perform an action using its accumulated memories and context:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/agents/twins/$TWIN_ID/actions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "generate_summary",
    "input": {
      "scope": "today",
      "format": "brief"
    }
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/twins/${TWIN_ID}/actions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'generate_summary',
    input: { scope: 'today', format: 'brief' },
  }),
});
const data = await res.json();
console.log(data);

Python

res = requests.post(
    f"{BASE}/agents/twins/{TWIN_ID}/actions",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "type": "generate_summary",
        "input": {"scope": "today", "format": "brief"},
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "action_01HQC...",
    "twinId": "twin_01HQA...",
    "type": "generate_summary",
    "status": "completed",
    "output": "Good morning! Based on your preferences, you have 3 bits scheduled before 7 AM. You completed your running streak yesterday (day 7). Keep it going today!",
    "completedAt": "2026-03-17T10:02:00.000Z"
  }
}

---

Step 4: Update the Twin

Modify the twin's persona or configuration:

cURL

curl -s -X PATCH "https://api.chainabit.com/api/v1/agents/twins/$TWIN_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "A focused productivity coach that specializes in fitness and nutrition routines."
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/twins/${TWIN_ID}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    persona:
      'A focused productivity coach that specializes in fitness and nutrition routines.',
  }),
});
const data = await res.json();
console.log(data);

Python

res = requests.patch(
    f"{BASE}/agents/twins/{TWIN_ID}",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "persona": "A focused productivity coach that specializes in fitness and nutrition routines.",
    },
)
print(res.json())

---

Step 5: Delete the Twin

Remove a twin when it is no longer needed:

cURL

curl -s -X DELETE "https://api.chainabit.com/api/v1/agents/twins/$TWIN_ID" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/twins/${TWIN_ID}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${TOKEN}` },
});
console.log(res.status); // 204

Python

res = requests.delete(
    f"{BASE}/agents/twins/{TWIN_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(res.status_code)  # 204

---

Summary

In this tutorial you:

1. Created an AI twin with a custom persona
2. Added memories to personalize the twin's context
3. Triggered an action to generate a summary
4. Updated the twin's persona
5. Deleted the twin

Next Steps

• Manage Skills to add capabilities to your agents
• Chain Triggers to run chains (workflows) on cron/event triggers
• Twins API Reference for all available endpoints