> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # Hold a slot > Reserves a slot for `ttlSeconds` (default 600) so two booking sessions cannot sell it twice. Holds are shared across Max AI replicas and subtracted from slot search. `advisory: true` means the EHR is not holding anything — a human booking directly in the EHR can still take the slot, and the booking write re-validates against the EHR. Returns 409 `slot_unavailable` when the slot is already held. ## OpenAPI ````yaml /openapi-v2.json post /schedule/holds openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '2.0' contact: {} servers: - url: https://api.maxcare.ai/v2 security: [] tags: [] paths: /schedule/holds: post: tags: - Schedule summary: Hold a slot description: >- Reserves a slot for `ttlSeconds` (default 600) so two booking sessions cannot sell it twice. Holds are shared across Max AI replicas and subtracted from slot search. `advisory: true` means the EHR is not holding anything — a human booking directly in the EHR can still take the slot, and the booking write re-validates against the EHR. Returns 409 `slot_unavailable` when the slot is already held. operationId: SchedulePublicController_createHold parameters: - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHoldBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreateHoldSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '409': description: Resource conflict (e.g. editing a signed note) content: application/json: schema: $ref: '#/components/schemas/PublicApiConflictResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' '503': description: EHR integration unavailable content: application/json: schema: $ref: '#/components/schemas/PublicApiServiceUnavailableResponse' security: - api-key: [] components: schemas: CreateHoldBody: type: object properties: providerId: type: string description: Provider ID (prv_…) facilityId: type: string description: Facility ID (fac_…) appointmentTypeId: type: string description: Appointment type ID (atp_…) startsAt: type: string description: Slot start, ISO-8601 with explicit offset example: '2026-08-03T08:00:00-04:00' durationMinutes: type: number description: Slot length in minutes example: 15 ttlSeconds: type: number description: Hold lifetime in seconds (30–1800). Defaults to 600. example: 600 required: - providerId - facilityId - appointmentTypeId - startsAt - durationMinutes CreateHoldSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/HoldResponse' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiConflictResponse: type: object properties: code: type: string description: Error code example: conflict message: type: string description: Human-readable error message example: Cannot edit a signed note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiServiceUnavailableResponse: type: object properties: code: type: string description: Error code example: server_unresponsive message: type: string description: Human-readable error message example: EHR integration is not available for this note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id HoldResponse: type: object properties: id: type: string example: hld_9f2c1d0e3b4a5968778695a4b3c2d1e0 expiresAt: type: string example: '2026-07-26T13:10:00.000Z' advisory: type: boolean description: >- `true` when the hold exists only in Max AI, not the EHR: it prevents double-selling between booking sessions, but a human booking directly in the EHR can still take the slot. Both current EHRs are advisory. example: true required: - id - expiresAt - advisory securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````