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/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	--

Who can execute

An execution always runs, and is billed, in the account and workspace selected for the request.

You can execute only bits and projects that you created in that workspace. Bits and projects that a team or a collaborator shares with you are readable but not executable.
agentInstanceId must name an active agent available in the same workspace: an agent of that workspace or one shared with the whole account.
A bit, project, or agent that you cannot execute returns 404, the same response as one that does not exist. Nothing is run or charged.
Automatic propagation only reaches your own bits in the same account and workspace.

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

json

{
  "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

cURLJavaScriptPython

bash

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

cURLJavaScriptPython

bash

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

json

{
  "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

cURLJavaScriptPython

bash

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

javascript

const response = await fetch(
  `${BASE_URL}/ai/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/models/available",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    params={"featureKey": "ai.bits.execute"},
)
data = response.json()["data"]

Description

Share execution results publicly or revoke sharing.

Only the member who started a run can share it or change its sharing. Anyone else, including account owners and admins, receives 403. A run with no recorded starter can be shared by a member working in the run's account and workspace. A run from a temporary conversation cannot be shared.

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

json

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

Code Examples

JavaScriptPython

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

json

{
  "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

cURLJavaScriptPython

bash

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	Free	Plus	Pro	Pro (higher capacity)
`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

Bit AI Execution ​

Endpoints ​

Who can execute ​

Execute a Bit ​

Description ​

Request ​

Request Body ​

Execution Modes ​

Response ​

Code Examples ​

Execute a Chainy ​

Description ​

Request ​

Response ​

Code Examples ​

List Available Models ​

Description ​

Request ​

Response ​

Code Examples ​

Share an Execution ​

Description ​

Request ​

Response ​

Code Examples ​

Community Executions ​

Description ​

Request ​

Response ​

Code Examples ​

Entitlement Matrix ​

Bit AI Execution

Endpoints

Who can execute

Execute a Bit

Description

Request

Request Body

Execution Modes

Response

Code Examples

Execute a Chainy

Description

Request

Response

Code Examples

List Available Models

Description

Request

Response

Code Examples

Share an Execution

Description

Request

Response

Code Examples

Community Executions

Description

Request

Response

Code Examples

Entitlement Matrix