Availability

Three endpoints for finding available time slots.

Single-agent availability

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

GET /v1/agents/:id/availability

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

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"

from chronary import Chronary

client = Chronary()

availability = client.availability.get(
    agent_id="agt_a1b2c3d4",
    start="2026-04-07T09:00:00Z",
    end="2026-04-07T17:00:00Z",
    slot_duration="30m",
)
for slot in availability.slots:
    print(f"{slot.start} — {slot.end}")

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

Same parameters, scoped to one calendar.

GET /v1/calendars/:id/availability

Example

curl
Python

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"

availability = client.availability.get_calendar(
    calendar_id="cal_x1y2z3",
    start="2026-04-07T09:00:00Z",
    end="2026-04-07T17:00:00Z",
)

Errors

Status	Type	Cause
`404`	`not_found`	Calendar not found

Cross-agent availability

Find time slots where multiple agents are all free.

GET /v1/availability

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

curl
Python

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"

availability = client.availability.find_meeting_time(
    agents=["agt_a1b2c3d4", "agt_e5f6g7h8"],
    start="2026-04-07T09:00:00Z",
    end="2026-04-07T17:00:00Z",
    slot_duration="30m",
)

Plan limits

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

Errors

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

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

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

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

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

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

import Chronary from '@chronary/sdk';

const client = new Chronary();

const rules = await client.calendars.setAvailabilityRules('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',
});

rules = client.calendars.set_availability_rules(
    "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",
)

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

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

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

Returns the current rules for the calendar.

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

const rules = await client.calendars.getAvailabilityRules('cal_01H9X4M2P5R8T6V0');

rules = client.calendars.get_availability_rules("cal_01H9X4M2P5R8T6V0")

Response `200 OK`

Same shape as the PUT response above.

Errors

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

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

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

await client.calendars.deleteAvailabilityRules('cal_01H9X4M2P5R8T6V0');

client.calendars.delete_availability_rules("cal_01H9X4M2P5R8T6V0")

Response `204 No Content`

Empty body.

Errors

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

Availability

Single-agent availability

Query parameters

Example

Response 200 OK

Single-calendar availability

Example

Errors

Cross-agent availability

Query parameters

Example

Plan limits

Errors

Availability rules

Set availability rules

Request body

Example

Response 200 OK

Errors

Get availability rules

Response 200 OK

Errors

Delete availability rules

Response 204 No Content

Errors

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `204 No Content`