{"openapi":"3.1.0","info":{"title":"Ordstage API","description":"The Ordstage public API connects a business's own systems to Ordstage.\n\n**Authentication.** Send a workspace API key in `Authorization: Bearer <key>` (or `X-Api-Key: <key>`). Keys start\nwith `ord_live_` (real data) or `ord_test_` (the business's test workspace). Never put a key in a URL: a key seen in a\nquery string is refused and revoked at once.\n\n**Conventions.** Every answer carries a `Request-Id` header; errors share one shape (see `Error`); requests that create\nsomething need an `Idempotency-Key` header; each key has a per-minute limit reported in `X-RateLimit-*` headers.\n\nGuides, quickstart and webhook signature examples: [https://docs.ordstage.com](https://docs.ordstage.com).","contact":{"name":"Ordstage developer support","url":"https://docs.ordstage.com/","email":"support@ordstage.com"},"version":"1.0.0"},"servers":[{"url":"https://api.ordstage.com","description":"Production"},{"url":"https://api.staging.ordstage.com","description":"Staging (Ordstage's own pre-release environment)"}],"paths":{"/v1/calendars":{"get":{"tags":["Bookings"],"summary":"List calendars","description":"Calendars this key can see, with their resources (rooms, doctors, tables) and services: the ids the other booking endpoints take.","operationId":"listCalendars","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"calendars":{"items":{"$ref":"#/components/schemas/Calendar"},"type":"array"}},"type":"object","required":["calendars"]},"example":{"calendars":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Nile Clinic","industry":"clinic","timezone":"Africa/Cairo","is_active":true,"rules":{},"resources":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel","kind":"staff","capacity":1,"attributes":{}}],"services":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Checkup","kind":"appointment","duration_minutes":20,"price":300.0,"currency":"EGP"}]}]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active"]}},"/v1/calendars/{calendar_id}/availability":{"get":{"tags":["Bookings"],"summary":"Check availability","description":"Free times, the same answer the assistant gets. `channel=online` is what the assistant offers; `team` also counts places kept for walk-ins or closed online.","operationId":"getAvailability","parameters":[{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The calendar's id, from List calendars.","title":"Calendar Id"},"description":"The calendar's id, from List calendars."},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Service id or name (defaults to the calendar's only service).","title":"Service"},"description":"Service id or name (defaults to the calendar's only service)."},{"name":"resource","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resource id or name, to see only its times.","title":"Resource"},"description":"Resource id or name, to see only its times."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day, YYYY-MM-DD (default today).","title":"Date From"},"description":"First day, YYYY-MM-DD (default today)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day, YYYY-MM-DD (at most 14 days after date_from).","title":"Date To"},"description":"Last day, YYYY-MM-DD (at most 14 days after date_from)."},{"name":"time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":5},{"type":"null"}],"description":"Preferred time, HH:MM: the closest options first.","title":"Time"},"description":"Preferred time, HH:MM: the closest options first."},{"name":"party_size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"description":"Guests (restaurants, stays).","title":"Party Size"},"description":"Guests (restaurants, stays)."},{"name":"check_in","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stays: check-in day, YYYY-MM-DD.","title":"Check In"},"description":"Stays: check-in day, YYYY-MM-DD."},{"name":"nights","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"description":"Stays: number of nights.","title":"Nights"},"description":"Stays: number of nights."},{"name":"rooms","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Stays: rooms wanted.","title":"Rooms"},"description":"Stays: rooms wanted."},{"name":"channel","in":"query","required":false,"schema":{"enum":["online","team"],"type":"string","description":"`online`: what the assistant offers; `team`: everything.","default":"online","title":"Channel"},"description":"`online`: what the assistant offers; `team`: everything."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"},"example":{"options":[{"start":"2026-11-02T09:00","end":"2026-11-02T09:20","resource":"Dr. Sara Adel"}]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: booking_rejected, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"booking_rejected":{"value":{"error":{"type":"invalid_request","code":"booking_rejected","message":"The booking engine refused the request; `code` says why (for example invalid_time).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active","not_found","validation_error","booking_rejected"]}},"/v1/calendars/{calendar_id}/bookings":{"get":{"tags":["Bookings"],"summary":"List bookings","description":"Every booking in a calendar from every source (the assistant, the team, other systems), by date range or changed since a time.","operationId":"listBookings","parameters":[{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The calendar's id, from List calendars.","title":"Calendar Id"},"description":"The calendar's id, from List calendars."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bookings ending after this day starts, YYYY-MM-DD.","title":"From"},"description":"Bookings ending after this day starts, YYYY-MM-DD."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bookings starting before this day ends, YYYY-MM-DD.","title":"To"},"description":"Bookings starting before this day ends, YYYY-MM-DD."},{"name":"updated_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only bookings changed after this time (ISO 8601), oldest change first: use it to sync.","title":"Updated Since"},"description":"Only bookings changed after this time (ISO 8601), oldest change first: use it to sync."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated statuses, like confirmed,cancelled.","title":"Status"},"description":"Comma-separated statuses, like confirmed,cancelled."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"At most this many bookings (1–1000).","default":200,"title":"Limit"},"description":"At most this many bookings (1–1000)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["bookings","has_more"],"properties":{"bookings":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}},"has_more":{"type":"boolean","description":"More match than `limit`."}}},"example":{"bookings":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"confirmed","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","updated_at":"2026-10-29T10:00:00+00:00"}],"has_more":false}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: booking_rejected, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"booking_rejected":{"value":{"error":{"type":"invalid_request","code":"booking_rejected","message":"The booking engine refused the request; `code` says why (for example invalid_time).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active","not_found","validation_error","booking_rejected"]}},"/v1/calendars/{calendar_id}/bookings/{external_id}":{"put":{"tags":["Bookings"],"summary":"Create or update a booking","description":"Record a booking made in your system under your own id. Sending it again updates it, so retries are safe. It is recorded even when the time is full (it already happened); the answer then says `overbooked: true` and the team gets an alert.","operationId":"upsertBooking","parameters":[{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The calendar's id, from List calendars.","title":"Calendar Id"},"description":"The calendar's id, from List calendars."},{"name":"external_id","in":"path","required":true,"schema":{"type":"string","description":"Your own id for it (1 to 255 characters): sending the same id again updates it.","title":"External Id"},"description":"Your own id for it (1 to 255 characters): sending the same id again updates it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingUpsert"},"example":{"resource":"Dr. Sara Adel","start":"2026-11-02T09:00","end":"2026-11-02T09:20","customer_name":"Mona"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingWrite"},"example":{"booking":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"confirmed","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","updated_at":"2026-10-29T10:00:00+00:00"},"overbooked":false,"alerts":[]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: booking_rejected, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"booking_rejected":{"value":{"error":{"type":"invalid_request","code":"booking_rejected","message":"The booking engine refused the request; `code` says why (for example invalid_time).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:write","x-ordstage-webhooks":"booking.created, booking.updated, booking.cancelled, booking.conflict","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active","not_found","validation_error","booking_rejected"]},"delete":{"tags":["Bookings"],"summary":"Cancel a booking","description":"Cancel a booking you sent earlier, by your id. Cancelling one that was never sent answers `booking: null`.","operationId":"cancelBooking","parameters":[{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The calendar's id, from List calendars.","title":"Calendar Id"},"description":"The calendar's id, from List calendars."},{"name":"external_id","in":"path","required":true,"schema":{"type":"string","description":"Your own id for it (1 to 255 characters): sending the same id again updates it.","title":"External Id"},"description":"Your own id for it (1 to 255 characters): sending the same id again updates it."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingWrite"},"example":{"booking":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"cancelled","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","updated_at":"2026-10-29T10:00:00+00:00"},"overbooked":false,"alerts":[]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: booking_rejected, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"booking_rejected":{"value":{"error":{"type":"invalid_request","code":"booking_rejected","message":"The booking engine refused the request; `code` says why (for example invalid_time).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:write","x-ordstage-webhooks":"booking.cancelled","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active","not_found","validation_error","booking_rejected"]}},"/v1/calendars/{calendar_id}/blocks/{external_id}":{"put":{"tags":["Bookings"],"summary":"Close time","description":"Close a resource (maintenance, a private event) or stop online selling for the whole calendar (`scope: online`), under your own id. Sending it again replaces it.","operationId":"closeTime","parameters":[{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The calendar's id, from List calendars.","title":"Calendar Id"},"description":"The calendar's id, from List calendars."},{"name":"external_id","in":"path","required":true,"schema":{"type":"string","description":"Your own id for it (1 to 255 characters): sending the same id again updates it.","title":"External Id"},"description":"Your own id for it (1 to 255 characters): sending the same id again updates it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockUpsert"},"example":{"starts_at":"2026-12-31T00:00","ends_at":"2026-12-31T23:59","scope":"online","reason":"Private event"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["blocks"],"properties":{"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["all","online"]}}}}}},"example":{"blocks":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","resource_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","scope":"online"}]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: booking_rejected, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"booking_rejected":{"value":{"error":{"type":"invalid_request","code":"booking_rejected","message":"The booking engine refused the request; `code` says why (for example invalid_time).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:write","x-ordstage-webhooks":"availability.closed","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active","not_found","validation_error","booking_rejected"]},"delete":{"tags":["Bookings"],"summary":"Reopen time","description":"Remove a closure you sent earlier, by your id.","operationId":"reopenTime","parameters":[{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The calendar's id, from List calendars.","title":"Calendar Id"},"description":"The calendar's id, from List calendars."},{"name":"external_id","in":"path","required":true,"schema":{"type":"string","description":"Your own id for it (1 to 255 characters): sending the same id again updates it.","title":"External Id"},"description":"Your own id for it (1 to 255 characters): sending the same id again updates it."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"integer","description":"Closures removed."}}},"example":{"deleted":1}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"bookings:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Not available yet: test keys are refused with sandbox_not_available.","x-ordstage-errors":["module_not_active","not_found","validation_error"]}},"/v1/business":{"get":{"tags":["Business"],"summary":"Get the business","description":"The business's profile and branding.","operationId":"getBusiness","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"business","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic","website":"https://nileclinic.example","logo_url":null,"brand_color":"#315CFF","accent_color":null,"timezone":"Africa/Cairo","language":"en"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"business:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]},"patch":{"tags":["Business"],"summary":"Update the business","description":"Change the name, website, colours, timezone or language; only the fields sent change. A logo can be removed here; a new one is chosen by previewing the website in Settings.","operationId":"updateBusiness","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessUpdate"},"example":{"name":"Nile Clinic Zamalek","timezone":"Africa/Cairo"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"business","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic Zamalek","website":"https://nileclinic.example","logo_url":null,"brand_color":"#315CFF","accent_color":null,"timezone":"Africa/Cairo","language":"en"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"business:write","x-ordstage-webhooks":"business.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["validation_error"]}},"/v1/members":{"get":{"tags":["Members"],"summary":"List members","description":"Everyone on the team, oldest first. Filter by role.","operationId":"listMembers","parameters":[{"name":"role","in":"query","required":false,"schema":{"anyOf":[{"enum":["owner","admin","manager","member"],"type":"string"},{"type":"null"}],"description":"Only members with this role.","title":"Role"},"description":"Only members with this role."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"member","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"sara@nileclinic.example","name":"Sara Adel","role":"manager","active":true,"email_verified":true,"teams":[]}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["invalid_cursor","validation_error"]}},"/v1/members/{member_id}":{"get":{"tags":["Members"],"summary":"Get a member","description":"One member of the team.","operationId":"getMember","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The member's id (their user id).","title":"Member Id"},"description":"The member's id (their user id)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"member","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"sara@nileclinic.example","name":"Sara Adel","role":"manager","active":true,"email_verified":true,"teams":[]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found"]},"patch":{"tags":["Members"],"summary":"Change a member's role","description":"Give a member another role. Only an owner's key can make or change owners, and the last active owner can't be demoted.","operationId":"updateMember","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The member's id (their user id).","title":"Member Id"},"description":"The member's id (their user id)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberUpdate"},"example":{"role":"admin"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"member","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"sara@nileclinic.example","name":"Sara Adel","role":"admin","active":true,"email_verified":true,"teams":[]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_role, last_owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_role":{"value":{"error":{"type":"invalid_request","code":"invalid_role","message":"Choose owner, admin, manager or member.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"last_owner":{"value":{"error":{"type":"invalid_request","code":"last_owner","message":"Assign another active owner before removing or changing the last owner.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, owner_role_required, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"owner_role_required":{"value":{"error":{"type":"permission","code":"owner_role_required","message":"Only an owner can manage owners; this key's creator is an admin.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:write","x-ordstage-webhooks":"member.role_changed","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox","invalid_role","owner_role_required","last_owner","validation_error"]},"delete":{"tags":["Members"],"summary":"Remove a member","description":"Remove someone from the team. Their account stays (they may belong to other businesses); their conversations are unassigned and their personal connections here stop. The last active owner can't be removed, and the key's creator can't remove themselves.","operationId":"removeMember","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The member's id (their user id).","title":"Member Id"},"description":"The member's id (their user id)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"member","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"sara@nileclinic.example","name":"Sara Adel","role":"manager","active":true,"email_verified":true,"teams":[]}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, cannot_remove_self, last_owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"last_owner":{"value":{"error":{"type":"invalid_request","code":"last_owner","message":"Assign another active owner before removing or changing the last owner.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"cannot_remove_self":{"value":{"error":{"type":"invalid_request","code":"cannot_remove_self","message":"The key's creator can't remove themselves.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, owner_role_required, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"owner_role_required":{"value":{"error":{"type":"permission","code":"owner_role_required","message":"Only an owner can manage owners; this key's creator is an admin.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:write","x-ordstage-webhooks":"member.removed","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox","owner_role_required","last_owner","cannot_remove_self"]}},"/v1/members/{member_id}/send_password_reset":{"post":{"tags":["Members"],"summary":"Email a password reset","description":"Email the member a link to choose a new password (valid 30 minutes). The link goes only to their own address; nothing about the password is ever returned or set by the API. An admin's key can't do this for an owner.","operationId":"sendMemberPasswordReset","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The member's id (their user id).","title":"Member Id"},"description":"The member's id (their user id)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordReset"},"example":{"object":"password_reset","member_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","sent_to":"sara@nileclinic.example","status":"sent","expires_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, owner_role_required, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"owner_role_required":{"value":{"error":{"type":"permission","code":"owner_role_required","message":"Only an owner can manage owners; this key's creator is an admin.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: password_reset_recently_sent, rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"password_reset_recently_sent":{"value":{"error":{"type":"rate_limit","code":"password_reset_recently_sent","message":"A reset email was sent less than a minute ago.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: member_inactive, not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"member_inactive":{"value":{"error":{"type":"conflict","code":"member_inactive","message":"This member's account is turned off.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox","owner_role_required","member_inactive","password_reset_recently_sent"]}},"/v1/invitations":{"get":{"tags":["Members"],"summary":"List invitations","description":"Invitations sent to join the team, oldest first. Filter by status.","operationId":"listInvitations","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["pending","accepted","expired","revoked"],"type":"string"},{"type":"null"}],"description":"Only invitations in this state.","title":"Status"},"description":"Only invitations in this state."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"pending","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["invalid_cursor","validation_error"]},"post":{"tags":["Members"],"summary":"Invite someone","description":"Email an invitation to join the team with a role (valid 7 days). Seats are counted, including pending invitations.","operationId":"createInvitation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationCreate"},"example":{"email":"omar@nileclinic.example","role":"member","name":"Omar"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"pending","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required, invalid_role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_role":{"value":{"error":{"type":"invalid_request","code":"invalid_role","message":"Choose owner, admin, manager or member.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, owner_role_required, plan_upgrade_required, sandbox_not_available, seat_limit_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"owner_role_required":{"value":{"error":{"type":"permission","code":"owner_role_required","message":"Only an owner can manage owners; this key's creator is an admin.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"seat_limit_reached":{"value":{"error":{"type":"permission","code":"seat_limit_reached","message":"All seats are in use. Add a seat or remove someone first.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: already_member, idempotency_conflict, idempotency_in_progress, invitation_exists, not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"already_member":{"value":{"error":{"type":"conflict","code":"already_member","message":"This person is already a member of this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invitation_exists":{"value":{"error":{"type":"conflict","code":"invitation_exists","message":"An invitation for this email is already pending. Resend it instead.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:write","x-ordstage-webhooks":"member.invited","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["key_creator_not_allowed","not_available_in_sandbox","invalid_role","owner_role_required","seat_limit_reached","already_member","invitation_exists","validation_error"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/invitations/{invitation_id}":{"get":{"tags":["Members"],"summary":"Get an invitation","description":"One invitation. Its link is never shown; only the invited address receives it.","operationId":"getInvitation","parameters":[{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The invitation's id.","title":"Invitation Id"},"description":"The invitation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"pending","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found"]}},"/v1/invitations/{invitation_id}/resend":{"post":{"tags":["Members"],"summary":"Resend an invitation","description":"Send the invitation again with a fresh link valid 7 days (the old link stops). At most once a minute.","operationId":"resendInvitation","parameters":[{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The invitation's id.","title":"Invitation Id"},"description":"The invitation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"pending","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, owner_role_required, plan_upgrade_required, sandbox_not_available, seat_limit_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"owner_role_required":{"value":{"error":{"type":"permission","code":"owner_role_required","message":"Only an owner can manage owners; this key's creator is an admin.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"seat_limit_reached":{"value":{"error":{"type":"permission","code":"seat_limit_reached","message":"All seats are in use. Add a seat or remove someone first.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, resend_too_soon, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"resend_too_soon":{"value":{"error":{"type":"rate_limit","code":"resend_too_soon","message":"Wait a minute before resending this invitation.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: invitation_not_pending, invitation_superseded, not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invitation_not_pending":{"value":{"error":{"type":"conflict","code":"invitation_not_pending","message":"This invitation was accepted or revoked.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invitation_superseded":{"value":{"error":{"type":"conflict","code":"invitation_superseded","message":"This person already has access or a newer invitation.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox","owner_role_required","invitation_not_pending","invitation_superseded","resend_too_soon","seat_limit_reached"]}},"/v1/invitations/{invitation_id}/revoke":{"post":{"tags":["Members"],"summary":"Revoke an invitation","description":"Stop an invitation from being accepted. Its link stops working.","operationId":"revokeInvitation","parameters":[{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The invitation's id.","title":"Invitation Id"},"description":"The invitation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"revoked","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, owner_role_required, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"owner_role_required":{"value":{"error":{"type":"permission","code":"owner_role_required","message":"Only an owner can manage owners; this key's creator is an admin.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: invitation_not_pending, not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invitation_not_pending":{"value":{"error":{"type":"conflict","code":"invitation_not_pending","message":"This invitation was accepted or revoked.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"members:write","x-ordstage-webhooks":"member.invitation_revoked","x-ordstage-sandbox":"The sandbox has no team: lists are empty, lookups answer not_found and changes answer not_available_in_sandbox.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox","owner_role_required","invitation_not_pending"]}},"/v1/webhooks":{"get":{"tags":["Webhook endpoints"],"summary":"List webhooks","description":"The business's webhook endpoints, oldest first. Secrets are never listed.","operationId":"listWebhooks","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"],"calendar_ids":null,"status":"active","paused_reason":null,"failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["invalid_cursor","validation_error"]},"post":{"tags":["Webhook endpoints"],"summary":"Create a webhook","description":"Add an endpoint. The answer has its signing secret, shown only this once. Choose events, or none for every event (including ones added later). At most 10 per business.","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"},"example":{"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"],"calendar_ids":null,"status":"active","paused_reason":null,"failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00","secret":"whsec_…"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available, webhooks_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"webhooks_not_allowed":{"value":{"error":{"type":"permission","code":"webhooks_not_allowed","message":"Webhooks aren't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: idempotency_conflict, idempotency_in_progress, webhook_limit_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_limit_reached":{"value":{"error":{"type":"conflict","code":"webhook_limit_reached","message":"A business can have 10 webhooks.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: invalid_webhook_url, unknown_calendar, unknown_event, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_webhook_url":{"value":{"error":{"type":"invalid_request","code":"invalid_webhook_url","message":"Use a public https:// address.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"unknown_event":{"value":{"error":{"type":"invalid_request","code":"unknown_event","message":"Choose events from the list of webhook events.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"unknown_calendar":{"value":{"error":{"type":"invalid_request","code":"unknown_calendar","message":"Choose calendars from this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["webhooks_not_allowed","webhook_limit_reached","invalid_webhook_url","unknown_event","unknown_calendar","module_not_active","validation_error"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/webhooks/{webhook_id}":{"get":{"tags":["Webhook endpoints"],"summary":"Get a webhook","description":"One webhook endpoint (never its secret).","operationId":"getWebhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"],"calendar_ids":null,"status":"active","paused_reason":null,"failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found"]},"patch":{"tags":["Webhook endpoints"],"summary":"Update a webhook","description":"Change its name, address, events or calendars; only the fields sent change.","operationId":"updateWebhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"},"example":{"events":[]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":[],"calendar_ids":null,"status":"active","paused_reason":null,"failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: invalid_webhook_url, unknown_calendar, unknown_event, validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_webhook_url":{"value":{"error":{"type":"invalid_request","code":"invalid_webhook_url","message":"Use a public https:// address.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"unknown_event":{"value":{"error":{"type":"invalid_request","code":"unknown_event","message":"Choose events from the list of webhook events.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"unknown_calendar":{"value":{"error":{"type":"invalid_request","code":"unknown_calendar","message":"Choose calendars from this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found","invalid_webhook_url","unknown_event","unknown_calendar","module_not_active","validation_error"]},"delete":{"tags":["Webhook endpoints"],"summary":"Delete a webhook","description":"Remove an endpoint and its delivery history. Nothing more is sent to it.","operationId":"deleteWebhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","deleted":true}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found"]}},"/v1/webhooks/{webhook_id}/pause":{"post":{"tags":["Webhook endpoints"],"summary":"Pause a webhook","description":"Stop sending. Events keep queuing and are sent after it is resumed (each is retried for about a day).","operationId":"pauseWebhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"],"calendar_ids":null,"status":"paused","paused_reason":"Paused by your team","failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found"]}},"/v1/webhooks/{webhook_id}/resume":{"post":{"tags":["Webhook endpoints"],"summary":"Resume a webhook","description":"Start sending again (also after it was paused for failing), with the failure count reset.","operationId":"resumeWebhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"],"calendar_ids":null,"status":"active","paused_reason":null,"failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available, webhooks_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"webhooks_not_allowed":{"value":{"error":{"type":"permission","code":"webhooks_not_allowed","message":"Webhooks aren't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found","webhooks_not_allowed"]}},"/v1/webhooks/{webhook_id}/rotate_secret":{"post":{"tags":["Webhook endpoints"],"summary":"Rotate a webhook's secret","description":"A new signing secret, shown only in this answer. Every delivery from now on (retries too) is signed with it; the old one stops at once.","operationId":"rotateWebhookSecret","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"webhook","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","url":"https://his.example.com/ordstage","events":["contact.created","lead.created"],"calendar_ids":null,"status":"active","paused_reason":null,"failures":0,"last_delivery_at":"2026-10-29T12:30:00+00:00","secret":"whsec_…"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found"]}},"/v1/webhooks/{webhook_id}/test":{"post":{"tags":["Webhook endpoints"],"summary":"Send a test event","description":"Send a signed `ping` now and answer with what the endpoint replied.","operationId":"testWebhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTest"},"example":{"object":"webhook_test","ok":true,"status_code":200,"error":null,"delivery_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available, webhooks_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"webhooks_not_allowed":{"value":{"error":{"type":"permission","code":"webhooks_not_allowed","message":"Webhooks aren't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"ping","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found","webhooks_not_allowed"]}},"/v1/webhooks/{webhook_id}/deliveries":{"get":{"tags":["Webhook endpoints"],"summary":"List deliveries","description":"What was sent to this webhook, oldest first; filter by status.","operationId":"listWebhookDeliveries","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["pending","delivered","failed"],"type":"string"},{"type":"null"}],"description":"Only deliveries in this state.","title":"Status"},"description":"Only deliveries in this state."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"webhook_delivery","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"webhook_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"lead.created","status":"delivered","attempts":1,"last_status_code":200,"last_error":null,"next_attempt_at":null,"delivered_at":"2026-10-29T10:00:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found","invalid_cursor","validation_error"]}},"/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry":{"post":{"tags":["Webhook endpoints"],"summary":"Retry a delivery","description":"Queue a delivery again now. It is signed with the current secret and sent only if the business still allows the event.","operationId":"retryWebhookDelivery","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The webhook's id.","title":"Webhook Id"},"description":"The webhook's id."},{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The delivery's id.","title":"Delivery Id"},"description":"The delivery's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"webhook_delivery","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"webhook_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"lead.created","status":"pending","attempts":0,"last_status_code":200,"last_error":null,"next_attempt_at":"2026-10-29T10:00:00+00:00","delivered_at":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: ping_not_retryable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ping_not_retryable":{"value":{"error":{"type":"conflict","code":"ping_not_retryable","message":"Test deliveries aren't retried; send a new test instead.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"webhooks:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys manage the sandbox's own webhooks, which receive only sandbox events (webhooks are the one thing the sandbox really sends).","x-ordstage-errors":["not_found","ping_not_retryable"]}},"/v1/api_keys":{"get":{"tags":["API keys"],"summary":"List API keys","description":"The business's keys (test keys: the sandbox's), oldest first: names, scopes, status and last use. Never a secret.","operationId":"listApiKeys","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","object":"api_key","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","description":null,"prefix":"ord_live_1a2b3c4d5e6f_…","environment":"live","scopes":["contacts:read","leads:write"],"status":"active","expires_at":null,"ip_allowlist":[],"last_used_at":"2026-10-29T12:30:00+00:00","revoked_at":null}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"api_keys:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys list the sandbox's test keys.","x-ordstage-errors":["invalid_cursor","validation_error"]}},"/v1/api_keys/{key_id}":{"get":{"tags":["API keys"],"summary":"Get an API key","description":"One key's name, scopes, status and last use. Never its secret.","operationId":"getApiKey","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The key's id.","title":"Key Id"},"description":"The key's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"},"example":{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","object":"api_key","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Clinic system","description":null,"prefix":"ord_live_1a2b3c4d5e6f_…","environment":"live","scopes":["contacts:read","leads:write"],"status":"active","expires_at":null,"ip_allowlist":[],"last_used_at":"2026-10-29T12:30:00+00:00","revoked_at":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"api_keys:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys see only the sandbox's test keys.","x-ordstage-errors":["not_found"]}},"/v1/assistants":{"get":{"tags":["Assistants"],"summary":"List assistants","description":"The business's assistants, oldest first.","operationId":"listAssistants","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Assistant"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"active","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["invalid_cursor","validation_error"]}},"/v1/assistants/{assistant_id}":{"get":{"tags":["Assistants"],"summary":"Get an assistant","description":"One assistant, with where its setup stands (`lifecycle`).","operationId":"getAssistant","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"active","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00","lifecycle":{"publication":"current","health":"healthy","display":"live"}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]}},"/v1/assistants/{assistant_id}/publish":{"post":{"tags":["Assistants"],"summary":"Publish an assistant","description":"Publish the current setup and make the assistant answer with it, exactly like Publish in Studio. Refused while required setup is missing.","operationId":"publishAssistant","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantPublication"},"example":{"object":"assistant_publication","assistant":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"active","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"},"publication":{"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","version":4}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: assistant_release_not_ready, brand_identity_unapproved, critical_action_tests_required, flow_draft_conflict, flow_validation_failed, idempotency_conflict, idempotency_in_progress, main_flow_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"assistant_release_not_ready":{"value":{"error":{"type":"conflict","code":"assistant_release_not_ready","message":"Resolve the assistant's required setup items before publishing; `message` lists them in Studio.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"brand_identity_unapproved":{"value":{"error":{"type":"conflict","code":"brand_identity_unapproved","message":"Approve the business profile in Studio before publishing.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"main_flow_missing":{"value":{"error":{"type":"conflict","code":"main_flow_missing","message":"Create a conversation flow before publishing this assistant.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"flow_validation_failed":{"value":{"error":{"type":"conflict","code":"flow_validation_failed","message":"Fix the assistant's conversation flow in the flow editor before publishing.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"critical_action_tests_required":{"value":{"error":{"type":"conflict","code":"critical_action_tests_required","message":"Run passing tests for each action in the flow editor before publishing.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"flow_draft_conflict":{"value":{"error":{"type":"conflict","code":"flow_draft_conflict","message":"The flow changed while publishing. Try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"assistant.published","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","key_creator_not_allowed","assistant_release_not_ready","brand_identity_unapproved","main_flow_missing","flow_validation_failed","critical_action_tests_required","flow_draft_conflict"]}},"/v1/assistants/{assistant_id}/pause":{"post":{"tags":["Assistants"],"summary":"Pause an assistant","description":"Stop the assistant answering customers; new messages go to the team. Pausing a paused assistant changes nothing.","operationId":"pauseAssistant","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"paused","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"assistant.paused","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","key_creator_not_allowed"]}},"/v1/assistants/{assistant_id}/resume":{"post":{"tags":["Assistants"],"summary":"Resume an assistant","description":"Make a paused assistant answer again. Only a published setup without blocking problems can be resumed.","operationId":"resumeAssistant","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"active","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: assistant_not_resumable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"assistant_not_resumable":{"value":{"error":{"type":"conflict","code":"assistant_not_resumable","message":"Publish the current setup and resolve required items before resuming.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"assistant.resumed","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","key_creator_not_allowed","assistant_not_resumable"]}},"/v1/assistants/{assistant_id}/test_messages":{"post":{"tags":["Assistants"],"summary":"Send a test message","description":"Send a message to the sandbox's assistant and get its reply, like the test chat in Studio: nothing reaches a customer. Pass the returned session_id to continue the same conversation.","operationId":"sendAssistantTestMessage","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestMessage"},"example":{"message":"Do you open on Fridays?"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantTestMessage"},"example":{"object":"assistant_test_message","livemode":false,"assistant_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","session_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","turn":1,"message":"Do you open on Fridays?","reply":"Yes, from 2 pm to 10 pm."}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: daily_limit_reached, rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"daily_limit_reached":{"value":{"error":{"type":"rate_limit","code":"daily_limit_reached","message":"The plan's daily limit for test messages is used up. Try again tomorrow.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: test_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"test_key_required":{"value":{"error":{"type":"conflict","code":"test_key_required","message":"Test messages run in the sandbox: send them with a test key (ord_test_…).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Test keys only: the message runs in the sandbox against its sample assistant, with the sandbox's AI allowance.","x-ordstage-errors":["not_found","key_creator_not_allowed","test_key_required","daily_limit_reached","validation_error"]}},"/v1/assistants/{assistant_id}/knowledge_sources":{"get":{"tags":["Assistants"],"summary":"List knowledge sources","description":"What the assistant learns from (pages, files, sheets), oldest first.","operationId":"listKnowledgeSources","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSource"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"knowledge_source","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"assistant_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Prices","type":"web_page","url":"https://nileclinic.example/prices","status":"ready","chunks":14,"last_synced_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","invalid_cursor","validation_error"]},"post":{"tags":["Assistants"],"summary":"Add a web page","description":"Add a public web page for the assistant to learn from. It is read right away (`status` processing, then ready or error); publish the assistant for customers to get it.","operationId":"createKnowledgeSource","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceCreate"},"example":{"url":"https://nileclinic.example/prices","name":"Prices"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSource"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"knowledge_source","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"assistant_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Prices","type":"web_page","url":"https://nileclinic.example/prices","status":"processing","chunks":0,"last_synced_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: idempotency_conflict, idempotency_in_progress, not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Refused with test keys (not_available_in_sandbox): reading web pages is only done for live assistants.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox","validation_error"]}},"/v1/assistants/{assistant_id}/knowledge_sources/{source_id}/refresh":{"post":{"tags":["Assistants"],"summary":"Refresh a knowledge source","description":"Read the source again; what it said before stays in use until the new text is ready.","operationId":"refreshKnowledgeSource","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The knowledge source's id.","title":"Source Id"},"description":"The knowledge source's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSource"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"knowledge_source","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"assistant_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Prices","type":"web_page","url":"https://nileclinic.example/prices","status":"processing","chunks":14,"last_synced_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: not_available_in_sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_available_in_sandbox":{"value":{"error":{"type":"conflict","code":"not_available_in_sandbox","message":"This isn't available in the sandbox. Use a live key.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Refused with test keys (not_available_in_sandbox): reading web pages is only done for live assistants.","x-ordstage-errors":["not_found","key_creator_not_allowed","not_available_in_sandbox"]}},"/v1/assistants/{assistant_id}/knowledge_sources/{source_id}":{"delete":{"tags":["Assistants"],"summary":"Remove a knowledge source","description":"The assistant stops using it at once. A source a published release used is kept (archived) for that release's history.","operationId":"deleteKnowledgeSource","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The assistant's id.","title":"Assistant Id"},"description":"The assistant's id."},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The knowledge source's id.","title":"Source Id"},"description":"The knowledge source's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"knowledge_source","deleted":true}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"assistants:write","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","key_creator_not_allowed"]}},"/v1/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","description":"Customer conversations oldest first; filter by status, who handles them, contact or channel.","operationId":"listConversations","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["open","pending","resolved","closed"],"type":"string"},{"type":"null"}],"description":"Only this status.","title":"Status"},"description":"Only this status."},{"name":"handled_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["assistant","team"],"type":"string"},{"type":"null"}],"description":"Only those the assistant or the team handles.","title":"Handled By"},"description":"Only those the assistant or the team handles."},{"name":"contact_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only this contact's.","title":"Contact Id"},"description":"Only this contact's."},{"name":"channel_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only this channel's.","title":"Channel Id"},"description":"Only this channel's."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["invalid_cursor","validation_error"]}},"/v1/conversations/{conversation_id}":{"get":{"tags":["Conversations"],"summary":"Get a conversation","description":"One conversation, with its channel, contact, status and labels.","operationId":"getConversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]},"patch":{"tags":["Conversations"],"summary":"Update a conversation","description":"Change its priority, assignee, team, or whether it waits for the customer (pending); only the fields sent change.","operationId":"updateConversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdate"},"example":{"priority":"high"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"high","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: assignee_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"assignee_not_available":{"value":{"error":{"type":"conflict","code":"assignee_not_available","message":"This member can't take the conversation now; `message` says why.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","assignee_not_available","validation_error"]}},"/v1/conversations/{conversation_id}/messages":{"get":{"tags":["Conversations"],"summary":"List messages","description":"The conversation's messages oldest first. Internal notes between teammates are never included.","operationId":"listConversationMessages","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","object":"message","created_at":"2026-10-29T12:30:00+00:00","livemode":true,"conversation_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","direction":"outgoing","author":"team","type":"text","content":"Your appointment is confirmed for Sunday at 10.","attachments":[],"delivery_status":"sent","sent_at":"2026-10-29T12:30:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","invalid_cursor","validation_error"]}},"/v1/conversations/{conversation_id}/reply":{"post":{"tags":["Conversations"],"summary":"Reply to a conversation","description":"Send a reply on the conversation's channel as the key's creator, like replying in the Inbox. Channel rules apply (for example WhatsApp's 24-hour window). The assistant keeps handling the conversation unless it is handed over.","operationId":"replyToConversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reply"},"example":{"content":"Your appointment is confirmed for Sunday at 10."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"},"example":{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","object":"message","created_at":"2026-10-29T12:30:00+00:00","livemode":true,"conversation_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","direction":"outgoing","author":"team","type":"text","content":"Your appointment is confirmed for Sunday at 10.","attachments":[],"delivery_status":"sent","sent_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, key_creator_not_allowed, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"key_creator_not_allowed":{"value":{"error":{"type":"permission","code":"key_creator_not_allowed","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: idempotency_conflict, idempotency_in_progress, reply_not_sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"reply_not_sent":{"value":{"error":{"type":"conflict","code":"reply_not_sent","message":"The channel didn't accept the reply; `message` says why (for example, its reply window closed).","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.reply_sent","x-ordstage-sandbox":"With test keys the reply is saved and recorded in the sandbox as a simulated send; it never reaches anyone.","x-ordstage-errors":["not_found","key_creator_not_allowed","reply_not_sent","validation_error"]}},"/v1/conversations/{conversation_id}/handover":{"post":{"tags":["Conversations"],"summary":"Hand over to the team","description":"The assistant stops answering and the team takes the conversation, optionally a teammate or Inbox team (who must be able to take it now).","operationId":"handOverConversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Handover"},"example":{"team_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"team","automation_mode":"human","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: assignee_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"assignee_not_available":{"value":{"error":{"type":"conflict","code":"assignee_not_available","message":"This member can't take the conversation now; `message` says why.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.handed_over, conversation.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","assignee_not_available","validation_error"]}},"/v1/conversations/{conversation_id}/return_to_assistant":{"post":{"tags":["Conversations"],"summary":"Return to the assistant","description":"The assistant answers the conversation again.","operationId":"returnConversationToAssistant","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.returned_to_assistant","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]}},"/v1/conversations/{conversation_id}/close":{"post":{"tags":["Conversations"],"summary":"Close a conversation","description":"Mark it resolved, like Done in the Inbox; the channel is told where it supports that. Closing a closed conversation changes nothing.","operationId":"closeConversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"resolved","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.closed","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]}},"/v1/conversations/{conversation_id}/reopen":{"post":{"tags":["Conversations"],"summary":"Reopen a conversation","description":"Open a resolved or closed conversation again.","operationId":"reopenConversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.reopened","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]}},"/v1/conversations/{conversation_id}/labels":{"post":{"tags":["Conversations"],"summary":"Add a label","description":"Label the conversation with one of the business's labels.","operationId":"addConversationLabel","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelAdd"},"example":{"label_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","validation_error"]}},"/v1/conversations/{conversation_id}/labels/{label_id}":{"delete":{"tags":["Conversations"],"summary":"Remove a label","description":"Take a label off the conversation.","operationId":"removeConversationLabel","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation's id.","title":"Conversation Id"},"description":"The conversation's id."},{"name":"label_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The label's id.","title":"Label Id"},"description":"The label's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:write","x-ordstage-webhooks":"conversation.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]}},"/v1/labels":{"get":{"tags":["Conversations"],"summary":"List labels","description":"The business's Inbox labels, to filter and label conversations with.","operationId":"listLabels","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b","object":"label","created_at":"2026-10-29T10:00:00+00:00","livemode":true}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"conversations:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["invalid_cursor","validation_error"]}},"/v1/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Contacts oldest first. Filter by exact email or phone, a tag, or search text.","operationId":"listContacts","parameters":[{"name":"email","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"description":"Exact email (any case).","title":"Email"},"description":"Exact email (any case)."},{"name":"phone","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Exact phone number.","title":"Phone"},"description":"Exact phone number."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Only contacts with this tag.","title":"Tag"},"description":"Only contacts with this tag."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Search in name, email and phone.","title":"Q"},"description":"Search in name, email and phone."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["invalid_cursor","validation_error"]},"post":{"tags":["Contacts"],"summary":"Create a contact","description":"Add a contact with at least a name, an email or a phone number.","operationId":"createContact","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactCreate"},"example":{"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","tags":["vip"],"attributes":{"his_patient_id":"P-1042"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: idempotency_conflict, idempotency_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:write","x-ordstage-webhooks":"contact.created","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["validation_error"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/contacts/{contact_id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","description":"One contact, with its tags and attributes.","operationId":"getContact","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The contact's id.","title":"Contact Id"},"description":"The contact's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]},"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Change details, tags (replaced) or attributes (merged; null removes a key). Only the fields sent change.","operationId":"updateContact","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The contact's id.","title":"Contact Id"},"description":"The contact's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdate"},"example":{"locale":"en","attributes":{"his_patient_id":"P-1042","old_field":null}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"en","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:write","x-ordstage-webhooks":"contact.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","validation_error"]},"delete":{"tags":["Contacts"],"summary":"Delete a contact","description":"Delete a contact. Their conversations, orders, bookings and leads stay, without a contact.","operationId":"deleteContact","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The contact's id.","title":"Contact Id"},"description":"The contact's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","deleted":true}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:write","x-ordstage-webhooks":"contact.deleted","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found"]}},"/v1/contacts/{contact_id}/tags":{"post":{"tags":["Contacts"],"summary":"Add or remove tags","description":"Add and remove tags without sending the whole list.","operationId":"tagContact","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The contact's id.","title":"Contact Id"},"description":"The contact's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactTags"},"example":{"add":["follow-up"],"remove":["new"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip","follow-up"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:write","x-ordstage-webhooks":"contact.updated","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","validation_error"]}},"/v1/contacts/{contact_id}/merge":{"post":{"tags":["Contacts"],"summary":"Merge a duplicate","description":"Merge `duplicate_id` into this contact: its conversations, orders, bookings, leads and channel identities move here, empty fields are filled from it, tags are joined, then it is deleted.","operationId":"mergeContacts","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The contact's id.","title":"Contact Id"},"description":"The contact's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactMerge"},"example":{"duplicate_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"contacts:write","x-ordstage-webhooks":"contact.merged","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["not_found","validation_error"]}},"/v1/leads":{"get":{"tags":["Leads"],"summary":"List leads","description":"Leads oldest first. Filter by status.","operationId":"listLeads","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["new","contacted","qualified","won","lost"],"type":"string"},{"type":"null"}],"description":"Only leads with this status.","title":"Status"},"description":"Only leads with this status."},{"name":"contact_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only leads about this contact.","title":"Contact Id"},"description":"Only leads about this contact."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many objects to return (1–100).","default":20,"title":"Limit"},"description":"How many objects to return (1–100)."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"The `next_cursor` of the previous page.","title":"Starting After"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as starting_after for the next page."}}},"example":{"object":"list","data":[{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"new","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":null}],"has_more":false,"next_cursor":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"invalid_cursor":{"value":{"error":{"type":"invalid_request","code":"invalid_cursor","message":"starting_after must be the id of an object from this list.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"leads:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["module_not_active","invalid_cursor","validation_error"]},"post":{"tags":["Leads"],"summary":"Create a lead","description":"Add someone who wants to be contacted: a name, what they need, and an email or phone.","operationId":"createLead","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadCreate"},"example":{"name":"Karim Said","need":"A price list for a group of 20","email":"karim@example.com","preferred_contact":"email"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"new","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":null,"assistant_id":null,"channel":"api","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url, idempotency_key_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_key_required":{"value":{"error":{"type":"invalid_request","code":"idempotency_key_required","message":"Send an Idempotency-Key header with this request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"409":{"description":"Conflict: idempotency_conflict, idempotency_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":{"type":"conflict","code":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"idempotency_in_progress":{"value":{"error":{"type":"conflict","code":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"leads:write","x-ordstage-webhooks":"lead.created","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["module_not_active","not_found","validation_error"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/leads/{lead_id}":{"get":{"tags":["Leads"],"summary":"Get a lead","description":"One lead, with its status and the team's note.","operationId":"getLead","parameters":[{"name":"lead_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The lead's id.","title":"Lead Id"},"description":"The lead's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"new","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":null}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"leads:read","x-ordstage-webhooks":"none","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["module_not_active","not_found"]},"patch":{"tags":["Leads"],"summary":"Update a lead","description":"Change its status (any status can follow any other; the first `contacted` sets contacted_at), the team's note, who follows up, or its details. Only the fields sent change.","operationId":"updateLead","parameters":[{"name":"lead_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The lead's id.","title":"Lead Id"},"description":"The lead's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadUpdate"},"example":{"status":"contacted","note":"Called, sending the list"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"contacted","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":"2026-10-29T12:30:00+00:00"}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Entity: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"leads:write","x-ordstage-webhooks":"lead.updated, lead.status_changed","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["module_not_active","not_found","validation_error"]},"delete":{"tags":["Leads"],"summary":"Delete a lead","description":"Delete a lead. Its conversation and contact stay.","operationId":"deleteLead","parameters":[{"name":"lead_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The lead's id.","title":"Lead Id"},"description":"The lead's id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"},"example":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","deleted":true}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized: invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":{"type":"authentication","code":"invalid_api_key","message":"Use a valid workspace API key: Authorization: Bearer ord_…","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Bad Request: api_key_in_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_key_in_url":{"value":{"error":{"type":"invalid_request","code":"api_key_in_url","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"403":{"description":"Forbidden: api_access_not_allowed, insufficient_scope, module_not_active, plan_upgrade_required, sandbox_not_available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sandbox_not_available":{"value":{"error":{"type":"permission","code":"sandbox_not_available","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"insufficient_scope":{"value":{"error":{"type":"permission","code":"insufficient_scope","message":"This key doesn't have the scope this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"api_access_not_allowed":{"value":{"error":{"type":"permission","code":"api_access_not_allowed","message":"API access for this request isn't included for this business.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"plan_upgrade_required":{"value":{"error":{"type":"permission","code":"plan_upgrade_required","message":"The API is included on Growth plans and up.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"module_not_active":{"value":{"error":{"type":"permission","code":"module_not_active","message":"This business doesn't have the module this request needs.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Too Many Requests: rate_limited, too_many_invalid_keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"type":"rate_limit","code":"rate_limited","message":"Too many requests for this key. Wait and try again.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}},"too_many_invalid_keys":{"value":{"error":{"type":"rate_limit","code":"too_many_invalid_keys","message":"Too many requests with invalid keys from this address. Try again in 15 minutes.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service Unavailable: rate_limiter_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limiter_unavailable":{"value":{"error":{"type":"api_error","code":"rate_limiter_unavailable","message":"The API is briefly unavailable. Try again shortly.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Internal Server Error: api_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"api_error":{"value":{"error":{"type":"api_error","code":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"404":{"description":"Not Found: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"type":"not_found","code":"not_found","message":"Not found.","param":null,"request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}},"422":{"description":"Unprocessable Content: validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"value":{"error":{"type":"invalid_request","code":"validation_error","message":"Field required","param":"start","request_id":"req_4f2a9c0d1e7b3a5c6d8e9f01"}}}}}},"headers":{"Request-Id":{"$ref":"#/components/headers/RequestId"}}}},"x-ordstage-scope":"leads:write","x-ordstage-webhooks":"lead.deleted","x-ordstage-sandbox":"Same with test keys, on the sandbox's own data (never the live business's).","x-ordstage-errors":["module_not_active","not_found"]}}},"components":{"schemas":{"BlockUpsert":{"properties":{"resource":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Resource","description":"Empty with scope=online: the whole calendar"},"starts_at":{"type":"string","maxLength":40,"title":"Starts At","description":"Local time, like 2026-12-31T00:00"},"ends_at":{"type":"string","maxLength":40,"title":"Ends At","description":"Local time, after starts_at"},"units":{"anyOf":[{"type":"integer","maximum":2000.0,"minimum":1.0},{"type":"null"}],"title":"Units","description":"Places closed (rooms, seats)"},"reason":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Reason","description":"Shown to the team"},"scope":{"type":"string","enum":["all","online"],"title":"Scope","description":"all: closed for everyone; online: only online booking stops","default":"all"}},"type":"object","required":["starts_at","ends_at"],"title":"BlockUpsert"},"BookingUpsert":{"properties":{"resource":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Resource","description":"Resource id, its name, or your own reference mapped in Ordstage"},"service":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Service","description":"Service id or name"},"start":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Start","description":"Local time, like 2026-10-20T10:00"},"end":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"End","description":"Local time, after start"},"check_in":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Check In","description":"Stays: check-in day, YYYY-MM-DD"},"nights":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Nights","description":"Stays: number of nights"},"units":{"anyOf":[{"type":"integer","maximum":2000.0,"minimum":1.0},{"type":"null"}],"title":"Units","description":"Rooms or seats taken; defaults from the party size"},"party_size":{"anyOf":[{"type":"integer","maximum":2000.0,"minimum":1.0},{"type":"null"}],"title":"Party Size","description":"Guests"},"status":{"type":"string","enum":["confirmed","cancelled"],"title":"Status","description":"Send cancelled to cancel it","default":"confirmed"},"customer_name":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Customer Name","description":"Shown to the team"},"customer_phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Customer Phone","description":"International format, like +201001234567"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes","description":"Notes for the team"}},"type":"object","title":"BookingUpsert"},"BusinessUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name","description":"The business's name"},"website":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Website","description":"Its website; empty to remove"},"remove_logo":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove Logo","description":"true removes the logo"},"timezone":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Timezone","description":"IANA timezone, like Africa/Cairo"},"language":{"anyOf":[{"type":"string","maxLength":8},{"type":"null"}],"title":"Language","description":"en or ar"},"brand_color":{"anyOf":[{"type":"string","maxLength":7},{"type":"null"}],"title":"Brand Color","description":"Like #315CFF; empty to clear"},"accent_color":{"anyOf":[{"type":"string","maxLength":7},{"type":"null"}],"title":"Accent Color","description":"Like #0F172A; empty to clear"}},"additionalProperties":false,"type":"object","title":"BusinessUpdate"},"ContactCreate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name","description":"Their name"},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email","description":"Email address"},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Phone","description":"Phone number, ideally with the country code"},"locale":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Locale","description":"Language, like ar or en"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tags","description":"Tags"},"attributes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Attributes","description":"Your own fields; null removes a key"}},"additionalProperties":false,"type":"object","title":"ContactCreate"},"ContactMerge":{"properties":{"duplicate_id":{"type":"string","format":"uuid","title":"Duplicate Id","description":"The contact merged into this one, then removed"}},"additionalProperties":false,"type":"object","required":["duplicate_id"],"title":"ContactMerge"},"ContactTags":{"properties":{"add":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Add","description":"Tags to add"},"remove":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Remove","description":"Tags to remove"}},"additionalProperties":false,"type":"object","title":"ContactTags"},"ContactUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name","description":"Their name"},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email","description":"Email address"},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Phone","description":"Phone number, ideally with the country code"},"locale":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Locale","description":"Language, like ar or en"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tags","description":"Tags"},"attributes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Attributes","description":"Your own fields; null removes a key"}},"additionalProperties":false,"type":"object","title":"ContactUpdate"},"ConversationUpdate":{"properties":{"priority":{"anyOf":[{"type":"string","enum":["low","normal","high","urgent"]},{"type":"null"}],"title":"Priority","description":"Priority"},"assigned_member_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Assigned Member Id","description":"A teammate, or null to unassign"},"team_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Team Id","description":"An Inbox team, or null for none"},"status":{"anyOf":[{"type":"string","enum":["open","pending"]},{"type":"null"}],"title":"Status","description":"open or pending (waiting for the customer); use close and reopen for the rest"}},"additionalProperties":false,"type":"object","title":"ConversationUpdate"},"Handover":{"properties":{"assigned_member_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Assigned Member Id","description":"A teammate to take it"},"team_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Team Id","description":"An Inbox team to take it"}},"additionalProperties":false,"type":"object","title":"Handover"},"InvitationCreate":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Where the invitation goes"},"role":{"type":"string","enum":["owner","admin","manager","member"],"title":"Role","description":"owner, admin, manager or member"},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name","description":"Their name, shown in the invitation"}},"additionalProperties":false,"type":"object","required":["email","role"],"title":"InvitationCreate"},"LabelAdd":{"properties":{"label_id":{"type":"string","format":"uuid","title":"Label Id","description":"One of the business's labels (GET /v1/labels)"}},"additionalProperties":false,"type":"object","required":["label_id"],"title":"LabelAdd"},"LeadCreate":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name","description":"Their name"},"need":{"type":"string","maxLength":5000,"minLength":1,"title":"Need","description":"What they need"},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email","description":"Email (an email or a phone is required)"},"phone":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Phone","description":"Phone (an email or a phone is required)"},"preferred_contact":{"anyOf":[{"type":"string","enum":["email","phone","whatsapp","any"]},{"type":"null"}],"title":"Preferred Contact","description":"email, phone, whatsapp or any"},"status":{"anyOf":[{"type":"string","enum":["new","contacted","qualified","won","lost"]},{"type":"null"}],"title":"Status","description":"Default new"},"note":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Note","description":"The team's note"},"assigned_member_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Assigned Member Id","description":"The member following up"},"contact_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contact Id","description":"The contact this lead is about"}},"additionalProperties":false,"type":"object","required":["name","need"],"title":"LeadCreate"},"LeadUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Name","description":"Their name"},"need":{"anyOf":[{"type":"string","maxLength":5000,"minLength":1},{"type":"null"}],"title":"Need","description":"What they need"},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email","description":"Email"},"phone":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Phone","description":"Phone"},"preferred_contact":{"anyOf":[{"type":"string","enum":["email","phone","whatsapp","any"]},{"type":"null"}],"title":"Preferred Contact","description":"email, phone, whatsapp or any"},"status":{"anyOf":[{"type":"string","enum":["new","contacted","qualified","won","lost"]},{"type":"null"}],"title":"Status","description":"new, contacted, qualified, won or lost"},"note":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Note","description":"The team's note; null clears it"},"assigned_member_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Assigned Member Id","description":"The member following up; null unassigns"},"contact_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contact Id","description":"The contact this lead is about; null unlinks"}},"additionalProperties":false,"type":"object","title":"LeadUpdate"},"MemberUpdate":{"properties":{"role":{"type":"string","enum":["owner","admin","manager","member"],"title":"Role","description":"owner, admin, manager or member"}},"additionalProperties":false,"type":"object","required":["role"],"title":"MemberUpdate"},"Reply":{"properties":{"content":{"type":"string","maxLength":20000,"minLength":1,"title":"Content","description":"The reply's text"}},"additionalProperties":false,"type":"object","required":["content"],"title":"Reply"},"SourceCreate":{"properties":{"url":{"type":"string","maxLength":2048,"minLength":8,"title":"Url","description":"A public web page"},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name","description":"What to call it (the address if empty)"}},"additionalProperties":false,"type":"object","required":["url"],"title":"SourceCreate"},"TestMessage":{"properties":{"message":{"type":"string","maxLength":8000,"minLength":1,"title":"Message","description":"What the customer says"},"session_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Session Id","description":"Continue this test conversation (from the previous answer)"}},"additionalProperties":false,"type":"object","required":["message"],"title":"TestMessage"},"WebhookCreate":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name","description":"A name for the team"},"url":{"type":"string","maxLength":2000,"minLength":8,"title":"Url","description":"A public https:// address"},"events":{"items":{"type":"string"},"type":"array","maxItems":28,"title":"Events","description":"Events to send; empty for every event"},"calendar_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100},{"type":"null"}],"title":"Calendar Ids","description":"Booking events only from these calendars"}},"additionalProperties":false,"type":"object","required":["name","url"],"title":"WebhookCreate"},"WebhookUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Name","description":"A name for the team"},"url":{"anyOf":[{"type":"string","maxLength":2000,"minLength":8},{"type":"null"}],"title":"Url","description":"A public https:// address"},"events":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":28},{"type":"null"}],"title":"Events","description":"Events to send; empty for every event"},"calendar_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100},{"type":"null"}],"title":"Calendar Ids","description":"Booking events only from these calendars"}},"additionalProperties":false,"type":"object","title":"WebhookUpdate"},"Error":{"type":"object","required":["error"],"description":"Every /v1 error has this shape. Branch on `type` and `code`, never on `message`.","properties":{"error":{"type":"object","required":["type","code","message","request_id"],"properties":{"type":{"type":"string","enum":["invalid_request","authentication","permission","not_found","conflict","rate_limit","api_error"]},"code":{"type":"string","description":"Stable machine-readable reason (see x-ordstage-error-codes)."},"message":{"type":"string","description":"A plain explanation for the developer."},"param":{"type":["string","null"],"description":"The parameter or header the error is about."},"request_id":{"type":["string","null"],"description":"Quote it to support."}}}}},"WebhookEvent":{"type":"object","required":["id","event","created_at","data"],"description":"Every webhook body: the event, when it happened and its data.","properties":{"id":{"type":"string","format":"uuid","description":"The delivery id (same as X-Ordstage-Delivery)."},"event":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}},"Booking":{"type":"object","description":"A booking from any source: the assistant, the team, another system or this API.","required":["id","reference","calendar_id","status","resource","starts_at","ends_at","source"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string","description":"The short reference customers and the team see."},"calendar_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"For example confirmed, pending_approval, cancelled, completed, no_show."},"resource":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]}}},"service":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]}}},{"type":"null"}]},"starts_at":{"type":"string","format":"date-time","description":"Local time with the calendar's offset."},"ends_at":{"type":"string","format":"date-time"},"units":{"type":["integer","null"],"description":"Rooms or seats taken."},"party_size":{"type":["integer","null"]},"customer_name":{"type":["string","null"]},"customer_phone":{"type":["string","null"]},"notes":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true},"source":{"type":"string","description":"assistant, team, api, ical, or another connected system."},"source_name":{"type":["string","null"]},"external_id":{"type":["string","null"],"description":"Your own id, for bookings you sent."},"updated_at":{"type":["string","null"],"format":"date-time","description":"API answers only."},"api_key_id":{"type":["string","null"],"description":"Webhooks only: the key that sent the booking, if one did."}}},"Calendar":{"type":"object","required":["id","name","industry","timezone","is_active","resources","services"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"industry":{"type":"string","description":"clinic, hotel, restaurant, salon or services."},"timezone":{"type":"string","description":"IANA name, like Africa/Cairo."},"is_active":{"type":"boolean"},"rules":{"type":"object","additionalProperties":true,"description":"The calendar's booking rules."},"resources":{"type":"array","items":{"type":"object","required":["id","name","kind"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string"},"capacity":{"type":["integer","null"]},"attributes":{"type":"object","additionalProperties":true}}}},"services":{"type":"array","items":{"type":"object","required":["id","name","kind"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string"},"duration_minutes":{"type":["integer","null"]},"price":{"type":["number","null"]},"currency":{"type":["string","null"]}}}}}},"Availability":{"type":"object","required":["options"],"additionalProperties":true,"properties":{"service":{"type":"string"},"timezone":{"type":"string"},"today":{"type":"string"},"options":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Free times (`start`, `end`, `resource`), or room types with `rooms_left` for stays."},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":["string","null"]}}},"requested":{"type":"string"},"requested_is_free":{"type":"boolean"},"online_closed":{"type":"boolean"}}},"BookingWrite":{"type":"object","required":["booking","overbooked"],"properties":{"booking":{"anyOf":[{"$ref":"#/components/schemas/Booking"},{"type":"null"}]},"overbooked":{"type":"boolean"},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"over_by":{"type":"integer"}}}}}},"BookingConflict":{"type":"object","required":["id","resource","over_by","starts_at","ends_at","bookings"],"properties":{"id":{"type":"string","format":"uuid"},"resource":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]}}},"over_by":{"type":"integer","description":"Places over capacity."},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"bookings":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}}}},"Deleted":{"type":"object","required":["id","object","deleted"],"description":"The answer to a delete.","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string"},"deleted":{"type":"boolean","const":true}}},"Assistant":{"type":"object","description":"An assistant that answers the business's customers.","required":["id","object","created_at","livemode","name","build_approach","status","revision"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"assistant"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"description":{"type":["string","null"]},"build_approach":{"type":"string","enum":["ai","flow"],"description":"ai: answers with AI; flow: follows a conversation flow."},"status":{"type":"string","enum":["active","paused"],"description":"active: answering customers."},"revision":{"type":"integer","description":"Goes up with every saved change to its setup."},"release_id":{"type":["string","null"],"format":"uuid","description":"The published release customers get (AI assistants)."},"updated_at":{"type":["string","null"],"format":"date-time"},"lifecycle":{"type":"object","description":"Only when getting one assistant.","properties":{"publication":{"type":"string","enum":["never_published","current","changes_pending","requires_republication"]},"health":{"type":"string","enum":["healthy","warning","blocked"]},"display":{"type":"string","description":"What Studio shows: draft, ready_to_publish, live, paused, unpublished_changes or needs_attention."}}}}},"KnowledgeSource":{"type":"object","description":"Something an assistant learns from.","required":["id","object","created_at","livemode","name","type","status"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"knowledge_source"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"assistant_id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string"},"type":{"type":"string","description":"web_page for pages added here; Studio adds files, sheets and others."},"url":{"type":["string","null"]},"status":{"type":"string","enum":["pending","processing","ready","error"]},"chunks":{"type":"integer","description":"Passages it was split into."},"last_synced_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"AssistantPublication":{"type":"object","required":["object","assistant","publication"],"description":"A publish's result.","properties":{"object":{"type":"string","const":"assistant_publication"},"assistant":{"$ref":"#/components/schemas/Assistant"},"publication":{"type":"object","additionalProperties":true,"description":"The release or flow version that went live."}}},"AssistantTestMessage":{"type":"object","required":["object","livemode","assistant_id","session_id","turn","message","reply"],"description":"One test turn in the sandbox.","properties":{"object":{"type":"string","const":"assistant_test_message"},"livemode":{"type":"boolean","const":false},"assistant_id":{"type":"string","format":"uuid"},"session_id":{"type":"string","format":"uuid","description":"Pass it with the next message to continue the conversation."},"turn":{"type":"integer"},"message":{"type":"string"},"reply":{"type":"string"}}},"Business":{"type":"object","description":"The business's profile and branding.","required":["id","object","created_at","livemode","name","language"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"business"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"website":{"type":["string","null"]},"logo_url":{"type":["string","null"],"description":"Found by previewing the website in Settings; the API can remove it, not set it."},"brand_color":{"type":["string","null"],"description":"Like #315CFF."},"accent_color":{"type":["string","null"]},"timezone":{"type":["string","null"],"description":"IANA name, like Africa/Cairo."},"language":{"type":"string","enum":["en","ar"]}}},"Contact":{"type":"object","description":"Someone the business talks to.","required":["id","object","created_at","livemode","name","email","phone","tags","attributes"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"contact"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"locale":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","additionalProperties":true,"description":"Your own fields (up to 50 keys, 8 KB)."},"first_seen_at":{"type":["string","null"],"format":"date-time"},"last_seen_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"Lead":{"type":"object","description":"Someone who asked to be contacted.","required":["id","object","created_at","livemode","name","need","preferred_contact","status"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"lead"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"need":{"type":"string"},"preferred_contact":{"type":"string","enum":["email","phone","whatsapp","any"]},"status":{"type":"string","enum":["new","contacted","qualified","won","lost"]},"note":{"type":["string","null"]},"assigned_member_id":{"type":["string","null"],"format":"uuid"},"contact_id":{"type":["string","null"],"format":"uuid"},"conversation_id":{"type":["string","null"],"format":"uuid"},"assistant_id":{"type":["string","null"],"format":"uuid"},"channel":{"type":["string","null"],"description":"Where it came from: whatsapp, webwidget, … or api."},"updated_at":{"type":["string","null"],"format":"date-time"},"contacted_at":{"type":["string","null"],"format":"date-time"}}},"Conversation":{"type":"object","description":"A conversation with a customer on one channel.","required":["id","object","created_at","livemode","channel","status","handled_by","automation_mode","priority","labels"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"conversation"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"channel":{"type":"object","required":["id","type","name"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":["string","null"]},"name":{"type":["string","null"]}}},"assistant_id":{"type":["string","null"],"format":"uuid"},"contact_id":{"type":["string","null"],"format":"uuid"},"contact_name":{"type":["string","null"]},"subject":{"type":["string","null"]},"status":{"type":"string","enum":["open","pending","resolved","closed"],"description":"pending: waiting for the customer; resolved or closed: done."},"handled_by":{"type":"string","enum":["assistant","team"]},"automation_mode":{"type":"string","enum":["autopilot","copilot","human"],"description":"autopilot: the assistant answers; copilot: it suggests replies; human: the team answers."},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"assigned_member_id":{"type":["string","null"],"format":"uuid"},"team_id":{"type":["string","null"],"format":"uuid"},"language":{"type":["string","null"]},"labels":{"type":"array","items":{"$ref":"#/components/schemas/LabelRef"}},"first_message_at":{"type":["string","null"],"format":"date-time"},"last_message_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"Message":{"type":"object","description":"A message in a conversation. Internal notes are never included.","required":["id","object","created_at","livemode","conversation_id","direction","author","type","content"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"message"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"conversation_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["incoming","outgoing"]},"author":{"type":"string","enum":["customer","assistant","team","campaign","system"]},"type":{"type":"string","description":"text, image, audio, video, file, …"},"content":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","additionalProperties":true}},"delivery_status":{"type":"string"},"sent_at":{"type":["string","null"],"format":"date-time"}}},"LabelRef":{"type":"object","required":["id","name","color"],"description":"A label on a conversation.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":"string"}}},"Label":{"type":"object","description":"One of the business's Inbox labels.","required":["id","object","created_at","livemode","name","color"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"label"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"color":{"type":"string"}}},"Member":{"type":"object","description":"Someone on the business's team.","required":["id","object","created_at","livemode","email","name","role","active"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"member"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","manager","member"]},"active":{"type":"boolean","description":"false when their account is turned off."},"email_verified":{"type":"boolean"},"teams":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}},"Invitation":{"type":"object","description":"An email invitation to join the team. Its link only ever goes to the invited address.","required":["id","object","created_at","livemode","email","role","status"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"invitation"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","enum":["owner","admin","manager","member"]},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"expires_at":{"type":["string","null"],"format":"date-time"},"accepted_at":{"type":["string","null"],"format":"date-time"},"delivery_status":{"type":"string","description":"accepted_by_provider, failed, not_configured, not_sent or unknown."},"last_sent_at":{"type":["string","null"],"format":"date-time"}}},"PasswordReset":{"type":"object","required":["object","member_id","sent_to","status"],"description":"A reset email sent to a member.","properties":{"object":{"type":"string","const":"password_reset"},"member_id":{"type":"string","format":"uuid"},"sent_to":{"type":"string"},"status":{"type":"string","enum":["sent","failed","not_configured"]},"expires_at":{"type":["string","null"],"format":"date-time"}}},"Webhook":{"type":"object","description":"A webhook endpoint.","required":["id","object","created_at","livemode","name","url","events","status"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"webhook"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"},"description":"Empty: every event, including ones added later."},"calendar_ids":{"type":["array","null"],"items":{"type":"string"},"description":"Booking events only from these calendars."},"status":{"type":"string","enum":["active","paused"]},"paused_reason":{"type":["string","null"]},"failures":{"type":"integer","description":"Failed deliveries in a row; 50 pause the webhook."},"last_delivery_at":{"type":["string","null"],"format":"date-time"}}},"WebhookWithSecret":{"type":"object","description":"A webhook endpoint with its signing secret, shown only now.","required":["id","object","created_at","livemode","name","url","events","status","secret"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"webhook"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"},"description":"Empty: every event, including ones added later."},"calendar_ids":{"type":["array","null"],"items":{"type":"string"},"description":"Booking events only from these calendars."},"status":{"type":"string","enum":["active","paused"]},"paused_reason":{"type":["string","null"]},"failures":{"type":"integer","description":"Failed deliveries in a row; 50 pause the webhook."},"last_delivery_at":{"type":["string","null"],"format":"date-time"},"secret":{"type":["string","null"],"description":"whsec_…: keep it safe; it is never shown again (null in a replayed Idempotency-Key answer)."}}},"WebhookDelivery":{"type":"object","description":"One event sent (or being sent) to a webhook.","required":["id","object","created_at","livemode","webhook_id","event","status","attempts"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"webhook_delivery"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"webhook_id":{"type":"string","format":"uuid"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"last_status_code":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"}}},"WebhookTest":{"type":"object","required":["object","ok","status_code","error","delivery_id"],"properties":{"object":{"type":"string","const":"webhook_test"},"ok":{"type":"boolean"},"status_code":{"type":["integer","null"]},"error":{"type":["string","null"]},"delivery_id":{"type":"string","format":"uuid"}}},"ApiKey":{"type":"object","description":"A key for the business's own systems. Never its secret.","required":["id","object","created_at","livemode","name","prefix","environment","scopes","status"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"api_key"},"created_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean","description":"false for the sandbox (test keys)."},"name":{"type":"string"},"description":{"type":["string","null"]},"prefix":{"type":"string","description":"Like ord_live_1a2b3c4d5e6f_…"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","expiring","expired","revoked"]},"expires_at":{"type":["string","null"],"format":"date-time"},"ip_allowlist":{"type":"array","items":{"type":"string"}},"last_used_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"}}}},"headers":{"RequestId":{"description":"Unique id of this request; quote it to support. Send `X-Request-Id` to choose your own.","schema":{"type":"string"},"example":"req_4f2a9c0d1e7b3a5c6d8e9f01"},"RateLimitLimit":{"description":"Requests this key may make per minute.","schema":{"type":"integer"},"example":300},"RateLimitRemaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"},"example":299},"RateLimitReset":{"description":"Unix time (seconds) when a request is next freed.","schema":{"type":"integer"},"example":1793260860},"RetryAfter":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"},"example":30},"IdempotentReplayed":{"description":"`true` when this is the stored answer to an earlier request with the same Idempotency-Key.","schema":{"type":"string","enum":["true"]}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"A unique value you choose per operation (a UUID works). Retrying with the same key and body within 24 hours returns the first answer instead of doing it twice.","example":"order-1042-create"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ord_live_<prefix>_<secret> or ord_test_<prefix>_<secret>","description":"A workspace API key: `Authorization: Bearer <key>`. Create keys in Settings → Developers."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"The same key in the X-Api-Key header, for tools that can't set Authorization."}}},"tags":[{"name":"Bookings","description":"Calendars, availability, bookings and closures. A calendar is a clinic's doctors, a hotel's room types or a restaurant's tables; push bookings made in your own system under your own ids and read every booking from every source."},{"name":"Assistants","description":"The business's assistants: publish the current setup, pause and resume them, send test messages, and manage the web pages they learn from. Building an assistant (its behaviour, flows and channels) stays in Studio."},{"name":"Business","description":"The business itself: its name, website, logo, brand colours, timezone and language, as customers see them."},{"name":"Contacts","description":"The people the business talks to on any channel, with their details, tags and your own attributes. Conversations, orders, bookings and leads point at them."},{"name":"Leads","description":"People who asked to be contacted (usually through the assistant), with what they need and where the team is with them."},{"name":"Conversations","description":"Customer conversations on every channel (WhatsApp, Instagram, website chat, email, …): read them, reply, hand them to the team or back to the assistant, close and reopen them, and label them."},{"name":"Members","description":"The people who work in the business and the invitations sent to new ones. Changes are made as the person who created the key, who must still be an owner or admin. Passwords are never exposed: a reset is only ever emailed."},{"name":"Webhook endpoints","description":"Where Ordstage sends events. Each webhook has its own signing secret, shown once when it is created or rotated; verify every delivery with it."},{"name":"API keys","description":"The business's API keys, read only: names, scopes, status and last use. Keys are created, rotated and revoked only in Settings → Developers, and a key's secret is never shown again."},{"name":"Webhooks","description":"Events Ordstage sends to your webhook endpoints, signed with the subscription secret. Verify every delivery: see https://docs.ordstage.com/webhooks/."}],"externalDocs":{"description":"Guides and quickstart","url":"https://docs.ordstage.com"},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"webhooks":{"booking.created":{"post":{"operationId":"webhook_booking_created","summary":"A booking was made","description":"Sent when a booking is made from any source (the assistant, the team, another system).","tags":["Bookings"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"booking.created"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"booking.created"},"data":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#/components/schemas/Booking"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"booking.created","created_at":"2026-10-29T10:00:00+00:00","data":{"booking":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"confirmed","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","api_key_id":null}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"booking.confirmed":{"post":{"operationId":"webhook_booking_confirmed","summary":"A booking was approved","description":"Sent when the team approves a booking that waited for approval.","tags":["Bookings"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"booking.confirmed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"booking.confirmed"},"data":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#/components/schemas/Booking"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"booking.confirmed","created_at":"2026-10-29T10:00:00+00:00","data":{"booking":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"confirmed","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","api_key_id":null}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"booking.updated":{"post":{"operationId":"webhook_booking_updated","summary":"A booking changed","description":"Sent when a booking's time, resource, details or status changes.","tags":["Bookings"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"booking.updated"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"booking.updated"},"data":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#/components/schemas/Booking"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"booking.updated","created_at":"2026-10-29T10:00:00+00:00","data":{"booking":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"confirmed","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","api_key_id":null}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"booking.cancelled":{"post":{"operationId":"webhook_booking_cancelled","summary":"A booking was cancelled","description":"Sent when a booking is cancelled, by the customer, the team or a system.","tags":["Bookings"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"booking.cancelled"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"booking.cancelled"},"data":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#/components/schemas/Booking"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"booking.cancelled","created_at":"2026-10-29T10:00:00+00:00","data":{"booking":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"cancelled","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","api_key_id":null}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"booking.conflict":{"post":{"operationId":"webhook_booking_conflict","summary":"A time is overbooked","description":"Sent when bookings from different sources overlap beyond a resource's capacity (for example a booking you pushed for a time that was already full). The team is alerted too.","tags":["Bookings"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"booking.conflict"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"booking.conflict"},"data":{"type":"object","required":["alert"],"properties":{"alert":{"$ref":"#/components/schemas/BookingConflict"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"booking.conflict","created_at":"2026-10-29T10:00:00+00:00","data":{"alert":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"over_by":1,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","bookings":[{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","reference":"BK-7Q2M","calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","status":"confirmed","resource":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","name":"Dr. Sara Adel"},"service":null,"starts_at":"2026-11-02T09:00:00+02:00","ends_at":"2026-11-02T09:20:00+02:00","units":1,"party_size":null,"customer_name":"Mona","customer_phone":null,"notes":null,"details":{},"source":"api","source_name":"Clinic system","external_id":"his-1","api_key_id":null}]}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"availability.closed":{"post":{"operationId":"webhook_availability_closed","summary":"Online booking was closed","description":"Sent when time is closed for online booking across a calendar (`scope: online`).","tags":["Bookings"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"availability.closed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"availability.closed"},"data":{"type":"object","required":["calendar_id","resources","starts_at","ends_at"],"properties":{"calendar_id":{"type":"string","format":"uuid"},"resources":{"type":"array","items":{"type":"string","format":"uuid"}},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]},"source":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"availability.closed","created_at":"2026-10-29T10:00:00+00:00","data":{"calendar_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","resources":["6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"],"starts_at":"2026-12-31T00:00:00+02:00","ends_at":"2026-12-31T23:59:00+02:00","reason":"Private event","source":"api"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"assistant.published":{"post":{"operationId":"webhook_assistant_published","summary":"An assistant was published","description":"Sent when an assistant's setup is published (from Studio or the API) and it starts answering with it.","tags":["Assistants"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"assistant.published"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"assistant.published"},"data":{"type":"object","required":["assistant","publication"],"properties":{"assistant":{"$ref":"#/components/schemas/Assistant"},"publication":{"type":"object","additionalProperties":true}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"assistant.published","created_at":"2026-10-29T10:00:00+00:00","data":{"assistant":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"active","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"},"publication":{"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","version":4}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"assistant.paused":{"post":{"operationId":"webhook_assistant_paused","summary":"An assistant was paused","description":"Sent when an assistant stops answering customers; conversations go to the team.","tags":["Assistants"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"assistant.paused"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"assistant.paused"},"data":{"type":"object","required":["assistant"],"properties":{"assistant":{"$ref":"#/components/schemas/Assistant"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"assistant.paused","created_at":"2026-10-29T10:00:00+00:00","data":{"assistant":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"paused","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"assistant.resumed":{"post":{"operationId":"webhook_assistant_resumed","summary":"An assistant was resumed","description":"Sent when a paused assistant answers customers again.","tags":["Assistants"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"assistant.resumed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"assistant.resumed"},"data":{"type":"object","required":["assistant"],"properties":{"assistant":{"$ref":"#/components/schemas/Assistant"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"assistant.resumed","created_at":"2026-10-29T10:00:00+00:00","data":{"assistant":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"assistant","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic assistant","description":"Answers patients on WhatsApp","build_approach":"ai","status":"active","revision":12,"release_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","updated_at":"2026-10-29T12:30:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"business.updated":{"post":{"operationId":"webhook_business_updated","summary":"The business profile changed","description":"Sent when the business's name, website, logo, colours, timezone or language change, from Settings or the API.","tags":["Business"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"business.updated"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"business.updated"},"data":{"type":"object","required":["business","changed"],"properties":{"business":{"$ref":"#/components/schemas/Business"},"changed":{"type":"array","items":{"type":"string"}}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"business.updated","created_at":"2026-10-29T10:00:00+00:00","data":{"business":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"business","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Nile Clinic","website":"https://nileclinic.example","logo_url":null,"brand_color":"#315CFF","accent_color":null,"timezone":"Africa/Cairo","language":"en"},"changed":["name"]}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"contact.created":{"post":{"operationId":"webhook_contact_created","summary":"A contact was created","description":"Sent when a contact is created anywhere: a new person messages the business, an order or booking is made, or the API.","tags":["Contacts"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"contact.created"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"contact.created"},"data":{"type":"object","required":["contact"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"contact.created","created_at":"2026-10-29T10:00:00+00:00","data":{"contact":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"contact.updated":{"post":{"operationId":"webhook_contact_updated","summary":"A contact changed","description":"Sent when a contact's details, tags or attributes change.","tags":["Contacts"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"contact.updated"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"contact.updated"},"data":{"type":"object","required":["contact","changed"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"},"changed":{"type":"array","items":{"type":"string"},"description":"The fields that changed."}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"contact.updated","created_at":"2026-10-29T10:00:00+00:00","data":{"contact":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"},"changed":["tags"]}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"contact.deleted":{"post":{"operationId":"webhook_contact_deleted","summary":"A contact was deleted","description":"Sent when a contact is deleted; `contact` is how it was.","tags":["Contacts"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"contact.deleted"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"contact.deleted"},"data":{"type":"object","required":["contact"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"contact.deleted","created_at":"2026-10-29T10:00:00+00:00","data":{"contact":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"contact.merged":{"post":{"operationId":"webhook_contact_merged","summary":"Two contacts were merged","description":"Sent when a duplicate is merged into a contact: `contact` is the one kept, `merged_contact_id` the one removed.","tags":["Contacts"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"contact.merged"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"contact.merged"},"data":{"type":"object","required":["contact","merged_contact_id"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"},"merged_contact_id":{"type":"string","format":"uuid"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"contact.merged","created_at":"2026-10-29T10:00:00+00:00","data":{"contact":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"contact","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Mona Adel","email":"mona@example.com","phone":"+201001234567","locale":"ar","tags":["vip"],"attributes":{"his_patient_id":"P-1042"},"first_seen_at":"2026-10-29T10:00:00+00:00","last_seen_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"},"merged_contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"lead.created":{"post":{"operationId":"webhook_lead_created","summary":"A lead was created","description":"Sent when someone asks to be contacted (through the assistant) or a lead is added through the API.","tags":["Leads"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"lead.created"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"lead.created"},"data":{"type":"object","required":["lead"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"lead.created","created_at":"2026-10-29T10:00:00+00:00","data":{"lead":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"new","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":null}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"lead.updated":{"post":{"operationId":"webhook_lead_updated","summary":"A lead changed","description":"Sent when a lead's details, note, assignee or status change.","tags":["Leads"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"lead.updated"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"lead.updated"},"data":{"type":"object","required":["lead","changed"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"changed":{"type":"array","items":{"type":"string"},"description":"The fields that changed."}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"lead.updated","created_at":"2026-10-29T10:00:00+00:00","data":{"lead":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"new","note":"Called, sending the list","assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":null},"changed":["note"]}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"lead.status_changed":{"post":{"operationId":"webhook_lead_status_changed","summary":"A lead's status changed","description":"Sent when a lead moves to another status.","tags":["Leads"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"lead.status_changed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"lead.status_changed"},"data":{"type":"object","required":["lead","previous_status"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"previous_status":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"lead.status_changed","created_at":"2026-10-29T10:00:00+00:00","data":{"lead":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"contacted","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":"2026-10-29T12:30:00+00:00"},"previous_status":"new"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"lead.deleted":{"post":{"operationId":"webhook_lead_deleted","summary":"A lead was deleted","description":"Sent when a lead is deleted; `lead` is how it was.","tags":["Leads"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"lead.deleted"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"lead.deleted"},"data":{"type":"object","required":["lead"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"lead.deleted","created_at":"2026-10-29T10:00:00+00:00","data":{"lead":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"lead","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"name":"Karim Said","email":"karim@example.com","phone":null,"need":"A price list for a group of 20","preferred_contact":"email","status":"new","note":null,"assigned_member_id":null,"contact_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","conversation_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","assistant_id":null,"channel":"whatsapp","updated_at":"2026-10-29T10:00:00+00:00","contacted_at":null}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"conversation.handed_over":{"post":{"operationId":"webhook_conversation_handed_over","summary":"A conversation was handed to the team","description":"Sent when a conversation moves from the assistant to the team (the assistant, a teammate or the API handed it over).","tags":["Conversations"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"conversation.handed_over"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"conversation.handed_over"},"data":{"type":"object","required":["conversation","previous_mode"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"previous_mode":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"conversation.handed_over","created_at":"2026-10-29T10:00:00+00:00","data":{"conversation":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"team","automation_mode":"human","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"},"previous_mode":"autopilot"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"conversation.returned_to_assistant":{"post":{"operationId":"webhook_conversation_returned_to_assistant","summary":"A conversation went back to the assistant","description":"Sent when the team gives a conversation back to the assistant to answer.","tags":["Conversations"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"conversation.returned_to_assistant"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"conversation.returned_to_assistant"},"data":{"type":"object","required":["conversation","previous_mode"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"previous_mode":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"conversation.returned_to_assistant","created_at":"2026-10-29T10:00:00+00:00","data":{"conversation":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"},"previous_mode":"human"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"conversation.closed":{"post":{"operationId":"webhook_conversation_closed","summary":"A conversation was closed","description":"Sent when a conversation is resolved or closed, from the Inbox or the API.","tags":["Conversations"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"conversation.closed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"conversation.closed"},"data":{"type":"object","required":["conversation","previous_status"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"previous_status":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"conversation.closed","created_at":"2026-10-29T10:00:00+00:00","data":{"conversation":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"resolved","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":"2026-10-29T12:30:00+00:00","updated_at":"2026-10-29T12:30:00+00:00"},"previous_status":"open"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"conversation.reopened":{"post":{"operationId":"webhook_conversation_reopened","summary":"A conversation was reopened","description":"Sent when a resolved or closed conversation is opened again by the team or the API.","tags":["Conversations"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"conversation.reopened"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"conversation.reopened"},"data":{"type":"object","required":["conversation","previous_status"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"previous_status":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"conversation.reopened","created_at":"2026-10-29T10:00:00+00:00","data":{"conversation":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"},"previous_status":"resolved"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"conversation.updated":{"post":{"operationId":"webhook_conversation_updated","summary":"A conversation changed","description":"Sent when a conversation's priority, assignee, team, labels or waiting status change.","tags":["Conversations"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"conversation.updated"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"conversation.updated"},"data":{"type":"object","required":["conversation","changed"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"changed":{"type":"array","items":{"type":"string"}}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"conversation.updated","created_at":"2026-10-29T10:00:00+00:00","data":{"conversation":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"open","handled_by":"assistant","automation_mode":"autopilot","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"},"changed":["labels"]}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"conversation.reply_sent":{"post":{"operationId":"webhook_conversation_reply_sent","summary":"The team replied","description":"Sent when a teammate's reply is sent from the Inbox or the API (not the assistant's own answers).","tags":["Conversations"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"conversation.reply_sent"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"conversation.reply_sent"},"data":{"type":"object","required":["conversation","message"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"message":{"$ref":"#/components/schemas/Message"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"conversation.reply_sent","created_at":"2026-10-29T10:00:00+00:00","data":{"conversation":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"conversation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"channel":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","type":"whatsapp","name":"Clinic WhatsApp"},"assistant_id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","contact_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","contact_name":"Mona Adel","subject":null,"status":"pending","handled_by":"team","automation_mode":"human","priority":"normal","assigned_member_id":null,"team_id":null,"language":"ar","labels":[{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","name":"Bulk order","color":"#64748b"}],"first_message_at":"2026-10-29T10:00:00+00:00","last_message_at":"2026-10-29T12:30:00+00:00","closed_at":null,"updated_at":"2026-10-29T12:30:00+00:00"},"message":{"id":"2b4d6f80-1a3c-4e5a-9b7d-0c2e4a6b8d0f","object":"message","created_at":"2026-10-29T12:30:00+00:00","livemode":true,"conversation_id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","direction":"outgoing","author":"team","type":"text","content":"Your appointment is confirmed for Sunday at 10.","attachments":[],"delivery_status":"sent","sent_at":"2026-10-29T12:30:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"member.invited":{"post":{"operationId":"webhook_member_invited","summary":"Someone was invited","description":"Sent when an invitation is created, in Settings or by the API.","tags":["Members"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"member.invited"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"member.invited"},"data":{"type":"object","required":["invitation"],"properties":{"invitation":{"$ref":"#/components/schemas/Invitation"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"member.invited","created_at":"2026-10-29T10:00:00+00:00","data":{"invitation":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"pending","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"member.invitation_revoked":{"post":{"operationId":"webhook_member_invitation_revoked","summary":"An invitation was revoked","description":"Sent when a pending invitation is revoked.","tags":["Members"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"member.invitation_revoked"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"member.invitation_revoked"},"data":{"type":"object","required":["invitation"],"properties":{"invitation":{"$ref":"#/components/schemas/Invitation"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"member.invitation_revoked","created_at":"2026-10-29T10:00:00+00:00","data":{"invitation":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","object":"invitation","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"omar@nileclinic.example","name":"Omar","role":"member","status":"revoked","expires_at":"2026-11-05T10:00:00+00:00","accepted_at":null,"delivery_status":"accepted_by_provider","last_sent_at":"2026-10-29T10:00:00+00:00"}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"member.role_changed":{"post":{"operationId":"webhook_member_role_changed","summary":"A member's role changed","description":"Sent when a member's role changes.","tags":["Members"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"member.role_changed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"member.role_changed"},"data":{"type":"object","required":["member","previous_role"],"properties":{"member":{"$ref":"#/components/schemas/Member"},"previous_role":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"member.role_changed","created_at":"2026-10-29T10:00:00+00:00","data":{"member":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"member","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"sara@nileclinic.example","name":"Sara Adel","role":"admin","active":true,"email_verified":true,"teams":[]},"previous_role":"manager"}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"member.removed":{"post":{"operationId":"webhook_member_removed","summary":"A member was removed","description":"Sent when someone is removed from the team (their account stays).","tags":["Members"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"member.removed"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"member.removed"},"data":{"type":"object","required":["member"],"properties":{"member":{"$ref":"#/components/schemas/Member"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"member.removed","created_at":"2026-10-29T10:00:00+00:00","data":{"member":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","object":"member","created_at":"2026-10-29T10:00:00+00:00","livemode":true,"email":"sara@nileclinic.example","name":"Sara Adel","role":"manager","active":true,"email_verified":true,"teams":[]}}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}},"ping":{"post":{"operationId":"webhook_ping","summary":"Test delivery","description":"Sent when you press Send test on a webhook in Developers settings.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Ordstage-Event","in":"header","required":true,"description":"The event name, like booking.created.","schema":{"type":"string"},"example":"ping"},{"name":"X-Ordstage-Delivery","in":"header","required":true,"description":"The delivery id; the same on every retry of this delivery.","schema":{"type":"string"},"example":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"},{"name":"X-Ordstage-Timestamp","in":"header","required":true,"description":"Unix time (seconds) when this attempt was signed.","schema":{"type":"string"},"example":"1793260800"},{"name":"X-Ordstage-Signature","in":"header","required":true,"description":"`sha256=` + hex HMAC-SHA256 of `\"{timestamp}.{delivery_id}.\" + raw body`, keyed with the subscription secret.","schema":{"type":"string"},"example":"sha256=<hex digest>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"event":{"const":"ping"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}]},"example":{"id":"6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f","event":"ping","created_at":"2026-10-29T10:00:00+00:00","data":{"message":"Ordstage can reach this address."}}}}},"responses":{"200":{"description":"Any 2xx answer within 10 seconds means received. Anything else is retried with backoff for about a day; a subscription that keeps failing is paused."}}}}},"x-ordstage-error-codes":[{"code":"invalid_api_key","status":401,"type":"authentication","message":"Use a valid workspace API key: Authorization: Bearer ord_…"},{"code":"api_key_in_url","status":400,"type":"invalid_request","message":"API keys go in the Authorization or X-Api-Key header, never in the address. This key has been revoked; create a new one."},{"code":"sandbox_not_available","status":403,"type":"permission","message":"Test keys work with the sandbox, which comes with API access. This business's plan doesn't include it."},{"code":"insufficient_scope","status":403,"type":"permission","message":"This key doesn't have the scope this request needs."},{"code":"module_not_active","status":403,"type":"permission","message":"This business doesn't have the module this request needs."},{"code":"api_access_not_allowed","status":403,"type":"permission","message":"API access for this request isn't included for this business."},{"code":"plan_upgrade_required","status":403,"type":"permission","message":"The API is included on Growth plans and up."},{"code":"rate_limited","status":429,"type":"rate_limit","message":"Too many requests for this key. Wait and try again."},{"code":"too_many_invalid_keys","status":429,"type":"rate_limit","message":"Too many requests with invalid keys from this address. Try again in 15 minutes."},{"code":"rate_limiter_unavailable","status":503,"type":"api_error","message":"The API is briefly unavailable. Try again shortly."},{"code":"idempotency_key_required","status":400,"type":"invalid_request","message":"Send an Idempotency-Key header with this request."},{"code":"idempotency_conflict","status":409,"type":"conflict","message":"This Idempotency-Key was already used with a different request."},{"code":"idempotency_in_progress","status":409,"type":"conflict","message":"A request with this Idempotency-Key is still running."},{"code":"invalid_cursor","status":400,"type":"invalid_request","message":"starting_after must be the id of an object from this list."},{"code":"validation_error","status":422,"type":"invalid_request","message":"The request isn't valid."},{"code":"not_found","status":404,"type":"not_found","message":"Not found."},{"code":"booking_rejected","status":422,"type":"invalid_request","message":"The booking engine refused the request; `code` says why (for example invalid_time)."},{"code":"key_creator_not_allowed","status":403,"type":"permission","message":"The person who created this key can no longer do this: changes that need a person are made as them, so they must still belong to the business with a role that may do it."},{"code":"not_available_in_sandbox","status":409,"type":"conflict","message":"This isn't available in the sandbox. Use a live key."},{"code":"invalid_role","status":400,"type":"invalid_request","message":"Choose owner, admin, manager or member."},{"code":"owner_role_required","status":403,"type":"permission","message":"Only an owner can manage owners; this key's creator is an admin."},{"code":"last_owner","status":400,"type":"invalid_request","message":"Assign another active owner before removing or changing the last owner."},{"code":"cannot_remove_self","status":400,"type":"invalid_request","message":"The key's creator can't remove themselves."},{"code":"seat_limit_reached","status":403,"type":"permission","message":"All seats are in use. Add a seat or remove someone first."},{"code":"already_member","status":409,"type":"conflict","message":"This person is already a member of this business."},{"code":"invitation_exists","status":409,"type":"conflict","message":"An invitation for this email is already pending. Resend it instead."},{"code":"invitation_not_pending","status":409,"type":"conflict","message":"This invitation was accepted or revoked."},{"code":"invitation_superseded","status":409,"type":"conflict","message":"This person already has access or a newer invitation."},{"code":"resend_too_soon","status":429,"type":"rate_limit","message":"Wait a minute before resending this invitation."},{"code":"member_inactive","status":409,"type":"conflict","message":"This member's account is turned off."},{"code":"password_reset_recently_sent","status":429,"type":"rate_limit","message":"A reset email was sent less than a minute ago."},{"code":"webhooks_not_allowed","status":403,"type":"permission","message":"Webhooks aren't included for this business."},{"code":"webhook_limit_reached","status":409,"type":"conflict","message":"A business can have 10 webhooks."},{"code":"invalid_webhook_url","status":422,"type":"invalid_request","message":"Use a public https:// address."},{"code":"unknown_event","status":422,"type":"invalid_request","message":"Choose events from the list of webhook events."},{"code":"unknown_calendar","status":422,"type":"invalid_request","message":"Choose calendars from this business."},{"code":"ping_not_retryable","status":409,"type":"conflict","message":"Test deliveries aren't retried; send a new test instead."},{"code":"assistant_release_not_ready","status":409,"type":"conflict","message":"Resolve the assistant's required setup items before publishing; `message` lists them in Studio."},{"code":"brand_identity_unapproved","status":409,"type":"conflict","message":"Approve the business profile in Studio before publishing."},{"code":"main_flow_missing","status":409,"type":"conflict","message":"Create a conversation flow before publishing this assistant."},{"code":"critical_action_tests_required","status":409,"type":"conflict","message":"Run passing tests for each action in the flow editor before publishing."},{"code":"flow_validation_failed","status":409,"type":"conflict","message":"Fix the assistant's conversation flow in the flow editor before publishing."},{"code":"flow_draft_conflict","status":409,"type":"conflict","message":"The flow changed while publishing. Try again."},{"code":"assistant_not_resumable","status":409,"type":"conflict","message":"Publish the current setup and resolve required items before resuming."},{"code":"test_key_required","status":409,"type":"conflict","message":"Test messages run in the sandbox: send them with a test key (ord_test_…)."},{"code":"daily_limit_reached","status":429,"type":"rate_limit","message":"The plan's daily limit for test messages is used up. Try again tomorrow."},{"code":"reply_not_sent","status":409,"type":"conflict","message":"The channel didn't accept the reply; `message` says why (for example, its reply window closed)."},{"code":"assignee_not_available","status":409,"type":"conflict","message":"This member can't take the conversation now; `message` says why."},{"code":"api_error","status":500,"type":"api_error","message":"Something went wrong on our side. Try again; if it keeps happening, contact support with the request id."}]}