Availability for one month
const url = 'https://api.useservice.app/v1/availability/months?month=example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.useservice.app/v1/availability/months?month=example' \ --header 'Authorization: Bearer <token>'Which days are worth opening, for every party size at once — the calendar grain. Deliberately filter-independent: no party size, no section. A projection of what was sellable at read time, not a promise. Requires the reservations:read scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”YYYY-MM
Answer as if this hold or booking did not exist (hold_… or resv_…), same
accepted ids and same refusals as on GET /v1/availability.
The calendar grain is coarser and party-size-agnostic, so one hold flips a day only when it took the last table that fits some party size across the whole service — which for a small dining room is an ordinary Saturday. Pass it, or your own hold can grey out the very day the guest is holding.
Language for the restaurant-authored text in this response — the per-day day_message and closure. Same accepted set and same refusal as on GET /v1/availability.
Header Parameters
Section titled “Header Parameters”Pin this request to a dated version of the contract, e.g. 2026-09-01. Omit it and the version pinned on the API key applies. A version we do not publish is a 400 bad_request with param: "Service-Version". The version that was applied comes back on the Service-Version response header, always.
Responses
Section titled “Responses”Month availability returned
Calendar-grain availability for one month, for every party size at once. A projection, not a promise.
object
The object type: always availability_month.
YYYY-MM.
Every day of the month, in order — never a sparse list.
object
The object type: always availability_day.
The day, YYYY-MM-DD in the restaurant’s timezone.
Already gone, allowing for an overnight service still seating.
Beyond how far ahead this restaurant takes bookings.
A closure covers this date.
The closure’s message to guests, in the restaurant’s own words, when closed is true. null when the day is not closed or the restaurant wrote no message.
No service runs — closed, not sold out.
No service runs, but staff left a note to read. Open the day; do not offer times.
Only a display-only service remains. Selectable, but it takes no online booking.
Every service is past its booking cutoff or simply over. Not the same as sold out.
Party sizes that could be seated somewhere on this day. EMPTY with every flag false means fully booked.
Per-seating-area breakdown; empty when the restaurant offers no seating choice online.
object
The object type: always availability_section.
The seating area, as its group_id from GET /v1/sections (sec_…). It can differ from the sec_… on a reservation’s table, which names one floor plan’s row.
Party sizes that could be seated in this area on this day. [] when none.
Party sizes that may join the queue for this day. Independent of whether any slot survives. Always empty while the booking widget is switched off.
Example
{ "object": "availability_month", "days": [ { "object": "availability_day", "sections": [ { "object": "availability_section" } ] } ]}Headers
Section titled “Headers”Dated API version applied to this response
Pass back as If-None-Match to revalidate cheaply
Invalid month
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Missing or invalid API key
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}The API key does not carry the reservations:read scope
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Headers
Section titled “Headers”Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.
Too many requests on the read budget
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Headers
Section titled “Headers”Requests permitted in the read burst
Requests remaining in the read burst
Seconds until the read bucket refills
Which budget the numbers describe. read here.
Seconds to wait before retrying
Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.