Events

Events are the individual entries on a calendar — meetings, appointments, tasks, or any time-boxed item your agent needs to track.

What you’ll accomplish

By the end of this guide you will be able to create events on a calendar, list and filter them, query across an agent’s calendars, update event details, and delete events.

Prerequisites

• A Chronary account with an API key
• At least one agent and calendar created (see the quickstart)

Create an event

curl

curl -X POST https://api.chronary.ai/v1/calendars/cal_x1y2z3/events \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product demo with Globex Industries",
    "start_time": "2026-04-10T15:00:00Z",
    "end_time": "2026-04-10T16:00:00Z",
    "description": "Walk through the new dashboard features and pricing tiers",
    "status": "confirmed",
    "metadata": {
      "deal_id": "deal_9823",
      "attendees": ["[email protected]", "[email protected]"]
    }
  }'

CLI

chronary events create \
  --calendar cal_x1y2z3 \
  --title "Product demo with Globex Industries" \
  --start "2026-04-10T15:00:00Z" \
  --end "2026-04-10T16:00:00Z" \
  --description "Walk through the new dashboard features and pricing tiers" \
  --status confirmed \
  --metadata '{"deal_id": "deal_9823", "attendees": ["[email protected]", "[email protected]"]}'
# Created event evt_m1n2o3 (Product demo with Globex Industries)

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Product demo with Globex Industries',
      start_time: '2026-04-10T15:00:00Z',
      end_time: '2026-04-10T16:00:00Z',
      description: 'Walk through the new dashboard features and pricing tiers',
      status: 'confirmed',
      metadata: {
        deal_id: 'deal_9823',
        attendees: ['[email protected]', '[email protected]'],
      },
    }),
  }
);
const event = await response.json();
console.log(event.id); // "evt_m1n2o3"

Python

from chronary import Chronary

client = Chronary()

event = client.events.create(
    calendar_id="cal_x1y2z3",
    title="Product demo with Globex Industries",
    start_time="2026-04-10T15:00:00Z",
    end_time="2026-04-10T16:00:00Z",
    description="Walk through the new dashboard features and pricing tiers",
    status="confirmed",
    metadata={
        "deal_id": "deal_9823",
        "attendees": ["[email protected]", "[email protected]"],
    },
)
print(event.id)  # "evt_m1n2o3"

You can also create all-day events by setting all_day: true and providing dates without times:

{
  "title": "Company offsite",
  "start_time": "2026-04-15T00:00:00Z",
  "end_time": "2026-04-17T00:00:00Z",
  "all_day": true
}

List events on a calendar

Retrieve events for a specific calendar with optional filters.

curl

curl "https://api.chronary.ai/v1/calendars/cal_x1y2z3/events?start_after=2026-04-07T00:00:00Z&start_before=2026-04-14T00:00:00Z&status=confirmed&limit=20" \
  -H "Authorization: Bearer chr_sk_your_key_here"

CLI

chronary events list \
  --calendar cal_x1y2z3 \
  --start-after "2026-04-07T00:00:00Z" \
  --start-before "2026-04-14T00:00:00Z" \
  --status confirmed \
  --limit 20

JavaScript

const params = new URLSearchParams({
  start_after: '2026-04-07T00:00:00Z',
  start_before: '2026-04-14T00:00:00Z',
  status: 'confirmed',
  limit: '20',
});
const response = await fetch(
  `https://api.chronary.ai/v1/calendars/cal_x1y2z3/events?${params}`,
  { headers: { 'Authorization': 'Bearer chr_sk_your_key_here' } }
);
const { data, total, limit, offset } = await response.json();
console.log(`Showing ${data.length} of ${total} events`);

Python

events = client.events.list(
    calendar_id="cal_x1y2z3",
    start_after="2026-04-07T00:00:00Z",
    start_before="2026-04-14T00:00:00Z",
    status="confirmed",
    limit=20,
)
for event in events:
    print(event.title)

Filter parameters:

