Chainabit Docs

English

Selector
Türkçe

English

Selector
Türkçe

Appearance

Türkçe

Agent Definitions ​

Agent definitions are blueprints that describe an agent's purpose, capabilities, and configuration. From definitions, you create versioned snapshots, deploy instances, assign scopes, and register tools.

Agent Definitions ​

Endpoints ​

MethodPathDescriptionAuthRate Limit
GET/agents/definitionsList definitionsJWT + Entitlement60/min
GET/agents/definitions/:idGet a definitionJWT + Entitlement60/min
POST/agents/definitionsCreate a definitionJWT + Entitlement10/min
PATCH/agents/definitions/:idUpdate a definitionJWT + Entitlement30/min
DELETE/agents/definitions/:idDelete a definitionJWT + Entitlement10/min

Create Definition ​

Request ​

FieldTypeRequiredDescription
namestringYesAgent name
descriptionstringNoAgent description
typestringYesassistant, worker, orchestrator
systemPromptstringNoSystem-level instructions
modelIdstringNoPreferred AI model ID
toolsstring[]NoTool IDs the agent can use
configobjectNoAdditional configuration

modelId is an existing AI model's id (see the AI Models API) — use it as $MODEL_ID. tools lists ids of tools you've already registered (see Create Tool below) — use them as $TOOL_ID / $TOOL_ID_2.

Response ​

json
{
  "data": {
    "id": "cm5def01",
    "name": "Productivity Workflow Coach",
    "description": "An agent specialized in helping users build and maintain productive workflows",
    "type": "assistant",
    "systemPrompt": "You are a productivity workflow expert...",
    "modelId": "cm5model01",
    "tools": ["cm5tool01", "cm5tool02"],
    "config": { "temperature": 0.7, "maxTurns": 20 },
    "createdAt": "2026-03-17T10:00:00.000Z",
    "updatedAt": "2026-03-17T10:00:00.000Z"
  }
}

Code Examples ​

bash
curl -X POST https://api.chainabit.com/api/v1/agents/definitions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Productivity Workflow Coach",
    "description": "An agent specialized in helping users build and maintain productive workflows",
    "type": "assistant",
    "systemPrompt": "You are a productivity workflow expert. Help users build sustainable executable workflows.",
    "modelId": "'$MODEL_ID'",
    "tools": ["'$TOOL_ID'", "'$TOOL_ID_2'"],
    "config": { "temperature": 0.7, "maxTurns": 20 }
  }'
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;
const modelId = process.env.MODEL_ID; // from the AI Models API
const toolId = process.env.TOOL_ID; // from Create Tool's response (data.id)
const toolId2 = process.env.TOOL_ID_2;

