Bit AI Execution

Execute any bit through an AI model for analysis, expansion, decomposition, or brainstorming. Supports file attachments, agent invocation, and automatic propagation to connected bits.

Endpoints

Method	Path	Description	Auth	Entitlement
POST	/bits/:id/execute	Execute a bit through AI	JWT	ai.bits.execute
POST	/chainies/:id/execute	Execute a chainy through AI	JWT	ai.bits.execute
GET	/ai/runs/models/available	List available models for a feature	JWT	--
GET	/ai/agents/instances/available	List available agents for invocation	JWT	--
PATCH	/ai/runs/:runId/share	Share an execution result	JWT	--
GET	/community/executions	List public execution shares	None	--

---

Execute a Bit

Description

Use the id of the bit you're executing -- not the literal value shown in the examples below.

Request

Request Body

Field	Type	Required	Description
mode	string	No	chat, analyze, expand, decompose, brainstorm (default: analyze)
prompt	string	No	Optional instruction to guide the AI
modelId	string	No	Override model UUID
agentInstanceId	string	No	Agent instance UUID for specialized execution
attachmentFileIds	string[]	No	File UUIDs from media library

Execution Modes

Mode	Description
chat	Conversational - responds naturally to user instructions
analyze	Structured insights: observations, issues, key points
expand	Adds context, resources, and depth to the task
decompose	Breaks the task into up to 10 action items
brainstorm	Generates creative and practical approaches

Response

{
  "data": {
    "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "sessionId": "c9a7d1e2-4b3f-4e8a-9012-3d4e5f6a7b8c",
    "text": "1. Research the topic and gather key references\n2. Draft an outline with main sections\n3. Write the first section focusing on introduction"
  }
}

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/bits/$BIT_ID/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "decompose",
    "prompt": "Break this into daily sub-tasks for a beginner."
  }'

JavaScript

const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;
const BIT_ID = process.env.BIT_ID; // the bit you're executing

const response = await fetch(`${BASE_URL}/bits/${BIT_ID}/execute`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "decompose",
    prompt: "Break this into daily sub-tasks for a beginner.",
  }),
});
const { data } = await response.json();

Python

import requests, os

response = requests.post(
    f"{os.environ['BASE_URL']}/bits/{os.environ['BIT_ID']}/execute",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "mode": "decompose",
        "prompt": "Break this into daily sub-tasks for a beginner.",
    },
)
data = response.json()["data"]

---

Execute a Chainy

Description

Same execution pipeline as bits, but the context includes the chainy's title, description, vision statement, and its top 20 recent bits. Use the id of the chainy you're executing -- not the literal value shown in the examples below.

Request

Field	Type	Required	Description
mode	string	No	Execution mode (default: analyze)
prompt	string	No	Optional instruction
modelId	string	No	Override model UUID
agentInstanceId	string	No	Agent instance UUID

Response

Same response shape as Execute a Bit (runId, sessionId, text).

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/chainies/$CHAINY_ID/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "brainstorm",
    "prompt": "Suggest new approaches for this project."
  }'

JavaScript

const CHAINY_ID = process.env.CHAINY_ID; // the chainy you're executing

const response = await fetch(`${BASE_URL}/chainies/${CHAINY_ID}/execute`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "brainstorm",
    prompt: "Suggest new approaches for this project.",
  }),
});
const { data } = await response.json();

Python

response = requests.post(
    f"{os.environ['BASE_URL']}/chainies/{os.environ['CHAINY_ID']}/execute",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={"mode": "brainstorm", "prompt": "Suggest new approaches."},
)
data = response.json()["data"]

---

List Available Models

Description

Returns models the authenticated user is entitled to use for a given feature key.

Request

Query params: see the featureKey query parameter used in the example below.

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "GPT-4o",
      "modelKey": "gpt-4o",
      "provider": "openai",
      "providerName": "OpenAI",
      "capabilities": ["chat", "tools", "vision"],
      "contextWindowTokens": 128000
    }
  ]
}

Code Examples

cURL

curl "https://api.chainabit.com/api/v1/ai/runs/models/available?featureKey=ai.bits.execute" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(
  `${BASE_URL}/ai/runs/models/available?featureKey=ai.bits.execute`,
  { headers: { Authorization: `Bearer ${TOKEN}` } },
);
const { data } = await response.json();

Python

response = requests.get(
    f"{os.environ['BASE_URL']}/ai/runs/models/available",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    params={"featureKey": "ai.bits.execute"},
)
data = response.json()["data"]

---

Share an Execution

Description

Share execution results publicly or revoke sharing.

Request

Field	Type	Required	Description
visibility	string	No	private or public
title	string	No	Share title
description	string	No	Share description
allowComments	boolean	No	Allow community comments
allowClone	boolean	No	Allow cloning

Response

{
  "data": {
    "shareId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "accessToken": "generated-uuid-token",
    "visibility": "public"
  }
}

Code Examples

cURL

curl -X PATCH "https://api.chainabit.com/api/v1/ai/runs/$RUN_ID/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "public", "title": "My AI Analysis" }'

JavaScript

const response = await fetch(`${BASE_URL}/ai/runs/${runId}/share`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ visibility: "public", title: "My AI Analysis" }),
});
const { data } = await response.json();

Python

response = requests.patch(
    f"{os.environ['BASE_URL']}/ai/runs/{run_id}/share",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={"visibility": "public", "title": "My AI Analysis"},
)
data = response.json()["data"]

---

Community Executions

Description

List publicly shared execution results. No authentication required.

Request

Query params: see the limit and offset query parameters used in the example below.

Response

{
  "data": [
    {
      "id": "share-uuid",
      "entity_id": "run-uuid",
      "visibility": "public",
      "allow_comments": true,
      "created_at": "2026-04-11T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasNextPage": true
  }
}

Code Examples

cURL

curl "https://api.chainabit.com/api/v1/community/executions?limit=10&offset=0"

JavaScript

const response = await fetch(`${BASE_URL}/community/executions?limit=10`);
const { data, meta } = await response.json();

Python

response = requests.get(
    f"{os.environ['BASE_URL']}/community/executions",
    params={"limit": 10, "offset": 0},
)
result = response.json()

---

Entitlement Matrix

Feature Key	Explorer (Free)	Bitter	Chainer	Architect
ai.bits.execute	10 executions	100	2000	Unlimited
ai.bits.model.openai	--	--	GPT-4o	GPT-4o
ai.bits.model.anthropic	--	--	Claude	Claude
ai.bits.model.mistral	--	--	Mistral	Mistral
ai.bits.attachments	--	5 files	10 files	20 files
ai.bits.concurrent_workflows	--	--	Enabled	Enabled
ai.bits.agent_invoke	--	Enabled	Enabled	Enabled