| Parameter | Type | Description | |-----------|------|-------------| | start_after | ISO 8601 | Only events starting after this time | | start_before | ISO 8601 | Only events starting before this time | | status | string | Filter by status: confirmed, tentative, cancelled | | source | string | Filter by source: api, external_ical | | limit | integer | Results per page (default: 50, max: 200) | | offset | integer | Number of results to skip for pagination |

List events across an agent’s calendars

Query all events across every calendar owned by an agent. This is useful when an agent has multiple calendars and you need a unified view.

curl

curl "https://api.chronary.ai/v1/agents/agt_a1b2c3d4/events?start_after=2026-04-07T00:00:00Z&limit=50" \
  -H "Authorization: Bearer chr_sk_your_key_here"

JavaScript

const params = new URLSearchParams({
  start_after: '2026-04-07T00:00:00Z',
  limit: '50',
});
const response = await fetch(
  `https://api.chronary.ai/v1/agents/agt_a1b2c3d4/events?${params}`,
  { headers: { 'Authorization': 'Bearer chr_sk_your_key_here' } }
);
const { data } = await response.json();
// Events from all of this agent's calendars

Python

# Events from all of this agent's calendars
for event in client.agents.events.list(
    "agt_a1b2c3d4",
    start_after="2026-04-07T00:00:00Z",
):
    print(f"{event.title} ({event.calendar_id})")

Get a single event

curl

curl https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3 \
  -H "Authorization: Bearer chr_sk_your_key_here"

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3',
  { headers: { 'Authorization': 'Bearer chr_sk_your_key_here' } }
);
const event = await response.json();

Python

event = client.events.get("cal_x1y2z3", "evt_m1n2o3")

Update an event

Only the fields you include in the request body are updated. Omitted fields remain unchanged.

curl

curl -X PATCH https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3 \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product demo with Globex Industries (rescheduled)",
    "start_time": "2026-04-11T15:00:00Z",
    "end_time": "2026-04-11T16:00:00Z"
  }'

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer chr_sk_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Product demo with Globex Industries (rescheduled)',
      start_time: '2026-04-11T15:00:00Z',
      end_time: '2026-04-11T16:00:00Z',
    }),
  }
);
const updated = await response.json();

Python

updated = client.events.update(
    "cal_x1y2z3",
    "evt_m1n2o3",
    title="Product demo with Globex Industries (rescheduled)",
    start_time="2026-04-11T15:00:00Z",
    end_time="2026-04-11T16:00:00Z",
)

Delete an event

curl

curl -X DELETE https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3 \
  -H "Authorization: Bearer chr_sk_your_key_here"

JavaScript

await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer chr_sk_your_key_here' },
  }
);
// Returns 204 No Content on success

Python

client.events.delete("cal_x1y2z3", "evt_m1n2o3")
# Returns None on success

External events are read-only

Caution

Events synced from external iCal subscriptions have source: "external_ical" and cannot be edited or deleted through the API. Attempting to update or delete them returns a 403 Forbidden error. To modify these events, change them in the original calendar (Google Calendar, Outlook, etc.) and wait for the next sync cycle.

Pagination

All list endpoints return paginated results:

{
  "data": [ ... ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

To fetch the next page, increment offset by limit:

GET /v1/calendars/cal_x1y2z3/events?limit=50&offset=50

The maximum limit is 200. The default is 50.

Common errors

| Status | Code | Cause | |--------|------|-------| | 400 | invalid_time_format | start_time or end_time is not valid ISO 8601 | | 400 | end_before_start | end_time is earlier than start_time | | 403 | external_event_readonly | Attempted to edit/delete an event with source: "external_ical" | | 404 | calendar_not_found | The calendar ID does not exist | | 404 | event_not_found | The event ID does not exist on this calendar |

What’s next?

• Availability guide — find free time slots based on existing events
• Webhooks guide — get notified when events are created, updated, or deleted
• iCal feeds guide — let humans see agent events in their own calendar apps