Gaplessly API

{
  "summary": "Create a service",
  "description": "Adds a bookable service (a haircut, a consultation). `company_id` comes from the verified JWT claim and is never read from the body. Busts the cached public booking config for this org.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createService",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name",
            "durationMinutes",
            "color"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "durationMinutes": {
              "type": "integer",
              "minimum": 5,
              "maximum": 600
            },
            "price": {
              "type": [
                "number",
                "string",
                "null"
              ],
              "description": "Coerced with Number() and rounded to 2 decimals. 0-100000. Empty string or null means \"no price shown\"."
            },
            "color": {
              "type": "string",
              "description": "Must be one of SERVICE_COLORS (src/lib/booking/palette.ts). Anything else is a 400."
            },
            "groupId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The service group this sits in (migration 0054). Null or omitted means ungrouped. Tenancy is enforced by the composite FK, so another org's group id, or a deleted one; comes back as a 400 \"Group not found\"."
            },
            "active": {
              "type": "boolean",
              "default": true,
              "description": "Defaults to true. Only the literal `false` turns it off (`active !== false`)."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "service"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "service": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseServiceInput, \"Group not found\" for a groupId that is not this org's (FK 23503), or the raw Postgres message if the insert itself failed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Reorder and/or regroup services",
  "description": "The body is one category's (or \"Uncategorized\"'s, via a null groupId) full shelf in its new order: position in the array becomes the new `sort_order`, and every listed id is written to `groupId`. A drag that only reorders within one category sends that category's own id back unchanged; a drag that moves a service into a different (or no) category sends the destination's id and its full resulting id list, including whichever service just arrived from elsewhere, so this one request is the only write a cross-category move needs. Same shape as PATCH /api/service-groups; an id that is not this org's simply matches zero rows under RLS.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "reorderServices",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "ids"
          ],
          "additionalProperties": false,
          "properties": {
            "groupId": {
              "type": "string",
              "format": "uuid",
              "nullable": true,
              "description": "The category this shelf belongs to, or null/omitted for \"Uncategorized\"."
            },
            "ids": {
              "type": "array",
              "minItems": 1,
              "maxItems": 300,
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "description": "Every service id on this shelf, in the order they should appear."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Reordered.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`ids` missing, empty, over 300 entries, or containing a non-uuid; `groupId` present but not a uuid; or \"Group not found\" for a groupId that is not this org's (FK 23503).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Update a service",
  "description": "Full replacement of the service's editable fields; despite the verb, every field in the schema is written on every call, so a partial body resets what it omits. RLS scopes the update, so an id from another org simply matches zero rows and returns 404.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "updateService",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Service id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name",
            "durationMinutes",
            "color"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "durationMinutes": {
              "type": "integer",
              "minimum": 5,
              "maximum": 600
            },
            "price": {
              "type": [
                "number",
                "string",
                "null"
              ],
              "description": "Coerced with Number() and rounded to 2 decimals. 0-100000. Empty string or null means \"no price shown\"."
            },
            "color": {
              "type": "string",
              "description": "Must be one of SERVICE_COLORS (src/lib/booking/palette.ts). Anything else is a 400."
            },
            "groupId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The service group this sits in (migration 0054). Null or omitted means ungrouped. Tenancy is enforced by the composite FK, so another org's group id, or a deleted one; comes back as a 400 \"Group not found\"."
            },
            "active": {
              "type": "boolean",
              "default": true,
              "description": "Defaults to true. Only the literal `false` turns it off (`active !== false`)."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseServiceInput, or \"Group not found\" for a groupId that is not this org's (FK 23503).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No service with that id in this org. A malformed uuid (Postgres 22P02) is deliberately mapped here rather than surfacing as a 500.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Delete a service (admin, or manage_services)",
  "description": "Hard delete. The foreign key from `book_appointments` has no cascade on purpose, so a service with booking history cannot be deleted; deactivate it instead (`active: false`). Gated to admin, or a staff login granted `manage_services` (migration 0082): price, duration and every other service setting is a delegable business decision now.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteService",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Service id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error other than the two handled below.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No service with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The service has bookings against it (foreign key violation 23503). \"This service has bookings. Deactivate it instead of deleting\".",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Upload a service image",
  "description": "Stores the file at `{companyId}/{serviceId}` in the `service-images` bucket and writes a cache-busted public URL onto the service row. Not admin-gated: a photo is part of editing the service.\n\nOwnership is checked BEFORE the upload (one indexed lookup ahead of a multi-megabyte write), so a request naming a service the caller does not own is a 404 with nothing written; this used to be upload-first-then-sweep, and this paragraph used to describe that.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "uploadServiceImage",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Service id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "required": [
            "file"
          ],
          "properties": {
            "file": {
              "type": "string",
              "format": "binary",
              "description": "PNG, JPEG or WebP, 2 MB or smaller. Anything else is a 400."
            }
          }
        },
        "encoding": {
          "file": {
            "contentType": "image/png, image/jpeg, image/webp"
          }
        }
      }
    },
    "description": "The service image. Sent as multipart/form-data under the field name `file`."
  },
  "responses": {
    "200": {
      "description": "Uploaded.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "imageUrl"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "imageUrl": {
                "type": "string",
                "format": "uri",
                "description": "Public URL with a `?v=<timestamp>` cache-buster; the storage path itself never changes."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "No file, wrong MIME type, over 2 MB, or a storage error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No service with that id in this org. Nothing was uploaded; the ownership check runs first.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Remove a service image",
  "description": "Deletes the stored object and nulls `image_url`. Storage removal is best-effort and its failure does not fail the request.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteServiceImage",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Service id."
    }
  ],
  "responses": {
    "200": {
      "description": "Removed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error updating the row.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No service with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Create a service group",
  "description": "A named shelf services hang off on the public page (migration 0054); \"Hair Colouring\", \"Mens Cuts\"; with an optional photo and colour. New groups land at the end of the order (`sort_order = max+1`). Busts the cached public booking config.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createServiceGroup",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "color": {
              "type": [
                "string",
                "null"
              ],
              "description": "One of SERVICE_COLORS, or null/omitted for no colour. Anything else is a 400."
            },
            "active": {
              "type": "boolean",
              "default": true,
              "description": "Defaults to true. An inactive group disappears from the public page; its services stay bookable in the flat list sense but stop being shelved under it."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "group"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "group": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseServiceGroupInput, or the raw Postgres message if the insert itself failed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Reorder service groups",
  "description": "The body is the full shelf in its new order, and position in the array IS the new `sort_order`. Idempotent; an id that is not this org's simply matches zero rows under RLS. One request and one cache bust per drag session, rather than one per step.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "reorderServiceGroups",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "ids"
          ],
          "additionalProperties": false,
          "properties": {
            "ids": {
              "type": "array",
              "minItems": 1,
              "maxItems": 100,
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "description": "Every group id, in the order they should appear."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Reordered.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`ids` missing, empty, over 100 entries, or containing a non-uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Update a service group",
  "description": "Full replacement of the group's editable fields, same PATCH-in-name-only semantics as PATCH /api/services/{id}. RLS scopes the update, so an id from another org matches zero rows and returns 404.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "updateServiceGroup",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Group id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "color": {
              "type": [
                "string",
                "null"
              ],
              "description": "One of SERVICE_COLORS, or null/omitted for no colour. Anything else is a 400."
            },
            "active": {
              "type": "boolean",
              "default": true,
              "description": "Defaults to true. An inactive group disappears from the public page; its services stay bookable in the flat list sense but stop being shelved under it."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseServiceGroupInput.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No group with that id in this org. A malformed uuid (Postgres 22P02) is mapped here rather than surfacing as a 500.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Delete a service group (admin, or manage_services)",
  "description": "Never blocks and never takes services with it: the composite FK's column-scoped `on delete set null (group_id)` (0054) un-groups them in the same statement. That column list is load-bearing; a bare composite `set null` would null `company_id` too and fail the delete outright (the 0039 lesson). Gated to admin, or a staff login granted `manage_services` (migration 0082), same as every other service-catalog write.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteServiceGroup",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Group id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted. Its services are now ungrouped.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No group with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Create a staff member",
  "description": "Creates the provider row, then its service links and working hours. If the second step fails the provider is deleted again (its cascade takes any partial links with it), so a failure leaves nothing behind. Returns the id so a follow-up avatar upload has something to hang off.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createProvider",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "email": {
              "type": [
                "string",
                "null"
              ],
              "format": "email",
              "maxLength": 254
            },
            "bio": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "title": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 120,
              "description": "The public team page's role line (migration 0114), e.g. \"Owner & Colorist\", not this app's own auth role (admin/staff)."
            },
            "active": {
              "type": "boolean",
              "default": true
            },
            "serviceIds": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "description": "Services this staff member offers. Every id must belong to the caller's org or the whole request is a 400 (\"Invalid service selection\"). Deduplicated server-side."
            },
            "hours": {
              "type": "array",
              "maxItems": 21,
              "items": {
                "type": "object",
                "required": [
                  "dayOfWeek",
                  "startTime",
                  "endTime"
                ],
                "additionalProperties": false,
                "properties": {
                  "dayOfWeek": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6,
                    "description": "0 = Sunday, matching `Date#getUTCDay()`."
                  },
                  "startTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM."
                  },
                  "endTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM, strictly after startTime."
                  }
                }
              },
              "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
            },
            "userId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The login this bookable person signs in as (migration 0034). **Admin only**: any other role sending this field gets a 403, because from 0034 onward this is what decides whose bookings are whose, and a staff member who could set it could hand themselves another person's work. Absent leaves an existing link untouched; explicit `null` unlinks. Must be somebody already on this company's roster: a composite FK to `book_org_members (company_id, user_id)` refuses anything else (400), and one login can hold at most one provider row per company (409); though the same person may hold one at each venue of an organization, which is what the future cross-venue work is built on."
            },
            "availabilityDelegation": {
              "type": "string",
              "enum": [
                "standard",
                "trusted"
              ],
              "description": "This staff member's schedule trust tier (migration 0052). **Admin only, PATCH only**: POST /api/providers accepts the field for shape but ignores it, since a brand-new row already starts 'standard' at the database default. Absent leaves the existing tier untouched. On PATCH, when a non-admin caller is editing their own row and it is currently 'standard', the `hours` field is silently ignored (the stored week is kept) rather than rejecting the request; their only path to a schedule change is POST /api/providers/{id}/availability-overrides."
            },
            "conflictAcknowledged": {
              "type": "boolean",
              "default": false,
              "description": "PATCH only, and only meaningful when the schedule (hours, cycleWeeks, rotationAnchor or rotationWeeks together) genuinely differs from what is currently stored. No admin-only gate here, unlike POST /api/providers/{id}/availability-overrides: a Standard-tier caller can never trigger the underlying conflict at all (their whole schedule is silently ignored, see `hours` above), so every caller who can reach a real conflict here (admin, a manage_staff holder, or a Trusted-tier caller on their own row) is already fully authorized to acknowledge it."
            },
            "cycleWeeks": {
              "type": "integer",
              "minimum": 1,
              "maximum": 8,
              "default": 1,
              "description": "Rotating multi-week rosters (migrations 0150/0151). 1 (the default) is the ordinary week, no rotation. Same wholesale-replace and Standard-tier-ignored rules as `hours`, which it rides alongside as one schedule template rather than a separate permission: omitting it is the same as sending 1. PATCH only; POST /api/providers accepts it for shape but ignores it, since a brand-new provider always starts unrotated."
            },
            "rotationAnchor": {
              "type": [
                "string",
                "null"
              ],
              "format": "date",
              "description": "Required, and validated, only when the resolved `cycleWeeks` is more than 1: any date that falls in week 1 of the cycle, used to resolve which week a future date lands on. Ignored (and stored as null) when `cycleWeeks` is 1."
            },
            "rotationWeeks": {
              "type": "array",
              "maxItems": 7,
              "items": {
                "type": "array",
                "maxItems": 21,
                "items": {
                  "type": "object",
                  "required": [
                    "dayOfWeek",
                    "startTime",
                    "endTime"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "dayOfWeek": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6,
                      "description": "0 = Sunday, matching `Date#getUTCDay()`."
                    },
                    "startTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM."
                    },
                    "endTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM, strictly after startTime."
                    }
                  }
                },
                "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
              },
              "description": "Hours for weeks 1..cycleWeeks-1: week 0 is `hours` above. `rotationWeeks[0]` is week 1 (the second week of the cycle), and so on. Length must exactly equal `cycleWeeks - 1` or the whole request is a 400; wholesale-replace, same as `hours`."
            }
          },
          "description": "On PATCH, serviceIds and the working-hours rows are replaced wholesale, not merged. Omitting `hours` entirely is the same as sending `[]`: the staff member works no days and is offered no slots; UNLESS the caller is a Standard-tier staff member editing their own row, in which case the whole schedule (hours, cycleWeeks, rotationAnchor, rotationWeeks) is ignored outright (see availabilityDelegation)."
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "provider"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "provider": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseProviderInput, \"Invalid service selection\" when a serviceId does not belong to this org, or a `userId` that is not on this company's roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "402": {
      "description": "The plan's seat cap is full and another seat cannot be billed (`reserveSeat`, src/lib/billing/seats.ts). Refused before any row is written, so nothing is left behind to clean up. Only a card that actually consumes a seat can reach this: one linked to somebody already on the roster, by `userId` or by an email that already matches a member, is not a second head and skips the reservation entirely.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Wrong engine for this org, a staff login without `manage_staff` (migration 0082, \"Admin access required\"), or a non-admin sent `userId` (\"Only an admin can link a staff login\").",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "That login is already linked to another staff member in this company.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "The links/hours insert failed; the provider row was rolled back.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Update a staff member",
  "description": "Replaces the provider's fields, their service links and their working hours; all three, in a single transaction. The whole replacement is one `book_replace_provider()` call (migration 0025, SECURITY DEFINER as of 0055) so RLS's tenant_all is never the real ownership boundary here: the function re-checks role and ownership itself, from the database.\n\nIt used to be four PostgREST calls with nothing transactional over them, so a failure after the deletes left the staff member with no services and no hours, which means no slots, so the public widget silently stopped offering them until somebody re-saved. That is why there is no longer a 500 here: a partial save is not a state this route can reach.\n\nLinks and hours are replaced wholesale, not diffed, because the editor posts the complete set every time.\n\n**Ownership (migration 0052)**: an admin may edit any provider in the org; any other role may only edit the provider row linked to their own login; a check this route was missing entirely before 0052, and the whole reason it exists: any staff-role login could open and submit any colleague's edit modal, `hours` included. A Standard-tier caller editing their own row additionally has the WHOLE schedule (hours, cycleWeeks, rotationAnchor, rotationWeeks) silently ignored (the stored template is kept) rather than the request being rejected.\n\n**Rotation (migrations 0150/0151)**: `cycleWeeks`/`rotationAnchor`/`rotationWeeks` layer an optional multi-week roster on top of `hours` (which stays week 0 either way): \"week A this week, week B next week, week A again the week after\". Wholesale-replace and the Standard-tier boundary both extend to all four fields as one schedule template, not a second permission to check.\n\n**Conflicts**, added after this route shipped with none at all: replacing the schedule used to write straight through even when a future appointment already sat outside the new pattern, silently orphaning it. Only checked when the schedule genuinely differs from what is currently stored (hours, cycleWeeks or rotationAnchor; changing only the anchor can orphan a booking exactly as surely as changing the hours), and applied per (week, day of week) pair against every non-cancelled future appointment resolved through its own date (an appointment on a date with an approved override is excluded; that date answers to the override, not the recurring week). No staff-vs-admin split on the acknowledgment, unlike the override route: a Standard-tier caller can never reach a real conflict here at all (their whole schedule is silently ignored), so anyone who CAN trigger one is already fully authorized to resend with `conflictAcknowledged: true`.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "updateProvider",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "email": {
              "type": [
                "string",
                "null"
              ],
              "format": "email",
              "maxLength": 254
            },
            "bio": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "title": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 120,
              "description": "The public team page's role line (migration 0114), e.g. \"Owner & Colorist\", not this app's own auth role (admin/staff)."
            },
            "active": {
              "type": "boolean",
              "default": true
            },
            "serviceIds": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "description": "Services this staff member offers. Every id must belong to the caller's org or the whole request is a 400 (\"Invalid service selection\"). Deduplicated server-side."
            },
            "hours": {
              "type": "array",
              "maxItems": 21,
              "items": {
                "type": "object",
                "required": [
                  "dayOfWeek",
                  "startTime",
                  "endTime"
                ],
                "additionalProperties": false,
                "properties": {
                  "dayOfWeek": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6,
                    "description": "0 = Sunday, matching `Date#getUTCDay()`."
                  },
                  "startTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM."
                  },
                  "endTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM, strictly after startTime."
                  }
                }
              },
              "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
            },
            "userId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The login this bookable person signs in as (migration 0034). **Admin only**: any other role sending this field gets a 403, because from 0034 onward this is what decides whose bookings are whose, and a staff member who could set it could hand themselves another person's work. Absent leaves an existing link untouched; explicit `null` unlinks. Must be somebody already on this company's roster: a composite FK to `book_org_members (company_id, user_id)` refuses anything else (400), and one login can hold at most one provider row per company (409); though the same person may hold one at each venue of an organization, which is what the future cross-venue work is built on."
            },
            "availabilityDelegation": {
              "type": "string",
              "enum": [
                "standard",
                "trusted"
              ],
              "description": "This staff member's schedule trust tier (migration 0052). **Admin only, PATCH only**: POST /api/providers accepts the field for shape but ignores it, since a brand-new row already starts 'standard' at the database default. Absent leaves the existing tier untouched. On PATCH, when a non-admin caller is editing their own row and it is currently 'standard', the `hours` field is silently ignored (the stored week is kept) rather than rejecting the request; their only path to a schedule change is POST /api/providers/{id}/availability-overrides."
            },
            "conflictAcknowledged": {
              "type": "boolean",
              "default": false,
              "description": "PATCH only, and only meaningful when the schedule (hours, cycleWeeks, rotationAnchor or rotationWeeks together) genuinely differs from what is currently stored. No admin-only gate here, unlike POST /api/providers/{id}/availability-overrides: a Standard-tier caller can never trigger the underlying conflict at all (their whole schedule is silently ignored, see `hours` above), so every caller who can reach a real conflict here (admin, a manage_staff holder, or a Trusted-tier caller on their own row) is already fully authorized to acknowledge it."
            },
            "cycleWeeks": {
              "type": "integer",
              "minimum": 1,
              "maximum": 8,
              "default": 1,
              "description": "Rotating multi-week rosters (migrations 0150/0151). 1 (the default) is the ordinary week, no rotation. Same wholesale-replace and Standard-tier-ignored rules as `hours`, which it rides alongside as one schedule template rather than a separate permission: omitting it is the same as sending 1. PATCH only; POST /api/providers accepts it for shape but ignores it, since a brand-new provider always starts unrotated."
            },
            "rotationAnchor": {
              "type": [
                "string",
                "null"
              ],
              "format": "date",
              "description": "Required, and validated, only when the resolved `cycleWeeks` is more than 1: any date that falls in week 1 of the cycle, used to resolve which week a future date lands on. Ignored (and stored as null) when `cycleWeeks` is 1."
            },
            "rotationWeeks": {
              "type": "array",
              "maxItems": 7,
              "items": {
                "type": "array",
                "maxItems": 21,
                "items": {
                  "type": "object",
                  "required": [
                    "dayOfWeek",
                    "startTime",
                    "endTime"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "dayOfWeek": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6,
                      "description": "0 = Sunday, matching `Date#getUTCDay()`."
                    },
                    "startTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM."
                    },
                    "endTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM, strictly after startTime."
                    }
                  }
                },
                "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
              },
              "description": "Hours for weeks 1..cycleWeeks-1: week 0 is `hours` above. `rotationWeeks[0]` is week 1 (the second week of the cycle), and so on. Length must exactly equal `cycleWeeks - 1` or the whole request is a 400; wholesale-replace, same as `hours`."
            }
          },
          "description": "On PATCH, serviceIds and the working-hours rows are replaced wholesale, not merged. Omitting `hours` entirely is the same as sending `[]`: the staff member works no days and is offered no slots; UNLESS the caller is a Standard-tier staff member editing their own row, in which case the whole schedule (hours, cycleWeeks, rotationAnchor, rotationWeeks) is ignored outright (see availabilityDelegation)."
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message, \"Invalid service selection\", a `userId` that is not on this company's roster, an out-of-range `cycleWeeks`, a missing/invalid `rotationAnchor` when `cycleWeeks` is more than 1, or a `rotationWeeks` length that does not exactly equal `cycleWeeks - 1`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Wrong engine for this org, a non-admin sent `userId` or `availabilityDelegation`, or the caller is staff editing a colleague's row with neither ownership nor `manage_staff` (\"You can only edit your own staff profile\", migrations 0052/0082).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No staff member with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Either that login is already linked to another staff member in this company, or the new schedule (hours, cycleWeeks or rotationAnchor) conflicts with existing future bookings. In the schedule case, body includes `conflicts` (same shape as GET /api/availability-overrides); resend with `conflictAcknowledged: true` to proceed anyway.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Delete a staff member (admin, or manage_staff)",
  "description": "Hard delete. As with services, the appointment foreign key has no cascade, so a provider with bookings cannot be removed. Gated to admin, or a staff login granted `manage_staff` (migration 0082).",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteProvider",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "An unhandled Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_staff` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No staff member with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The staff member has bookings against them. \"Deactivate them instead of deleting\".",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Archive a staff member (admin, or manage_staff)",
  "description": "The third state alongside active and deleted, and the one to reach for when somebody leaves: unlike DELETE it works on a staff member who has bookings, and unlike the free `active` toggle it stops the seat being billed.\n\nDeliberately reversible. Only the photo is thrown away; bio, phone, service links and working hours all survive untouched, and a linked login is suspended rather than unlinked, so POST /api/providers/{id}/reactivate has nothing to re-enter or re-link. All of it happens inside one `book_archive_provider()` call (migration 0086), so a partial failure cannot leave a login suspended with the card still reading as active, or the reverse.\n\nBilling moves rather than stops: the person leaves the normal seat cap (`seatsUsed()` excludes them) and joins a separate archived count, free and unlimited on Pro and Enterprise, $1/mo each on Basic. Solo and Free are refused with a 400 rather than a 402, because there is nothing to buy: the plan-gated feature is archiving itself, and those tiers keep the free `active` toggle on PATCH /api/providers/{id} instead. The tier is re-read from the database here rather than trusted from the caller.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "archiveProvider",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "responses": {
    "200": {
      "description": "Archived.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The plan does not include archiving (\"This plan doesn't include archiving. Use the Active toggle instead, which stays free\", Solo and Free), the staff member is already archived, they are the caller's own profile, they are the last admin, or an unhandled Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_staff` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No staff member with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Reactivate an archived staff member (admin, or manage_staff)",
  "description": "The exact inverse of POST /api/providers/{id}/archive, and it takes no request body at all: archiving kept everything except the photo, so `book_reactivate_provider()` only has to clear `archived_at` and, where a login was linked, that membership row's `suspended_at`.\n\nThe seat is reserved FIRST, before the person is restored, so an org that has since filled its plan refuses cleanly with the same 402 a brand-new hire would get rather than half-reactivating somebody the plan can no longer afford. Their archived-seat charge is dropped only once the reactivation has actually succeeded.\n\nNo sign-out is needed on the member's side: role and suspension are re-read from the roster on every dashboard request and were never cached in the JWT, so access returns on their very next request.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "reactivateProvider",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "responses": {
    "200": {
      "description": "Reactivated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "That staff member is not archived, or an unhandled Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "402": {
      "description": "The plan's seat cap is full and another seat cannot be billed (`reserveSeat`, src/lib/billing/seats.ts), so there is no room to bring this person back. Nothing was changed. Free a seat or upgrade, then retry; the archived record is untouched and keeps waiting.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_staff` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No staff member with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Upload a staff photo",
  "description": "Byte-for-byte the service-image route with the nouns swapped: bucket `staff-photos`, path `{companyId}/{providerId}`, same verify-then-upload ordering (the id is validated and the row confirmed to be the caller's before anything is written).",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "uploadProviderAvatar",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "required": [
            "file"
          ],
          "properties": {
            "file": {
              "type": "string",
              "format": "binary",
              "description": "PNG, JPEG or WebP, 2 MB or smaller. Anything else is a 400."
            }
          }
        },
        "encoding": {
          "file": {
            "contentType": "image/png, image/jpeg, image/webp"
          }
        }
      }
    },
    "description": "The staff photo. Sent as multipart/form-data under the field name `file`."
  },
  "responses": {
    "200": {
      "description": "Uploaded.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "avatarUrl"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "avatarUrl": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "No file, wrong MIME type, over 2 MB, or a storage error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No staff member with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Remove a staff photo",
  "description": "Deletes the stored object and nulls `avatar_url`.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteProviderAvatar",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "responses": {
    "200": {
      "description": "Removed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error updating the row.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No staff member with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Request a date-specific schedule override",
  "description": "Submit a one-date replacement for this provider's recurring hours (migration 0052); more hours, fewer, or none at all (a day off). The approve-immediately-or-queue decision is made INSIDE `book_submit_availability_override`, from the caller's role, the provider's `availability_delegation` tier, and the org's `availability_approval_horizon_days`, all read from the database inside the function's own transaction, never trusted from this request body, so calling the underlying RPC directly cannot produce a different outcome than this route does.\n\n**Ownership**: an admin may submit for any provider in the org; any other role only for the provider row linked to their own login. An unlinked staff login gets 403; a deliberate fail-closed departure from this codebase's usual fail-open convention for an unlinked staff member, because that convention protects a front-desk person's own usability, not license to edit someone else's schedule with no approval.\n\n**Conflicts** against existing, non-cancelled appointments on the date are checked live, unconditionally. A staff caller with a conflict is always hard-blocked (409, nothing persisted); they already have the tool to fix it themselves (reschedule/cancel their own booking). An admin caller may proceed by sending `conflictAcknowledged: true`.\n\nOn success, notifies the org's admins always, and the affected staff login too when the change applied without needing their own approval and they were not the one who submitted it (an admin acting on their behalf).",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "submitAvailabilityOverride",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "overrideDate"
          ],
          "additionalProperties": false,
          "properties": {
            "overrideDate": {
              "type": "string",
              "format": "date",
              "description": "Must not be in the past."
            },
            "windows": {
              "type": "array",
              "maxItems": 6,
              "items": {
                "type": "object",
                "required": [
                  "startTime",
                  "endTime"
                ],
                "additionalProperties": false,
                "properties": {
                  "startTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM."
                  },
                  "endTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM, must differ from startTime."
                  }
                }
              },
              "description": "Up to 6 windows for the one date. Empty means the whole day off."
            },
            "reason": {
              "type": "string",
              "maxLength": 300
            },
            "conflictAcknowledged": {
              "type": "boolean",
              "default": false,
              "description": "Admin only; ignored for any other caller, both here and inside the RPC."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Submitted; either pending or already applied, see `status`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "id",
              "status"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "approved"
                ]
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "An invalid date, malformed windows, a reason over 300 characters, or a Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Wrong engine for this org, or the caller is staff with no linked provider or a linked provider other than this one (\"You can only request a change to your own schedule\").",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No provider with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The proposed windows conflict with existing bookings on that date. Body includes `conflicts` (see GET /api/availability-overrides). A staff caller cannot proceed at all; an admin caller may resend with `conflictAcknowledged: true`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Mark a staff member away (admin, or manage_staff)",
  "description": "Writes a book_blocked_periods row (migration 0001) with this provider's id, covering `firstDay` 00:00 to `lastDay` 23:59:59 as one instant range: the same \"wall clock wearing a +00\" convention every other date-scoped write in this app uses. No engine change was needed to make this take effect. book_blocked_periods with a `provider_id` was already read on every public path that decides whether a provider is bookable (GET /api/book/{slug}/availability, POST /api/book/{slug}/appointments, the guest reschedule inside /api/book/{slug}/manage/{token}) before this route existed to write one. A `provider_id IS NULL` row is a DIFFERENT, older feature (a whole-venue closure, set from Organization > Special hours); this route never writes one.\n\n**Conflicts** against existing, non-cancelled appointments anywhere in the range are checked live, the same `findConflictingAppointments` pattern `POST /api/providers/{id}/availability-overrides` and `POST /api/organization/special-hours` already prove: refused with 409 unless `conflictAcknowledged: true`. Every caller who can reach this route already holds `manage_staff`, so unlike the override route there is no staff-vs-admin branch; acknowledgment alone is the gate, same as special-hours' own reasoning.\n\nSelf-service (a staff member marking their own leave) is deliberately out of scope: this is the same admin/manage_staff boundary as the rest of provider CRUD, not the tiered self-request flow `book_availability_overrides` uses.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createProviderBlockedPeriod",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "firstDay",
            "lastDay"
          ],
          "additionalProperties": false,
          "properties": {
            "firstDay": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD. The range must not have already fully passed."
            },
            "lastDay": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD. Must not be before firstDay."
            },
            "reason": {
              "type": "string",
              "maxLength": 300
            },
            "conflictAcknowledged": {
              "type": "boolean",
              "default": false
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Saved.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "blockedPeriod"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "blockedPeriod": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "starts_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "ends_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "reason": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "An invalid or backwards date range, a reason over 300 characters, or a Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_staff` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No provider with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The date range conflicts with existing bookings. Body includes `conflicts` (same shape as GET /api/availability-overrides). Resend with `conflictAcknowledged: true` to proceed anyway.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Remove a time-away entry (admin, or manage_staff)",
  "description": "The provider's ordinary hours (and any approved date-specific override) apply again over that range immediately. Scoped to both `id` and this provider: a bare id match would let a caller delete a whole-venue closure or another provider's entry by reusing a uuid from the same table.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteProviderBlockedPeriod",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider id."
    },
    {
      "name": "id",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The blocked-period row id."
    }
  ],
  "responses": {
    "200": {
      "description": "Removed, or already absent.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The query `id` is missing, or a Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_staff` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "The query `id` is not a well-formed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "List availability-override requests",
  "description": "Staff sees only their own linked provider's rows (server-forced, ignoring any client filter; there is none to send); admin sees every row across every status, so this one endpoint powers both a \"needs attention\" view (filter client-side on `status: pending`, or `approved` with `conflictAcknowledged` and `conflictCount > 0`) and a full history view.\n\n`conflictCount` is recomputed live on every call for an admin caller (always 0 for staff); migration 0052 deliberately does not persist which appointments conflicted, so a later cancellation or reassignment through the ordinary calendar screen makes a row stop needing attention with no write required.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "listAvailabilityOverrides",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "responses": {
    "200": {
      "description": "The list, newest date first.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "overrides"
            ],
            "properties": {
              "overrides": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "providerId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "providerName": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "overrideDate": {
                      "type": "string",
                      "format": "date"
                    },
                    "windows": {
                      "type": "array",
                      "maxItems": 6,
                      "items": {
                        "type": "object",
                        "required": [
                          "startTime",
                          "endTime"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "startTime": {
                            "type": "string",
                            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                            "description": "HH:MM."
                          },
                          "endTime": {
                            "type": "string",
                            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                            "description": "HH:MM, must differ from startTime."
                          }
                        }
                      },
                      "description": "Up to 6 windows for the one date. Empty means the whole day off."
                    },
                    "reason": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "maxLength": 300
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "approved",
                        "rejected",
                        "cancelled",
                        "superseded"
                      ]
                    },
                    "requiresApproval": {
                      "type": "boolean"
                    },
                    "autoApplyReason": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "trusted_tier",
                        "beyond_horizon",
                        "admin_direct",
                        null
                      ]
                    },
                    "createdByRole": {
                      "type": "string",
                      "enum": [
                        "admin",
                        "staff"
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "reviewedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "decisionNote": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "maxLength": 300
                    },
                    "conflictAcknowledged": {
                      "type": "boolean"
                    },
                    "conflictCount": {
                      "type": "integer",
                      "description": "Admin only, live-recomputed on every GET; always 0 in a staff response. Never persisted; see the route file for why."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error reading the rows.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Cancel or reject an availability-override request",
  "description": "Two plain status transitions on a `pending` row: `cancelled` (the staff member who owns the linked provider, on their own row, or any admin) and `rejected` (admin only). `approved` is deliberately refused here even though the request shape alone would not stop it; it is a special action (POST .../approve), same rule PATCH /api/waitlist/{id} enforces for `notified`. `superseded` is never client-settable at all.\n\nBoth transitions call a SECURITY INVOKER database function (`book_cancel_availability_override` / `book_decide_availability_override`, migration 0052) rather than writing the row directly; this table has no update policy for `authenticated` at all, so a raw PostgREST update would be refused the same way from anywhere else. The functions re-check role/ownership themselves from the database; this route's own gates are the ordinary UX path, not the enforcement.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "updateAvailabilityOverride",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Availability-override request id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status"
          ],
          "additionalProperties": false,
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "cancelled",
                "rejected"
              ]
            },
            "decisionNote": {
              "type": "string",
              "maxLength": 300,
              "description": "Only meaningful with `rejected`."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "An unknown status, one this route refuses (`approved`, `superseded`), a note over 300 characters, or a Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Wrong engine for this org, a non-admin sent `rejected`, or the function itself refused (staff trying to cancel someone else's row).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No request with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The request is not currently `pending`; it was already decided, cancelled, or superseded by a newer submission.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Approve a pending availability-override request",
  "description": "Admin only, mirroring POST /api/waitlist/{id}/offer's shape (a special action gets its own route rather than being a plain status PATCH). Re-runs the conflict check LIVE rather than trusting anything the client sends; a booking made after the request was submitted, or after the admin last looked at the list, must not be silently approved over.\n\n**Reassignment is not a parameter here.** The dashboard calls the existing, unmodified PATCH /api/appointments/{id} for each conflicting booking it wants to move, sequentially, BEFORE calling this route, never one endpoint doing both, so a failed reassignment cannot leave the override half-decided.\n\nNotifies the submitting staff member's linked login on success.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "approveAvailabilityOverride",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "x-required-role": "admin",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Availability-override request id."
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "conflictAcknowledged": {
              "type": "boolean",
              "default": false
            },
            "decisionNote": {
              "type": "string",
              "maxLength": 300
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Approved.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A note over 300 characters, or a Postgres error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. Covers three refusals: a `staff` member (this action is admin-only), an account with no organization or not on the roster, and **the engine boundary**: an org whose `business_type` is `hospitality` cannot reach the appointments engine at all.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No request with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The request is not currently `pending`, or it conflicts with existing bookings and `conflictAcknowledged` was not sent (body includes `conflicts`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Create an appointment, or a repeat series (staff side)",
  "description": "A booking taken by staff; a phone call, a walk-in. Deliberately NOT slot-validated the way guest checkout is: staff have the calendar in front of them, and `book_appointments_no_overlap` (a Postgres exclusion constraint) is the real backstop either way.\n\n`price`, `duration_minutes` and `ends_at` are all snapshotted from the chosen service; sending them is not possible and would not be honoured. Status is always `confirmed`.\n\n**Repeats (migration 0149).** An optional `repeats` object turns this into a series: every so-many weeks, on one or more weekdays, ending after a number of visits or on a date. When present it REPLACES `startsAt` entirely (`repeats.startsOn` + `repeats.timeOfDay` already say when the first visit is) and the response shape changes; see the 200 below. Deliberately the only creation surface a repeat series gets: not the public booking widget, and not the hospitality engine. `book_appointments_no_overlap` is still what actually prevents double-booking a generated date; a date that conflicts is skipped, not fatal to the rest of the series, matching the shipped feature this follows (\"dates that don't fit... can be skipped\"). One `series_confirmed` notification job is queued for the whole series, not one `booking_confirmed` per visit: each visit still gets its own reminder for free, since it is an ordinary row the existing reminder cron already reaches, and can still be individually moved or cancelled through this same PATCH/route below exactly like any other booking.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createAppointment",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "description": "The client is given one of two ways, matching the picker on the dashboard: **either** `customerId` for someone already on the roster, **or** `customerName` and `customerPhone` (plus optionally an email) to find-or-create one. When `customerId` is present the typed fields are ignored entirely.\n\n`customerPhone` is required on the typed branch and only there. The check lives in `resolveOrCreateCustomer`, the single writer that creates a client from typed details, so it applies identically here, on `POST /api/reservations` and on `POST /api/clients`. Picking an existing client short-circuits to their id and never reaches it, which is what keeps a regular who predates the rule bookable.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "serviceId",
            "providerId",
            "startsAt"
          ],
          "properties": {
            "serviceId": {
              "type": "string",
              "format": "uuid"
            },
            "providerId": {
              "type": "string",
              "format": "uuid"
            },
            "startsAt": {
              "type": "string",
              "format": "date-time",
              "description": "Anything Date.parse accepts. Stored as ISO 8601 UTC. Ignored when `repeats` is present."
            },
            "notes": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 1000,
              "description": "The guest's request for this visit."
            },
            "repeats": {
              "type": [
                "object",
                "null"
              ],
              "description": "Present to create a series instead of one booking. Exactly one of `endsOn`/`occurrenceCount` must be set, never both or neither.",
              "properties": {
                "intervalWeeks": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 4,
                  "description": "1 = weekly, 2 = fortnightly, up to every 4 weeks."
                },
                "weekdays": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6
                  },
                  "minItems": 1,
                  "description": "0 = Sunday. A Monday-and-Friday plan is one series with two entries."
                },
                "timeOfDay": {
                  "type": "string",
                  "description": "\"HH:MM\", every visit's start time."
                },
                "startsOn": {
                  "type": "string",
                  "format": "date",
                  "description": "The first visit's date. Must not be in the past."
                },
                "endsOn": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date"
                },
                "occurrenceCount": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 52
                }
              }
            },
            "customerId": {
              "type": "string",
              "format": "uuid",
              "description": "An existing client in this org. A foreign or unknown id is a 400 (\"Client not found\")."
            },
            "customerName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Required when `customerId` is absent."
            },
            "customerEmail": {
              "type": [
                "string",
                "null"
              ],
              "format": "email",
              "maxLength": 254,
              "description": "Lowercased. Matches an existing client on (company_id, email) and updates that record rather than creating a second one. Omit and a fresh, undeduplicated record is always created: there is no other dedup key."
            },
            "customerPhone": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "description": "Required when `customerId` is absent; see the note above. A blank or missing number is a 400 (\"A contact number is required\") from `resolveOrCreateCustomer`, after the other field validation."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created. Two shapes, dispatched on whether `repeats` was sent. Without it: the bare `{id}` this route has always returned (this and POST /api/reservations are the only two routes that do). With it: a series summary of `seriesId`, `createdCount` (visits actually booked), `requestedCount` (dates the rule generated), and `skippedDates` (an array of `YYYY-MM-DD` strings for any date `book_appointments_no_overlap` refused).",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "seriesId": {
                "type": "string",
                "format": "uuid"
              },
              "createdCount": {
                "type": "integer"
              },
              "requestedCount": {
                "type": "integer"
              },
              "skippedDates": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "date"
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message; \"Service not found\" or \"Client not found\" for an id outside this org (400, not 404; these arrive in the body, not the path); \"That staff member no longer exists\" from the composite foreign key; or, for a `repeats` request, a message from `parseSeriesRule`/`generateSeriesDates` (a malformed rule, or one that would generate more than 52 visits).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Without `repeats`: `book_appointments_no_overlap` fired; that staff member already has a booking overlapping this window. Note the asymmetry with reservations: only `cancelled` releases an appointment slot, so `no_show` and `completed` still block it. With `repeats`: every generated date conflicted, so nothing was created and the series definition itself was not kept.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Whether this booking is part of a repeat series",
  "description": "One id in, one (possibly null) id out. Its own tiny route rather than folding `seriesId` into GET /api/appointments/{id}'s already-large select: `series_id` (migration 0149) is a brand-new column, and the same \"isolated, tolerated read\" a brand-new column always gets here (see loadCardOnFileForBooking in lib/billing/checkout.ts for the precedent): folding it into a shared select would 42703 the WHOLE row for every booking on screen the moment this column isn't confirmed live yet, not just this one field. What BookingDetailDialog fetches once on open to decide whether to offer \"End series\" at all.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "getAppointmentSeriesMembership",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Appointment id."
    }
  ],
  "responses": {
    "200": {
      "description": "Series membership.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "seriesId"
            ],
            "properties": {
              "seriesId": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Read one repeat series and its visits",
  "description": "The series row plus every book_appointments row it generated, in date order, each with its OWN current status, not just the ones still upcoming. What the \"End series\" confirm step (BookingDetailDialog) reads to say how many visits are actually about to be cancelled, versus already past or already cancelled individually; that distinction needs the full list, not a second round trip filtered ahead of time.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "getBookingSeries",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "book_booking_series id."
    }
  ],
  "responses": {
    "200": {
      "description": "The series and its visits.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "series",
              "visits"
            ],
            "properties": {
              "series": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "ended",
                      "cancelled"
                    ]
                  }
                }
              },
              "visits": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "starts_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "confirmed",
                        "cancelled",
                        "completed",
                        "no_show"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No series with this id for this company.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "End a series early",
  "description": "\"End a series early from any of its visits: the rest cancel in one go and the customer hears once\" (the shipped spec this follows). Only `{\"status\":\"cancelled\"}` is accepted: there is no other transition a series makes.\n\nCancels every visit in the series that is both in the future AND not already `cancelled`/`completed`; a visit that already happened, or was cancelled individually by the guest or staff before this ran, is left exactly as it was rather than double-touched. `book_booking_series.status` flips to `cancelled` in the same action, which is what refuses a second call on an already-ended series with 409. One `series_cancelled` notification job is queued for the whole batch, not one per visit.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "endBookingSeries",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "book_booking_series id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status"
          ],
          "properties": {
            "status": {
              "const": "cancelled"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Ended.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "cancelledCount"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "cancelledCount": {
                "type": "integer",
                "description": "How many visits this call actually cancelled."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`status` was anything other than `\"cancelled\"`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No series with this id for this company.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "This series was already cancelled.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Read one booking",
  "description": "The single-booking twin of the row builder behind the Bookings list: same embeds, same staff-scope confinement, same redaction. Exists so Calendar can pop the exact same BookingDetailDialog in place on a click, instead of navigating to /dashboard/main/bookings?open=id and stranding the viewer on a different page once they close it.\n\nStaff-scope and redaction both follow docs/staff-privacy.md: a scoped staff member reaching a colleague's booking gets a 403, not a 404, since reads are filtered rather than hidden; and a staff caller's view of the customer is redacted per the org's staffClientVisibility setting, using this booking's own providerConfirmed as the anonymized-mode grant.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "getAppointment",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Appointment id."
    }
  ],
  "responses": {
    "200": {
      "description": "The booking, with an unread-message count and its service, staff and customer fields resolved.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "row"
            ],
            "properties": {
              "row": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "startsAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "endsAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "confirmed",
                      "cancelled",
                      "completed",
                      "no_show"
                    ]
                  },
                  "price": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "notes": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "serviceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "providerId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "Nullable as of migration 0051: a permanently deleted staff member leaves this null and keeps `providerName` instead."
                  },
                  "durationMinutes": {
                    "type": "integer"
                  },
                  "depositStatus": {
                    "type": "string",
                    "enum": [
                      "none",
                      "pending",
                      "paid",
                      "refunded",
                      "forfeited"
                    ]
                  },
                  "unreadCount": {
                    "type": "integer",
                    "description": "Unread guest messages on this booking's thread, the same definition the Inbox and the bookings list use."
                  },
                  "serviceName": {
                    "type": "string",
                    "description": "\"(deleted service)\" when the service no longer exists."
                  },
                  "itemNames": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "A multi-service visit's (migration 0054) line items, in position order. Empty for a single-service booking."
                  },
                  "serviceColor": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "providerName": {
                    "type": "string",
                    "description": "\"(no longer on staff)\" when the provider row has been deleted."
                  },
                  "providerConfirmed": {
                    "type": "boolean",
                    "description": "False on an \"Available specialist\" booking the system auto-assigned but nobody has confirmed yet (migration 0080)."
                  },
                  "customerName": {
                    "type": "string",
                    "description": "Redacted for a scoped staff member per the org's staffClientVisibility, same as the bookings list. \"(unknown)\" when no customer is linked."
                  },
                  "customerEmail": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "customerPhone": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No booking with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Update an appointment",
  "description": "A true partial update: only keys actually present in the body are written, so the drawer's `{status}`-only call cannot blank a field it never mentioned.\n\nDerived fields, none of which the caller may set: sending `serviceId` re-snapshots `price` and `duration_minutes` from the service actually chosen; `ends_at` is always recomputed from `starts_at` + duration. `phone` is a shortcut to the linked client's record and updates it everywhere that client appears.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "updateAppointment",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Appointment id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "minProperties": 1,
          "additionalProperties": false,
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "confirmed",
                "cancelled",
                "completed",
                "no_show"
              ],
              "description": "Transitioning INTO `cancelled` sends the cancellation notification once; re-cancelling an already-cancelled booking does not."
            },
            "serviceId": {
              "type": "string",
              "format": "uuid",
              "description": "Refused with a 409 on a multi-service visit (0054): the row's price/duration are TOTALS and the breakdown lives in book_appointment_services, so a single-service swap would orphan the itemization. Time, status, staff and notes edits all still work on such rows."
            },
            "providerId": {
              "type": "string",
              "format": "uuid",
              "description": "Cannot be empty; an appointment with no provider is not a legal state."
            },
            "startsAt": {
              "type": "string",
              "format": "date-time"
            },
            "notes": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 1000
            },
            "phone": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 40,
              "description": "Writes to book_customers, not to this booking. May be corrected but not removed: an explicit null is a 400 when the guest already has a number, and a no-op when they do not, the same rule `PATCH /api/reservations/{id}` and `PATCH /api/clients/{id}` apply to the same column."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid status, invalid date, over-length notes, an unknown service, or \"Nothing to change\" when the body contained no recognised key.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No appointment with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The new time collides with another booking for that staff member, or `serviceId` was sent for a multi-service visit (see its property note).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "List appointments (API key)",
  "description": "The appointments engine's bookings, for a program.\n\nOrdered newest first, which is what a human wants and the wrong order for \"what is on today\": that is what `from` and `to` are for, and they are the reason this is one of only two v1 lists with filters. The configuration lists (services, staff, tables, service periods) are bounded by how many a business has, so one page is the whole list; bookings are unbounded and time-shaped.\n\nThe engine boundary holds here exactly as it does on the session routes: the gate takes the same `BusinessType` argument `requireMember()` takes, so a hospitality organization's key is refused with `wrong_vertical`. A key must not be a way around a boundary the session routes hold. It is enforced twice over, in fact: `appointments:*` scopes cannot even be *granted* to a hospitality org at issuance.\n\nTenancy comes from the key row's stored `company_id` and nothing else. There is no Supabase JWT behind an API key, so RLS has no claim to read and is **not** a second line of defence: the explicit `company_id` filter in the handler is the entire tenant boundary. A static check asserts that filter exists on every key-authenticated route.\n\n**Two clocks in one object.** `startsAt` and `endsAt` are the venue's wall clock wearing a `+00` suffix; `createdAt` is a true UTC instant. They serialise identically and there is no way to tell them apart from the payload, so a caller that parses the whole object one way is wrong about one of them by the venue's entire UTC offset. `from` and `to` filter on the same wall clock `startsAt` does. Resolve the venue's zone from `timezone` on `GET /api/v1/organization`, which needs the separate `organization:read` scope. See the timestamps section of `docs/api-keys.md`.\n\nOrdered newest first.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "listAppointmentsV1",
  "security": [
    {
      "bearerApiKey": [
        "appointments:read"
      ]
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A `?limit=1e9` from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop."
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "The `nextCursor` from the previous response, passed back unchanged. Omit it for the first page. **Opaque**: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a `400 invalid_cursor` rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.\n\nThe scheme is keyset (seek) paging on `(order column, id)`, not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and `limit` may change between pages; the cursor only says *where you got to*."
    },
    {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "Inclusive lower bound on `startsAt`. Any timestamp Postgres accepts; a value it rejects is a 400. Combine with `to` for a day or a week.\n\n**Compared against `startsAt`, so it is in the venue's wall clock, not UTC**, whatever offset you write on it. `from=2026-08-20T00:00:00Z` means midnight at the venue, not midnight UTC, and the `Z` is not honoured. To ask for a venue's day, write that day's local midnight and ignore the offset. Asking in real UTC instead returns a window shifted by the venue's offset, which for an Australian venue is most of a different day."
    },
    {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "EXCLUSIVE upper bound on `startsAt`. Exclusive so that `from=2026-07-26T00:00:00&to=2026-07-27T00:00:00` is exactly one day with no double-counting at the seam. **That day is the venue's, not UTC**: like `from`, this is compared against the venue's wall clock and any offset you write is ignored."
    }
  ],
  "responses": {
    "200": {
      "description": "The appointments, newest first.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data",
              "nextCursor"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "camelCase. There is no embedded service, provider or customer object; you get their ids, and `GET /api/v1/services` and `GET /api/v1/providers` resolve them. Three columns are withheld: `manage_token` (the entire credential for the guest self-service link, handing it to a program hands over the ability to act as the guest), `internal_note` (the venue's private note, excluded for the same reason `book_customers.notes` is), and `stripe_payment_intent_id` (an identifier in somebody else's system).",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "startsAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "**The venue's local wall clock, not a UTC instant, despite the `+00` suffix.** A 19:00 booking at a Sydney venue is returned as `2026-08-20T19:00:00+00`, not as the `09:00Z` that instant really is. Read the digits as local time and ignore the offset, or convert properly using `timezone` from `GET /api/v1/organization`. Do not hand it to a UTC-aware parser and render the result in the reader's zone: that shifts every booking by the venue's whole offset, ten or eleven hours for an Australian venue. `createdAt` in this same object IS a true instant, so the two cannot be treated alike. See the timestamps section of `docs/api-keys.md`."
                    },
                    "endsAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "**The venue's local wall clock, not a UTC instant, despite the `+00` suffix.** A 19:00 booking at a Sydney venue is returned as `2026-08-20T19:00:00+00`, not as the `09:00Z` that instant really is. Read the digits as local time and ignore the offset, or convert properly using `timezone` from `GET /api/v1/organization`. Do not hand it to a UTC-aware parser and render the result in the reader's zone: that shifts every booking by the venue's whole offset, ten or eleven hours for an Australian venue. `createdAt` in this same object IS a true instant, so the two cannot be treated alike. See the timestamps section of `docs/api-keys.md`."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "confirmed",
                        "cancelled",
                        "completed",
                        "no_show"
                      ]
                    },
                    "durationMinutes": {
                      "type": "integer"
                    },
                    "price": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "notes": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The customer's request for this booking, as they typed it."
                    },
                    "serviceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "providerId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid"
                    },
                    "customerId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "depositStatus": {
                      "type": "string",
                      "enum": [
                        "none",
                        "pending",
                        "paid",
                        "refunded",
                        "forfeited"
                      ]
                    },
                    "depositAmountCents": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "A **true UTC instant** (the row's `now()` default), unlike `startsAt`/`endsAt` above. Parse and render this one normally."
                    }
                  }
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Pass to `?cursor=` for the next page. **`null` means there are no more rows**: always present, never absent and never undefined, so a caller does not have to distinguish the two. It is exact rather than optimistic: the handler fetches `limit + 1` rows and reports the extra one as a cursor, so N pages take N requests, not N+1."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "400": {
      "description": "Two causes, distinguishable by whether `code` is present. **`invalid_cursor`**: the `cursor` was not one this API issued. **A malformed `from` or `to`**: Postgres rejected the timestamp, and the body is its message with **no `code`**, since it did not come from the gate. Both are the caller's input, which is why neither is a 500.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "const": "invalid_cursor"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "The credential itself is not usable. Stop and fix the key, do not retry. `missing_authorization`: no `Authorization: Bearer` header. `invalid_key`: wrong format, unknown key id, or digest mismatch (these are one code on purpose: distinguishing them would confirm which key ids exist). `key_revoked` / `key_expired`: reported distinctly, which is safe because both are only reachable after the digest already matched, so only the legitimate holder ever sees them. `organization_inactive`: the org itself is switched off, so none of its keys work.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "missing_authorization",
                  "invalid_key",
                  "key_revoked",
                  "key_expired",
                  "organization_inactive"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The credential is fine but may not do this. Stop and fix the request, or re-issue the key with more scopes. `insufficient_scope`: the key does not hold the scope named in `required_scope`. `wrong_vertical`: **the engine boundary**, this operation belongs to the appointments engine and the key belongs to a hospitality organization. Checked BEFORE scope, so the key is told the truth (wrong product) rather than being told to add a scope its org can never be granted, verified by attacking it: a key that DOES hold the scope is still refused with `wrong_vertical`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "insufficient_scope",
                  "wrong_vertical"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "429": {
      "description": "Per-key fixed-window rate limit exceeded. The counter is incremented as soon as the caller is *identified*, before scope is checked, so a key hammering endpoints it has no scope for is still throttled. Honest limitation: a fixed window allows up to 2x the limit across a boundary; the limit exists to stop a runaway script and bound database load, not to meter billing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "rate_limited"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "Seconds until the window ends."
        },
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "500": {
      "description": "The query failed. The body is the raw Postgres message and carries no `code`, unlike the gate's own errors above.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": []
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    }
  }
}

