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

Method	Path	Description	Auth	Rate Limit
GET	`/agents/definitions`	List definitions	JWT + Entitlement	60/min
GET	`/agents/definitions/:id`	Get a definition	JWT + Entitlement	60/min
POST	`/agents/definitions`	Create a definition	JWT + Entitlement	10/min
PATCH	`/agents/definitions/:id`	Update a definition	JWT + Entitlement	30/min
DELETE	`/agents/definitions/:id`	Delete a definition	JWT + Entitlement	10/min

Create Definition

Request

Field	Type	Required	Description
`name`	string	Yes	Agent name
`description`	string	No	Agent description
`type`	string	Yes	`assistant`, `worker`, `orchestrator`
`systemPrompt`	string	No	System-level instructions
`modelId`	string	No	Preferred AI model ID
`tools`	string[]	No	Tool IDs the agent can use
`config`	object	No	Additional 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

cURLJavaScriptPython

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 routines.",
    "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 routines.",
    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 routines.",
        "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

cURLJavaScriptPython

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

Method	Path	Description	Auth	Rate Limit
GET	`/agents/versions`	List versions	JWT + Entitlement	60/min
GET	`/agents/versions/:id`	Get a version	JWT + Entitlement	60/min
POST	`/agents/versions`	Create a version	JWT + Entitlement	10/min
PATCH	`/agents/versions/:id`	Update a version	JWT + Entitlement	30/min
DELETE	`/agents/versions/:id`	Delete a version	JWT + Entitlement	10/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

cURLJavaScriptPython

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

Method	Path	Description	Auth	Rate Limit
GET	`/agents/instances`	List instances	JWT + Entitlement	60/min
GET	`/agents/instances/:id`	Get an instance	JWT + Entitlement	60/min
POST	`/agents/instances`	Create an instance	JWT + Entitlement	10/min
PATCH	`/agents/instances/:id`	Update an instance	JWT + Entitlement	30/min
DELETE	`/agents/instances/:id`	Delete an instance	JWT + Entitlement	10/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

cURLJavaScriptPython

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

Method	Path	Description	Auth	Rate Limit
GET	`/agents/instances/available`	List available agents	JWT + Entitlement	60/min

Request

Parameter	Type	Default	Description
`q`	string	—	Filter by agent name or description (case-insensitive, partial match)
`is_public`	boolean	—	`true` = public agents only · `false` = your own non-public agents only · omit = both
`limit`	integer (1–50)	20	Page size
`offset`	integer (≥0)	0	Number 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

cURLJavaScriptPython

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

Method	Path	Description	Auth	Rate Limit
GET	`/agents/scopes`	List scopes	JWT + Entitlement	60/min
GET	`/agents/scopes/:id`	Get a scope	JWT + Entitlement	60/min
POST	`/agents/scopes`	Create a scope	JWT + Entitlement	30/min
PATCH	`/agents/scopes/:id`	Update a scope	JWT + Entitlement	30/min
DELETE	`/agents/scopes/:id`	Delete a scope	JWT + Entitlement	30/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

cURLJavaScriptPython

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

Endpoints

Method	Path	Description	Auth	Rate Limit
GET	`/agents/tools`	List tools	JWT + Entitlement	60/min
GET	`/agents/tools/:id`	Get a tool	JWT + Entitlement	60/min
POST	`/agents/tools`	Create a tool	JWT + Entitlement	10/min
PATCH	`/agents/tools/:id`	Update a tool	JWT + Entitlement	30/min
DELETE	`/agents/tools/:id`	Delete a tool	JWT + Entitlement	10/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

cURLJavaScriptPython

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

Agent Definitions ​