> For the complete documentation index, see [llms.txt](https://mobile-calendar.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobile-calendar.gitbook.io/v1/rest-api/availability.md).

# Availability

Get room availability for date range.

## Get room availability for date range

> Returns per-night availability for the requested rooms and/or room types. Each item in \`availability\` represents one night: \`from\` is inclusive (the first night) and \`to\` is exclusive (the check-out day, not included in the response). For example, for a stay from 2025-11-06 to 2025-11-08 request \`from=2025-11-06\&to=2025-11-08\`; the response contains the nights of 2025-11-06 and 2025-11-07.

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"availability","description":"Get room availability for date range."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"AvailabilityResponse":{"description":"Room availability response for specified date range","required":["data","meta"],"properties":{"data":{"description":"Availability data for all requested rooms or room types","type":"array","items":{"$ref":"#/components/schemas/RoomAvailabilityItem"}},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"RoomAvailabilityItem":{"description":"Availability data for a room or room type","required":["type","roomId","typeId","availability"],"properties":{"type":{"description":"Type of availability item","type":"string","enum":["ROOM","ROOM_TYPE"]},"roomId":{"description":"Room ID (integer for ROOM type) or array of room IDs (for ROOM_TYPE)","oneOf":[{"type":"integer"},{"type":"array","items":{"type":"integer"}}]},"typeId":{"description":"Room type ID (null for ROOM type, integer for ROOM_TYPE)","type":"integer","nullable":true},"availability":{"description":"Daily availability for the requested date range","type":"array","items":{"$ref":"#/components/schemas/AvailabilityDay"}}},"type":"object"},"AvailabilityDay":{"description":"Daily availability for a specific date","required":["date","roomsToSell"],"properties":{"date":{"type":"string","format":"date"},"roomsToSell":{"description":"Number of rooms available for sale on this date","type":"integer"}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem400":{"description":"Request syntax/format error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"400 Bad Request","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/availability":{"get":{"tags":["availability"],"summary":"Get room availability for date range","description":"Returns per-night availability for the requested rooms and/or room types. Each item in `availability` represents one night: `from` is inclusive (the first night) and `to` is exclusive (the check-out day, not included in the response). For example, for a stay from 2025-11-06 to 2025-11-08 request `from=2025-11-06&to=2025-11-08`; the response contains the nights of 2025-11-06 and 2025-11-07.","operationId":"getAvailability","parameters":[{"name":"roomId","in":"query","description":"Room ID (integer) or array of room IDs to check availability for. Can be used together with typeId. At least one of roomId or typeId is required.","required":false,"schema":{"oneOf":[{"type":"integer"},{"type":"array","items":{"type":"integer"}}]}},{"name":"typeId","in":"query","description":"Room type ID (integer) or array of room type IDs to check availability for. Can be used together with roomId. At least one of roomId or typeId is required.","required":false,"schema":{"oneOf":[{"type":"integer"},{"type":"array","items":{"type":"integer"}}]}},{"name":"from","in":"query","description":"Start date for availability check (inclusive) - YYYY-MM-DD. Works like a check-in date: this is the first night included in the response.","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"End date for availability check (exclusive) - YYYY-MM-DD. Works like a check-out date: the response contains nights up to and including the day before `to`; the `to` date itself is not returned. Must be strictly greater than `from`. Maximum 90 days from 'from' date.","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Room availability data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"}}}},"400":{"description":"Bad request - missing roomId and typeId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"422":{"description":"Validation error - invalid date order, date range exceeds 90 days, or invalid format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```