{
  "summary": "List services (API key)",
  "description": "The appointments engine's bookable services. Engine-guarded: a hospitality organization's key is refused with `wrong_vertical` **even if it holds `services:read` and even if the org has `book_services` rows**, the boundary is about what the organization IS, not about what happens to be in its tables.\n\n**Ordered by `id`, which is stable but arbitrary.** `book_services` has no `created_at` (none of the four configuration tables do), and keyset paging needs a column that is both unique and stable, so `id` is the only candidate. Not worth a migration: a business sells tens of services, so the first page of 200 is the whole list in practice, and a caller wanting them alphabetical can sort them itself. Documented rather than hidden.\n\n`active: false` rows ARE returned. A program reconciling against its own copy needs to see a service that was switched off, not have it silently disappear; the public booking widget is where `active` is filtered.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "listServicesV1",
  "security": [
    {
      "bearerApiKey": [
        "services:read"
      ]
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A `?limit=1e9` from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop."
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "The `nextCursor` from the previous response, passed back unchanged. Omit it for the first page. **Opaque**: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a `400 invalid_cursor` rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.\n\nThe scheme is keyset (seek) paging on `(order column, id)`, not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and `limit` may change between pages; the cursor only says *where you got to*."
    }
  ],
  "responses": {
    "200": {
      "description": "The services.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data",
              "nextCursor"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "camelCase.",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "durationMinutes": {
                      "type": "integer"
                    },
                    "price": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Null means \"no price shown\"."
                    },
                    "color": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "One of SERVICE_COLORS: the swatch the dashboard and the widget draw this service in."
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "imageUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Pass to `?cursor=` for the next page. **`null` means there are no more rows**: always present, never absent and never undefined, so a caller does not have to distinguish the two. It is exact rather than optimistic: the handler fetches `limit + 1` rows and reports the extra one as a cursor, so N pages take N requests, not N+1."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "400": {
      "description": "`invalid_cursor`: the `cursor` was not one this API issued. Pass back `nextCursor` unchanged; do not construct one.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_cursor"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "The credential itself is not usable. Stop and fix the key, do not retry. `missing_authorization`: no `Authorization: Bearer` header. `invalid_key`: wrong format, unknown key id, or digest mismatch (these are one code on purpose: distinguishing them would confirm which key ids exist). `key_revoked` / `key_expired`: reported distinctly, which is safe because both are only reachable after the digest already matched, so only the legitimate holder ever sees them. `organization_inactive`: the org itself is switched off, so none of its keys work.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "missing_authorization",
                  "invalid_key",
                  "key_revoked",
                  "key_expired",
                  "organization_inactive"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The credential is fine but may not do this. Stop and fix the request, or re-issue the key with more scopes. `insufficient_scope`: the key does not hold the scope named in `required_scope`. `wrong_vertical`: **the engine boundary**, this operation belongs to the appointments engine and the key belongs to a hospitality organization. Checked BEFORE scope, so the key is told the truth (wrong product) rather than being told to add a scope its org can never be granted, verified by attacking it: a key that DOES hold the scope is still refused with `wrong_vertical`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "insufficient_scope",
                  "wrong_vertical"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "429": {
      "description": "Per-key fixed-window rate limit exceeded. The counter is incremented as soon as the caller is *identified*, before scope is checked, so a key hammering endpoints it has no scope for is still throttled. Honest limitation: a fixed window allows up to 2x the limit across a boundary; the limit exists to stop a runaway script and bound database load, not to meter billing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "rate_limited"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "Seconds until the window ends."
        },
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "500": {
      "description": "The query failed. The body is the raw Postgres message and carries no `code`, unlike the gate's own errors above.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": []
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    }
  }
}

{
  "summary": "List staff (API key)",
  "description": "The appointments engine's staff members. Engine-guarded, ordered by `id`: see `GET /api/v1/services` for why.\n\n**`serviceIds` is the one place a v1 list does more than select a row**, and it earns the exception twice over: which services a staff member can perform is the fact a program needs before it can offer anyone a slot, and the field is not invented here. The public booking config already exposes `serviceIds` per provider, and `POST /api/providers` already *accepts* it. Omitting it would be the inconsistency.\n\nIt comes from a second query against the link table, filtered by the key's own `company_id` rather than trusting the ids from the first. The link table carries its own `company_id` for exactly that reason (migration 0013). Two queries rather than a PostgREST embed, so the link table's name never becomes part of this contract.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "listProvidersV1",
  "security": [
    {
      "bearerApiKey": [
        "providers:read"
      ]
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A `?limit=1e9` from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop."
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "The `nextCursor` from the previous response, passed back unchanged. Omit it for the first page. **Opaque**: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a `400 invalid_cursor` rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.\n\nThe scheme is keyset (seek) paging on `(order column, id)`, not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and `limit` may change between pages; the cursor only says *where you got to*."
    }
  ],
  "responses": {
    "200": {
      "description": "The staff members.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data",
              "nextCursor"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "camelCase.",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "email"
                    },
                    "bio": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "title": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The public team page's role line, e.g. \"Owner & Colorist\"."
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "avatarUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "serviceIds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "description": "The services this staff member can perform. Empty array, never absent."
                    }
                  }
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Pass to `?cursor=` for the next page. **`null` means there are no more rows**: always present, never absent and never undefined, so a caller does not have to distinguish the two. It is exact rather than optimistic: the handler fetches `limit + 1` rows and reports the extra one as a cursor, so N pages take N requests, not N+1."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "400": {
      "description": "`invalid_cursor`: the `cursor` was not one this API issued. Pass back `nextCursor` unchanged; do not construct one.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_cursor"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "The credential itself is not usable. Stop and fix the key, do not retry. `missing_authorization`: no `Authorization: Bearer` header. `invalid_key`: wrong format, unknown key id, or digest mismatch (these are one code on purpose: distinguishing them would confirm which key ids exist). `key_revoked` / `key_expired`: reported distinctly, which is safe because both are only reachable after the digest already matched, so only the legitimate holder ever sees them. `organization_inactive`: the org itself is switched off, so none of its keys work.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "missing_authorization",
                  "invalid_key",
                  "key_revoked",
                  "key_expired",
                  "organization_inactive"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The credential is fine but may not do this. Stop and fix the request, or re-issue the key with more scopes. `insufficient_scope`: the key does not hold the scope named in `required_scope`. `wrong_vertical`: **the engine boundary**, this operation belongs to the appointments engine and the key belongs to a hospitality organization. Checked BEFORE scope, so the key is told the truth (wrong product) rather than being told to add a scope its org can never be granted, verified by attacking it: a key that DOES hold the scope is still refused with `wrong_vertical`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "insufficient_scope",
                  "wrong_vertical"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "429": {
      "description": "Per-key fixed-window rate limit exceeded. The counter is incremented as soon as the caller is *identified*, before scope is checked, so a key hammering endpoints it has no scope for is still throttled. Honest limitation: a fixed window allows up to 2x the limit across a boundary; the limit exists to stop a runaway script and bound database load, not to meter billing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "rate_limited"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "Seconds until the window ends."
        },
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "500": {
      "description": "The query failed. The body is the raw Postgres message and carries no `code`, unlike the gate's own errors above.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": []
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    }
  }
}

