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)
• Optionally, the Chronary CLI installed for a terminal-first workflow

Signing up as an AI agent?

This quickstart assumes a human operator registering their first agent via the Chronary console. AI agents can also self-provision a Chronary org and API key programmatically via email + OTP verification — start the flow at console.chronary.ai/signup.

Step 1: Register your agent

Every calendar belongs to an agent. Register yours first — this creates a Chronary identity for the agent so it can own calendars, events, and webhooks:

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

CLI

chronary agents create \
  --name "Sales Agent - Acme Corp" \
  --type ai \
  --description "Handles meeting scheduling for the sales team"
# Registered agent agt_a1b2c3d4 (active)

JavaScript

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

Python

from chronary import Chronary

client = Chronary(api_key="chr_sk_your_key_here")

agent = client.agents.create(
    name="Sales Agent - Acme Corp",
    type="ai",
    description="Handles meeting scheduling for the sales team",
)
print(agent.id)  # "agt_a1b2c3d4"

Step 2: Create a calendar

curl

curl -X POST https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Meetings",
    "timezone": "America/New_York"
  }'

CLI

chronary calendars create \
  --agent agt_a1b2c3d4 \
  --name "Sales Meetings" \
  --timezone "America/New_York"
# Created calendar cal_x1y2z3 (Sales Meetings)

JavaScript

const response = await fetch(
  `https://api.chronary.ai/v1/agents/${agent.id}/calendars`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_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"

Python

calendar = client.agents.calendars.create(
    agent.id,
    name="Sales Meetings",
    timezone="America/New_York",
)
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

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

CLI

chronary events create \
  --calendar cal_x1y2z3 \
  --title "Strategy sync with Acme Corp" \
  --start "2026-04-07T14:00:00Z" \
  --end "2026-04-07T14:30:00Z" \
  --description "Quarterly strategy alignment"
# Created event evt_m1n2o3 (Strategy sync with Acme Corp)

JavaScript

const response = await fetch(
  `https://api.chronary.ai/v1/calendars/${calendar.id}/events`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_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"

Python

event = client.events.create(
    calendar_id=calendar.id,
    title="Strategy sync with Acme Corp",
    start_time="2026-04-07T14:00:00Z",
    end_time="2026-04-07T14:30:00Z",
    description="Quarterly strategy alignment",
)
print(event.id)  # "evt_m1n2o3"

Step 4: Check availability

curl

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_your_key_here"

CLI

chronary availability agent agt_a1b2c3d4 \
  --start "2026-04-07T09:00:00Z" \
  --end "2026-04-07T17:00:00Z" \
  --slot-duration 30m
# 15 available slots

JavaScript

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_your_key_here' } }
);
const { slots } = await response.json();
console.log(`${slots.length} available slots found`);

Python

availability = client.availability.get(
    agent_id=agent.id,
    start="2026-04-07T09:00:00Z",
    end="2026-04-07T17:00:00Z",
    slot_duration="30m",
)
print(f"{len(availability.slots)} available slots found")

What’s next?

• Python SDK quickstart — pagination, async, agent-scoped access, and more
• CLI quickstart — install the CLI and do this whole workflow from the terminal
• 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