CRUD Operations for Bits

In this tutorial you will perform the full lifecycle of a Bit: create it, read its details, update it, record completion events, and delete it. Bits are the atomic trackable tasks in Chainabit.

Prerequisites

• A Chainabit account with a valid access token
• curl available in your terminal
• An existing Chain to attach Bits to (create one via the Productivity API)

Set your environment variables:

export TOKEN="your-access-token"
export CHAIN_ID="chain_01HQA..."

---

Bit Lifecycle

---

Step 1: Create a Bit

Add a trackable task to your Chain:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/bits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "'"$CHAIN_ID"'",
    "title": "Read 20 pages",
    "description": "Read at least 20 pages of the current book"
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/bits`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chainId: CHAIN_ID,
    title: 'Read 20 pages',
    description: 'Read at least 20 pages of the current book',
  }),
});
const data = await res.json();
console.log(data);

Python

import requests

res = requests.post(
    f"{BASE}/bits",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "chainId": CHAIN_ID,
        "title": "Read 20 pages",
        "description": "Read at least 20 pages of the current book",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "bit_01HQA...",
    "chainId": "chain_01HQA...",
    "title": "Read 20 pages",
    "description": "Read at least 20 pages of the current book",
    "createdAt": "2026-03-17T10:00:00.000Z",
    "updatedAt": "2026-03-17T10:00:00.000Z"
  }
}

Save the bit ID:

export BIT_ID="bit_01HQA..."

---

Step 2: Read a Bit

Retrieve the bit details by ID:

cURL

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

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/bits/${BIT_ID}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const data = await res.json();
console.log(data);

Python

res = requests.get(
    f"{BASE}/bits/{BIT_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(res.json())

Response:

{
  "data": {
    "id": "bit_01HQA...",
    "chainId": "chain_01HQA...",
    "title": "Read 20 pages",
    "description": "Read at least 20 pages of the current book",
    "createdAt": "2026-03-17T10:00:00.000Z",
    "updatedAt": "2026-03-17T10:00:00.000Z"
  }
}

---

Step 3: Update a Bit

Modify the bit's title or description:

cURL

curl -s -X PATCH "https://api.chainabit.com/api/v1/bits/$BIT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Read 30 pages",
    "description": "Read at least 30 pages of the current book"
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/bits/${BIT_ID}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Read 30 pages',
    description: 'Read at least 30 pages of the current book',
  }),
});
const data = await res.json();
console.log(data);

Python

res = requests.patch(
    f"{BASE}/bits/{BIT_ID}",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "title": "Read 30 pages",
        "description": "Read at least 30 pages of the current book",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "bit_01HQA...",
    "title": "Read 30 pages",
    "description": "Read at least 30 pages of the current book",
    "updatedAt": "2026-03-17T10:05:00.000Z"
  }
}

---

Step 4: Record a Completion Event

Track that the bit was completed:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/bits/$BIT_ID/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completedAt": "2026-03-17T08:00:00.000Z",
    "notes": "Finished chapters 5 and 6"
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/bits/${BIT_ID}/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    completedAt: '2026-03-17T08:00:00.000Z',
    notes: 'Finished chapters 5 and 6',
  }),
});
const data = await res.json();
console.log(data);

Python

res = requests.post(
    f"{BASE}/bits/{BIT_ID}/completions",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "completedAt": "2026-03-17T08:00:00.000Z",
        "notes": "Finished chapters 5 and 6",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "event_01HQB...",
    "bitId": "bit_01HQA...",
    "completedAt": "2026-03-17T08:00:00.000Z",
    "notes": "Finished chapters 5 and 6",
    "createdAt": "2026-03-17T08:01:00.000Z"
  }
}

---

Step 5: Delete a Bit

Remove a bit that is no longer needed:

cURL

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

JavaScript

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

Python

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

A successful deletion returns a 204 No Content status with no body.

---

Summary

In this tutorial you:

1. Created a Bit under an existing Chain
2. Read the bit details by ID
3. Updated the bit's title and description
4. Recorded a completion event to track progress
5. Deleted the bit

Next Steps

• Chain Triggers to run chains (Bit-DAG workflows) on cron/event triggers
• Bits API Reference for all available endpoints