> ## Documentation Index > Fetch the complete documentation index at: https://docs.casa-layer.com/llms.txt > Use this file to discover all available pages before exploring further. # Get reservation by ID > Returns a single reservation by its Casa Layer ID, scoped to the credential. Requires scope `read:reservations`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/reservations/{id} openapi: 3.1.0 info: title: Casa Layer API version: 1.0.0 description: > Headless, read-only access to the guest context layer — the entire canonical data model over HTTP. Every endpoint is **scoped by the credential**: the default scope is the caller's property group, returning data across all of its properties. Auth sources resolve to the same credential: a user-generated **API key** (`casa_…`, created in Account settings — the recommended method for first-party machines), a **partner credential** access token (third-party agents, REST-only), a session JWT (the web app; org and role come from verified token claims), or a static token. (The MCP server also accepts read-only OAuth connector tokens, but those are rejected on these REST routes.) Send `X-Property-Id` to drill one request down to a single property. Personal API keys and partner credentials accept that header. A property-pinned API key ignores it. Tenant isolation holds by construction. The Model Context Protocol (MCP) server is exposed separately at `/mcp` and is documented under **MCP Server** in the guides — it is not a REST endpoint and is intentionally omitted from this reference. It accepts the same API keys. servers: - url: https://api.casa-layer.com description: Production Cloudflare Worker security: - bearerAuth: [] tags: - name: System description: Liveness, health, and the public welcome page. - name: Guests description: Canonical guest profiles as ingested from each source system. - name: Master Profiles description: >- Identity-resolved golden records — one entity per real guest, merged across sources and properties. - name: Reservations description: >- Reservation records linked to guest profiles, searchable by status, stay window, and channel. - name: Transactions description: >- Revenue lines (Pace Transactions V2–shaped) linked to guests and optionally reservations. - name: Consents description: > Contact-grain consent observations (contact method + value × purpose). Rows store decisive signals only (granted/withdrawn/denied); absence of a row means unknown / not eligible. Effective eligibility within a property group is the most restrictive status among stored observations for the same contact×purpose (withdrawn/denied beat granted). - name: Tables description: > Attio-style ops tables — curated or filter-defined containers for day-to-day work inside Casa Layer. Tables are not consent eligibility records and not marketing segments; campaign audiences stay in downstream ESP tools (Klaviyo, Mailchimp, and peers). - name: Actions description: Guest actions (purchases, visits, and other tracked events). - name: Events description: >- The append-only guest event log — full change history or latest delta slice per entity. - name: Reviews description: Guest reviews with free-text search and an aggregate summary. - name: Loyalty description: Loyalty programs and member search (tier, points, guest). - name: Resources description: Reference resources — booking channels and bookable spaces. - name: Properties description: Properties within a group (the group's property roster). - name: Integrations description: > Source-system mappings in the credential's scope. Use each row's `id` as `integration_id` when you query by `source_id`. paths: /v1/reservations/{id}: get: tags: - Reservations summary: Get reservation by ID description: >- Returns a single reservation by its Casa Layer ID, scoped to the credential. Requires scope `read:reservations`. parameters: - name: id in: path required: true description: Resource ID (UUID) of the reservation in Casa Layer. schema: type: string format: uuid - $ref: '#/components/parameters/PropertyHeader' responses: '200': description: Reservation. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Reservation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: PropertyHeader: name: X-Property-Id in: header required: false description: > Optional single-property drill-down. Narrows this request to one property in the caller's group. A property outside the group returns `403`. Personal API keys and partner credentials accept this header. A property-pinned API key ignores it. Casa Layer sign-in tokens reject it. schema: type: string format: uuid schemas: Reservation: type: object description: A reservation linked to a guest profile. required: - id - property_id - integration_id - guest_profile_id - source_id - source_version - gross_revenue - source_payload - created_at - updated_at properties: id: type: string format: uuid property_id: type: string format: uuid integration_id: type: string format: uuid guest_profile_id: type: string format: uuid source_id: type: string source_version: type: string status: type: - string - 'null' enum: - pending - confirmed - in_progress - completed - cancelled - declined - no_show - null start_at: type: - string - 'null' format: date-time end_at: type: - string - 'null' format: date-time category: type: - string - 'null' space_category_name: type: - string - 'null' description: Human-readable space/room category label (e.g. Deluxe, Single Room). description: type: - string - 'null' description: >- Human-readable booking label (e.g. a Square appointment service name). net_revenue: type: - string - 'null' description: >- Decimal serialized as a string. Optional when the PMS only exposes gross. gross_revenue: type: string description: Required stay gross (decimal as string). May be 0. currency: type: - string - 'null' channel_category: type: - string - 'null' enum: - direct - ota - gds - corporate - walk_in - channel_manager - other - null channel_name: type: - string - 'null' description: Human-readable channel label (e.g. Booking.com). notes: type: array description: Reservation-scoped notes from the source system. items: type: object properties: source_id: type: string content: type: string classifications: type: array items: type: string is_active: type: boolean rate_plan_name: type: - string - 'null' description: Denormalized rate plan label. rate_plan_source_id: type: - string - 'null' description: Source-system rate plan id. business_segment_name: type: - string - 'null' description: Denormalized business segment label. business_segment_source_id: type: - string - 'null' description: Source-system business segment id. source_payload: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: string description: Machine-readable error code. scope: type: string description: The scope that was required when the error is a scope failure.: null detail: type: string description: Optional human-readable detail. responses: Unauthorized: description: Missing, unknown, or revoked bearer credential. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized Forbidden: description: > The credential lacks the scope required for this endpoint, or the auth surface is wrong. Machine-readable codes include `forbidden` (scope or role), `tenant_not_provisioned` (org claim present but no property group), and `mcp_oauth_required` (SPA session token used on `/mcp`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: forbidden scope: read:guests NotFound: description: Resource not found within the credential's scope. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found securitySchemes: bearerAuth: type: http scheme: bearer description: > `Authorization: Bearer `. Token types resolve to the same scoped credential: a user-generated **API key** (`casa_…`, from Account settings — recommended for first-party machines and MCP clients), a **partner credential** access token (third-party agents; REST-only), a session JWT (the web app; org and role come from verified token claims), or a static token. API keys are group-scoped, optionally pinned to one property at creation. Personal API keys and partner credentials accept `X-Property-Id` to drill down to one property in the group. A property-pinned API key ignores that header. MCP OAuth connector tokens authenticate the MCP server only and are rejected on these REST routes. ````