Agents

Agents are the top-level entity in Chronary. Each agent can own multiple calendars and has its own availability.

Register an agent

Registers your agent with Chronary, creating a Chronary identity it can use to own calendars, events, and webhooks. The agent itself already exists in your system — this gives it a Chronary record.

POST /v1/agents

Request body

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | 1–255 characters | | type | string | Yes | ai, human, or resource | | description | string | No | Free-text description | | metadata | object | No | Key-value pairs, max 16KB JSON |

Example

curl

curl -X POST https://api.chronary.ai/v1/agents \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Agent - Acme Corp",
    "type": "ai",
    "description": "Handles meeting scheduling for the sales team",
    "metadata": { "team": "sales" }
  }'

Python

from chronary import Chronary

client = Chronary()

agent = client.agents.create(
    name="Sales Agent - Acme Corp",
    type="ai",
    description="Handles meeting scheduling for the sales team",
    metadata={"team": "sales"},
)

Response 201 Created

{
  "id": "agt_a1b2c3d4",
  "org_id": "org_abc",
  "name": "Sales Agent - Acme Corp",
  "type": "ai",
  "status": "active",
  "description": "Handles meeting scheduling for the sales team",
  "metadata": { "team": "sales" },
  "created_at": "2026-04-04T12:00:00Z",
  "updated_at": "2026-04-04T12:00:00Z"
}

Triggers an agent.created webhook.

Errors

| Status | Type | Cause | |--------|------|-------| | 429 | quota_exceeded | Agent limit reached on your plan |

---

List agents

GET /v1/agents

Query parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | type | string | — | Filter by ai, human, or resource | | status | string | — | Filter by active, paused, or decommissioned | | limit | integer | 50 | 1–200 | | offset | integer | 0 | Pagination offset |

Example

curl

curl "https://api.chronary.ai/v1/agents?type=ai&status=active&limit=10" \
  -H "Authorization: Bearer chr_sk_your_key_here"

Python

for agent in client.agents.list(type="ai", status="active", limit=10):
    print(agent.name)

Response 200 OK

{
  "data": [
    {
      "id": "agt_a1b2c3d4",
      "name": "Sales Agent - Acme Corp",
      "type": "ai",
      "status": "active",
      ...
    }
  ],
  "total": 3,
  "limit": 10,
  "offset": 0
}

---

Get an agent

GET /v1/agents/:id

Example

curl

curl https://api.chronary.ai/v1/agents/agt_a1b2c3d4 \
  -H "Authorization: Bearer chr_sk_your_key_here"

Python

agent = client.agents.get("agt_a1b2c3d4")

Errors

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Agent not found |

---

Update an agent

PATCH /v1/agents/:id

Request body

| Field | Type | Description | |-------|------|-------------| | name | string | 1–255 characters | | description | string | null | Set to null to clear | | metadata | object | Replaces existing metadata | | status | string | active or paused |

At least one field must be provided.

Example

curl

curl -X PATCH https://api.chronary.ai/v1/agents/agt_a1b2c3d4 \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Python

updated = client.agents.update("agt_a1b2c3d4", status="paused")

Triggers an agent.updated webhook.

Errors

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Agent not found |

---

Delete (decommission) an agent

DELETE /v1/agents/:id

Sets the agent status to decommissioned. Returns 204 No Content.

Example

curl

curl -X DELETE https://api.chronary.ai/v1/agents/agt_a1b2c3d4 \
  -H "Authorization: Bearer chr_sk_your_key_here"

Python

client.agents.delete("agt_a1b2c3d4")

Errors

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Agent not found |