const response = await fetch(`${BASE_URL}/agents/definitions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Productivity Workflow Coach",
    description: "An agent specialized in helping users build and maintain productive workflows",
    type: "assistant",
    systemPrompt: "You are a productivity workflow expert. Help users build sustainable executable workflows.",
    modelId: modelId,
    tools: [toolId, toolId2],
    config: { temperature: 0.7, maxTurns: 20 },
  }),
});
const { data } = await response.json();
python
import requests, os

model_id = os.environ["MODEL_ID"]  # from the AI Models API
tool_id = os.environ["TOOL_ID"]  # from Create Tool's response (data["id"])
tool_id_2 = os.environ["TOOL_ID_2"]

response = requests.post(
    f"{os.environ['BASE_URL']}/agents/definitions",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "name": "Productivity Workflow Coach",
        "description": "An agent specialized in helping users build and maintain productive workflows",
        "type": "assistant",
        "systemPrompt": "You are a productivity workflow expert. Help users build sustainable executable workflows.",
        "modelId": model_id,
        "tools": [tool_id, tool_id_2],
        "config": {"temperature": 0.7, "maxTurns": 20},
    },
)
data = response.json()["data"]

List Definitions ​

Request ​

No path or query parameters.

Response ​

json
{
  "data": [
    {
      "id": "cm5def01",
      "name": "Productivity Workflow Coach",
      "type": "assistant",
      "createdAt": "2026-03-17T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1 }
}

Code Examples ​

bash
curl https://api.chainabit.com/api/v1/agents/definitions \
  -H "Authorization: Bearer $TOKEN"
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;

const response = await fetch(`${BASE_URL}/agents/definitions`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await response.json();
python
import requests, os

response = requests.get(
    f"{os.environ['BASE_URL']}/agents/definitions",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
)
data = response.json()["data"]

Agent Versions ​

Manage versioned snapshots of agent definitions for reproducibility and rollback.

Endpoints ​

MethodPathDescriptionAuthRate Limit
GET/agents/versionsList versionsJWT + Entitlement60/min
GET/agents/versions/:idGet a versionJWT + Entitlement60/min
POST/agents/versionsCreate a versionJWT + Entitlement10/min
PATCH/agents/versions/:idUpdate a versionJWT + Entitlement30/min
DELETE/agents/versions/:idDelete a versionJWT + Entitlement10/min

List Versions ​

Request ​

No path or query parameters.

Response ​

json
{
  "data": [
    {
      "id": "cm5ver01",
      "definitionId": "cm5def01",
      "version": "1.0.0",
      "status": "published",
      "createdAt": "2026-03-17T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1 }
}

Code Examples ​

bash
curl https://api.chainabit.com/api/v1/agents/versions \
  -H "Authorization: Bearer $TOKEN"
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;

const response = await fetch(`${BASE_URL}/agents/versions`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await response.json();
python
import requests, os

response = requests.get(
    f"{os.environ['BASE_URL']}/agents/versions",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
)
data = response.json()["data"]

Agent Instances ​

Running instances of agent definitions. An instance represents an active deployment.

Endpoints ​

MethodPathDescriptionAuthRate Limit
GET/agents/instancesList instancesJWT + Entitlement60/min
GET/agents/instances/:idGet an instanceJWT + Entitlement60/min
POST/agents/instancesCreate an instanceJWT + Entitlement10/min
PATCH/agents/instances/:idUpdate an instanceJWT + Entitlement30/min
DELETE/agents/instances/:idDelete an instanceJWT + Entitlement10/min

Create Instance ​

Request ​

Use the id from Create Definition's response (data.id) as $DEFINITION_ID, and the id from a definition's version list (data[].id in Agent Versions) as $VERSION_ID.

Response ​

json
{
  "data": {
    "id": "cm5inst01",
    "definitionId": "cm5def01",
    "versionId": "cm5ver01",
    "name": "My Workflow Coach",
    "status": "active",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Code Examples ​

bash
curl -X POST https://api.chainabit.com/api/v1/agents/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionId": "'$DEFINITION_ID'",
    "versionId": "'$VERSION_ID'",
    "name": "My Workflow Coach"
  }'
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;
const definitionId = process.env.DEFINITION_ID; // from Create Definition's response
const versionId = process.env.VERSION_ID; // from Agent Versions' response

const response = await fetch(`${BASE_URL}/agents/instances`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    definitionId: definitionId,
    versionId: versionId,
    name: "My Workflow Coach",
  }),
});
const { data } = await response.json();
python
import requests, os

definition_id = os.environ["DEFINITION_ID"]  # from Create Definition's response
version_id = os.environ["VERSION_ID"]  # from Agent Versions' response

response = requests.post(
    f"{os.environ['BASE_URL']}/agents/instances",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "definitionId": definition_id,
        "versionId": version_id,
        "name": "My Workflow Coach",
    },
)
data = response.json()["data"]

Available Instances ​

Discover active agent instances accessible to your account — your own agents plus any publicly shared agents on the platform. Results are ordered A-Z by display name.

Endpoint ​

MethodPathDescriptionAuthRate Limit
GET/agents/instances/availableList available agentsJWT + Entitlement60/min

Request ​

ParameterTypeDefaultDescription
qstring—Filter by agent name or description (case-insensitive, partial match)
is_publicboolean—true = public agents only · false = your own non-public agents only · omit = both
limitinteger (1–50)20Page size
offsetinteger (≥0)0Number of records to skip

Response ​

json
{
  "data": [
    {
      "id": "cm5inst01",
      "displayName": "Productivity Workflow Coach",
      "avatarUrl": null,
      "isPublic": true,
      "agentType": "custom",
      "description": "An agent specialized in helping users build and maintain productive workflows",
      "capabilities": ["chat", "tools"]
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 1,
    "hasNextPage": false
  }
}

Code Examples ​

bash
curl "https://api.chainabit.com/api/v1/agents/instances/available?q=coach&is_public=true&limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN"
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;

const params = new URLSearchParams({ q: 'coach', is_public: 'true', limit: '10', offset: '0' });
const response = await fetch(`${BASE_URL}/agents/instances/available?${params}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data, meta } = await response.json();
python
import requests, os

