Calendars

Calendars are the core container for events in Chronary. There are two kinds:

• Agent-owned calendars belong to a specific agent (e.g., “Dr. Chen’s Patient Appointments”).
• Org-level calendars are shared across your organization (e.g., “Conference Room B” or “Company Holidays”).

What you’ll accomplish

By the end of this guide you will be able to create both types of calendars, list and retrieve them, update their properties, and delete them when no longer needed.

Prerequisites

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

Create an org-level calendar

Org-level calendars are not tied to any agent. Use them for shared resources like meeting rooms or company-wide schedules.

curl

curl -X POST https://api.chronary.ai/v1/calendars \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conference Room B — 4th Floor",
    "timezone": "America/Chicago",
    "metadata": {
      "capacity": 12,
      "building": "HQ",
      "floor": 4,
      "amenities": ["projector", "whiteboard", "video_conferencing"]
    }
  }'

JavaScript

const response = await fetch('https://api.chronary.ai/v1/calendars', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer chr_sk_test_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Conference Room B — 4th Floor',
    timezone: 'America/Chicago',
    metadata: {
      capacity: 12,
      building: 'HQ',
      floor: 4,
      amenities: ['projector', 'whiteboard', 'video_conferencing'],
    },
  }),
});
const calendar = await response.json();
console.log(calendar.id);       // "cal_r4s5t6"
console.log(calendar.ical_url); // "https://api.chronary.ai/ical/def456.ics"

Python

import requests

response = requests.post(
    'https://api.chronary.ai/v1/calendars',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'name': 'Conference Room B — 4th Floor',
        'timezone': 'America/Chicago',
        'metadata': {
            'capacity': 12,
            'building': 'HQ',
            'floor': 4,
            'amenities': ['projector', 'whiteboard', 'video_conferencing'],
        },
    },
)
calendar = response.json()
print(calendar['id'])        # "cal_r4s5t6"
print(calendar['ical_url'])  # "https://api.chronary.ai/ical/def456.ics"

Create an agent-owned calendar

Agent-owned calendars belong to a specific agent. Most agents have one calendar, but you can create multiple (e.g., separate calendars for “Client Meetings” and “Internal Syncs”).

curl

curl -X POST https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dr. Chen — Patient Appointments",
    "timezone": "America/New_York"
  }'

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_test_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Dr. Chen — Patient Appointments',
      timezone: 'America/New_York',
    }),
  }
);
const calendar = await response.json();
console.log(calendar.id);       // "cal_x1y2z3"
console.log(calendar.ical_url); // "https://api.chronary.ai/ical/abc123.ics"

Python

response = requests.post(
    'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'name': 'Dr. Chen — Patient Appointments',
        'timezone': 'America/New_York',
    },
)
calendar = response.json()
print(calendar['ical_url'])  # Subscribe to this in any calendar app

List calendars

List org-level calendars or all calendars belonging to a specific agent.

curl

# Org-level calendars
curl https://api.chronary.ai/v1/calendars \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

# Agent-owned calendars
curl https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

JavaScript

// Org-level calendars
const orgCals = await fetch('https://api.chronary.ai/v1/calendars', {
  headers: { 'Authorization': 'Bearer chr_sk_test_your_key_here' },
}).then(r => r.json());

// Agent-owned calendars
const agentCals = await fetch(
  'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars',
  { headers: { 'Authorization': 'Bearer chr_sk_test_your_key_here' } }
).then(r => r.json());

Python

headers = {'Authorization': 'Bearer chr_sk_test_your_key_here'}

# Org-level calendars
org_cals = requests.get(
    'https://api.chronary.ai/v1/calendars', headers=headers
).json()

# Agent-owned calendars
agent_cals = requests.get(
    'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars',
    headers=headers,
).json()

Get a single calendar

Retrieve full details for a calendar by ID. The response includes the ical_url you can use to subscribe from any calendar app.

curl

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

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3',
  { headers: { 'Authorization': 'Bearer chr_sk_test_your_key_here' } }
);
const calendar = await response.json();
console.log(calendar.ical_url);  // paste into Google Calendar to subscribe
console.log(calendar.metadata);  // your custom JSON data

Python

response = requests.get(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
)
calendar = response.json()
print(calendar['ical_url'])

Example response:

{
  "id": "cal_x1y2z3",
  "name": "Dr. Chen — Patient Appointments",
  "timezone": "America/New_York",
  "agent_id": "agt_a1b2c3d4",
  "ical_url": "https://api.chronary.ai/ical/abc123.ics",
  "metadata": {},
  "created_at": "2026-04-04T10:00:00Z",
  "updated_at": "2026-04-04T10:00:00Z"
}

Update a calendar

Change the name, timezone, or metadata of an existing calendar. Only the fields you include are updated.

curl

curl -X PATCH https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dr. Chen — All Appointments",
    "metadata": {
      "department": "cardiology",
      "location": "Building A, Suite 200"
    }
  }'

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/calendars/cal_x1y2z3',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer chr_sk_test_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Dr. Chen — All Appointments',
      metadata: {
        department: 'cardiology',
        location: 'Building A, Suite 200',
      },
    }),
  }
);
const updated = await response.json();

Python

response = requests.patch(
    'https://api.chronary.ai/v1/calendars/cal_x1y2z3',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'name': 'Dr. Chen — All Appointments',
        'metadata': {
            'department': 'cardiology',
            'location': 'Building A, Suite 200',
        },
    },
)
updated = response.json()

Delete a calendar

Deleting a calendar permanently removes it and all of its events. This action cannot be undone.

curl

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

JavaScript

await fetch('https://api.chronary.ai/v1/calendars/cal_x1y2z3', {
  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',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
)
# Returns 204 No Content on success

Key concepts

Metadata

Every calendar has a metadata field that accepts any valid JSON object up to 16 KB. Use it to store application-specific data like room capacity, department codes, or external system IDs.

{
  "metadata": {
    "salesforce_id": "001ABC",
    "department": "engineering",
    "color": "#4A90D9"
  }
}

Timezones

The timezone field must be a valid IANA timezone identifier such as America/New_York, Europe/London, or Asia/Tokyo. The timezone is used when generating iCal feeds and computing availability.

iCal URL

Every calendar response includes an ical_url field. This is a live feed that can be subscribed to from Google Calendar, Apple Calendar, Outlook, or any other app that supports iCal. See the iCal feeds guide for details on subscribing.

Common errors

Status	Code	Cause
400	invalid_timezone	The timezone value is not a valid IANA identifier
400	metadata_too_large	The metadata object exceeds 16 KB
404	agent_not_found	The agent_id in the URL does not exist
404	calendar_not_found	The calendar ID does not exist or does not belong to your organization
409	calendar_has_events	Attempted to delete a calendar that still has events (delete events first)

What’s next?

• Events guide — create, list, and manage events on your calendars
• Availability guide — find open time slots across agents
• iCal feeds guide — subscribe to calendars from human calendar apps