Quickstart

Get from zero to your first calendar event in 5 minutes.

Prerequisites

A Chronary account — sign up at console.chronary.ai
Your API key (found in the console after sign-up)

Step 1: Create an agent

Every calendar belongs to an agent. Create one first:

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

const response = await fetch('https://api.chronary.ai/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer chr_sk_test_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales Agent - Acme Corp',
    type: 'ai',
    description: 'Handles meeting scheduling for the sales team',
  }),
});
const agent = await response.json();
console.log(agent.id); // "agt_a1b2c3d4"

import requests

response = requests.post(
    'https://api.chronary.ai/v1/agents',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'name': 'Sales Agent - Acme Corp',
        'type': 'ai',
        'description': 'Handles meeting scheduling for the sales team',
    },
)
agent = response.json()
print(agent['id'])  # "agt_a1b2c3d4"

Step 2: Create a calendar

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": "Sales Meetings",
    "timezone": "America/New_York"
  }'

const response = await fetch(
  `https://api.chronary.ai/v1/agents/${agent.id}/calendars`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_test_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Sales Meetings',
      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"

response = requests.post(
    f'https://api.chronary.ai/v1/agents/{agent["id"]}/calendars',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'name': 'Sales Meetings',
        'timezone': 'America/New_York',
    },
)
calendar = response.json()
print(calendar['ical_url'])  # Subscribe to this in Google Calendar!

The ical_url in the response is a live feed — paste it into Google Calendar, Apple Calendar, or Outlook to see events as they’re created.

Step 3: Add an event

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": "Strategy sync with Acme Corp",
    "start_time": "2026-04-07T14:00:00Z",
    "end_time": "2026-04-07T14:30:00Z",
    "description": "Quarterly strategy alignment"
  }'

const response = await fetch(
  `https://api.chronary.ai/v1/calendars/${calendar.id}/events`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_test_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Strategy sync with Acme Corp',
      start_time: '2026-04-07T14:00:00Z',
      end_time: '2026-04-07T14:30:00Z',
      description: 'Quarterly strategy alignment',
    }),
  }
);
const event = await response.json();
console.log(event.id); // "evt_m1n2o3"

response = requests.post(
    f'https://api.chronary.ai/v1/calendars/{calendar["id"]}/events',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'title': 'Strategy sync with Acme Corp',
        'start_time': '2026-04-07T14:00:00Z',
        'end_time': '2026-04-07T14:30:00Z',
        'description': 'Quarterly strategy alignment',
    },
)
event = response.json()

Step 4: Check availability

curl "https://api.chronary.ai/v1/agents/agt_a1b2c3d4/availability?start=2026-04-07T09:00:00Z&end=2026-04-07T17:00:00Z&slot_duration=30m" \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

const params = new URLSearchParams({
  start: '2026-04-07T09:00:00Z',
  end: '2026-04-07T17:00:00Z',
  slot_duration: '30m',
});
const response = await fetch(
  `https://api.chronary.ai/v1/agents/${agent.id}/availability?${params}`,
  { headers: { 'Authorization': 'Bearer chr_sk_test_your_key_here' } }
);
const { slots } = await response.json();
console.log(`${slots.length} available slots found`);

response = requests.get(
    f'https://api.chronary.ai/v1/agents/{agent["id"]}/availability',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    params={
        'start': '2026-04-07T09:00:00Z',
        'end': '2026-04-07T17:00:00Z',
        'slot_duration': '30m',
    },
)
data = response.json()
print(f"{len(data['slots'])} available slots found")

What’s next?

Calendars guide — org-level vs agent-owned, metadata, iCal URLs
Webhooks guide — get notified when events change
MCP server — connect to Claude Desktop, ChatGPT, or Cursor
API reference — every endpoint documented