response = requests.get(
    f"{os.environ['BASE_URL']}/agents/instances/available",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    params={"q": "coach", "is_public": "true", "limit": 10, "offset": 0},
)
payload = response.json()
data, meta = payload["data"], payload["meta"]

Agent Scopes ​

Define the boundaries within which an agent can operate (e.g., specific chains, chainies, or workspaces).

Endpoints ​

MethodPathDescriptionAuthRate Limit
GET/agents/scopesList scopesJWT + Entitlement60/min
GET/agents/scopes/:idGet a scopeJWT + Entitlement60/min
POST/agents/scopesCreate a scopeJWT + Entitlement30/min
PATCH/agents/scopes/:idUpdate a scopeJWT + Entitlement30/min
DELETE/agents/scopes/:idDelete a scopeJWT + Entitlement30/min

Create Scope ​

Request ​

Use the id from Create Instance's response (data.id) as $INSTANCE_ID. targetId is the id of the resource being scoped (a chainy, in this example) — use its own id as $CHAINY_ID.

Response ​

json
{
  "data": {
    "id": "cm5scope01",
    "instanceId": "cm5inst01",
    "type": "chainy",
    "targetId": "cm5abc123",
    "permissions": ["read", "suggest", "execute"],
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Code Examples ​

bash
curl -X POST https://api.chainabit.com/api/v1/agents/scopes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "'$INSTANCE_ID'",
    "type": "chainy",
    "targetId": "'$CHAINY_ID'",
    "permissions": ["read", "suggest", "execute"]
  }'
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;
const instanceId = process.env.INSTANCE_ID; // from Create Instance's response
const targetId = process.env.CHAINY_ID; // the chainy (or other resource) to scope to

const response = await fetch(`${BASE_URL}/agents/scopes`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    instanceId: instanceId,
    type: "chainy",
    targetId: targetId,
    permissions: ["read", "suggest", "execute"],
  }),
});
const { data } = await response.json();
python
import requests, os

instance_id = os.environ["INSTANCE_ID"]  # from Create Instance's response
target_id = os.environ["CHAINY_ID"]  # the chainy (or other resource) to scope to

response = requests.post(
    f"{os.environ['BASE_URL']}/agents/scopes",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "instanceId": instance_id,
        "type": "chainy",
        "targetId": target_id,
        "permissions": ["read", "suggest", "execute"],
    },
)
data = response.json()["data"]

Agent Tools ​

Register external tools and integrations that agents can invoke during execution.

Endpoints ​

MethodPathDescriptionAuthRate Limit
GET/agents/toolsList toolsJWT + Entitlement60/min
GET/agents/tools/:idGet a toolJWT + Entitlement60/min
POST/agents/toolsCreate a toolJWT + Entitlement10/min
PATCH/agents/tools/:idUpdate a toolJWT + Entitlement30/min
DELETE/agents/tools/:idDelete a toolJWT + Entitlement10/min

Create Tool ​

Request ​

Response ​

json
{
  "data": {
    "id": "cm5tool01",
    "name": "Calendar Lookup",
    "description": "Look up events from the user calendar",
    "type": "api",
    "schema": {},
    "endpoint": "https://api.example.com/calendar",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Code Examples ​

bash
curl -X POST https://api.chainabit.com/api/v1/agents/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calendar Lookup",
    "description": "Look up events from the user calendar",
    "type": "api",
    "schema": {
      "input": { "date": { "type": "string", "format": "date" } },
      "output": { "events": { "type": "array" } }
    },
    "endpoint": "https://api.example.com/calendar"
  }'
javascript
const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;

const response = await fetch(`${BASE_URL}/agents/tools`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Calendar Lookup",
    description: "Look up events from the user calendar",
    type: "api",
    schema: {
      input: { date: { type: "string", format: "date" } },
      output: { events: { type: "array" } },
    },
    endpoint: "https://api.example.com/calendar",
  }),
});
const { data } = await response.json();
python
import requests, os

response = requests.post(
    f"{os.environ['BASE_URL']}/agents/tools",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "name": "Calendar Lookup",
        "description": "Look up events from the user calendar",
        "type": "api",
        "schema": {
            "input": {"date": {"type": "string", "format": "date"}},
            "output": {"events": {"type": "array"}},
        },
        "endpoint": "https://api.example.com/calendar",
    },
)
data = response.json()["data"]

Built with purpose.

Copyright 2026-present Chainabit