# Bookings

## POST /bookings/bulk

> Create many bookings at once, optionally tied together as a block booking. Supports per-row override (void/checkout an existing live booking on the same room).

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/bulk":{"post":{"tags":["Bookings"],"description":"Create many bookings at once, optionally tied together as a block booking. Supports per-row override (void/checkout an existing live booking on the same room).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site","contract_start","assignments"],"properties":{"site":{"type":"string"},"contract_start":{"type":"string"},"contract_end":{"type":"string"},"flags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"block":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1},"notes":{"type":"string"}}},"assignments":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["person_id","location_id"],"properties":{"person_id":{"type":"string"},"location_id":{"type":"string"},"additional_people":{"type":"array","items":{"type":"string"}},"override":{"type":"object","required":["conflict_booking_id","action"],"properties":{"conflict_booking_id":{"type":"string"},"action":{"type":"string","enum":["void","checkout"]},"cancellation_code":{"type":"string"}}}}}}}}}}},"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /bookings

> List bookings for a site.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings":{"get":{"tags":["Bookings"],"description":"List bookings for a site.","parameters":[{"schema":{"type":"string"},"in":"query","name":"site","required":true},{"schema":{"type":"string"},"in":"query","name":"person","required":false},{"schema":{"type":"string"},"in":"query","name":"location","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"block_booking","required":false},{"schema":{"type":"string"},"in":"query","name":"q","required":false},{"schema":{"type":"string"},"in":"query","name":"include","required":false},{"schema":{"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"number"},"in":"query","name":"skip","required":false},{"schema":{"type":"string","enum":["location","last_name","first_name","contract_end","contract_start"]},"in":"query","name":"sort","required":false}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /bookings

> Create a booking.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings":{"post":{"tags":["Bookings"],"description":"Create a booking.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site","lead_person","location"],"properties":{"site":{"type":"string"},"lead_person":{"type":"string"},"additional_people":{"type":"array","items":{"type":"string"}},"location":{"type":"string"},"status":{"type":"string","enum":["checked_in","arrived","not_arrived","checked_out","void"]},"contract_start":{"type":"string"},"contract_end":{"type":"string"},"vehicle_registration":{"type":"string"},"parking_expiry_at":{"type":"string"},"departure_slot_at":{"type":"string"},"flags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"block_booking":{"type":"string"},"override":{"type":"object","required":["conflict_booking_id","action"],"properties":{"conflict_booking_id":{"type":"string"},"action":{"type":"string","enum":["void","checkout"]},"cancellation_code":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /bookings/{bookingId}

> Retrieve a single booking.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/{bookingId}":{"get":{"tags":["Bookings"],"description":"Retrieve a single booking.","parameters":[{"schema":{"type":"string"},"in":"query","name":"site","required":true},{"schema":{"type":"string"},"in":"query","name":"include","required":false},{"schema":{"type":"string"},"in":"path","name":"bookingId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## PATCH /bookings/{bookingId}

> Update a booking (metadata only — use /transitions to change status).

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/{bookingId}":{"patch":{"tags":["Bookings"],"description":"Update a booking (metadata only — use /transitions to change status).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site"],"properties":{"site":{"type":"string"},"lead_person":{"type":"string"},"additional_people":{"type":"array","items":{"type":"string"}},"location":{"type":"string"},"contract_start":{"type":["string","null"]},"contract_end":{"type":["string","null"]},"vehicle_registration":{"type":["string","null"]},"parking_expiry_at":{"type":["string","null"]},"departure_slot_at":{"type":["string","null"]},"flags":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"bookingId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /bookings/export

> Export bookings as CSV.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/export":{"get":{"tags":["Bookings"],"description":"Export bookings as CSV.","parameters":[{"schema":{"type":"string"},"in":"query","name":"site","required":true},{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["first_name","last_name","location","contract_start","contract_end"]},"in":"query","name":"sort_by","required":false}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /bookings/import/preview

> Preview a CSV import: resolves people, locations, status inference and conflicts without writing.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/import/preview":{"post":{"tags":["Bookings"],"description":"Preview a CSV import: resolves people, locations, status inference and conflicts without writing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site","rows"],"properties":{"site":{"type":"string"},"rows":{"type":"array","items":{"type":"object","required":["row_index","values"],"properties":{"row_index":{"type":"number"},"values":{"type":"object","properties":{"student_id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"room":{"type":"string"},"contract_start":{"type":"string"},"contract_end":{"type":"string"},"vehicle_registration":{"type":"string"},"parking_expiry":{"type":"string"},"departure_slot":{"type":"string"},"notes":{"type":"string"}},"additionalProperties":true}}}}}}}}},"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /bookings/import/commit

> Commit a previously-previewed CSV import with user decisions applied.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/import/commit":{"post":{"tags":["Bookings"],"description":"Commit a previously-previewed CSV import with user decisions applied.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site","rows","idempotency_key","resolutions"],"properties":{"site":{"type":"string"},"idempotency_key":{"type":"string"},"rows":{"type":"array","items":{"type":"object","required":["row_index","values"],"properties":{"row_index":{"type":"number"},"values":{"type":"object","properties":{"student_id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"room":{"type":"string"},"contract_start":{"type":"string"},"contract_end":{"type":"string"},"vehicle_registration":{"type":"string"},"parking_expiry":{"type":"string"},"departure_slot":{"type":"string"},"notes":{"type":"string"}},"additionalProperties":true}}}},"resolutions":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"responses":{"200":{"description":"Default Response"}}}}}}
```

## POST /bookings/{bookingId}/transitions

> Record a state transition / transaction on a booking.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/{bookingId}/transitions":{"post":{"tags":["Bookings"],"description":"Record a state transition / transaction on a booking.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site","type"],"properties":{"site":{"type":"string"},"type":{"type":"string","enum":["check_in","check_out","move_in","move_out","arrival","no_show","void","status_change"]},"occurred_at":{"type":"string"},"notes":{"type":"string"},"cancellation_code":{"type":"string"},"cancellation_reason":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"bookingId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```

## GET /bookings/{bookingId}/transactions

> List all transactions for a booking.

```json
{"openapi":"3.0.3","info":{"title":"Incident Tracker API","version":"1.0.0"},"servers":[{"url":"https://api.kitehouse.co.uk"}],"paths":{"/bookings/{bookingId}/transactions":{"get":{"tags":["Bookings"],"description":"List all transactions for a booking.","parameters":[{"schema":{"type":"string"},"in":"query","name":"site","required":true},{"schema":{"type":"string"},"in":"path","name":"bookingId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```


---

# 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/bookings.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.