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_test_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]"]
    }
  }'

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_test_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

import requests

response = requests.post(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        '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]'],
        },
    },
)
event = response.json()
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_test_your_key_here"

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_test_your_key_here' } }
);
const { data, total, limit, offset } = await response.json();
console.log(`Showing ${data.length} of ${total} events`);

Python

response = requests.get(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    params={
        'start_after': '2026-04-07T00:00:00Z',
        'start_before': '2026-04-14T00:00:00Z',
        'status': 'confirmed',
        'limit': 20,
    },
)
result = response.json()
print(f"Showing {len(result['data'])} of {result['total']} events")

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_test_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_test_your_key_here' } }
);
const { data } = await response.json();
// Events from all of this agent's calendars

Python

response = requests.get(
    'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/events',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    params={'start_after': '2026-04-07T00:00:00Z', 'limit': 50},
)
data = response.json()['data']

Get a single event

curl

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

JavaScript

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

Python

response = requests.get(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
)
event = response.json()

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_test_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_test_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

response = requests.patch(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'title': 'Product demo with Globex Industries (rescheduled)',
        'start_time': '2026-04-11T15:00:00Z',
        'end_time': '2026-04-11T16:00:00Z',
    },
)
updated = response.json()

Delete an event

curl

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

JavaScript

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

Python

response = requests.delete(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3/events/evt_m1n2o3',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
)
# Returns 204 No Content 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