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",
  "orgId": "org_abc",
  "name": "Sales Agent - Acme Corp",
  "type": "ai",
  "description": "Handles meeting scheduling for the sales team",
  "status": "active",
  "metadata": { "team": "sales" },
  "createdAt": "2026-04-04T12:00:00Z",
  "updatedAt": "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