# Search availability slots

Computes available start times for the given services within a date range —
optionally narrowed to one Team Member. Slots are derived from configured schedules,
existing appointments, and service durations; `starts_at` values carry the Location's
local UTC offset and can be passed directly to `createAppointment`.
This is a computed read-only aggregate: slots have no ids and can disappear at any
moment when another request schedules an overlapping appointment (a lost race on create
returns `409 slot_taken`).

Endpoint: GET /locations/{location_id}/availability
Version: 3.0.0-preview
Security: OAuth2, ApiKey

## Security:

  - `OAuth2` (unknown)
    oauth2 scopes: availability:read

  - `ApiKey` (unknown)
    http bearer

## Path parameters:

  - `location_id` (integer, required)
    Identifier of the Location. Verified against the credential on every call — a Location the credential cannot access responds with `404`.

## Query parameters:

  - `service_ids` (array, required)
    Services the appointment will consist of.

  - `team_member_id` (integer)
    Restrict the search to one Team Member.

  - `date_from` (string, required)
    First date of the range (inclusive), `YYYY-MM-DD`.

  - `date_to` (string, required)
    Last date of the range (inclusive), `YYYY-MM-DD`.

## Response 200:

  - `200` (unknown)
    Free slots for the requested services and range.

## Response 200 fields (application/json):

  - `object` (string, required)
    Enum: "list"

  - `has_more` (boolean, required)
    Whether more items exist beyond this page.

  - `next_cursor` (string | null, required)
    Opaque cursor for the next page; `null` on the last page.

  - `data` (array, required)

  - `data.object` (string, required)
    Enum: "availability_slot"

  - `data.team_member_id` (integer, required)

  - `data.starts_at` (string, required)
    RFC 3339 with the Location's local UTC offset; pass directly to `createAppointment`.

  - `data.is_bookable` (boolean, required)

  - `data.duration_seconds` (integer)
    Slot duration in seconds.

  - `data.resource_instance_ids` (array)
    Resource instances occupied by the slot.

  - `data.components` (array)
    For package services, per-component scheduling segments in execution order.

  - `data.components.package_component_id` (integer, required)
    Stable component id from `ServicePackage.components[].id`.

  - `data.components.service_id` (integer, required)

  - `data.components.team_member_id` (integer, required)

  - `data.components.starts_at` (string, required)

  - `data.components.duration_seconds` (integer, required)

  - `data.components.resource_instance_ids` (array, required)

## Response 200 headers (application/json):

  - `RateLimit-Remaining` (integer)
    Requests left in the most constrained policy window that applies to this request.

  - `RateLimit-Reset` (integer)
    On `429`, seconds until the most constrained policy frees up; it equals `Retry-After` there.
On a successful response it reports the **length** of that policy's window rather than the
time left in the current one, so treat it as the window size, not as a countdown — the
counter to pace against is `RateLimit-Remaining`.

  - `RateLimit-Policy` (string)
    Most constrained policy applied to the request, as `<limit>;w=<window in seconds>`.
    Example: 10;w=60

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 400:

  - `400` (unknown)
    Client error without a more specific registered code (`bad_request` — status default for
bare 400 and unknown 4xx), or protocol/syntax failure (`malformed_request` — broken JSON /
unparseable body only; must be thrown explicitly, never used as a synonym for every 400).
Semantic field validation is `422 validation_failed`, not 400.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 400 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 401:

  - `401` (unknown)
    The request has no valid Bearer credential (`invalid_token`).

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 401 headers (application/problem+json):

  - `WWW-Authenticate` (string)
    Bearer challenge with the URL of the protected resource metadata (RFC 9728 §5.1),
where the client finds the authorization server.
    Example: Bearer resource_metadata="https://api.alteg.io/.well-known/oauth-protected-resource/api/v3"

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 403:

  - `403` (unknown)
    The token lacks the required scope (`missing_scope`), the scope is present but the token subject lacks the business permission (`permission_denied`), or the Location has no active license (`subscription_inactive`).

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 403 headers (application/problem+json):

  - `WWW-Authenticate` (string)
    Only on `missing_scope`: Bearer challenge with `error="insufficient_scope"`, the scope the
operation requires and the URL of the protected resource metadata (RFC 6750 §3.1, RFC 9728 §5.1).
    Example: Bearer error="insufficient_scope", scope="team_members:read", resource_metadata="https://api.alteg.io/.well-known/oauth-protected-resource/api/v3"

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 404:

  - `404` (unknown)
    The resource does not exist or is hidden by tenant policy. Prefer a resource-specific
code (`appointment_not_found`, `location_not_found`, …). Routing/gate/unknown-path 404s
use the generic `resource_not_found` (same shape, so "no pin" and "missing" are not distinguished).

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 404 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 406:

  - `406` (unknown)
    Requested `Accept` media type cannot be satisfied (`not_acceptable`).

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 406 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 409:

  - `409` (unknown)
    Domain conflict (`slot_taken`, `duplicate_location`, `last_location_owner`), idempotency conflict, or generic `conflict` when no more specific registered code applies.

## Response 409 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 409 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

  - `Retry-After` (integer)
    Seconds to wait before retrying.

## Response 422:

  - `422` (unknown)
    Semantic validation failed (`validation_failed`); field-level details are in `errors[]`. Merge-patch violations use `field_not_nullable` / `field_immutable`.

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 422 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 429:

  - `429` (unknown)
    Rate limit exceeded (`rate_limit_exceeded`). Retry after `Retry-After`.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 429 headers (application/problem+json):

  - `Retry-After` (integer)
    Seconds to wait before retrying.

  - `RateLimit-Remaining` (integer)
    Requests left in the most constrained policy window that applies to this request.

  - `RateLimit-Reset` (integer)
    On `429`, seconds until the most constrained policy frees up; it equals `Retry-After` there.
On a successful response it reports the **length** of that policy's window rather than the
time left in the current one, so treat it as the window size, not as a countdown — the
counter to pace against is `RateLimit-Remaining`.

  - `RateLimit-Policy` (string)
    Most constrained policy applied to the request, as `<limit>;w=<window in seconds>`.
    Example: 10;w=60

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 500:

  - `500` (unknown)
    Unexpected server error (`internal_error`).

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 500 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 503:

  - `503` (unknown)
    A dependency required for safe processing (e.g. the idempotency store) is unavailable; the write was **not** performed (`dependency_unavailable`). Retry with the same `Idempotency-Key` after a backoff.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 503 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 400 examples:

  - `Generic client reject (status default)` (unknown)

  - `Broken JSON / protocol only` (unknown)

## Response 403 examples:

  - `Token scope is insufficient` (unknown)

  - `Subject lacks the business permission` (unknown)

  - `Location license is not active` (unknown)

## Response 404 examples:

  - `Generic 404 (routing / gate / hidden)` (unknown)

  - `Resource-specific 404` (unknown)