# Locations

## GET /locations/{siteId}/availability

> List rooms available for booking in a date range. Supports filtering by housekeeping status (clean/dirty/check/out\_of\_service), location type, and an ancestor scope. Out-of-order rooms are never returned.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/availability":{"get":{"tags":["Locations"],"description":"List rooms available for booking in a date range. Supports filtering by housekeeping status (clean/dirty/check/out_of_service), location type, and an ancestor scope. Out-of-order rooms are never returned.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":true},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"boolean"},"in":"query","name":"include_occupied","required":false},{"schema":{"type":"string"},"in":"query","name":"types","required":false},{"schema":{"type":"string"},"in":"query","name":"statuses","required":false},{"schema":{"type":"string"},"in":"query","name":"under","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /locations/{siteId}/availability/cluster

> Find the tightest cluster of N available rooms — the deepest ancestor with at least N available descendants.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/availability/cluster":{"get":{"tags":["Locations"],"description":"Find the tightest cluster of N available rooms — the deepest ancestor with at least N available descendants.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":true},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"number","minimum":1},"in":"query","name":"count","required":true},{"schema":{"type":"boolean"},"in":"query","name":"include_occupied","required":false},{"schema":{"type":"string"},"in":"query","name":"types","required":false},{"schema":{"type":"string"},"in":"query","name":"statuses","required":false},{"schema":{"type":"string"},"in":"query","name":"under","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /locations/{siteId}/tree

> Hierarchical location tree for a site. When date filters are provided, each node is annotated with \`available\_under\` and \`total\_under\` counts so callers can show which branches contain availability.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/tree":{"get":{"tags":["Locations"],"description":"Hierarchical location tree for a site. When date filters are provided, each node is annotated with `available_under` and `total_under` counts so callers can show which branches contain availability.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"boolean"},"in":"query","name":"include_occupied","required":false},{"schema":{"type":"string"},"in":"query","name":"types","required":false},{"schema":{"type":"string"},"in":"query","name":"statuses","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /locations/{siteId}

> Get all locations for a site (nested children)

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}":{"get":{"tags":["Locations"],"description":"Get all locations for a site (nested children)","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"with_occupants","required":false},{"schema":{"type":"boolean"},"in":"query","name":"with_type","required":false},{"schema":{"type":"boolean"},"in":"query","name":"with_children","required":false},{"schema":{"type":"boolean"},"in":"query","name":"with_active_bookings","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /locations/{siteId}

> Create a new location

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}":{"post":{"tags":["Locations"],"description":"Create a new location","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"parent_code":{"type":"string"},"parent_id":{"type":"string","nullable":true},"erp_code":{"type":"string"},"description":{"type":"string"},"out_of_order_reason":{"type":"string","nullable":true},"out_of_order_remarks":{"type":"string","nullable":true},"through_date":{"type":"string","nullable":true},"return_as":{"type":"string","nullable":true}},"required":["name","code","type","status"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /locations/{siteId}/bookable

> List bookable locations (those whose type has can\_be\_allocated\_to\_bookings=true).

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/bookable":{"get":{"tags":["Locations"],"description":"List bookable locations (those whose type has can_be_allocated_to_bookings=true).","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## DELETE /locations/{siteId}/{locationId}

> Delete a location

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/{locationId}":{"delete":{"tags":["Locations"],"description":"Delete a location","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"locationId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## PATCH /locations/{siteId}/{locationId}

> Update a location

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/{locationId}":{"patch":{"tags":["Locations"],"description":"Update a location","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"parent_code":{"type":"string"},"parent_id":{"type":"string","nullable":true},"erp_code":{"type":"string"},"description":{"type":"string"},"out_of_order_reason":{"type":"string","nullable":true},"out_of_order_remarks":{"type":"string","nullable":true},"through_date":{"type":"string","nullable":true},"return_as":{"type":"string","nullable":true}},"required":["name","code","type"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"locationId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /locations/{siteId}/bulk-status

> Apply a status (and optional OOO reason/remarks/through/return) to multiple locations at once.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/bulk-status":{"post":{"tags":["Locations"],"description":"Apply a status (and optional OOO reason/remarks/through/return) to multiple locations at once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["location_ids","status"],"properties":{"location_ids":{"type":"array","minItems":1,"items":{"type":"string"}},"status":{"type":"string"},"out_of_order_reason":{"type":"string","nullable":true},"out_of_order_remarks":{"type":"string","nullable":true},"through_date":{"type":"string","nullable":true},"return_as":{"type":"string","nullable":true}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## DELETE /locations/{siteId}/bulk

> Delete multiple locations. Skips any that have children or active bookings.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/bulk":{"delete":{"tags":["Locations"],"description":"Delete multiple locations. Skips any that have children or active bookings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["location_ids"],"properties":{"location_ids":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /locations/{siteId}/export-csv

> Export all locations for a site as CSV using the same columns as import (type is location type id).

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/export-csv":{"get":{"tags":["Locations"],"description":"Export all locations for a site as CSV using the same columns as import (type is location type id).","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /locations/{site}/import

> Import a list of locations.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{site}/import":{"post":{"tags":["Locations"],"description":"Import a list of locations.","parameters":[{"schema":{"type":"string"},"in":"path","name":"site","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /locations/{siteId}/out-of-order-events

> List Out of Order / Out of Service events for a site, filtered by date.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/out-of-order-events":{"get":{"tags":["Locations"],"description":"List Out of Order / Out of Service events for a site, filtered by date.","parameters":[{"schema":{"type":"string"},"in":"query","name":"for_date","required":false},{"schema":{"type":"string"},"in":"query","name":"location","required":false},{"schema":{"type":"boolean"},"in":"query","name":"show_ooo","required":false},{"schema":{"type":"boolean"},"in":"query","name":"show_oos","required":false},{"schema":{"type":"boolean"},"in":"query","name":"include_closed","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"site":{"type":"string"},"location":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"}}},"status":{"type":"string"},"reason":{"type":"object","properties":{"_id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"}}},"from_date":{"type":"string"},"through_date":{"type":"string","nullable":true},"return_as":{"type":"string","nullable":true},"remarks":{"type":"string","nullable":true},"closed_at":{"type":"string","nullable":true},"closed_to_status":{"type":"string","nullable":true},"created_by":{"type":"string"},"closed_by":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}}}}}}
```

## PATCH /locations/{siteId}/out-of-order-events/{eventId}

> Update remarks / through\_date / return\_as on an out-of-order event (admin retrospective edit).

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/locations/{siteId}/out-of-order-events/{eventId}":{"patch":{"tags":["Locations"],"description":"Update remarks / through_date / return_as on an out-of-order event (admin retrospective edit).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"remarks":{"type":"string","nullable":true},"through_date":{"type":"string","nullable":true},"return_as":{"type":"string","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"eventId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"site":{"type":"string"},"location":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"}}},"status":{"type":"string"},"reason":{"type":"object","properties":{"_id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"}}},"from_date":{"type":"string"},"through_date":{"type":"string","nullable":true},"return_as":{"type":"string","nullable":true},"remarks":{"type":"string","nullable":true},"closed_at":{"type":"string","nullable":true},"closed_to_status":{"type":"string","nullable":true},"created_by":{"type":"string"},"closed_by":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kitehouse.co.uk/docs/api-reference/locations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.