Skip to content
Chronary Docs

Availability

Three endpoints for finding available time slots.

Single-agent availability

Section titled “Single-agent availability”

Returns available slots across all of an agent’s calendars.

GET /v1/agents/:id/availability

Query parameters

Section titled “Query parameters”

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | start | datetime | Yes | — | Start of time range (ISO 8601) | | end | datetime | Yes | — | End of time range (must be after start) | | slot_duration | string | No | 30m | 15m, 30m, 45m, 1h, or 2h | | include_busy | boolean | No | false | Include busy slots in response |

Example

Section titled “Example”
Terminal window
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"

Response 200 OK

Section titled “Response 200 OK”
{
  "slots": [
    { "start": "2026-04-07T09:00:00Z", "end": "2026-04-07T09:30:00Z" },
    { "start": "2026-04-07T09:30:00Z", "end": "2026-04-07T10:00:00Z" },
    { "start": "2026-04-07T15:00:00Z", "end": "2026-04-07T15:30:00Z" }
  ]
}

Single-calendar availability

Section titled “Single-calendar availability”

Same parameters, scoped to one calendar.

GET /v1/calendars/:id/availability

Example

Section titled “Example”
Terminal window
curl "https://api.chronary.ai/v1/calendars/cal_x1y2z3/availability?start=2026-04-07T09:00:00Z&end=2026-04-07T17:00:00Z" \
  -H "Authorization: Bearer chr_sk_your_key_here"

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Calendar not found |

Cross-agent availability

Section titled “Cross-agent availability”

Find time slots where multiple agents are all free.

GET /v1/availability

Query parameters

Section titled “Query parameters”

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | agents | string | Yes | — | Comma-separated agent IDs | | start | datetime | Yes | — | Start of time range (ISO 8601) | | end | datetime | Yes | — | End of time range | | slot_duration | string | No | 30m | 15m, 30m, 45m, 1h, or 2h | | calendars | string | No | — | Comma-separated calendar IDs to narrow scope | | include_busy | boolean | No | false | Include busy slots |

Example

Section titled “Example”
Terminal window
curl "https://api.chronary.ai/v1/availability?agents=agt_a1b2c3d4,agt_e5f6g7h8&start=2026-04-07T09:00:00Z&end=2026-04-07T17:00:00Z&slot_duration=30m" \
  -H "Authorization: Bearer chr_sk_your_key_here"

Plan limits

Section titled “Plan limits”

| Plan | Max agents per query | Max date range | |------|---------------------|----------------| | Free | 5 agents | 30 days | | Pro | 20 agents | 90 days | | Custom | Custom | Custom |

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 400 | bad_request | Too many agents for your plan | | 400 | bad_request | Date range exceeds plan limit |

Availability rules

Section titled “Availability rules”

Availability rules let you pad events with buffer time and restrict free slots to working hours on a per-calendar basis. Rules are applied automatically to all three availability endpoints above — the engine expands each event by the configured buffers and marks time outside working hours as busy before computing free slots.

By default, calendars have no rules: buffers are 0, there are no working-hours restrictions, and every minute outside an event is considered free. Rules are stored per calendar, so a single agent can mix strict (business hours) and always-on calendars.

Set availability rules

Section titled “Set availability rules”

Upsert rules for a calendar. Any existing rules are replaced.

PUT /v1/calendars/:id/availability-rules

Request body

Section titled “Request body”

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | buffer_before_minutes | integer | No | 0 | Minutes of buffer before each event (0–120) | | buffer_after_minutes | integer | No | 0 | Minutes of buffer after each event (0–120) | | working_hours | object | null | No | null | Per-day working-hours map. null means no working-hours restriction | | timezone | string | No | "UTC" | IANA timezone for working_hours (e.g. America/New_York) |

working_hours is an object keyed by lowercase 3-letter weekday abbreviations. Each day is optional; days that are omitted are treated as entirely non-working.

| Day key | Value | |---------|-------| | mon, tue, wed, thu, fri, sat, sun | { "start": "HH:MM", "end": "HH:MM" } |

start and end are 24-hour local times in the configured timezone. end must be after start. At least one day must be present when working_hours is not null.

Example

Section titled “Example”
Terminal window
curl -X PUT https://api.chronary.ai/v1/calendars/cal_01H9X4M2P5R8T6V0/availability-rules \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "buffer_before_minutes": 15,
    "buffer_after_minutes": 15,
    "working_hours": {
      "mon": { "start": "09:00", "end": "17:00" },
      "tue": { "start": "09:00", "end": "17:00" },
      "wed": { "start": "09:00", "end": "17:00" },
      "thu": { "start": "09:00", "end": "17:00" },
      "fri": { "start": "09:00", "end": "17:00" }
    },
    "timezone": "America/New_York"
  }'

Response 200 OK

Section titled “Response 200 OK”
{
  "id": "avr_01H9X4M2P5R8T6V0",
  "calendar_id": "cal_01H9X4M2P5R8T6V0",
  "buffer_before_minutes": 15,
  "buffer_after_minutes": 15,
  "working_hours": {
    "mon": { "start": "09:00", "end": "17:00" },
    "tue": { "start": "09:00", "end": "17:00" },
    "wed": { "start": "09:00", "end": "17:00" },
    "thu": { "start": "09:00", "end": "17:00" },
    "fri": { "start": "09:00", "end": "17:00" }
  },
  "timezone": "America/New_York",
  "created_at": "2026-04-07T12:00:00.000Z",
  "updated_at": "2026-04-07T12:00:00.000Z"
}

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 400 | bad_request | Buffer outside 0–120, end not after start, or empty working_hours object | | 404 | not_found | Calendar not found |

Get availability rules

Section titled “Get availability rules”
GET /v1/calendars/:id/availability-rules

Returns the current rules for the calendar.

Terminal window
curl https://api.chronary.ai/v1/calendars/cal_01H9X4M2P5R8T6V0/availability-rules \
  -H "Authorization: Bearer chr_sk_your_key_here"

Response 200 OK

Section titled “Response 200 OK”

Same shape as the PUT response above.

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Calendar not found, or no rules set for this calendar |

Delete availability rules

Section titled “Delete availability rules”

Removes buffers and working-hours restrictions. After deletion, the calendar reverts to the default “every minute is free unless blocked by an event” behavior.

DELETE /v1/calendars/:id/availability-rules
Terminal window
curl -X DELETE https://api.chronary.ai/v1/calendars/cal_01H9X4M2P5R8T6V0/availability-rules \
  -H "Authorization: Bearer chr_sk_your_key_here"

Response 204 No Content

Section titled “Response 204 No Content”

Empty body.

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Calendar not found, or no rules set for this calendar |