{
  "summary": "Create a product",
  "description": "Adds a retail catalog item. `company_id` comes from the verified JWT claim, never the body. `stockOnHand` is the opening count, written directly ONLY on create: every change after this goes through POST /api/products/{id}/stock, which records a reason. **Appointments only** as of 2026-09-06: see migration 0200's own comment for why hospitality never had a real equivalent here at all, and /api/experiences for the screen it actually gets.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createProduct",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name",
            "price"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "sku": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 60
            },
            "price": {
              "type": "number",
              "minimum": 0,
              "maximum": 100000,
              "description": "Dollars (or the venue currency's major unit). Coerced with Number(), converted to price_cents = round(price * 100)."
            },
            "categoryId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The product category this sits in (migration 0176). Null or omitted means uncategorised. Tenancy is enforced by the composite FK, so another org's category id, or a deleted one, comes back as a 400 \"Category not found\"."
            },
            "lowStockAt": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "maximum": 100000,
              "description": "The threshold the Products list flags as running low. Null/omitted means tracking stays quiet, distinct from 0, a real \"tell me the moment this hits zero\" threshold."
            },
            "stockOnHand": {
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "description": "The opening count. Defaults to 0 if omitted."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "product"
            ],
            "properties": {
              "product": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseProductInput, \"Stock on hand must be a whole number, 0 or more\", \"Category not found\" for a categoryId that is not this org's (FK 23503), or the raw Postgres message if the insert itself failed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Update a product, or archive/restore it",
  "description": "Two shapes in one route. A body of exactly `{\"archived\": true|false}` sets/clears `archived_at` and returns immediately, no other field required. Any other body is a full replacement of the catalog fields (parseProductInput's contract); `stockOnHand` is never accepted here, only through POST /api/products/{id}/stock. RLS scopes the update, so an id from another org matches zero rows and returns 404. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "updateProduct",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Product id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "required": [
                "archived"
              ],
              "additionalProperties": false,
              "properties": {
                "archived": {
                  "type": "boolean"
                }
              }
            },
            {
              "type": "object",
              "required": [
                "name",
                "price"
              ],
              "additionalProperties": false,
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 500
                },
                "sku": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 60
                },
                "price": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100000,
                  "description": "Dollars (or the venue currency's major unit). Coerced with Number(), converted to price_cents = round(price * 100)."
                },
                "categoryId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uuid",
                  "description": "The product category this sits in (migration 0176). Null or omitted means uncategorised. Tenancy is enforced by the composite FK, so another org's category id, or a deleted one, comes back as a 400 \"Category not found\"."
                },
                "lowStockAt": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 0,
                  "maximum": 100000,
                  "description": "The threshold the Products list flags as running low. Null/omitted means tracking stays quiet, distinct from 0, a real \"tell me the moment this hits zero\" threshold."
                }
              }
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseProductInput, or \"Category not found\" for a categoryId that is not this org's (FK 23503).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No product with that id in this org. A malformed uuid (Postgres 22P02) is mapped here rather than surfacing as a 500.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Upload a product image",
  "description": "Stores the file at `{companyId}/{productId}` in the `product-images` bucket and writes a cache-busted public URL onto the product row. Not gated on `manage_services`: a photo is part of editing the product, same posture as the equivalent service-image route. Ownership is checked BEFORE the upload, so a request naming a product the caller does not own is a 404 with nothing written. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "uploadProductImage",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Product id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "required": [
            "file"
          ],
          "properties": {
            "file": {
              "type": "string",
              "format": "binary",
              "description": "PNG, JPEG or WebP, 2 MB or smaller. Anything else is a 400."
            }
          }
        },
        "encoding": {
          "file": {
            "contentType": "image/png, image/jpeg, image/webp"
          }
        }
      }
    },
    "description": "The product image. Sent as multipart/form-data under the field name `file`."
  },
  "responses": {
    "200": {
      "description": "Uploaded.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "imageUrl"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "imageUrl": {
                "type": "string",
                "format": "uri",
                "description": "Public URL with a `?v=<timestamp>` cache-buster; the storage path itself never changes."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "No file, wrong MIME type, over 2 MB, or a storage error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No product with that id in this org. Nothing was uploaded; the ownership check runs first.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Remove a product image",
  "description": "Deletes the stored object and nulls `image_url`. Storage removal is best-effort and its failure does not fail the request. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteProductImage",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Product id."
    }
  ],
  "responses": {
    "200": {
      "description": "Removed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error updating the row.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No product with that id in this org.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "A product's recent stock movements",
  "description": "The last 20 rows off the append-only book_product_stock_movements ledger, newest first: backs the Adjust stock dialog's own recent-movements list. RLS-scoped read; any signed-in member may read it, no `manage_services` gate. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "listProductStockMovements",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Product id."
    }
  ],
  "responses": {
    "200": {
      "description": "Up to 20 movements.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "movements"
            ],
            "properties": {
              "movements": {
                "type": "array",
                "maxItems": 20,
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "reason": {
                      "type": "string",
                      "enum": [
                        "received",
                        "stocktake",
                        "damaged",
                        "adjustment",
                        "sale",
                        "sale_undo"
                      ]
                    },
                    "delta": {
                      "type": "integer",
                      "description": "Signed. Negative for a removal."
                    },
                    "resulting_stock": {
                      "type": "integer"
                    },
                    "note": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error reading the rows.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Adjust a product's stock",
  "description": "Three reasons, two shapes. `received` and `damaged` send a signed `delta` (the route itself flips the sign for `damaged` client-side, BeNotely's own \"how many you're removing\" framing, never a typed minus). `stocktake` sends the counted `count` instead; book_product_stock_adjust() (migration 0176) computes the delta against the LIVE, row-locked current value, never a value the client read moments earlier. Every call writes a reasoned book_product_stock_movements row. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "adjustProductStock",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Product id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "reason"
          ],
          "properties": {
            "reason": {
              "type": "string",
              "enum": [
                "received",
                "stocktake",
                "damaged"
              ]
            },
            "delta": {
              "type": "integer",
              "description": "Required (and must be non-zero) when reason is `received` or `damaged`. Ignored for `stocktake`."
            },
            "count": {
              "type": "integer",
              "minimum": 0,
              "description": "Required (0 or more) when reason is `stocktake`: the counted total on the shelf, not a delta."
            },
            "note": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 300
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Adjusted.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "stockOnHand"
            ],
            "properties": {
              "stockOnHand": {
                "type": "integer",
                "description": "The new count after this adjustment."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Reason missing/unrecognised, `delta`/`count` missing or invalid for the chosen reason, or the RPC's own error message.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No product with that id in this org, or it is archived: book_product_stock_adjust() only matches a live row.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Create a product category",
  "description": "A named shelf products hang off on the Products list (\"Hair care\", \"Tools\"), purely for finding things; it never changes a price (migration 0176). New categories land at the end of the shelf (`sort_order = max+1`). v1 is flat, name-only: no rename or reorder route exists yet. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "createProductCategory",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "category"
            ],
            "properties": {
              "category": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Name missing or over 60 characters, or the raw Postgres message if the insert itself failed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Delete a product category",
  "description": "Never blocks and never takes products with it: the composite FK's column-scoped `on delete set null (category_id)` (0176) un-groups them in the same statement, same shape book_service_groups' own DELETE takes. **Appointments only**, see POST /api/products.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "deleteProductCategory",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Category id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error other than the not-found case below.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_services` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No category with that id in this org, or a malformed uuid.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Read the venue opening hours (admin, or manage_org_settings)",
  "description": "Venue-level opening hours (`book_company_hours`, migration 0027); \"when is the business open\", as distinct from a staff member's own working hours. `computeAvailableSlots` intersects the two, so a booking must fit inside both. Times come back as HH:MM, ordered by day then start time. Appointments only: a hospitality org uses `book_service_periods`, which already carries the lunch/dinner split plus turn time, last seating and covers caps. Gated to admin, or a staff login granted `manage_org_settings` (migration 0082).",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "getOrganizationHours",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "responses": {
    "200": {
      "description": "The configured week. An empty array means no venue restriction.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "hours"
            ],
            "properties": {
              "hours": {
                "type": "array",
                "maxItems": 21,
                "items": {
                  "type": "object",
                  "required": [
                    "dayOfWeek",
                    "startTime",
                    "endTime"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "dayOfWeek": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6,
                      "description": "0 = Sunday, matching `Date#getUTCDay()`."
                    },
                    "startTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM."
                    },
                    "endTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM, strictly after startTime."
                    }
                  }
                },
                "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error reading the rows.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_org_settings` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Replace the venue opening hours (admin, or manage_org_settings)",
  "description": "PUT, not PATCH: the editor holds the whole week and a window has no stable identity in it, so \"these are the hours\" is the only honest request shape. **An empty array means NO VENUE RESTRICTION, not \"closed all week\"**: zero rows has to keep meaning unclamped, because that is the state every org is in until it saves hours here, and any other reading would take every existing booking page to zero availability. Delete-then-insert over PostgREST is two transactions; if the insert fails the org is left with no rows, which fails permissive (staff hours alone apply) and is reported as such. Gated to admin, or a staff login granted `manage_org_settings` (migration 0082).",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "replaceOrganizationHours",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "hours"
          ],
          "additionalProperties": false,
          "properties": {
            "hours": {
              "type": "array",
              "maxItems": 21,
              "items": {
                "type": "object",
                "required": [
                  "dayOfWeek",
                  "startTime",
                  "endTime"
                ],
                "additionalProperties": false,
                "properties": {
                  "dayOfWeek": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6,
                    "description": "0 = Sunday, matching `Date#getUTCDay()`."
                  },
                  "startTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM."
                  },
                  "endTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                    "description": "HH:MM, strictly after startTime."
                  }
                }
              },
              "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Saved. Echoes the stored week back.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "hours"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "hours": {
                "type": "array",
                "maxItems": 21,
                "items": {
                  "type": "object",
                  "required": [
                    "dayOfWeek",
                    "startTime",
                    "endTime"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "dayOfWeek": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6,
                      "description": "0 = Sunday, matching `Date#getUTCDay()`."
                    },
                    "startTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM."
                    },
                    "endTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                      "description": "HH:MM, strictly after startTime."
                    }
                  }
                },
                "description": "Up to 21 windows (3 a day for a week). Repeat a `dayOfWeek` to give that day a second window; the gap between the two is not bookable. Windows are not checked for overlapping each other; an overlap costs nothing downstream."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseHoursWindows, or a Postgres error clearing the old rows.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_org_settings` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "The insert failed after the clear; the opening hours are now unset and the message says so.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Save a page's draft content (admin, or manage_org_settings)",
  "description": "Writes `draft_content` ONLY; the live site (`published_content`) never moves until POST .../publish. `book_site_pages` (migration 0112), upserted rather than updated because a company that has never had this page edited before has no row yet. Gated the same way /api/organization/hours gates general org settings: admin, or a staff member holding `manage_org_settings` (0082). What a page SAYS is business-profile-shaped work, not a daily-operations action every staff login should get by default.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "saveSitePageDraft",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "type",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "home",
          "services",
          "about",
          "team",
          "gallery",
          "reviews",
          "contact"
        ]
      },
      "description": "Which of the seven site pages (SITE_PAGE_TYPES). Anything else is a 404."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "content"
          ],
          "additionalProperties": false,
          "properties": {
            "content": {
              "type": "object",
              "required": [
                "visible",
                "heading",
                "intro",
                "body",
                "order",
                "showOnHome",
                "textMotion",
                "metaTitle",
                "metaDescription",
                "noIndex"
              ],
              "additionalProperties": false,
              "properties": {
                "visible": {
                  "type": "boolean",
                  "description": "False hides the page: its route 404s and nav omits it."
                },
                "heading": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 120,
                  "description": "Overrides the page's generated H1. About is the one exception: its heading is a standalone story headline instead; see SitePageContent's own comment."
                },
                "intro": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 600,
                  "description": "A short paragraph under the heading. Null renders no intro at all."
                },
                "body": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "maxItems": 6,
                  "description": "Long-form prose, one section per named subheading. At most 6 sections and 12 paragraphs combined across every section; each paragraph is 2000 characters or fewer.",
                  "items": {
                    "type": "object",
                    "required": [
                      "heading",
                      "paragraphs"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "heading": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 100
                      },
                      "paragraphs": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "maxLength": 2000
                        }
                      }
                    }
                  }
                },
                "order": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "This page's position among the six routable pages. Null falls back to ROUTABLE_SITE_PAGES' own declared order."
                },
                "showOnHome": {
                  "type": "boolean",
                  "description": "Whether this page's teaser section appears on Home, independent of `visible`."
                },
                "textMotion": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "A TEXT_MOTION_STYLES id (palette.ts) overriding the site-wide heading-motion preset for this page, or null for no override."
                },
                "metaTitle": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 60,
                  "description": "Overrides the `<title>` tag and OpenGraph/Twitter title."
                },
                "metaDescription": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 160,
                  "description": "Overrides the meta description and OpenGraph/Twitter description."
                },
                "noIndex": {
                  "type": "boolean",
                  "description": "True asks search engines not to index this page; it still renders and still books."
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Saved.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The body is missing or not an object, or a validateSitePageContent rejection (a field over its length cap, a malformed section, or a blocked term); see that function for the exact message.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster, and a `staff` member without the `manage_org_settings` permission (migration 0082, `Admin access required`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "`type` is not one of the seven SITE_PAGE_TYPES.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Publish a page's draft content live (admin)",
  "description": "Copies `draft_content` over `published_content` and stamps `published_at`. Unconditionally admin-only, no `manage_org_settings` escape hatch (unlike the save route above): migration 0112 grants UPDATE on `draft_content`/`updated_at` only, deliberately never on `published_content`, so this is the ONLY place \"publish\" is actually enforced. A company that never touched this page's draft gets a clean 200 no-op: the live page already renders its generated default and there is nothing to copy forward.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "publishSitePage",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "x-required-role": "admin",
  "parameters": [
    {
      "name": "type",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "home",
          "services",
          "about",
          "team",
          "gallery",
          "reviews",
          "contact"
        ]
      },
      "description": "Which of the seven site pages (SITE_PAGE_TYPES). Anything else is a 404."
    }
  ],
  "responses": {
    "200": {
      "description": "Published (or a no-op success if nothing was ever drafted for this page).",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A Postgres error on the read or the write.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. Covers three refusals: a `staff` member (this action is admin-only), an account with no organization or not on the roster, and **the engine boundary**: an org whose `business_type` is `hospitality` cannot reach the appointments engine at all.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "`type` is not one of the seven SITE_PAGE_TYPES.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Read this company's connected custom domain",
  "description": "The \"Your domain\" card on the Website status screen. `domain` is null until an admin connects one. Appointments only, same as every other route under the Website screen: the page itself already redirects a hospitality org away before this could ever be called. Readable by any member; only the writes below are admin-only.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "getWebsiteDomain",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "responses": {
    "200": {
      "description": "The connected domain, or null.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "domain"
            ],
            "properties": {
              "domain": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "hostname",
                  "vercelVerified",
                  "dnsMisconfigured",
                  "verificationChallenge",
                  "lastCheckedAt",
                  "createdAt"
                ],
                "properties": {
                  "hostname": {
                    "type": "string"
                  },
                  "vercelVerified": {
                    "type": "boolean",
                    "description": "Whether Vercel accepted the ownership claim. Often true immediately on a fresh, uncontested hostname, before any DNS record exists for it: this is NOT \"the domain works,\" see dnsMisconfigured."
                  },
                  "dnsMisconfigured": {
                    "type": "boolean",
                    "description": "Vercel's own live DNS-resolution check. A domain is only actually reachable when vercelVerified is true AND this is false; found live while testing 0148 that vercelVerified alone was misleading the UI into showing \"Connected\" for a hostname nobody had pointed anywhere."
                  },
                  "verificationChallenge": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "domain": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "description": "A TXT ownership challenge Vercel wants before it will verify, or null once none is outstanding."
                  },
                  "lastCheckedAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "description": "null means this company has no custom domain connected."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "Not actually reachable from this GET (it reads no Vercel state), but scripts/check-openapi.ts scans status codes per FILE rather than per handler, and notConfigured() (used by POST/PATCH/DELETE below) lives in this same route.ts.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Connect a custom domain (admin)",
  "description": "v1 is subdomain-CNAME only (migration 0148's own header has the full reasoning): an apex/root domain like \"yourbusiness.com.au\" is accepted the same way at this layer, the scope restriction is a UI/product decision, not a validation rule here. Attaches `hostname` to this Vercel project (`src/lib/vercel/domains.ts`) and upserts `book_custom_domains`, one row per company (migration 0148's `unique(company_id)`); connecting a second domain replaces the first. `verificationChallenge` in the response is a TXT record Vercel wants for ownership proof, present only when Vercel could not verify immediately (most often a domain seen elsewhere before); the CNAME instruction itself is constant and not part of the response, the UI renders it directly.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "connectWebsiteDomain",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "x-required-role": "admin",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "hostname"
          ],
          "properties": {
            "hostname": {
              "type": "string",
              "description": "A bare hostname, e.g. \"book.yourbusiness.com.au\". Lowercased and trimmed before validation."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Connected. Echoes the stored row, including Vercel's current verification state.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "domain"
            ],
            "properties": {
              "domain": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "hostname",
                  "vercelVerified",
                  "dnsMisconfigured",
                  "verificationChallenge",
                  "lastCheckedAt",
                  "createdAt"
                ],
                "properties": {
                  "hostname": {
                    "type": "string"
                  },
                  "vercelVerified": {
                    "type": "boolean",
                    "description": "Whether Vercel accepted the ownership claim. Often true immediately on a fresh, uncontested hostname, before any DNS record exists for it: this is NOT \"the domain works,\" see dnsMisconfigured."
                  },
                  "dnsMisconfigured": {
                    "type": "boolean",
                    "description": "Vercel's own live DNS-resolution check. A domain is only actually reachable when vercelVerified is true AND this is false; found live while testing 0148 that vercelVerified alone was misleading the UI into showing \"Connected\" for a hostname nobody had pointed anywhere."
                  },
                  "verificationChallenge": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "domain": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "description": "A TXT ownership challenge Vercel wants before it will verify, or null once none is outstanding."
                  },
                  "lastCheckedAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "description": "null means this company has no custom domain connected."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`hostname` failed format validation (HOSTNAME_RE, lib/booking/custom-domain.ts).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "402": {
      "description": "Connecting a custom domain needs the `own_domain` PlanFeature: included on Pro/Enterprise, a $10 AUD/mo add-on on Solo/Basic (src/lib/plan.ts).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. Covers three refusals: a `staff` member (this action is admin-only), an account with no organization or not on the roster, and **the engine boundary**: an org whose `business_type` is `hospitality` cannot reach the appointments engine at all.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "This hostname is already connected to a different Gaplessly account, either caught by our own pre-check or by Vercel refusing a hostname already attached to another project (VercelDomainConflictError), or lost a same-hostname race after Vercel accepted it (the domain is rolled back off Vercel in that case).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "502": {
      "description": "Vercel's API rejected or failed the add call for a reason other than a conflict.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "VERCEL_API_TOKEN or VERCEL_PROJECT_ID is not configured yet (VercelDomainsNotConfiguredError).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Re-check this company's connected domain against Vercel (admin)",
  "description": "The poll the UI drives every ~30s while a connected domain sits unverified, waiting on the operator's own DNS change to propagate. Vercel has no webhook for \"DNS propagated\" or \"cert issued\" (see src/lib/vercel/domains.ts), so re-checking on demand against Vercel's own verify + config endpoints is the documented pattern. No-op success is not possible here: 404 if nothing is connected yet.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "recheckWebsiteDomain",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "x-required-role": "admin",
  "responses": {
    "200": {
      "description": "The domain's refreshed state.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "domain"
            ],
            "properties": {
              "domain": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "hostname",
                  "vercelVerified",
                  "dnsMisconfigured",
                  "verificationChallenge",
                  "lastCheckedAt",
                  "createdAt"
                ],
                "properties": {
                  "hostname": {
                    "type": "string"
                  },
                  "vercelVerified": {
                    "type": "boolean",
                    "description": "Whether Vercel accepted the ownership claim. Often true immediately on a fresh, uncontested hostname, before any DNS record exists for it: this is NOT \"the domain works,\" see dnsMisconfigured."
                  },
                  "dnsMisconfigured": {
                    "type": "boolean",
                    "description": "Vercel's own live DNS-resolution check. A domain is only actually reachable when vercelVerified is true AND this is false; found live while testing 0148 that vercelVerified alone was misleading the UI into showing \"Connected\" for a hostname nobody had pointed anywhere."
                  },
                  "verificationChallenge": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "domain": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "description": "A TXT ownership challenge Vercel wants before it will verify, or null once none is outstanding."
                  },
                  "lastCheckedAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "description": "null means this company has no custom domain connected."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. Covers three refusals: a `staff` member (this action is admin-only), an account with no organization or not on the roster, and **the engine boundary**: an org whose `business_type` is `hospitality` cannot reach the appointments engine at all.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No domain is connected for this company.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "502": {
      "description": "Vercel's verify or config call failed for a reason other than \"already verified\".",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "VERCEL_API_TOKEN or VERCEL_PROJECT_ID is not configured yet (VercelDomainsNotConfiguredError).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Disconnect the connected custom domain (admin)",
  "description": "Removes the domain from this Vercel project, then the `book_custom_domains` row. Idempotent: 200 with no error if nothing was connected in the first place, the end state (\"no domain connected\") is what the caller wants either way.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "disconnectWebsiteDomain",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "x-required-role": "admin",
  "responses": {
    "200": {
      "description": "Disconnected, or already had nothing connected.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. Covers three refusals: a `staff` member (this action is admin-only), an account with no organization or not on the roster, and **the engine boundary**: an org whose `business_type` is `hospitality` cannot reach the appointments engine at all.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "502": {
      "description": "Vercel's remove call failed for a reason other than the domain already being gone (404 from Vercel is treated as success).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "VERCEL_API_TOKEN or VERCEL_PROJECT_ID is not configured yet (VercelDomainsNotConfiguredError).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "This website's traffic (self-hosted, cookieless)",
  "description": "The \"Your website\" card's one data source: a self-hosted Umami instance (analytics.solvintia.com), one Umami \"website\" per company for clean per-tenant isolation (no cross-tenant prefix-summing to get wrong). Cookieless by design, see the Cookie Policy entry this shipped alongside for the exact claim. Lazily provisions the company's Umami website on first call if it has none yet (ensureUmamiWebsiteId, src/lib/booking/umami-website-admin.ts) rather than requiring a separate setup step. Included from Pro upward, or a $4.99/mo standalone add-on on Solo/Basic (src/lib/plan.ts, `analytics`), checked before any Umami call; readable by any member once past that gate, since this is a display of the business's own public traffic, not a setting.",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "getWebsiteAnalytics",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "parameters": [
    {
      "name": "days",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "enum": [
          7,
          30,
          90
        ]
      },
      "description": "The trailing window. Anything else silently falls back to 30, the same permissive-default posture holidays' own `year` param takes."
    }
  ],
  "responses": {
    "200": {
      "description": "Summary, a daily trend, and four ranked breakdowns, each capped at 8 rows.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "days",
              "summary",
              "trend",
              "popularPages",
              "referrers",
              "devices",
              "countries"
            ],
            "properties": {
              "days": {
                "type": "integer"
              },
              "summary": {
                "type": "object",
                "required": [
                  "views",
                  "visitors",
                  "visits"
                ],
                "properties": {
                  "views": {
                    "type": "integer"
                  },
                  "visitors": {
                    "type": "integer"
                  },
                  "visits": {
                    "type": "integer"
                  }
                }
              },
              "trend": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "date",
                    "views",
                    "visitors"
                  ],
                  "properties": {
                    "date": {
                      "type": "string"
                    },
                    "views": {
                      "type": "integer"
                    },
                    "visitors": {
                      "type": "integer"
                    }
                  }
                }
              },
              "popularPages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "count"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "referrers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "count"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "devices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "count"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "countries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "count"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "402": {
      "description": "The analytics dashboard is included from Pro upward, or purchasable standalone at A$4.99/mo on Solo/Basic (src/lib/plan.ts, `analytics`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the appointments engine, so an org whose `business_type` is `hospitality` gets 403 with \"This organization takes table reservations, not appointments.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "502": {
      "description": "The Umami API call itself failed (network error, or a non-2xx from analytics.solvintia.com) for a reason other than being unconfigured.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "UMAMI_URL/UMAMI_USERNAME/UMAMI_PASSWORD is not configured yet (UmamiNotConfiguredError).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Take the public site offline, or bring it back (admin)",
  "description": "Flips `book_companies.site_offline`. Unconditionally admin-only, no `manage_org_settings` escape hatch, same posture the publish route (`/api/site-pages/{type}/publish`) takes: this makes or stops making the tenant's public site unreachable for every visitor, a bigger call than the general settings a staff member with that grant can already make. Appointments only, same as every other route under the Website screen: the page itself already redirects a hospitality org away before this control could ever render. Revalidates the public site's cache tag on success, keyed off the company's slug (fetched via the same `.select('slug')` the update itself performs, not a separate read).",
  "tags": [
    "Appointments engine"
  ],
  "operationId": "setWebsiteOffline",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "appointments",
  "x-required-role": "admin",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "offline"
          ],
          "properties": {
            "offline": {
              "type": "boolean",
              "description": "true takes the site offline; false brings it back."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The flag was updated.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "const": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`offline` was missing or not a boolean, or the update itself failed (e.g. the company row could not be found).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. Covers three refusals: a `staff` member (this action is admin-only), an account with no organization or not on the roster, and **the engine boundary**: an org whose `business_type` is `hospitality` cannot reach the appointments engine at all.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "List reservations (API key)",
  "description": "The hospitality engine's table reservations. The mirror of `GET /api/v1/appointments` (same envelope, same paging, same filters, different table), and deliberately **not** the same endpoint with a flag. The two engines share plumbing and never booking logic (migration 0011), and a single `/bookings` endpoint would be the first place that line got crossed.\n\nEngine-guarded: an appointments organization's key is refused with `wrong_vertical` before scope is even checked.\n\nOrdered newest first; use `from` and `to` for a service, a day or a week. `holdExpiresAt` IS exposed, unlike the other withheld columns: a `hold` row whose hold has expired is not a booking, and a program reading reservations has to be able to tell.\n\n**Three clocks in one object, and they are not interchangeable.** `startsAt` and `endsAt` are the venue's wall clock wearing a `+00` suffix; `holdExpiresAt` and `createdAt` are true UTC instants. All four serialise identically, so nothing in the payload distinguishes them and a caller that parses them alike is wrong about some of them by the venue's entire UTC offset. The sharpest edge is comparing `holdExpiresAt` against `startsAt`, or evaluating it in venue-local terms: it is the one field here whose whole purpose is a comparison against the current real instant. `from` and `to` filter on the same wall clock `startsAt` does. Resolve the venue's zone from `timezone` on `GET /api/v1/organization`, which needs the separate `organization:read` scope. See the timestamps section of `docs/api-keys.md`. Three columns are withheld: `manage_token` (the entire credential for the guest self-service link, handing it to a program hands over the ability to act as the guest), `internal_note` (the venue's private note, excluded for the same reason `book_customers.notes` is), and `stripe_payment_intent_id` (an identifier in somebody else's system).",
  "tags": [
    "Hospitality engine"
  ],
  "operationId": "listReservationsV1",
  "security": [
    {
      "bearerApiKey": [
        "reservations:read"
      ]
    }
  ],
  "x-engine": "hospitality",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A `?limit=1e9` from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop."
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "The `nextCursor` from the previous response, passed back unchanged. Omit it for the first page. **Opaque**: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a `400 invalid_cursor` rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.\n\nThe scheme is keyset (seek) paging on `(order column, id)`, not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and `limit` may change between pages; the cursor only says *where you got to*."
    },
    {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "Inclusive lower bound on `startsAt`. Any timestamp Postgres accepts; a value it rejects is a 400. Combine with `to` for a day or a week.\n\n**Compared against `startsAt`, so it is in the venue's wall clock, not UTC**, whatever offset you write on it. `from=2026-08-20T00:00:00Z` means midnight at the venue, not midnight UTC, and the `Z` is not honoured. To ask for a venue's day, write that day's local midnight and ignore the offset. Asking in real UTC instead returns a window shifted by the venue's offset, which for an Australian venue is most of a different day."
    },
    {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "EXCLUSIVE upper bound on `startsAt`. Exclusive so that `from=2026-07-26T00:00:00&to=2026-07-27T00:00:00` is exactly one day with no double-counting at the seam. **That day is the venue's, not UTC**: like `from`, this is compared against the venue's wall clock and any offset you write is ignored."
    }
  ],
  "responses": {
    "200": {
      "description": "The reservations, newest first.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data",
              "nextCursor"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "camelCase.",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "startsAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "**The venue's local wall clock, not a UTC instant, despite the `+00` suffix.** A 19:00 booking at a Sydney venue is returned as `2026-08-20T19:00:00+00`, not as the `09:00Z` that instant really is. Read the digits as local time and ignore the offset, or convert properly using `timezone` from `GET /api/v1/organization`. Do not hand it to a UTC-aware parser and render the result in the reader's zone: that shifts every booking by the venue's whole offset, ten or eleven hours for an Australian venue. `createdAt` in this same object IS a true instant, so the two cannot be treated alike. See the timestamps section of `docs/api-keys.md`."
                    },
                    "endsAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "**The venue's local wall clock, not a UTC instant, despite the `+00` suffix.** A 19:00 booking at a Sydney venue is returned as `2026-08-20T19:00:00+00`, not as the `09:00Z` that instant really is. Read the digits as local time and ignore the offset, or convert properly using `timezone` from `GET /api/v1/organization`. Do not hand it to a UTC-aware parser and render the result in the reader's zone: that shifts every booking by the venue's whole offset, ten or eleven hours for an Australian venue. `createdAt` in this same object IS a true instant, so the two cannot be treated alike. See the timestamps section of `docs/api-keys.md`."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "hold",
                        "pending",
                        "confirmed",
                        "seated",
                        "completed",
                        "cancelled",
                        "no_show"
                      ]
                    },
                    "partySize": {
                      "type": "integer"
                    },
                    "turnMinutes": {
                      "type": "integer",
                      "description": "How long the table is held for. `endsAt` is `startsAt` plus this."
                    },
                    "occasion": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "notes": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The guest's request for this booking."
                    },
                    "tableId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid"
                    },
                    "customerId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid"
                    },
                    "holdExpiresAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "Set only while `status` is `hold`. Past means the hold lapsed and the slot is free again.\n\n**A true UTC instant**, unlike `startsAt`/`endsAt` in this same object: it is written as a real `Date.now()` offset, not as venue wall clock. Compare it against the current UTC time (`Date.now()`), never against `startsAt`, and never after shifting it into the venue's zone. Getting this backwards reads every live hold as long expired, or every expired one as live, by the venue's whole UTC offset."
                    },
                    "depositStatus": {
                      "type": "string",
                      "enum": [
                        "none",
                        "pending",
                        "paid",
                        "refunded",
                        "forfeited"
                      ]
                    },
                    "depositAmountCents": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "A **true UTC instant** (the row's `now()` default), like `holdExpiresAt` and unlike `startsAt`/`endsAt`. Parse and render this one normally."
                    }
                  }
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Pass to `?cursor=` for the next page. **`null` means there are no more rows**: always present, never absent and never undefined, so a caller does not have to distinguish the two. It is exact rather than optimistic: the handler fetches `limit + 1` rows and reports the extra one as a cursor, so N pages take N requests, not N+1."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "400": {
      "description": "Two causes, distinguishable by whether `code` is present. **`invalid_cursor`**: the `cursor` was not one this API issued. **A malformed `from` or `to`**: Postgres rejected the timestamp, and the body is its message with **no `code`**, since it did not come from the gate. Both are the caller's input, which is why neither is a 500.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "const": "invalid_cursor"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "The credential itself is not usable. Stop and fix the key, do not retry. `missing_authorization`: no `Authorization: Bearer` header. `invalid_key`: wrong format, unknown key id, or digest mismatch (these are one code on purpose: distinguishing them would confirm which key ids exist). `key_revoked` / `key_expired`: reported distinctly, which is safe because both are only reachable after the digest already matched, so only the legitimate holder ever sees them. `organization_inactive`: the org itself is switched off, so none of its keys work.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "missing_authorization",
                  "invalid_key",
                  "key_revoked",
                  "key_expired",
                  "organization_inactive"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The credential is fine but may not do this. Stop and fix the request, or re-issue the key with more scopes. `insufficient_scope`: the key does not hold the scope named in `required_scope`. `wrong_vertical`: **the engine boundary**, this operation belongs to the table-reservations engine and the key belongs to an appointments organization. Checked BEFORE scope, so the key is told the truth (wrong product) rather than being told to add a scope its org can never be granted, verified by attacking it: a key that DOES hold the scope is still refused with `wrong_vertical`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "insufficient_scope",
                  "wrong_vertical"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "429": {
      "description": "Per-key fixed-window rate limit exceeded. The counter is incremented as soon as the caller is *identified*, before scope is checked, so a key hammering endpoints it has no scope for is still throttled. Honest limitation: a fixed window allows up to 2x the limit across a boundary; the limit exists to stop a runaway script and bound database load, not to meter billing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "rate_limited"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "Seconds until the window ends."
        },
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "500": {
      "description": "The query failed. The body is the raw Postgres message and carries no `code`, unlike the gate's own errors above.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": []
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    }
  }
}

{
  "summary": "List tables (API key)",
  "description": "The hospitality engine's tables. Engine-guarded, ordered by `id`: see `GET /api/v1/services` for why.\n\n`areaId` is returned but **there is no `/api/v1/areas` or `/api/v1/levels`**, and that is a recorded gap rather than an oversight: `book_areas`/`book_levels` have no scope in the vocabulary (dashboard-only `/api/areas` and `/api/levels` exist as of migration 0030, but neither is exposed to API keys), and inventing `areas:read`/`levels:read` would change what every future key can be granted. The id is enough to group tables by room.",
  "tags": [
    "Hospitality engine"
  ],
  "operationId": "listTablesV1",
  "security": [
    {
      "bearerApiKey": [
        "tables:read"
      ]
    }
  ],
  "x-engine": "hospitality",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A `?limit=1e9` from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop."
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "The `nextCursor` from the previous response, passed back unchanged. Omit it for the first page. **Opaque**: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a `400 invalid_cursor` rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.\n\nThe scheme is keyset (seek) paging on `(order column, id)`, not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and `limit` may change between pages; the cursor only says *where you got to*."
    }
  ],
  "responses": {
    "200": {
      "description": "The tables.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data",
              "nextCursor"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "camelCase.",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "areaId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid"
                    },
                    "seatsMin": {
                      "type": "integer"
                    },
                    "seatsMax": {
                      "type": "integer",
                      "description": "A party larger than this cannot be seated here: the constraint reservation availability is computed against."
                    },
                    "active": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Pass to `?cursor=` for the next page. **`null` means there are no more rows**: always present, never absent and never undefined, so a caller does not have to distinguish the two. It is exact rather than optimistic: the handler fetches `limit + 1` rows and reports the extra one as a cursor, so N pages take N requests, not N+1."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "400": {
      "description": "`invalid_cursor`: the `cursor` was not one this API issued. Pass back `nextCursor` unchanged; do not construct one.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_cursor"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "The credential itself is not usable. Stop and fix the key, do not retry. `missing_authorization`: no `Authorization: Bearer` header. `invalid_key`: wrong format, unknown key id, or digest mismatch (these are one code on purpose: distinguishing them would confirm which key ids exist). `key_revoked` / `key_expired`: reported distinctly, which is safe because both are only reachable after the digest already matched, so only the legitimate holder ever sees them. `organization_inactive`: the org itself is switched off, so none of its keys work.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "missing_authorization",
                  "invalid_key",
                  "key_revoked",
                  "key_expired",
                  "organization_inactive"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The credential is fine but may not do this. Stop and fix the request, or re-issue the key with more scopes. `insufficient_scope`: the key does not hold the scope named in `required_scope`. `wrong_vertical`: **the engine boundary**, this operation belongs to the table-reservations engine and the key belongs to an appointments organization. Checked BEFORE scope, so the key is told the truth (wrong product) rather than being told to add a scope its org can never be granted, verified by attacking it: a key that DOES hold the scope is still refused with `wrong_vertical`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "insufficient_scope",
                  "wrong_vertical"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "429": {
      "description": "Per-key fixed-window rate limit exceeded. The counter is incremented as soon as the caller is *identified*, before scope is checked, so a key hammering endpoints it has no scope for is still throttled. Honest limitation: a fixed window allows up to 2x the limit across a boundary; the limit exists to stop a runaway script and bound database load, not to meter billing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "rate_limited"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "Seconds until the window ends."
        },
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "500": {
      "description": "The query failed. The body is the raw Postgres message and carries no `code`, unlike the gate's own errors above.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": []
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    }
  }
}

{
  "summary": "List service periods (API key)",
  "description": "The hospitality engine's service periods: which days a venue serves, between which times, on what turn. Engine-guarded, ordered by `id`: see `GET /api/v1/services` for why.\n\nThis is the endpoint that makes reservation availability **explicable** rather than magic. No active period for a weekday means an empty grid that day, and a program told \"no availability\" with no way to see why will simply keep asking.\n\n`startTime`, `endTime` and `lastSeating` are wall-clock `HH:MM:SS` in the organization's own `timezone` (on `GET /api/v1/organization`), not instants. A service period is a rule about clock time, not a moment, so converting them here would be lossy. Group by `dayOfWeek` for a week grid.",
  "tags": [
    "Hospitality engine"
  ],
  "operationId": "listServicePeriodsV1",
  "security": [
    {
      "bearerApiKey": [
        "service-periods:read"
      ]
    }
  ],
  "x-engine": "hospitality",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      },
      "description": "Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A `?limit=1e9` from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop."
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "The `nextCursor` from the previous response, passed back unchanged. Omit it for the first page. **Opaque**: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a `400 invalid_cursor` rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.\n\nThe scheme is keyset (seek) paging on `(order column, id)`, not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and `limit` may change between pages; the cursor only says *where you got to*."
    }
  ],
  "responses": {
    "200": {
      "description": "The service periods.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data",
              "nextCursor"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "camelCase.",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "dayOfWeek": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6,
                      "description": "0 = Sunday, matching both Postgres and JavaScript."
                    },
                    "startTime": {
                      "type": "string",
                      "description": "Wall clock, `HH:MM:SS`."
                    },
                    "endTime": {
                      "type": "string",
                      "description": "Wall clock, `HH:MM:SS`."
                    },
                    "lastSeating": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The latest a party may be seated. Null means up to `endTime`."
                    },
                    "turnMinutes": {
                      "type": "integer"
                    },
                    "slotMinutes": {
                      "type": "integer",
                      "description": "The granularity offered: 15 means quarter-past bookings."
                    },
                    "maxCovers": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "A cap on concurrent covers across the whole venue, independent of table capacity. Null means uncapped."
                    },
                    "active": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Pass to `?cursor=` for the next page. **`null` means there are no more rows**: always present, never absent and never undefined, so a caller does not have to distinguish the two. It is exact rather than optimistic: the handler fetches `limit + 1` rows and reports the extra one as a cursor, so N pages take N requests, not N+1."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "400": {
      "description": "`invalid_cursor`: the `cursor` was not one this API issued. Pass back `nextCursor` unchanged; do not construct one.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_cursor"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "The credential itself is not usable. Stop and fix the key, do not retry. `missing_authorization`: no `Authorization: Bearer` header. `invalid_key`: wrong format, unknown key id, or digest mismatch (these are one code on purpose: distinguishing them would confirm which key ids exist). `key_revoked` / `key_expired`: reported distinctly, which is safe because both are only reachable after the digest already matched, so only the legitimate holder ever sees them. `organization_inactive`: the org itself is switched off, so none of its keys work.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "missing_authorization",
                  "invalid_key",
                  "key_revoked",
                  "key_expired",
                  "organization_inactive"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The credential is fine but may not do this. Stop and fix the request, or re-issue the key with more scopes. `insufficient_scope`: the key does not hold the scope named in `required_scope`. `wrong_vertical`: **the engine boundary**, this operation belongs to the table-reservations engine and the key belongs to an appointments organization. Checked BEFORE scope, so the key is told the truth (wrong product) rather than being told to add a scope its org can never be granted, verified by attacking it: a key that DOES hold the scope is still refused with `wrong_vertical`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "insufficient_scope",
                  "wrong_vertical"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "429": {
      "description": "Per-key fixed-window rate limit exceeded. The counter is incremented as soon as the caller is *identified*, before scope is checked, so a key hammering endpoints it has no scope for is still throttled. Honest limitation: a fixed window allows up to 2x the limit across a boundary; the limit exists to stop a runaway script and bound database load, not to meter billing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "rate_limited"
                ]
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      },
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "Seconds until the window ends."
        },
        "X-RateLimit-Limit": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests allowed in the current 60-second window."
        },
        "X-RateLimit-Remaining": {
          "schema": {
            "type": "integer"
          },
          "description": "Requests left in it."
        },
        "X-RateLimit-Reset": {
          "schema": {
            "type": "integer"
          },
          "description": "Unix seconds at which the window rolls over."
        }
      }
    },
    "500": {
      "description": "The query failed. The body is the raw Postgres message and carries no `code`, unlike the gate's own errors above.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "code"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": []
              },
              "required_scope": {
                "type": "string",
                "description": "Present only on `insufficient_scope`: the scope the key would need."
              }
            }
          }
        }
      }
    }
  }
}

{
  "summary": "Create a table",
  "description": "Unlike services and staff, tables are not part of the cached public booking config; reservation availability is computed live per request, so nothing is revalidated here.",
  "tags": [
    "Hospitality engine"
  ],
  "operationId": "createTable",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "hospitality",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name",
            "seatsMin",
            "seatsMax"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            },
            "seatsMin": {
              "type": "integer",
              "minimum": 1,
              "maximum": 40
            },
            "seatsMax": {
              "type": "integer",
              "minimum": 1,
              "maximum": 40,
              "description": "Must be >= seatsMin."
            },
            "areaId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Floor area (a room). A foreign org's area id is rejected by a composite foreign key (400). Mutually exclusive with levelId; sending both is a 400."
            },
            "levelId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "A floor level, for a table that sits directly on it with no room subdivision. A foreign org's level id is rejected by a composite foreign key (400). Mutually exclusive with areaId; sending both is a 400."
            },
            "linkGroupId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "A run of tables that can physically be pushed together (migration 0035). null; the default; means this table combines with nothing. A foreign org's group id is rejected by a composite foreign key (400), and so is a group whose other tables are in a different room, since two tables in different rooms cannot be pushed together."
            },
            "active": {
              "type": "boolean",
              "default": true
            },
            "shape": {
              "type": "string",
              "enum": [
                "rect",
                "round",
                "square",
                "booth",
                "bar",
                "bar_l",
                "bar_u",
                "bar_horseshoe",
                "bar_island",
                "bar_organic",
                "bar_octagon",
                "bar_chevron"
              ],
              "default": "rect",
              "description": "Floor-plan geometry (migration 0091, extended 0092/0206/0219/0220/0222/0223/0224). Omitting it on an EDIT resets the table to rect: send the table's current shape back, the same way every other field here is a full replace, not a merge."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "table"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "table": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseTableInput, or a Postgres error (including a foreign `areaId` refused by the composite foreign key).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the table-reservations engine, so an org whose `business_type` is `appointments` gets 403 with \"This organization takes appointments, not table reservations.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "summary": "Create a range of tables in one request",
  "description": "Generates `prefix + separator + n` for every n from `from` to `to` inclusive (capped at 50 per batch) and inserts them as one atomic statement. Rejects the whole batch; nothing is created; if any generated name already exists in this org; table names are not unique in the schema, so this is an app-level check on a fresh read, not a database constraint.",
  "tags": [
    "Hospitality engine"
  ],
  "operationId": "bulkCreateTables",
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "x-engine": "hospitality",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "from",
            "to",
            "seatsMin",
            "seatsMax"
          ],
          "additionalProperties": false,
          "properties": {
            "prefix": {
              "type": "string",
              "maxLength": 40,
              "description": "Free text, e.g. \"Booth\". May be empty for pure numbers (\"10\", \"11\"...)."
            },
            "from": {
              "type": "integer",
              "minimum": 0,
              "description": "First number in the run. Does not have to be 1."
            },
            "to": {
              "type": "integer",
              "minimum": 0,
              "description": "Last number in the run, inclusive. `to - from + 1` is capped at 50."
            },
            "separator": {
              "type": "string",
              "maxLength": 10,
              "description": "\"Booth 10\" vs \"Booth-10\" vs \"Booth10\". Defaults to \"\" (no separator) if omitted."
            },
            "seatsMin": {
              "type": "integer",
              "minimum": 1,
              "maximum": 40
            },
            "seatsMax": {
              "type": "integer",
              "minimum": 1,
              "maximum": 40,
              "description": "Must be >= seatsMin. Applied to every table in the run."
            },
            "areaId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Same rule as POST /api/tables, applied to every table in the run. Mutually exclusive with levelId."
            },
            "levelId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Same rule as POST /api/tables, applied to every table in the run. Mutually exclusive with areaId."
            },
            "linkGroupId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Same rule as POST /api/tables, applied to every table in the run."
            },
            "active": {
              "type": "boolean",
              "default": true
            },
            "shape": {
              "type": "string",
              "enum": [
                "rect",
                "round",
                "square",
                "booth",
                "bar",
                "bar_l",
                "bar_u",
                "bar_horseshoe",
                "bar_island",
                "bar_organic",
                "bar_octagon",
                "bar_chevron"
              ],
              "default": "rect",
              "description": "Applied to every table in the run."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "tables"
            ],
            "properties": {
              "ok": {
                "const": true
              },
              "tables": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "A validation message from parseBulkTableInput (a bad range, the 50-table cap, a generated name over 40 characters, or a link-group room mismatch), or a Postgres error (including a foreign areaId/levelId/linkGroupId refused by a composite foreign key).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "No valid session cookie. `{\"error\":\"Not signed in\"}`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Not permitted. **Includes the engine-boundary refusal**: this operation belongs to the table-reservations engine, so an org whose `business_type` is `appointments` gets 403 with \"This organization takes appointments, not table reservations.\" Also covers no linked organization and not being on the roster.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "One or more generated names already exist in this org. The whole batch is rejected; nothing is created, and the message names which ones collided.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}