API reference/POST /v1/availability

POST /v1/availability

requires akidempotentP99 ~184 ms

Discover available slots and create a hold.

Request

POST /v1/availability HTTP/1.1
Authorization: Bearer ak_01HX7QQM…
Content-Type: application/json

{
  "calendar_owner_id": "…uuid…",
  "duration_minutes": 45,
  "window": { "start": "2026-06-01T09:00:00Z", "end": "2026-06-01T18:00:00Z" },
  "meeting_class": "recruiting_interview"
}

calendar_owner_idreq

string

duration_minutesreq

integer

windowreq

object

meeting_classreq

string

next_available_lookahead_hours

integer

Response

Returns 200 OK with the response body below. Every successful arbitration also stamps an audit_row_id you can query against audit log.

200 OK · example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hold_id": "hld_4f8b2a…",
  "expires_at": "2026-06-10T09:05:00Z",
  "slots": [
    { "start": "2026-06-10T10:00:00Z", "end": "2026-06-10T10:45:00Z" },
    { "start": "2026-06-10T11:00:00Z", "end": "2026-06-10T11:45:00Z" }
  ],
  "resolved_calendar_type": "work",
  "warnings": [],
  "pending_notifications": []
}

Errors

Code	Description
`400`	Validation failed — body is malformed or missing required fields.
`401`	Missing or invalid API key. Send the raw key as a Bearer token in the Authorization header.
`403`	Agent does not hold the permission scope required for this call (e.g. preempt on a higher-priority class).
`404`	Calendar owner or booking id not found.
`409`	Conflict — the requested slot was already committed at higher priority. Inspect alternatives[] in the response body.
`422`	Engine refused the request — a hard rule (working hours, daily limit, sacred meeting) fired. reason_code names the rule.