Developers

Read provider-neutral property and reservation records through a small, stable contract.

Text
https://supahost.io/api/v1

The machine-readable OpenAPI 3.1 schema is available at /api/v1/openapi.json.

Create a test key in Settings to build an integration without touching real data. Test keys start with sh_test_; live keys start with sh_live_.

A test key serves a fixed synthetic dataset: three sandbox properties with room types, rate plans, and calendar days, plus eight sandbox reservations across every status and channel. Filters, cursor pagination, and error responses behave exactly as they do for live keys.

  • Sandbox records are clearly fake: names like Sandbox Seaside Resort, @example.com emails, and 555 phone numbers.
  • The dataset is stable, so a cursor chain reads the same records on every run. Unknown IDs return not_found, the same as live keys.
  • Test keys share the scopes, rate limit, and request audit of live keys. The audit record marks the key environment.

Writes need a live key. Test keys answer every write endpoint (property, task, message, calendar, rate-plan, and webhook management) with sandbox_read_only.

Property endpoints require the properties:read scope. Required response fields are always present; nullable fields include null in their type.

GET /properties

Return one stable page of properties.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
status'active' | 'inactive' | 'all'OptionalFilter by property status. The default is active, or all when reference is sent.
referencestringOptionalReturn only the property whose reference is exactly this value. Without status, every status is searched.
200 JSON response
FieldTypeRequiredDescription
dataProperty[]RequiredA stable page of property records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable public property UUID.
data[].codestringRequiredProperty code.
data[].namestringRequiredDisplay name.
data[].timezonestringRequiredIANA time zone.
data[].lodgingTypestring | nullOptionalAccommodation type, or null for an unclassified legacy property. Omitted only in older idempotent replay snapshots.
data[].status'active' | 'inactive'RequiredProperty status.
data[].updatedAtstring (date-time)RequiredLast property change time.
data[].inventoryobjectRequiredProperty inventory summary.
data[].inventory.maxGuestsintegerRequiredMaximum occupancy across active room types.
data[].inventory.baseCapacityintegerOptionalTotal base capacity of active inventory pools. Excludes dated entitlement allocations and does not subtract reservations or blocks; use the calendar for date-specific availability.
data[].inventory.physicalUnitsintegerRequiredNumber of active physical units.
data[].inventory.strategiesstring[]RequiredInventory strategies used by active pools.
data[].channelsstring[]RequiredActive channel names.
data[].startingRateobject | nullRequiredLowest active starting rate, or null when no rate exists.
data[].startingRate.amountstringConditionalRequired when startingRate is an object. Amount in the currency unit with two decimals (325.00).
data[].startingRate.amountMinorstringConditionalRequired when startingRate is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data[].startingRate.currencystringConditionalRequired when startingRate is an object. Three-letter currency code.
data[].syncobjectOptionalChannel sync state of the property details. It does not change updatedAt. Omitted only in older idempotent replay snapshots.
data[].sync.state'synced' | 'pending' | 'failed' | 'not_applicable'Requiredsynced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write.
data[].sync.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
data[].sync.failedAtstring (date-time) | nullRequiredWhen the last attempt failed, or null.
data[].sync.pendingSincestring (date-time) | nullRequiredWhen the pending change was queued, or null when the state is not pending.
data[].referencestring | nullOptionalYour own identifier for the property, unique within the workspace, or null when none is set. Omitted only in older idempotent replay snapshots.

GET /properties/{propertyId}

Return one property from the API key workspace.

Property IDs are UUID strings, including property references in reservations, tasks, conversations, channels, calendar and rate-plan write results, and new webhook events. Keep IDs as opaque strings. A property path or filter accepts only the UUID.

Pre-GA identifier transition: refresh your property list and stored references after this release. Start a new property pagination chain; old numeric property cursors return invalid_cursor. Retry writes with the same URL, body and Idempotency-Key to preserve replay behavior. Previously queued webhook events retain their original payload.

The response includes an ETag header that names this version of the property. Send it in If-None-Match to get 304 with no body when the property did not change. The tag names the whole response, so it also changes when a derived value, such as the channel sync state, changes.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-None-MatchstringOptionalThe ETag from your last read. Returns 304 with no body when the property did not change.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
200 JSON response
FieldTypeRequiredDescription
dataPropertyRequiredThe requested property.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable public property UUID.
data.codestringRequiredProperty code.
data.namestringRequiredDisplay name.
data.timezonestringRequiredIANA time zone.
data.lodgingTypestring | nullOptionalAccommodation type, or null for an unclassified legacy property. Omitted only in older idempotent replay snapshots.
data.status'active' | 'inactive'RequiredProperty status.
data.updatedAtstring (date-time)RequiredLast property change time.
data.inventoryobjectRequiredProperty inventory summary.
data.inventory.maxGuestsintegerRequiredMaximum occupancy across active room types.
data.inventory.baseCapacityintegerOptionalTotal base capacity of active inventory pools. Excludes dated entitlement allocations and does not subtract reservations or blocks; use the calendar for date-specific availability.
data.inventory.physicalUnitsintegerRequiredNumber of active physical units.
data.inventory.strategiesstring[]RequiredInventory strategies used by active pools.
data.channelsstring[]RequiredActive channel names.
data.startingRateobject | nullRequiredLowest active starting rate, or null when no rate exists.
data.startingRate.amountstringConditionalRequired when startingRate is an object. Amount in the currency unit with two decimals (325.00).
data.startingRate.amountMinorstringConditionalRequired when startingRate is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.startingRate.currencystringConditionalRequired when startingRate is an object. Three-letter currency code.
data.syncobjectOptionalChannel sync state of the property details. It does not change updatedAt. Omitted only in older idempotent replay snapshots.
data.sync.state'synced' | 'pending' | 'failed' | 'not_applicable'Requiredsynced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write.
data.sync.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
data.sync.failedAtstring (date-time) | nullRequiredWhen the last attempt failed, or null.
data.sync.pendingSincestring (date-time) | nullRequiredWhen the pending change was queued, or null when the state is not pending.
data.referencestring | nullOptionalYour own identifier for the property, unique within the workspace, or null when none is set. Omitted only in older idempotent replay snapshots.

POST /properties

Create a draft property with properties:write. Send name, code, the postal address fields (addressLine, city, state, postalCode, countryCode), timezone, lodgingType, strategy, bedrooms, bathrooms, maxGuests, baseCapacity, and baseRate, the default nightly rate: { "amount": "225.50", "currency": "USD" }, the same money object as every other rate. A bare amount in USD such as 225 or "225.50" also works. The OpenAPI request schema lists supported types and limits.

lodgingType describes the accommodation, such as hotel, apart_hotel, apartment, or villa. strategy independently selects pooled, fixed_unit, or entitlement inventory. baseCapacity is the number of sellable units in the first room type: at least 1, or 0 for entitlement inventory whose capacity comes from dated owner-night allocations. Bedrooms, bathrooms, guest capacity and the USD nightly rate apply per unit. baseRateMinor in hundredths still works and will be removed.

Returns 201 with the property, first room type, inventory pool and standard rate plan saved atomically. The property stays inactive until activated in the dashboard. Send Idempotency-Key to retry safely. Test keys cannot create properties. inventory.baseCapacity in read responses is the base unit count, not remaining availability; use the calendar for specific dates.

Send reference, your own identifier for the property, to make the create safe to repeat. It is 1 to 128 characters and unique in the workspace. If a property already has the reference, nothing is created. When every field of the request matches that property as stored, the answer is 200 with that property. Text is compared trimmed, code and countryCode in capitals, and an empty state or postalCode as none. When any field differs, the answer is 409 reference_in_use. Find a property by its reference with GET /properties?reference=. An Idempotency-Key is checked first: its replay returns the stored answer.

PUT /properties/{propertyId}

Replace the writable details of one property. This endpoint requires the properties:write scope. Only name, timezone and reference are writable; the other read fields are ignored when sent back.

The response is the updated property record. On a channel-connected property a change of name or timezone also queues to the channel sync outbox and propagates to connected channels asynchronously. A write that changes only reference, or changes nothing, queues nothing: the reference goes to no channel. An archived property must be restored in the dashboard before editing. One exception: send its stored name and timezone with a new reference, or null, to change only the reference. That change goes to no channel.

A reference that another property holds fails with 409 reference_in_use.

Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original record and applies nothing twice; the same key with a different payload fails with 409 idempotency_key_reused. The replay returns the stored response body unchanged, so its sync shows the state at the time of the original write; read the property to get the current state.

A write that meets a channel sync of the property, or of a record it depends on, fails with 409. sync_in_progress means the sync is pending or being retried: wait for Retry-After, then send the write again. sync_failed means the sync failed and Supahost will not retry it: stop, and ask a person in your workspace to resolve it in Supahost. Both name the blocking record in blockedBy.

To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the property changed since, the response is 412 precondition_failed and nothing is written. Read the property again and repeat the change. Without If-Match, the replacement always applies. A 412 can also come from a derived value that moved, such as the channel sync state: read the property again and repeat the change; it is not an error to show.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes retries safe.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the property changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
JSON body
FieldTypeRequiredDescription
namestringRequiredDisplay name, 2 to 100 characters.
timezonestringRequiredIANA time zone. Other read fields sent back on round-trip are ignored.
referencestring | nullOptionalYour own identifier for the property, 1 to 128 characters, unique in the workspace. Omit it to keep the stored value. Send null to clear it.
200 JSON response
FieldTypeRequiredDescription
dataPropertyRequiredThe requested property.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable public property UUID.
data.codestringRequiredProperty code.
data.namestringRequiredDisplay name.
data.timezonestringRequiredIANA time zone.
data.lodgingTypestring | nullOptionalAccommodation type, or null for an unclassified legacy property. Omitted only in older idempotent replay snapshots.
data.status'active' | 'inactive'RequiredProperty status.
data.updatedAtstring (date-time)RequiredLast property change time.
data.inventoryobjectRequiredProperty inventory summary.
data.inventory.maxGuestsintegerRequiredMaximum occupancy across active room types.
data.inventory.baseCapacityintegerOptionalTotal base capacity of active inventory pools. Excludes dated entitlement allocations and does not subtract reservations or blocks; use the calendar for date-specific availability.
data.inventory.physicalUnitsintegerRequiredNumber of active physical units.
data.inventory.strategiesstring[]RequiredInventory strategies used by active pools.
data.channelsstring[]RequiredActive channel names.
data.startingRateobject | nullRequiredLowest active starting rate, or null when no rate exists.
data.startingRate.amountstringConditionalRequired when startingRate is an object. Amount in the currency unit with two decimals (325.00).
data.startingRate.amountMinorstringConditionalRequired when startingRate is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.startingRate.currencystringConditionalRequired when startingRate is an object. Three-letter currency code.
data.syncobjectOptionalChannel sync state of the property details. It does not change updatedAt. Omitted only in older idempotent replay snapshots.
data.sync.state'synced' | 'pending' | 'failed' | 'not_applicable'Requiredsynced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write.
data.sync.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
data.sync.failedAtstring (date-time) | nullRequiredWhen the last attempt failed, or null.
data.sync.pendingSincestring (date-time) | nullRequiredWhen the pending change was queued, or null when the state is not pending.
data.referencestring | nullOptionalYour own identifier for the property, unique within the workspace, or null when none is set. Omitted only in older idempotent replay snapshots.

GET /properties/{propertyId}/rooms

Return one stable page of room types for one property, each with its physical units. Inactive records stay in the response with status inactive. inventoryPool.id is the ID that calendar and rate plan writes name; send ?reference= to find the room type that holds your own reference. sync shows whether the channel has the latest version of each room type; send ?sync=failed to list the ones that need a person.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
referencestringOptionalReturn only the room type whose reference is exactly this value, active or inactive.
syncstringOptionalReturn only the room types whose sync.state is one of these values: pending, failed, or both, separated by commas without spaces. A value may repeat. The filter is part of the cursor, so keep it on every page.
200 JSON response
FieldTypeRequiredDescription
dataRoomType[]RequiredA stable page of room type records, each with its physical units and inventory pool.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable room type ID.
data[].codestringRequiredRoom type code.
data[].namestringRequiredRoom type display name.
data[].status'active' | 'inactive'RequiredRoom type status.
data[].maxOccupancyintegerRequiredMaximum occupancy.
data[].bedroomsintegerRequiredBedroom count.
data[].bathroomsintegerRequiredBathroom count.
data[].updatedAtstring (date-time)RequiredLast change time of the room type, its physical units, or its inventory pool.
data[].unitsobject[]RequiredPhysical units of this room type.
data[].units[].idstringRequiredStable physical unit ID.
data[].units[].codestringRequiredPhysical unit code.
data[].units[].namestringRequiredPhysical unit display name.
data[].units[].floorstring | nullRequiredFloor label, or null.
data[].units[].status'active' | 'inactive'RequiredPhysical unit status.
data[].inventoryPoolobject | nullRequiredThe room type’s inventory pool, or null when it has no active pool or more than one.
data[].inventoryPool.idstringConditionalRequired when inventoryPool is an object. Inventory pool ID. Calendar and rate plan writes name it as inventoryPool.id.
data[].inventoryPool.strategy'pooled' | 'fixed_unit' | 'entitlement'ConditionalRequired when inventoryPool is an object. Inventory strategy of the pool.
data[].inventoryPool.capacityintegerConditionalRequired when inventoryPool is an object. Sellable units before reservations and blocks; 0 for entitlement inventory.
data[].referencestring | nullRequiredYour own identifier for the room type, unique within the property, or null when none is set.
data[].syncobjectRequiredChannel sync state of the record itself. A write can also be refused by the sync of a record it depends on, which blockedBy names. It does not change updatedAt, which tracks the record itself.
data[].sync.state'synced' | 'pending' | 'failed' | 'not_applicable'Requiredsynced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write.
data[].sync.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
data[].sync.failedAtstring (date-time) | nullRequiredWhen the last attempt failed, or null.
data[].sync.pendingSincestring (date-time) | nullRequiredWhen the pending change was queued, or null when the state is not pending.

PUT /properties/{propertyId}/rooms

Create and update room types for one property. This endpoint requires the room-types:write scope. The body is an array of room type entries shaped like the read rows; read-only fields such as units and inventoryPool are ignored when sent back.

Each entry is an upsert keyed by id: an entry with an id replaces that room type’s details, and an entry without an id creates a room type with its own inventory pool. Room types not mentioned stay untouched. Every entry applies, or none does. Changes queue to the channel sync outbox and propagate to connected channels asynchronously, the same as a change made in Supahost.

Set reference to your own identifier for a room type to make creates safe to repeat. An entry without an id whose reference already belongs to an active room type on the property updates that room type instead of creating a second one. A reference held by an inactive room type fails with 409 reference_inactive: to reuse it, send that room type back by its id with status: inactive and reference set to null or another value, or use a different reference. A reference another room type holds, on an entry with an id, fails with 409 reference_in_use, as does the losing request when two creates with one reference run at once.

The response lists the room type each entry wrote in roomTypes, one item per entry in request order, with its id, its reference after the write, and its inventoryPool.id, so a create returns the IDs that the calendar and rate plan writes need. An Idempotency-Key replay returns the same list.

The errors calendar_feed_managed and calendar_move_pending (409) belong to a retired setup. No property returns them.

While Supahost pauses calendar writes to a property, it refuses the same room type changes with 409 calendar_writes_paused. Send them again after the Retry-After seconds.

Every error that names a field names it as roomTypes.N.field, where N is the entry’s position in the body array, starting at 0.

Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original summary and applies nothing twice; the same key with a different payload fails with 409 idempotency_key_reused.

A write that meets a channel sync of the room type, or of a record it depends on, fails with 409. sync_in_progress means the sync is pending or being retried: wait for Retry-After, then send the write again. sync_failed means the sync failed and Supahost will not retry it: stop, and ask a person in your workspace to resolve it in Supahost. Both name the blocking record in blockedBy. A property whose channel setup is not complete also fails a create with sync_failed.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes retries safe.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
JSON body
FieldTypeRequiredDescription
roomTypes[].idstringOptionalRoom type ID to update. Omit to create a room type.
roomTypes[].codestringRequiredRoom type code, unique within the property across active and inactive room types. 2 to 40 letters, numbers, or hyphens, stored in capitals.
roomTypes[].namestringRequiredRoom type display name, 2 to 100 characters.
roomTypes[].statusstringRequiredOnly active is writable. inactive is accepted on room types already inactive, where only a reference change applies; archiving is not supported.
roomTypes[].maxOccupancyintegerRequiredMaximum guests, 1 to 500.
roomTypes[].bedroomsintegerRequiredBedroom count, 0 to 50.
roomTypes[].bathroomsintegerRequiredBathroom count, 0 to 50.
roomTypes[].capacityintegerConditionalSellable units of the room type’s inventory pool, 0 to 10,000, before reservations and blocks. Required when the entry creates a room type, and at least 1 unless the property sells entitlement inventory; a create without it fails with 400 invalid_request on roomTypes.N.capacity. Omit on an update, by id or matched by reference, to leave it unchanged. Ignored for entitlement inventory.
roomTypes[].referencestring | nullOptionalYour own identifier for the room type, 1 to 128 characters without leading or trailing spaces, unique within the property across active and inactive room types. Omit to leave unchanged; null clears it. Each reference can appear once per request.
200 JSON response
FieldTypeRequiredDescription
dataRoomTypesWriteResultRequiredThe applied rooms write summary.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.propertyIdstringRequiredPublic UUID of the property the rooms write applied to.
data.roomTypesWrittenintegerRequiredRoom type entries applied by the write.
data.roomTypesobject[]RequiredOne item per request entry, in entry order: the room type each entry created or updated (an inactive room type sent back unchanged included).
data.roomTypes[].idstringRequiredRoom type ID: the new room type for a create, the room type written for an update.
data.roomTypes[].referencestring | nullRequiredThe room type’s reference after the write, or null when it has none.
data.roomTypes[].inventoryPoolobject | nullRequiredThe room type’s inventory pool, or null when it has no active pool or more than one.
data.roomTypes[].inventoryPool.idstringConditionalRequired when inventoryPool is an object. Inventory pool ID, for calendar and rate plan writes.

GET /properties/{propertyId}/rate-plans

Return one stable page of rate plans for one property. This endpoint requires the rate-plans:read scope. sync shows whether the channel has the latest version of each plan; send ?sync=failed to list the ones that need a person.

calendarRate says whether a calendar write must send the plan a rate on a night with units to sell (night_value_required). On a property whose calendar is supplied by a connected source, an active plan is required when an active listing sells it or when it has a stored rate above 0 on a night from today on. A listing you disconnected does not count, even while its channel connection remains. Past rates and stored rates of 0 (stopped nights) do not count. A request that sends a plan a rate on any night also makes it required on the other nights of that request. A plan the channel derives from another plan is derived, and derivedFrom names the parent. Every other plan is not_required: nothing sells or prices it, it is inactive, or the property’s nights fall back to the plan base rate.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
referencestringOptionalReturn only the rate plan whose reference is exactly this value, active or inactive.
syncstringOptionalReturn only the rate plans whose sync.state is one of these values: pending, failed, or both, separated by commas without spaces. A value may repeat. The filter is part of the cursor, so keep it on every page.
200 JSON response
FieldTypeRequiredDescription
dataRatePlan[]RequiredA stable page of rate plan records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable rate plan ID.
data[].codestringRequiredRate plan code.
data[].namestringRequiredRate plan display name.
data[].status'active' | 'inactive'RequiredRate plan status.
data[].updatedAtstring (date-time)RequiredLast rate plan or inventory pool change time.
data[].inventoryPoolobjectRequiredInventory pool this rate plan prices.
data[].inventoryPool.idstringRequiredStable inventory pool ID.
data[].inventoryPool.codestringRequiredInventory pool code.
data[].inventoryPool.namestringRequiredInventory pool display name.
data[].inventoryPool.strategy'pooled' | 'fixed_unit' | 'entitlement'RequiredInventory strategy of the pool.
data[].inventoryPool.roomTypeIdstringRequiredRoom type the pool sells.
data[].baseRateobjectRequiredDefault nightly rate.
data[].baseRate.amountstringRequiredAmount in the currency unit with two decimals (325.00).
data[].baseRate.amountMinorstringRequiredDeprecated: the same amount in hundredths (32500). Read amount.
data[].baseRate.currencystringRequiredThree-letter currency code.
data[].includedOccupancyintegerRequiredGuests included in the base rate.
data[].extraGuestRateobjectRequiredNightly rate for each extra guest.
data[].extraGuestRate.amountstringRequiredAmount in the currency unit with two decimals (325.00).
data[].extraGuestRate.amountMinorstringRequiredDeprecated: the same amount in hundredths (32500). Read amount.
data[].extraGuestRate.currencystringRequiredThree-letter currency code.
data[].weeklyDiscountPercentnumber | nullRequiredPercent off the accommodation for direct stays of 7 or more nights, or null for none.
data[].monthlyDiscountPercentnumber | nullRequiredPercent off the accommodation for direct stays of 28 or more nights, or null for none. The larger tier applies.
data[].referencestring | nullRequiredYour own identifier for the rate plan, unique within the property, or null when none is set.
data[].calendarRate'required' | 'not_required' | 'derived'RequiredWhether a calendar write must send this rate plan a rate on a night with units to sell. required: the property’s calendar is supplied by a connected source and an active listing sells this active plan, or the calendar prices it (it has a stored rate above 0 on a night from today on). A request that sends the plan a rate on any night also makes it required on the request’s other nights. not_required: nothing sells or prices it, it is inactive, or the property’s nights fall back to the plan base rate. derived: the channel derives the plan from derivedFrom, so it never needs a rate of its own.
data[].derivedFromobject | nullRequiredThe rate plan the channel derives this plan from, or null when Supahost has none on record.
data[].derivedFrom.idstringConditionalRequired when derivedFrom is an object. ID of the rate plan this plan is derived from.
data[].syncobjectRequiredChannel sync state of the record itself. A write can also be refused by the sync of a record it depends on, which blockedBy names. It does not change updatedAt, which tracks the record itself.
data[].sync.state'synced' | 'pending' | 'failed' | 'not_applicable'Requiredsynced: the channel has the current record. pending: a change is on its way to the channel, or Supahost is retrying it; writes to the record fail with 409 sync_in_progress. failed: the change failed and Supahost will not retry it; a person must resolve it in Supahost, and writes to the record fail with 409 sync_failed. not_applicable: the record is not synced to a channel, for example on a draft property or one without a channel connection. synced and not_applicable mean the record's own sync blocks no write.
data[].sync.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
data[].sync.failedAtstring (date-time) | nullRequiredWhen the last attempt failed, or null.
data[].sync.pendingSincestring (date-time) | nullRequiredWhen the pending change was queued, or null when the state is not pending.

PUT /properties/{propertyId}/rate-plans

Create and update rate plans for one property. This endpoint requires the rate-plans:write scope. The body is an array of rate plan entries shaped like the read rows.

Send each rate as { "amount": "225.00", "currency": "USD" }. amount is a string or a number with at most two decimals. A read row also carries amountMinor, the deprecated amount in hundredths. You can send it back with amount when both name the same amount, and a mismatch returns HTTP 400 on ratePlans.N.baseRate.amount.

Each entry is an upsert keyed by id: an entry with an id replaces that plan’s fields, so nights that inherit the base rate follow the new rate, and an entry without an id creates a plan under inventoryPool.id. Plans not mentioned stay untouched. Changes queue to the channel sync outbox and propagate to connected channels asynchronously. A changed base rate also queues the repriced nights for the channel and sends one calendar.updated webhook with kind rates.

Set reference to your own identifier for a plan to make creates safe to repeat. An entry without an id whose reference already belongs to an active plan on the property updates that plan, under the same rules as an update by id, instead of creating a second one. A reference held by an inactive plan fails with 409 reference_inactive: to reuse it, send that plan back by its id with status: inactive and reference set to null or another value (the one change an inactive plan accepts), or use a different reference; a reference another plan holds, on an entry with an id, fails with 409 reference_in_use, as does the losing request when two creates with one reference run at once.

The response lists the plan each entry wrote in ratePlans, one item per entry in request order, with its id and its reference after the write, so a create returns the new plan’s ID and a repeated create returns the ID of the plan it matched. An Idempotency-Key replay returns the same list. Only a replay of a request first made before ratePlans existed returns the summary without it; read those plans with GET /properties/{propertyId}/rate-plans?reference=….

The errors calendar_feed_managed and calendar_move_pending (409) belong to a retired setup. No property returns them.

While Supahost pauses calendar writes to a property, a create fails with 409 calendar_writes_paused. Updates to existing rate plans still work. Send the create again after the Retry-After seconds.

Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original summary and applies nothing twice; the same key with a different payload fails with 409 idempotency_key_reused.

A write that meets a channel sync of the rate plan, or of a record it depends on, fails with 409. sync_in_progress means the sync is pending or being retried: wait for Retry-After, then send the write again. sync_failed means the sync failed and Supahost will not retry it: stop, and ask a person in your workspace to resolve it in Supahost. Both name the blocking record in blockedBy.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes retries safe.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
JSON body
FieldTypeRequiredDescription
ratePlans[].idstringOptionalRate plan ID to update. Omit to create a rate plan.
ratePlans[].codestringRequiredRate plan code, unique within its inventory pool. 2 to 40 letters, numbers, or hyphens.
ratePlans[].namestringRequiredRate plan display name, 2 to 100 characters.
ratePlans[].statusstringRequiredOnly active is writable. inactive is accepted on plans already inactive, where only a reference change applies; archiving is not supported.
ratePlans[].inventoryPool.idstringConditionalInventory pool ID the plan prices. Required when creating; on update it must match the plan’s pool. Other read fields on inventoryPool are ignored.
ratePlans[].baseRateobjectRequiredamount/currency pair for the default nightly rate. amount is a currency amount with two decimals, such as 225.00. amountMinor still works and will be removed. All rate plans on one property share one currency.
ratePlans[].includedOccupancyintegerRequiredGuests included in the base rate, 1 to 500.
ratePlans[].extraGuestRateobject | nullRequiredamount/currency pair for each extra guest, or null for no extra-guest rate. amount is a currency amount with two decimals, such as 25.00.
ratePlans[].weeklyDiscountPercentnumber | nullOptionalPercent off the accommodation for direct stays of 7 or more nights, 0 to 100 with at most two decimals. Omit to leave unchanged; null or 0 clears it. Not sent to channels.
ratePlans[].monthlyDiscountPercentnumber | nullOptionalPercent off the accommodation for direct stays of 28 or more nights. When both tiers qualify the larger one applies.
ratePlans[].referencestring | nullOptionalYour own identifier for the plan, 1 to 128 characters without leading or trailing spaces, unique within the property across active and inactive plans. Omit to leave unchanged; null clears it. Each reference can appear once per request.
200 JSON response
FieldTypeRequiredDescription
dataRatePlansWriteResultRequiredThe applied rate-plans write summary.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.propertyIdstringRequiredPublic UUID of the property the rate-plans write applied to.
data.plansWrittenintegerRequiredRate plan entries applied by the write.
data.ratePlansobject[]OptionalOne item per request entry, in entry order: the plan each entry created or updated (an inactive plan sent back unchanged included). Present on every write. Absent only when an Idempotency-Key replays a request first made before this field existed; read those plans with ?reference= instead.
data.ratePlans[].idstringRequiredRate plan ID: the new plan for a create, the plan written for an update.
data.ratePlans[].referencestring | nullRequiredThe plan’s reference after the write, or null when it has none.

Protected closures

A normal closed date or availability block is editable. A protected closure adds a durable guard for one inventory pool and stay date. It closes the pool, sets stop sell on every active rate plan, and prevents ordinary API, import, agent and dashboard calendar edits from reopening it. It also prevents removal of existing closed-to-arrival and closed-to-departure flags. It does not turn those flags on automatically.

Protection preserves bookings, reserved and sellable quantities, prices and other restrictions. Its channel update contains only stop sell and existing true arrival/departure flags. It does not publish prices or stay-length rules, or clear channel flags that are false locally. Derived channel plans keep their inherited prices. Booking modifications and cancellations can still update reserved quantities without reopening the date. This is closure protection, not a price freeze or reservation lock.

Protection is enforced in the database and checked again before queued Supahost channel writes. A stale queued reopening is superseded by current closed state. A provider request already in flight finishes before protection commits; the closure is then queued. HTTP 200 proves the Supahost change committed, not that the connected channel has acknowledged delivery. Verify channel delivery separately.

Protection stays active until explicitly removed; there is no automatic expiry. It cannot control direct edits made in the channel manager or an OTA, another application that bypasses Supahost, or privileged database administration. Keep one authorized channel writer for the protected scope.

Writes require the opt-in calendar-protections:write scope, separately from calendar:write. Existing keys do not gain this scope. The key creator must remain an active workspace member with availability.manage permission, including on idempotent retries. Missing scope or permission returns 403. Test keys cannot write; their GET response is an empty sandbox collection.

GET /properties/{propertyId}/calendar/protections

Requires calendar:read. Supply one inventory pool and an inclusive range of 1 to 366 dates. Returns every active protection in that range, ordered by stay date, with no truncation. An unprotected range returns data: []. Unknown properties or pools return 404.

Send Authorization: Bearer $SUPAHOST_API_KEY. For POST and DELETE, use a unique Idempotency-Key (1 to 200 characters) for each intended operation. A retry with the same key and payload replays its original response without changing current state. Reusing a key with different content returns 409 idempotency_key_reused. After removing and re-creating protection, use a new key.

Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
Query parameters
FieldTypeRequiredDescription
inventoryPoolIdstringRequiredOne inventory pool on the property.
startsOnstring (date)RequiredFirst date, inclusive. Range must span 1 to 366 dates.
endsOnstring (date)RequiredLast date, inclusive.
200 JSON response
FieldTypeRequiredDescription
dataCalendarProtection[]RequiredProtection records with id, inventoryPoolId, stayDate, original reason, createdAt and releasedAt. No pagination; at most 366 records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data[].idstringRequired
data[].inventoryPoolIdstringRequired
data[].stayDatestringRequired
data[].reasonstringRequired
data[].createdAtstring (date-time)Required
data[].releasedAtstring (date-time) | nullRequired

POST /properties/{propertyId}/calendar/protections

Writes require the opt-in calendar-protections:write scope, separately from calendar:write. Existing keys do not gain this scope. The key creator must remain an active workspace member with availability.manage permission, including on idempotent retries. Missing scope or permission returns 403. Test keys cannot write; their GET response is an empty sandbox collection.

Send Authorization: Bearer $SUPAHOST_API_KEY. For POST and DELETE, use a unique Idempotency-Key (1 to 200 characters) for each intended operation. A retry with the same key and payload replays its original response without changing current state. Reusing a key with different content returns 409 idempotency_key_reused. After removing and re-creating protection, use a new key.

Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.

The strict JSON body requires inventoryPoolId, startsOn, endsOn and a trimmed reason of 2 to 240 characters. Dates must be today or later in the property time zone, span 1 to 366 dates inclusive, and target an active property and non-entitlement pool. Unknown fields and invalid dates return 400 before any mutation. A date already protected keeps its original ID, reason and creator.

cURL
curl -X POST "https://supahost.io/api/v1/properties/$PROPERTY_ID/calendar/protections" \
  -H "Authorization: Bearer $SUPAHOST_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: protect-maintenance-1" \
  -d '{"inventoryPoolId":"123","startsOn":"2030-10-10","endsOn":"2030-10-12","reason":"Owner maintenance closure"}'
200 JSON response
FieldTypeRequiredDescription
dataCalendarProtection[]RequiredProtection records with id, inventoryPoolId, stayDate, original reason, createdAt and releasedAt. No pagination; at most 366 records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data[].idstringRequired
data[].inventoryPoolIdstringRequired
data[].stayDatestringRequired
data[].reasonstringRequired
data[].createdAtstring (date-time)Required
data[].releasedAtstring (date-time) | nullRequired

DELETE /properties/{propertyId}/calendar/protections/{closureId}

Writes require the opt-in calendar-protections:write scope, separately from calendar:write. Existing keys do not gain this scope. The key creator must remain an active workspace member with availability.manage permission, including on idempotent retries. Missing scope or permission returns 403. Test keys cannot write; their GET response is an empty sandbox collection.

Send Authorization: Bearer $SUPAHOST_API_KEY. For POST and DELETE, use a unique Idempotency-Key (1 to 200 characters) for each intended operation. A retry with the same key and payload replays its original response without changing current state. Reusing a key with different content returns 409 idempotency_key_reused. After removing and re-creating protection, use a new key.

Read the current protection, review it, then pass its exact closureId and a strict JSON body containing reason (2 to 240 characters). One call removes one date’s protection. Repeat for each approved date. An already released ID returns 409 closure_changed and cannot remove a replacement protection. An ID outside the property returns 400 invalid_reference.

Removal retains the protection record and its release reason, actor and timestamp for audit. The date remains closed, with stop sell and other restrictions unchanged. To reopen it, make a separate ordinary calendar write after removal. The agent has no unlock tool.

Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
closureIdstring (uuid)RequiredExact UUID of the active protection to remove.
cURL
curl -X DELETE "https://supahost.io/api/v1/properties/$PROPERTY_ID/calendar/protections/$CLOSURE_ID" \
  -H "Authorization: Bearer $SUPAHOST_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: release-maintenance-1" \
  -d '{"reason":"Owner approved reopening"}'
200 JSON response
FieldTypeRequiredDescription
dataCalendarProtection[]RequiredProtection records with id, inventoryPoolId, stayDate, original reason, createdAt and releasedAt. No pagination; at most 366 records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data[].idstringRequired
data[].inventoryPoolIdstringRequired
data[].stayDatestringRequired
data[].reasonstringRequired
data[].createdAtstring (date-time)Required
data[].releasedAtstring (date-time) | nullRequired

GET /properties/{propertyId}/calendar

Return per-day availability, lowest rate, and minimum stay for every active inventory pool of one property. This endpoint requires the calendar:read scope. The range spans at most 92 days and defaults to the next 31 days in the property time zone. Dates accept years 1 through 9999. The response is limited to 2000 rows (dates × active pools); larger requests fail with calendar_result_too_large, so narrow the range or pass inventoryPoolId.

availableUnits subtracts reservations and availability blocks from the sellable count and is 0 on closed dates. rate, minStay and minStayThrough come from the lowest-priced sellable rate plan. All three are null when no active plan sells the date, and stopSell is true when every active plan is stop-sold. minStayThrough is also null when that plan’s night follows minStay; it shows a value only when the night has a separate one.

Send include=channel to add a channel object to each row. It says, per night, whether the channel has what Supahost holds for it, and why not. See Channel delivery state below. Without include the response and its cost are unchanged.

Send include=holds to see, for each pool night, what Supahost takes off the count for reservations the count may not include yet, and why. It needs the reservations:read scope as well as calendar:read; a key without one of them gets 403 insufficient_scope, and the detail names the scope it lacks. With holds the response is limited to 500 rows (dates × active pools). Send include=channel,holds for both objects. Every time in holds and meta.asOf is UTC with 6 fractional digits. A test key reads a fixed sample with no reservations, so its holds objects list nothing and take nothing off.

meta.asOf says about when Supahost read the calendar, on its own database clock. A write that committed around that time may or may not be in the read, and the row fields and holds are read one after the other, so do not use meta.asOf to decide whether a write is included.

On a pool whose count a connected source sets, every reservation night the count does not include yet comes off the count before Supahost sends the night to the channel. A reservation night counts as included (reflected: true) only when the connected source confirmed it after the reservation got the night and before the read time behind your count, your observedAt. heldNights lists each reservation on the pool night. subtracted is the sum of units over those not reflected. On any other pool nothing comes off, subtracted is 0 and heldNights is empty. A night that is not reflected has the first reason that applies:

  • no_observation: no read time stands behind the count: you sent observedAt: null, or no count with a read time was stored.
  • count_changed_since_observation: the stored count is no longer the count the read time belongs to.
  • several_rooms: the reservation holds more than one room that night, and one confirmation cannot stand for each.
  • no_confirmation: the connected source has not confirmed the reservation for this night.
  • confirmed_before_allocation: a confirmation is from before the reservation got this pool night, so it does not prove this room.
  • confirmed_after_observation: a confirmation is not earlier than the read time, so the read did not see it.

sends is this pool’s part of the availability Supahost computes for the channel for the room type night; the room type gets the sum over its active pools. It is null when the channel receives nothing for this room type night: the night is in the past, the property or its room type is not connected to a channel, or the property’s calendar comes from a connected source and a pool of the room type has no count of its own that night. sends is the value before Supahost holds a property closed on the channel (it then sends 0) and before the channel closes tonight at its own cut-off. Read include=channel for what the channel has.

Supahost stores each observedAt 2 minutes earlier than you send it, to allow for clock differences, and compares confirmations with that stored time: observedAtUsed shows it, and sent.observedAt shows what you sent. reflectedFromObservedAt and reflectableAfter already include those 2 minutes, so compare them with the observedAt you would send. Send the same count again with a newer observedAt only when the new value is later than holds.reflectableAfter. A value equal to it or earlier changes nothing the channel receives, so skip it. When reflectableAfter is null, no later read time takes less off that night.

A later observedAt changes what the channel receives only on a property whose calendar you write through this API; on any other property the write is refused. On a closed night, or a night already at 0 after the held nights that stay off, it changes nothing the channel receives either: Supahost stores the new time and sends nothing.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
Query parameters
FieldTypeRequiredDescription
fromstring (date)OptionalFirst stay date, inclusive. The default is today in the property time zone.
tostring (date)OptionalLast stay date, inclusive. The default is 30 days after from; the range can span at most 92 days.
inventoryPoolIdstringOptionalReturn rows for one inventory pool ID.
pool_idstringOptionalDeprecated: use inventoryPoolId.
include'channel' | 'holds' | 'channel,holds'OptionalSend channel to add a channel object to each row: whether the channel has what Supahost holds for that night, and why not. Send holds to add a holds object to each row: what Supahost takes off the pool night’s count for held nights, and why. holds needs the reservations:read scope as well as calendar:read, and limits the response to 500 rows. Send channel,holds for both. Without it the response is unchanged.
200 JSON response
FieldTypeRequiredDescription
dataCalendarDay[]RequiredOne row per active inventory pool per stay date in the range.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.asOfstring (date-time)OptionalWith include=holds: about when Supahost read the calendar, on Supahost’s database clock, UTC with 6 fractional digits. A write that committed around this time may or may not be in the read, so do not use it to decide whether a write is included.
data[].datestring (date)RequiredStay date in YYYY-MM-DD format.
data[].inventoryPoolobjectRequiredInventory pool this row describes.
data[].inventoryPool.idstringRequiredStable inventory pool ID.
data[].inventoryPool.codestringRequiredInventory pool code.
data[].inventoryPool.namestringRequiredInventory pool display name.
data[].inventoryPool.strategy'pooled' | 'fixed_unit' | 'entitlement'RequiredInventory strategy of the pool.
data[].inventoryPool.roomTypeIdstringRequiredRoom type the pool sells.
data[].availableUnitsintegerRequiredUnits left after reservations and blocks; 0 when the pool is closed.
data[].closedbooleanRequiredWhether the pool is closed on this date.
data[].stopSellbooleanRequiredWhether every active rate plan is stop-sold on this date.
data[].rateobject | nullRequiredLowest nightly rate across sellable active rate plans, or null when none sells.
data[].rate.amountstringConditionalRequired when rate is an object. Amount in the currency unit with two decimals (325.00).
data[].rate.amountMinorstringConditionalRequired when rate is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data[].rate.currencystringConditionalRequired when rate is an object. Three-letter currency code.
data[].minStayinteger | nullRequiredMinimum stay of the lowest sellable rate plan, or null when no rate exists.
data[].minStayThroughinteger | nullRequiredSeparate minimum stay through this date of the lowest sellable rate plan. Null means the night follows minStay, or that no rate exists.
data[].channelobjectOptionalWhether the channel has what Supahost holds for this night. Present only with include=channel.
data[].channel.availabilityobjectRequiredChannel state of the room type availability on this night.
data[].channel.availability.state'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent'Requiredsynced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why.
data[].channel.availability.reasonstring | nullRequiredWhy the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other.
data[].channel.availability.valueinteger | nullRequiredThe availability Supahost holds for the channel on this night: the room type total after holds and the close-out. It can differ from the row's availableUnits, which is one pool. 0 while held. Null when the night is not sent.
data[].channel.availability.observedValueintegerOptionalThe availability a read of the channel showed when it differed from value. Present only then.
data[].channel.availability.changedAtstring (date-time) | nullRequiredWhen Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent.
data[].channel.restrictionsobjectRequiredChannel state of the rates and stay rules on this night. On the rate plan calendar it is that plan. On the property calendar it sums up the pool's active rate plans: failed when one failed, else pending when one is pending, else synced when one reaches the channel, else not_sent (no_rate_plan when the pool has no active plan).
data[].channel.restrictions.state'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent'Requiredsynced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why.
data[].channel.restrictions.reasonstring | nullRequiredWhy the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other.
data[].channel.restrictions.changedAtstring (date-time) | nullRequiredWhen Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent.
data[].holdsobjectOptionalWith include=holds: what Supahost takes off this pool night’s count for held nights, and why.
data[].holds.countinteger | nullRequiredThe night’s own count before blocks and held nights come off: the stored sellable count less reservations. On a property whose calendar was moved from the retired supplier feed to the API, Supahost stores the availableUnits you write as sent, so count is your number. On every other property it stores your availableUnits plus the units blocks hold at that moment. Either way a block added or removed later changes blocked, not count. Null when the night has no count of its own and follows the pool capacity.
data[].holds.closedbooleanRequiredWhether the pool is closed on this date.
data[].holds.sentobject | nullRequiredThe times of the last count the API wrote for this pool night, or null when the API never wrote one.
data[].holds.sent.observedAtstring (date-time) | nullConditionalRequired when sent is an object. The observedAt you sent, or null when you sent observedAt: null.
data[].holds.sent.revisionAtstring (date-time)ConditionalRequired when sent is an object. The newest revisionAt Supahost accepted for this pool night.
data[].holds.sent.recordedAtstring (date-time)ConditionalRequired when sent is an object. When Supahost stored it.
data[].holds.observedAtUsedstring (date-time) | nullRequiredThe read time Supahost compares confirmations with, as stored. When your write stored it, it is 2 minutes before the observedAt you sent; when the retired supplier feed stored it, it is the feed’s own read time. Null when no read time belongs to the stored count.
data[].holds.blockedintegerRequiredUnits availability blocks hold on this date.
data[].holds.subtractedintegerRequiredUnits that come off the count for held nights not yet included in it: the sum of units over heldNights with reflected: false. Always 0 on a pool whose count no connected source sets, and on a night without its own count.
data[].holds.sendsinteger | nullRequiredThis pool’s part of the availability Supahost computes for the channel for the room type night: 0 when closed, otherwise the count (or the pool capacity less reservations) less blocked and subtracted, never below 0. The room type gets the sum over its active pools. Null when the channel receives nothing for this room type night: the night is in the past, the property or its room type is not connected to a channel, or the property’s calendar comes from a connected source and a pool of the room type has no count of its own that night. It is the value before Supahost holds a property closed on the channel, which sends 0 instead, and before the channel closes tonight at its own cut-off. What the channel has is in include=channel.
data[].holds.reflectableAfterstring (date-time) | nullRequiredThe earliest reflectedFromObservedAt among heldNights with reflected: false, or null when no such night has one. Sending the same count again with a later observedAt can change what the channel receives only when that observedAt is later than this, and only on a property whose calendar you write through the API (elsewhere the write is refused). On a closed night, or one already at 0 after the held nights that stay off, it changes nothing the channel receives: Supahost stores the new time and sends nothing.
data[].holds.heldNightsobject[]RequiredEach reservation holding units on this pool night, oldest allocation first. Empty where nothing comes off for held nights: a pool whose count no connected source sets, or a night without its own count.
data[].holds.heldNights[].reservationIdstringRequiredThe reservation that holds units on this pool night.
data[].holds.heldNights[].status'tentative' | 'confirmed'RequiredReservation status. Cancelled reservations hold nothing and are not listed.
data[].holds.heldNights[].unitsintegerRequiredUnits the reservation holds on this pool night.
data[].holds.heldNights[].allocatedAtstring (date-time)RequiredWhen the reservation got this pool night.
data[].holds.heldNights[].confirmationRecordedAtstring (date-time) | nullRequiredWhen Supahost recorded the newest confirmation from the connected source that covers this night, or null when there is none.
data[].holds.heldNights[].reflectedbooleanRequiredWhether your count already includes this night, so nothing comes off for it.
data[].holds.heldNights[].reason'no_observation' | 'count_changed_since_observation' | 'several_rooms' | 'no_confirmation' | 'confirmed_before_allocation' | 'confirmed_after_observation' | 'null'RequiredWhy the night still comes off your count, the first that applies: no_observation (no read time stands behind the count), count_changed_since_observation (the stored count is no longer the count that read time belongs to), several_rooms (the reservation holds more than one room that night), no_confirmation, confirmed_before_allocation (a confirmation is from before the reservation got this pool night), confirmed_after_observation (a confirmation is not earlier than the read time). Null when reflected is true.
data[].holds.heldNights[].reflectedFromObservedAtstring (date-time) | nullRequiredThe latest observedAt that still leaves this night off your count: sent with the same count, an observedAt later than this counts the night as included. It is the confirmation time plus the 2 minutes Supahost takes off every observedAt. Null when no read time can include the night: the reservation holds more than one room that night, it has no confirmation, or a confirmation is from before it got this pool night. reason names only the first cause, so this can be null under no_observation or count_changed_since_observation too.

PUT /properties/{propertyId}/calendar

Bulk-update per-day availability, rates, and restrictions for one property. This endpoint requires the calendar:write scope, or calendar:read to validate a request with validateOnly=true. The body is an array of day entries shaped like the read rows. A property calendar row summarizes the pool’s lowest-priced sellable rate plan, and it shows an inherited rate as a number. An entry without ratePlanId writes every active plan on the pool. So do not send a read row back unchanged for a pool with more than one rate plan. Read the rate plan calendar instead, send entries with ratePlanId, and leave out rate and minStay unless you mean to set them.

The error calendar_feed_managed (409) belongs to a retired setup. No property returns it.

When Supahost pauses calendar writes to a property, the request returns 409 calendar_writes_paused and changes nothing. Read the calendar with GET, and send the write again after the Retry-After seconds.

On a property whose calendar is supplied by a connected source, the channel sells a night only from values written for it: an available count for the pool and a rate on the rate plan. There is no fallback to the pool capacity or the plan base rate. Supahost merges your entries for a pool and date with the values it stores, and refuses the request with 400 night_value_required when the night would miss a value the channel needs to sell it. A night with units to sell (an open night whose sellable count is above 0, counted before reservations and blocks, since a cancelled booking or a removed block frees those units without a calendar write) needs a rate on each rate plan that an active listing sells or that the calendar prices, and a rate on at least one rate plan of its pool. The calendar prices a rate plan that has a stored rate above 0 on a night from today on, or that your request sends a rate on any night. A rate plan with no active listing and no rate is not sold, so it needs none (a listing you disconnected does not count, even while its channel connection remains), and a rate plan the channel derives from another one never does. The rate plans read says which rate plans need one in calendarRate. An entry that sends a rate, or reopens a rate plan with stopSell: false, on a night without an available count needs that count. On a room type with more than one active inventory pool, the channel receives the room type’s availability only when every active pool has an available count, so an entry that gives one pool units to sell while another pool of the room type has no count for that night is refused on days.N.availableUnits, and the message names the other pool: send a count for it in the same request.

A rate plan stopped from selling on a night needs no rate there: send stopSell: true without a rate, and the channel receives the night as stopped, with no rate. One rate plan can sell a night while another is stopped. Supahost keeps such a night without a rate, and the rate plan calendar reads it with rate: null. Sending the same stop again changes nothing. To reopen it, send stopSell: false with a rate: without one the request is refused with night_value_required on days.N.rate, for every rate plan, whether or not it needs a rate to sell. That includes an entry without ratePlanId that sends stopSell: false and reaches such a night: the message names each rate plan it would reopen. A night that keeps its rate when you stop it keeps that rate when you reopen it. A stop that Supahost stores on a night that still follows the plan base rate is not sent to the channel, so it does not count until an entry writes that rate plan night.

A night with no units to sell needs no rate. To close a night, send closed: true or availableUnits: 0. A close or a stop is never refused for a missing value: on a night without an available count the channel never received the night, so closed: true there changes nothing it sells. Send availableUnits: 0 too when you want the channel to receive the night as closed. Each errors item names one missing field (days.N.availableUnits, days.N.rate, or days.N.ratePlanId for a rate plan that no entry in the request writes), and its message names the rate plan and why it needs a rate. Nothing is stored. An entry that changes only the rate or the stay rules of a night that has its values is valid. A night with neither a count nor a rate is valid and is not sold. Minimum and maximum stay, stop sell and the arrival and departure flags are not required: they keep their defaults. On every other property the pool capacity and the plan base rate still apply to a night without its own value.

Protected closures cannot be overridden by this endpoint. Reopening inventory or removing protected restrictions returns 409 protected_calendar_closure and rolls back the entire batch, also with skipLocked=true. The protectedNights member lists each protected night the request would reopen by inventory pool and date, up to 100, and protectedNightCount gives the total. Remove those entries, or explicitly remove protection in the calendar or through the protection API first. Removing protection alone leaves the date closed.

Each entry needs date and inventoryPool. An entry that sends availableUnits or closed also needs revisionAt and observedAt, described below. Every other field is optional. An omitted field keeps the stored value. Days that you do not mention stay as they are. For rate, minStay and minStayThrough, null also keeps the stored value.

Every entry that sends availableUnits or closed carries two times. revisionAt is required and cannot be null: send a time that only goes up for a pool night, such as the start of your sync run. The observedAt key is required too: send a time no later than the supplier read behind the count, or null when no supplier read stands behind it. Both are RFC 3339 date-times with a time-zone offset and at most 6 fractional digits, and neither may be more than 2 minutes after Supahost’s own time for the request. A missing time fails the request with 400 count_time_required, a time in the wrong format with 400 invalid_datetime, and a time too far ahead with 400 count_time_in_future. Each errors item names the field, and the request stores nothing. Entries for the same pool and date that send a count must send the same two times. An entry that sends neither availableUnits nor closed may leave both out; a time it sends is checked for its format only, and it never has to match another entry’s. This applies on every property.

Supahost keeps the newest revisionAt for each pool night. When an entry sends an older revisionAt than the stored one, Supahost refuses that pool night: nothing is stored for it, not its count, its rates or its stay rules, and every entry for the same pool and date is refused with it. A refused night is set aside before the other checks, so it never fails the request, and the other entries are checked without it. The request still answers 200 and applies the other nights. refusedNights lists each refused night with reason: "stale_revision", retry: false, the revisionAt you sent and the later storedRevisionAt, both in UTC with 6 fractional digits, and refusedNightCount gives the total. Drop a refused night: sending it again cannot succeed. An equal revisionAt is accepted, so a retry of the same request changes nothing. A write that changes nothing still keeps your revisionAt, so an older run that arrives later is refused. With skipLocked=true, a locked night is listed only in skippedNights and is never compared. Supahost keeps a record of each refused night.

On a property whose calendar was moved from the retired supplier feed to the API, Supahost stores the availableUnits you send as your count, without adding back the units availability blocks hold. A block a person adds in Supahost comes off your count where Supahost computes the channel value, so the channel receives availableUnits less the blocked units, never below 0. A lower count and a close always apply, also on a blocked night. When a person removes the block, the channel value rises by the blocked units with no write from you. The GET calendar then shows availableUnits less the blocked units, which is what the channel receives: on a blocked night do not write back what you read, or the block comes off twice. Send your own count. On every other property a block is added back to your availableUnits, as described below.

On a pool whose sellable count a connected source sets, observedAt decides which reservations the count already includes. A reservation night counts as included only when the connected source confirmed it after the night was booked and before observedAt. Every other reservation night comes off your count before Supahost sends it to the channel, and with observedAt: null they all do. Supahost treats the read as 2 minutes earlier than sent, to allow for clock differences. When you send the same count with a different observedAt and that changes the availability the channel receives, Supahost sends that night to the channel and counts it in nightsChanged.observations. It sends no calendar.updated webhook for it, because the stored calendar did not change. When it changes nothing the channel receives, nothing is sent and nothing is recorded. countsWithoutObservation counts the pool nights the write applied with observedAt: null.

An entry without availableUnits and closed does not touch pool availability. Use it to change prices or restrictions only. A booking that arrives between your read and your write keeps its units. On a night with no stored value, an omitted field keeps its default: availability follows the pool capacity, the pool stays open, and the flags stay false. This is how the API works today: when an entry creates a rate plan night, the minimum and maximum stay it leaves out store the plan’s current defaults, and a later change to the plan defaults does not move that night (issue #1097). An entry that changes nothing is valid.

minStay is the minimum stay for an arrival on the date. minStayThrough is the minimum stay for any stay that includes the date. A night without its own minStayThrough uses its minStay. When you change minStay and omit minStayThrough, a night that has its own through value keeps it. Send both to change both. null or an omitted minStayThrough keeps the stored value. Sending minStayThrough stores a fixed value for that night. The night then no longer follows minStay, and the API cannot clear the value today (issue #1097). To keep a night following minStay, do not send minStayThrough. A night whose read shows null follows minStay. A property calendar row summarizes the pool’s lowest-priced sellable rate plan, and it shows an inherited rate as a number. An entry without ratePlanId writes every active plan on the pool. So do not send a read row back unchanged for a pool with more than one rate plan. Read the rate plan calendar instead, send entries with ratePlanId, and leave out rate and minStay unless you mean to set them. A maxStay you send must be zero or at least both minimum stays, including a stored through value.

Nights locked in the Supahost calendar cannot be written by this endpoint. By default, a request that includes a locked night returns 409 calendar_night_locked and changes nothing. The lockedNights member lists each locked night by inventory pool and date, with the reason it is locked, up to 100. lockedNightCount gives the total. A lock covers the whole pool on that date. The reason is manual (a person locked it), edit (a person or the Supahost agent changed it on a property whose calendar was moved from the retired supplier feed to the API, or earlier, while the feed wrote it), feed_conflict (a lock the retired feed set when it found the night changed outside the feed; locks of this reason can still be on a property), or carried_over (an earlier lock on the whole day).

Send skipLocked=true to write every other entry in the same transaction. The response lists every locked night in skippedNights, with its reason and no cap, and gives the total in skippedNightCount. daysApplied counts the entries accepted and not skipped, including an entry that changed nothing. A skipped entry is not checked against stored values, so it cannot fail the request. When every entry is locked, nothing changes and the response is still 200. Supahost keeps a record of each skipped night and its reason.

The lock wins over your value. When you close a skipped night, or send fewer availableUnits than the lock keeps, while the night is still for sale, Supahost flags the night to an operator because it can be oversold. The night itself does not change. Send the night again after it is unlocked.

A person can lock a night in the calendar. A night is also locked when a person or the Supahost agent edits it on a property whose calendar was moved from the retired supplier feed to the API. A person can unlock the night in the calendar, and your next write of it applies. Locks from the time the feed wrote the property can still be there, and are unlocked the same way.

Send a rate as { "amount": "325.00", "currency": "USD" }. amount is a string or a number with at most two decimals. A read row also carries amountMinor, the deprecated amount in hundredths. You can send it back with amount when both name the same amount, and a mismatch returns HTTP 400 on days.N.rate.amount.

Unknown fields return HTTP 400 before any change. This also applies inside inventoryPool and rate. Use camelCase names such as maxStay. Null rejects for availableUnits, closed, stopSell, maxStay, closedToArrival and closedToDeparture. Use zero or false to clear them.

Without ratePlanId an entry writes every active rate plan on the pool; with it, only that plan’s nightly state changes. Entries for the same pool and date may target different rate plans, but their pool-level fields (availableUnits, closed) must agree, and a pool-level entry cannot share a date with targeted entries. availableUnits is the target availability, and reservations and blocks are added back when the sellable count is stored (only reservations on a property whose calendar was moved from the retired supplier feed to the API, where a block comes off at the channel). That count must fit the pool capacity, or the write fails with 400 invalid_request. A pool whose sellable count a connected source sets is the exception: its count is the source’s own number, not a count of units, so it can exceed the capacity. A request can form at most 90 disjoint date ranges in total; batch genuinely sparse updates into multiple requests. Changed values queue to the channel sync outbox and propagate to connected channels asynchronously. An entry that does not change availability queues no availability update.

Supahost compares each night with the values it stores. A night sent with the values Supahost already stores is not stored again. Supahost sends the channel only the nights that changed, so you can send your whole calendar window on every write. nightsChanged counts the nights that changed: availability counts inventory pool nights, and restrictions counts rate plan nights. A night that follows the pool capacity or the plan base rate changes when you send a value for it, also the same value: from then on it keeps that value. A night with no stored rate plan values changes when an entry writes it. A write that changes nothing queues nothing and sends no calendar.updated webhook.

Supahost sends an unchanged night to the channel again in one case: its last change failed and Supahost stopped retrying it. Then the same values in a new write send it again. A night whose change is still pending is not sent twice. Read the calendar with include=channel to see which nights failed.

Send an Idempotency-Key header to make retries safe: a repeated PUT with the same key and the same payload returns the original summary and applies nothing twice. A replay returns the same skippedNights. The same key with a different payload, a different revisionAt included, or with a different skipLocked value, fails with 409 idempotency_key_reused.

The 200 body also has channelSync. It says what the write queued for the channel, for availability and for restrictions. queued: Supahost queued a change for the channel. unchanged: no stored value of that kind changed, so Supahost queued nothing new. It does not say whether the channel has the values. Read the calendar with include=channel for that. not_written: no entry wrote that kind of value. not_sent: Supahost does not send these values, changed or not, and reason says why (property_inactive, not_connected, no_rate_plan, awaiting_feed, derived_rate_plan). It is the same reason the rate plan calendar with include=channel gives for those nights. heldClosed is true while Supahost holds the property closed on the channel, so availability goes out as 0. channelSync does not say that the channel accepted the change. Read the calendar with include=channel for that. A replay with the same Idempotency-Key returns the stored channelSync.

Send validateOnly=true to test a request against the live calendar without writing it. Supahost runs the checks a real write runs before it writes, under the same rules, and answers 200. accepted is true when the calendar checks would accept the request now, and then refusals is empty. It does not check an Idempotency-Key against the keys Supahost has stored, so a real write that reuses a key with a different body can still answer 409 idempotency_key_reused. refusals lists every refusal it would answer with, in the order it would meet them, each with its HTTP status and the same problem document: the same code, errors items and field paths, and the same named nights. A property whose calendar writes are paused is still checked: calendar_writes_paused comes first, and the field errors of your entries follow it. With skipLocked=true, an accepted validation lists in skippedNights the locked nights a real write would skip. An accepted validation also lists in refusedNights the pool nights a real write would refuse for an older revisionAt. Nothing is stored, queued or sent, no calendar.updated webhook is sent, and no operator alert is raised. The queueing, webhook and audit steps of a real write do not run, so a database failure in them is not predicted.

How far a validation goes depends on the key and the property. With the calendar:write scope, on a property a real write would not refuse for its calendar authority, it takes the real write’s locks and runs its night writes in a transaction that it rolls back: an accepted answer then carries daysApplied, nightsChanged and countsWithoutObservation, counted as the write counts them. With only calendar:read, or on a property whose calendar writes are paused, it runs the same checks as plain reads, takes no lock and writes nothing, and the answer carries neither daysApplied nor nightsChanged. A validation that cannot finish within about 2 seconds, for example while a booking or another write holds the nights, answers 503 service_busy; send it again.

Validation needs the calendar:read or the calendar:write scope; a real write still needs calendar:write. An Idempotency-Key sent with validateOnly=true is checked for its format and otherwise ignored: nothing is stored under it, so you can send the same key with the real write. These answer as a real write does, not with a validation: 401 for an invalid key, 403 for a missing scope, 403 sandbox_read_only for a test key, 429 for the rate limit, 400 for a body that is not JSON, an invalid validateOnly or skipLocked, an invalid Idempotency-Key or a malformed property ID, and 404 for a property outside the key’s workspace, also when the body is invalid. A body that is JSON but does not match the schema is listed in refusals. A test key reads a fixed sample dataset, not your live calendar, and a validation checks the request against the live calendar, so validation needs a live key. Validations count toward the rate limit.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes retries safe.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
Query parameters
FieldTypeRequiredDescription
skipLocked'true' | 'false'OptionalSend true to write every unlocked entry and list the locked nights, with their reasons, in skippedNights. A skipped entry is not checked against stored values, so it cannot fail the request. Without it, one locked night fails the whole request with 409. It does not skip a protected closure: reopening one still fails the request.
skip_locked'true' | 'false'OptionalDeprecated: use skipLocked.
validateOnly'true' | 'false'OptionalSend true, once, to check the request without writing it: Supahost runs the checks a real write runs before it writes and answers 200 with validateOnly, accepted (true when the calendar checks would accept the request now; the Idempotency-Key is not checked against stored keys, so a real write that reuses a key with a different body can still answer 409 idempotency_key_reused) and every refusal a real write would answer with, in its order, each with its status and problem document. Nothing is stored, queued or sent, and no webhook or Idempotency-Key record is made; the queueing and audit steps of a real write do not run, so a failure there is not predicted. Needs calendar:read or calendar:write and a live key: a test key reads a fixed sample dataset, not the live calendar a validation checks, so it answers 403 sandbox_read_only. With calendar:write, on a property a real write would not refuse for its calendar authority, the validation takes the real write's locks and runs its night writes in a transaction it rolls back, and an accepted answer carries daysApplied, nightsChanged and countsWithoutObservation. Either way an accepted answer lists in refusedNights the pool nights a real write would refuse. Otherwise (a calendar:read key, or a property whose calendar writes are paused) it takes no lock and writes nothing, and the answer carries neither. A validation that cannot finish within about 2 seconds answers 503 service_busy. Any other value, or the parameter sent twice, is a 400.
validate_only'true' | 'false'OptionalDeprecated: use validateOnly.
JSON body
FieldTypeRequiredDescription
days[].datestring (date)RequiredStay date in YYYY-MM-DD format.
days[].inventoryPool.idstringRequiredInventory pool ID this entry writes. Optional code, name, strategy and roomTypeId fields are read metadata. Their values do not change the pool.
days[].ratePlanIdstringOptionalActive rate plan ID on the pool to write. Omit to write every active rate plan on the pool. Entries sharing a pool and date must target different plans with matching pool-level fields.
days[].revisionAtstring (date-time)ConditionalRequired, and never null, on an entry that sends availableUnits or closed. A time that only goes up for a pool night, such as the start of your sync run. Supahost keeps the newest one per pool night and refuses an older one for that night. An RFC 3339 date-time with a time-zone offset and at most 6 fractional digits, no more than 2 minutes after Supahost’s own time for the request. Optional on any other entry: then only its format is checked.
days[].observedAtstring (date-time) | nullConditionalRequired on an entry that sends availableUnits or closed, as a date-time or null. A time no later than the supplier read behind the count. Supahost treats the read as 2 minutes earlier than sent, to allow for clock differences. Send null when no supplier read stands behind it. Same format and limit as revisionAt. Optional on any other entry: then only its format is checked.
days[].availableUnitsintegerOptionalTarget available units after reservations and blocks. With them it must fit the pool capacity, except on a pool whose sellable count a connected source sets. Omit it to keep the stored availability.
days[].closedbooleanOptionalWhether the pool is closed on this date. Omit it to keep the stored value. New nights default to open.
days[].stopSellbooleanOptionalWhether active rate plans stop selling this date. Omit it to keep the stored value. New nights default to false.
days[].rateobject | nullOptionalamount/currency pair, where amount is a currency amount with two decimals, such as 325.00, and must be positive. amountMinor still works and will be removed. Omit rate or send null to keep the stored rate.
days[].minStayinteger | nullOptionalMinimum stay for an arrival on this date. Omit it or send null to keep the stored value. Today a new night stores the plan’s current default when this is left out. A later change to the plan default does not move that night.
days[].minStayThroughinteger | nullOptional1 to 365 nights. Minimum stay for any stay that includes this date. Omit it or send null to keep the stored value. A night without its own value uses its minimum stay. Sending minStayThrough stores a fixed value for that night. The night then no longer follows minStay, and the API cannot clear the value today (issue #1097). To keep a night following minStay, do not send minStayThrough.
days[].maxStayintegerOptional0 to 365 nights. Zero removes the limit. Omission preserves the stored value. Today a new night stores the plan’s current default, or 14, when this is left out. A later change to the plan default does not move that night. A positive maximum cannot be less than the effective minimum stays.
days[].closedToArrivalbooleanOptionalWhether arrivals are closed. Omission preserves the stored value; new nights default to false.
days[].closedToDeparturebooleanOptionalWhether departures are closed. Omission preserves the stored value; new nights default to false.
200 JSON response
FieldTypeRequiredDescription
dataCalendarWriteResultRequiredThe applied calendar write summary.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.propertyIdstringRequiredPublic UUID of the property the calendar write applied to.
data.daysAppliedintegerRequiredEntries the write accepted and did not skip or refuse. It counts entries, including an entry that changed nothing. nightsChanged counts the nights that changed.
data.nightsChangedobjectOptionalNights the write changed. A night sent with the values Supahost already stores does not count and is not stored again. Supahost sends it to the channel again only when its last change failed and Supahost stopped retrying it. When both counts are 0, the write sends no calendar.updated webhook. Absent only when an Idempotency-Key replays a request first made before Supahost counted changed nights.
data.nightsChanged.availabilityintegerRequiredInventory pool nights whose stored availability or closed value changed.
data.nightsChanged.restrictionsintegerRequiredRate plan nights whose stored rate or stay rules changed. An entry without ratePlanId counts once for each active plan it changed.
data.nightsChanged.observationsintegerOptionalInventory pool nights whose count did not change, but whose new observedAt changed the availability the channel receives, because it changed how many held reservation nights come off the count. Supahost sends each one to the channel. It does not send a calendar.updated webhook for them, because the stored calendar did not change. Absent only when an Idempotency-Key replays a request first made before Supahost counted them.
data.countsWithoutObservationintegerOptionalInventory pool nights the write applied with observedAt: null: no supplier read stands behind their count, so every held reservation night comes off it. Absent only when an Idempotency-Key replays a request first made before Supahost counted them.
data.refusedNightsobject[]OptionalEvery pool night the write refused, with the reason. Nothing is stored for a refused night: not its count, its rates or its stay rules. The request still answers 200 and applies the other nights. The list is not capped. Absent only when an Idempotency-Key replays a request first made before Supahost refused nights.
data.refusedNights[].inventoryPoolIdstringRequiredInventory pool of the refused night.
data.refusedNights[].datestring (date)RequiredRefused stay date in YYYY-MM-DD format.
data.refusedNights[].reason'stale_revision'RequiredWhy the night was refused. "stale_revision": Supahost already stores a count for the night with a later revisionAt, so this one is older and was not applied.
data.refusedNights[].retrybooleanRequiredWhether sending the same entry again can succeed. Always false for stale_revision: drop the entry.
data.refusedNights[].revisionAtstring (date-time)RequiredThe revisionAt the request sent for the night, in UTC with 6 fractional digits.
data.refusedNights[].storedRevisionAtstring (date-time)RequiredThe later revisionAt Supahost stores for the night, in UTC with 6 fractional digits.
data.refusedNightCountintegerOptionalNumber of pool nights the write refused. Present with refusedNights.
data.skippedNightsobject[]OptionalEvery locked night the write skipped, with the reason it is locked. Present only with skipLocked=true. The list is not capped. Each night appears once, even when several entries name it.
data.skippedNights[].inventoryPoolIdstringRequiredInventory pool of the locked night. A lock covers the whole pool on that date.
data.skippedNights[].datestring (date)RequiredLocked stay date in YYYY-MM-DD format.
data.skippedNights[].reason'manual' | 'edit' | 'feed_conflict' | 'carried_over'OptionalWhy the night is locked (see lockedNights[].reason). Absent only when an Idempotency-Key replays a request first made before 2026-11-11.
data.skippedNightCountintegerOptionalNumber of locked nights the write skipped. Present only with skipLocked=true.
data.channelSyncobjectOptionalWhat the write sent to the channel. It says what was queued, not whether the channel accepted it: read the calendar with include=channel for that. Absent only when an Idempotency-Key replays a request first made before 2026-11-11.
data.channelSync.availabilityobjectRequiredAvailability of the room types the write changed.
data.channelSync.availability.outcome'queued' | 'unchanged' | 'not_written' | 'not_sent'Requiredqueued: a change is on its way to the channel. unchanged: no stored value of this kind changed, so Supahost queued nothing new. It does not say whether the channel has the values: read the calendar with include=channel for that. not_written: no entry wrote this kind of value. not_sent: Supahost does not send these values, changed or not; see reason.
data.channelSync.availability.reasonstring | nullRequiredWhy the change is not sent, or null. One of property_inactive, not_connected, no_rate_plan, awaiting_feed, derived_rate_plan: the reason the rate plan calendar with include=channel gives for those nights.
data.channelSync.restrictionsobjectRequiredRates and stay rules of the rate plans the write changed.
data.channelSync.restrictions.outcome'queued' | 'unchanged' | 'not_written' | 'not_sent'Requiredqueued: a change is on its way to the channel. unchanged: no stored value of this kind changed, so Supahost queued nothing new. It does not say whether the channel has the values: read the calendar with include=channel for that. not_written: no entry wrote this kind of value. not_sent: Supahost does not send these values, changed or not; see reason.
data.channelSync.restrictions.reasonstring | nullRequiredWhy the change is not sent, or null. One of property_inactive, not_connected, no_rate_plan, awaiting_feed, derived_rate_plan: the reason the rate plan calendar with include=channel gives for those nights.
data.channelSync.heldClosedbooleanRequiredTrue when Supahost holds the property closed on the channel, so availability goes out as 0. Read GET /properties/{propertyId}/channel-sync.
200 JSON response with validateOnly=true
FieldTypeRequiredDescription
dataCalendarValidationResultRequiredWhat a real write of the same request would answer, with nothing stored.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.propertyIdstringRequiredPublic UUID of the property the calendar write was validated against.
data.validateOnly'true'RequiredAlways true: Supahost checked the request and stored, queued and sent nothing.
data.acceptedbooleanRequiredTrue when the calendar checks would accept the request now; refusals is then empty. The Idempotency-Key is not checked against stored keys, so a real write that reuses a key with a different body can still answer 409 idempotency_key_reused.
data.refusalsobject[]RequiredEvery refusal a real write would answer with, in the order it would meet them: a body that does not match the schema, then a property whose calendar writes are paused (calendar_writes_paused), then the first failed check of the entries (the field errors, a locked night or a protected night). A paused property is still checked, so its field errors are listed too.
data.refusals[].statusintegerRequiredThe HTTP status the real write would answer with, such as 400 or 409.
data.refusals[].problemobjectRequiredThe problem document the real write would answer with: the same code, detail, errors items and field paths, and the same named nights.
data.refusals[].problem.typestringRequired
data.refusals[].problem.titlestringRequired
data.refusals[].problem.statusintegerRequired
data.refusals[].problem.codestringRequiredStable machine-readable error code. Current codes: invalid_api_key, insufficient_scope, rate_limit_exceeded, sandbox_read_only, closure_permission_required, flow_permission_required, invalid_request, invalid_reference, invalid_date_range, invalid_date, invalid_datetime, invalid_limit, invalid_status, invalid_cursor, invalid_idempotency_key, missing_idempotency_key, invalid_status_transition, invalid_property_id, invalid_reservation_id, invalid_task_id, invalid_conversation_id, invalid_webhook_id, invalid_delivery_id, invalid_flow_id, invalid_rate_plan_id, invalid_pool_id, invalid_block_id, invalid_adjustment_id, invalid_flow_request, payload_too_large, night_value_required, count_time_required, count_time_in_future, calendar_result_too_large, closure_pool_unavailable, closure_date_unavailable, not_found, idempotency_key_reused, sync_in_progress, sync_failed, reference_changed, reference_in_use, reference_inactive, calendar_feed_managed, calendar_move_pending, calendar_writes_paused, protected_calendar_closure, calendar_night_locked, date_block_started, closure_changed, conversation_closed, replies_not_supported, member_inactive, insufficient_inventory, channel_rate_plan, channel_managed, reservation_cancelled, reservation_completed, unit_assigned, multiple_items, flow_unavailable, flow_webhook_key_changed, flow_scope_mismatch, flow_context_unavailable, webhook_endpoint_disabled, webhook_delivery_in_flight, flow_changed, price_adjustment_limit_reached, precondition_failed, write_conflict, service_busy, internal_error.
data.refusals[].problem.detailstringRequired
data.refusals[].problem.requestIdstringRequired
data.refusals[].problem.retryable'no' | 'now' | 'after'RequiredWhat to do next. no: the same request fails the same way, so change the request or the records first. now: send the same request again. after: send it again once the Retry-After header’s seconds have passed. One code can carry more than one class, so read this member rather than the code.
data.refusals[].problem.errorsobject[]OptionalEvery invalid field the server found in the request, in request order, at most 100. The first item is the one detail describes. Fix them all before you send the request again.
data.refusals[].problem.errors[].fieldstringRequiredThe invalid field as a dot path: an array index is a plain number, and an array body starts with its collection name, such as days.3.rate, roomTypes.0.capacity or stay.arrivalDate. body names the request body as a whole.
data.refusals[].problem.errors[].messagestringRequiredWhat is wrong with this field.
data.refusals[].problem.errors[].codestringOptionalThe problem code for this field, such as invalid_reference. The first item has the top-level code.
data.refusals[].problem.errorsTruncatedbooleanOptionalPresent and true when the request has more than 100 invalid fields and errors lists only the first 100.
data.refusals[].problem.blockedByobjectOptionalThe record whose channel sync blocks the write. Present on sync_in_progress and sync_failed.
data.refusals[].problem.blockedBy.type'property' | 'room_type' | 'rate_plan'RequiredKind of record whose channel sync blocks the write.
data.refusals[].problem.blockedBy.idstringRequiredID of that record. Read it to see its sync state.
data.refusals[].problem.blockedBy.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
data.refusals[].problem.lockedNightsobject[]ConditionalLocked nights in the request, ordered by date and pool, each with its lock reason. Lists at most 100.
data.refusals[].problem.lockedNights[].inventoryPoolIdstringConditionalInventory pool of the locked night. A lock covers the whole pool on that date.
data.refusals[].problem.lockedNights[].datestring (date)ConditionalLocked stay date in YYYY-MM-DD format.
data.refusals[].problem.lockedNights[].reason'manual' | 'edit' | 'feed_conflict' | 'carried_over'ConditionalWhy the night is locked. "manual": a person locked it in the calendar. "edit": a person or the Supahost agent changed it on a property whose calendar was moved from the retired supplier feed to the API, or earlier, while the feed wrote it. "feed_conflict": a lock the retired supplier feed set when it found the night changed outside the feed; locks of this reason can still be on a property. "carried_over": an earlier lock on the whole day, kept for each room type.
data.refusals[].problem.lockedNightCountintegerConditionalNumber of locked nights in the request.
data.refusals[].problem.protectedNightsobject[]ConditionalProtected nights the request would reopen, ordered by date and pool. Lists at most 100. Remove these entries, or remove their protection first. Absent only in the rare case where the database refused the write before the nights could be named.
data.refusals[].problem.protectedNights[].inventoryPoolIdstringConditionalInventory pool of the protected night.
data.refusals[].problem.protectedNights[].datestring (date)ConditionalProtected stay date in YYYY-MM-DD format.
data.refusals[].problem.protectedNightCountintegerConditionalNumber of protected nights the request would reopen. Present with protectedNights.
data.daysAppliedintegerOptionalPresent when accepted and the validation ran the night writes: a key with calendar:write, on a property a real write would not refuse for its calendar authority. The entries a real write would apply now, as in the write summary.
data.nightsChangedobjectOptionalPresent with daysApplied: the nights a real write would change now, counted exactly as the write counts them.
data.nightsChanged.availabilityintegerRequiredInventory pool nights whose stored availability or closed value changed.
data.nightsChanged.restrictionsintegerRequiredRate plan nights whose stored rate or stay rules changed. An entry without ratePlanId counts once for each active plan it changed.
data.nightsChanged.observationsintegerOptionalInventory pool nights whose count did not change, but whose new observedAt changed the availability the channel receives, because it changed how many held reservation nights come off the count. Supahost sends each one to the channel. It does not send a calendar.updated webhook for them, because the stored calendar did not change. Absent only when an Idempotency-Key replays a request first made before Supahost counted them.
data.countsWithoutObservationintegerOptionalPresent with daysApplied: the inventory pool nights a real write would apply with observedAt: null.
data.refusedNightsobject[]OptionalPresent when accepted: every pool night a real write would refuse now, with the reason, as in the write summary. A refused night does not make the request a refusal.
data.refusedNights[].inventoryPoolIdstringRequiredInventory pool of the refused night.
data.refusedNights[].datestring (date)RequiredRefused stay date in YYYY-MM-DD format.
data.refusedNights[].reason'stale_revision'RequiredWhy the night was refused. "stale_revision": Supahost already stores a count for the night with a later revisionAt, so this one is older and was not applied.
data.refusedNights[].retrybooleanRequiredWhether sending the same entry again can succeed. Always false for stale_revision: drop the entry.
data.refusedNights[].revisionAtstring (date-time)RequiredThe revisionAt the request sent for the night, in UTC with 6 fractional digits.
data.refusedNights[].storedRevisionAtstring (date-time)RequiredThe later revisionAt Supahost stores for the night, in UTC with 6 fractional digits.
data.refusedNightCountintegerOptionalPresent with refusedNights: how many there are.
data.skippedNightsobject[]OptionalPresent when accepted with skipLocked=true: every locked night a real write would skip, with its reason.
data.skippedNights[].inventoryPoolIdstringRequiredInventory pool of the locked night. A lock covers the whole pool on that date.
data.skippedNights[].datestring (date)RequiredLocked stay date in YYYY-MM-DD format.
data.skippedNights[].reason'manual' | 'edit' | 'feed_conflict' | 'carried_over'OptionalWhy the night is locked (see lockedNights[].reason). Absent only when an Idempotency-Key replays a request first made before 2026-11-11.
data.skippedNightCountintegerOptionalPresent with skippedNights: how many there are.
409 calendar_night_locked response
FieldTypeRequiredDescription
typestringRequired
titlestringRequired
statusintegerRequired
codestringRequiredStable machine-readable error code. Current codes: invalid_api_key, insufficient_scope, rate_limit_exceeded, sandbox_read_only, closure_permission_required, flow_permission_required, invalid_request, invalid_reference, invalid_date_range, invalid_date, invalid_datetime, invalid_limit, invalid_status, invalid_cursor, invalid_idempotency_key, missing_idempotency_key, invalid_status_transition, invalid_property_id, invalid_reservation_id, invalid_task_id, invalid_conversation_id, invalid_webhook_id, invalid_delivery_id, invalid_flow_id, invalid_rate_plan_id, invalid_pool_id, invalid_block_id, invalid_adjustment_id, invalid_flow_request, payload_too_large, night_value_required, count_time_required, count_time_in_future, calendar_result_too_large, closure_pool_unavailable, closure_date_unavailable, not_found, idempotency_key_reused, sync_in_progress, sync_failed, reference_changed, reference_in_use, reference_inactive, calendar_feed_managed, calendar_move_pending, calendar_writes_paused, protected_calendar_closure, calendar_night_locked, date_block_started, closure_changed, conversation_closed, replies_not_supported, member_inactive, insufficient_inventory, channel_rate_plan, channel_managed, reservation_cancelled, reservation_completed, unit_assigned, multiple_items, flow_unavailable, flow_webhook_key_changed, flow_scope_mismatch, flow_context_unavailable, webhook_endpoint_disabled, webhook_delivery_in_flight, flow_changed, price_adjustment_limit_reached, precondition_failed, write_conflict, service_busy, internal_error.
detailstringRequired
requestIdstringRequired
retryable'no' | 'now' | 'after'RequiredWhat to do next. no: the same request fails the same way, so change the request or the records first. now: send the same request again. after: send it again once the Retry-After header’s seconds have passed. One code can carry more than one class, so read this member rather than the code.
errorsobject[]OptionalEvery invalid field the server found in the request, in request order, at most 100. The first item is the one detail describes. Fix them all before you send the request again.
errors[].fieldstringRequiredThe invalid field as a dot path: an array index is a plain number, and an array body starts with its collection name, such as days.3.rate, roomTypes.0.capacity or stay.arrivalDate. body names the request body as a whole.
errors[].messagestringRequiredWhat is wrong with this field.
errors[].codestringOptionalThe problem code for this field, such as invalid_reference. The first item has the top-level code.
errorsTruncatedbooleanOptionalPresent and true when the request has more than 100 invalid fields and errors lists only the first 100.
blockedByobjectOptionalThe record whose channel sync blocks the write. Present on sync_in_progress and sync_failed.
blockedBy.type'property' | 'room_type' | 'rate_plan'RequiredKind of record whose channel sync blocks the write.
blockedBy.idstringRequiredID of that record. Read it to see its sync state.
blockedBy.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
lockedNightsobject[]RequiredLocked nights in the request, ordered by date and pool, each with its lock reason. Lists at most 100.
lockedNights[].inventoryPoolIdstringRequiredInventory pool of the locked night. A lock covers the whole pool on that date.
lockedNights[].datestring (date)RequiredLocked stay date in YYYY-MM-DD format.
lockedNights[].reason'manual' | 'edit' | 'feed_conflict' | 'carried_over'RequiredWhy the night is locked. "manual": a person locked it in the calendar. "edit": a person or the Supahost agent changed it on a property whose calendar was moved from the retired supplier feed to the API, or earlier, while the feed wrote it. "feed_conflict": a lock the retired supplier feed set when it found the night changed outside the feed; locks of this reason can still be on a property. "carried_over": an earlier lock on the whole day, kept for each room type.
lockedNightCountintegerRequiredNumber of locked nights in the request.
409 protected_calendar_closure response
FieldTypeRequiredDescription
typestringRequired
titlestringRequired
statusintegerRequired
codestringRequiredStable machine-readable error code. Current codes: invalid_api_key, insufficient_scope, rate_limit_exceeded, sandbox_read_only, closure_permission_required, flow_permission_required, invalid_request, invalid_reference, invalid_date_range, invalid_date, invalid_datetime, invalid_limit, invalid_status, invalid_cursor, invalid_idempotency_key, missing_idempotency_key, invalid_status_transition, invalid_property_id, invalid_reservation_id, invalid_task_id, invalid_conversation_id, invalid_webhook_id, invalid_delivery_id, invalid_flow_id, invalid_rate_plan_id, invalid_pool_id, invalid_block_id, invalid_adjustment_id, invalid_flow_request, payload_too_large, night_value_required, count_time_required, count_time_in_future, calendar_result_too_large, closure_pool_unavailable, closure_date_unavailable, not_found, idempotency_key_reused, sync_in_progress, sync_failed, reference_changed, reference_in_use, reference_inactive, calendar_feed_managed, calendar_move_pending, calendar_writes_paused, protected_calendar_closure, calendar_night_locked, date_block_started, closure_changed, conversation_closed, replies_not_supported, member_inactive, insufficient_inventory, channel_rate_plan, channel_managed, reservation_cancelled, reservation_completed, unit_assigned, multiple_items, flow_unavailable, flow_webhook_key_changed, flow_scope_mismatch, flow_context_unavailable, webhook_endpoint_disabled, webhook_delivery_in_flight, flow_changed, price_adjustment_limit_reached, precondition_failed, write_conflict, service_busy, internal_error.
detailstringRequired
requestIdstringRequired
retryable'no' | 'now' | 'after'RequiredWhat to do next. no: the same request fails the same way, so change the request or the records first. now: send the same request again. after: send it again once the Retry-After header’s seconds have passed. One code can carry more than one class, so read this member rather than the code.
errorsobject[]OptionalEvery invalid field the server found in the request, in request order, at most 100. The first item is the one detail describes. Fix them all before you send the request again.
errors[].fieldstringRequiredThe invalid field as a dot path: an array index is a plain number, and an array body starts with its collection name, such as days.3.rate, roomTypes.0.capacity or stay.arrivalDate. body names the request body as a whole.
errors[].messagestringRequiredWhat is wrong with this field.
errors[].codestringOptionalThe problem code for this field, such as invalid_reference. The first item has the top-level code.
errorsTruncatedbooleanOptionalPresent and true when the request has more than 100 invalid fields and errors lists only the first 100.
blockedByobjectOptionalThe record whose channel sync blocks the write. Present on sync_in_progress and sync_failed.
blockedBy.type'property' | 'room_type' | 'rate_plan'RequiredKind of record whose channel sync blocks the write.
blockedBy.idstringRequiredID of that record. Read it to see its sync state.
blockedBy.reasonstring | nullRequiredWhy the sync is failing, or null. Current reasons: channel_rejected, channel_unreachable, confirmation_unavailable, connection_problem, setup_incomplete, other. Treat an unknown reason as other.
protectedNightsobject[]OptionalProtected nights the request would reopen, ordered by date and pool. Lists at most 100. Remove these entries, or remove their protection first. Absent only in the rare case where the database refused the write before the nights could be named.
protectedNights[].inventoryPoolIdstringRequiredInventory pool of the protected night.
protectedNights[].datestring (date)RequiredProtected stay date in YYYY-MM-DD format.
protectedNightCountintegerOptionalNumber of protected nights the request would reopen. Present with protectedNights.

GET /properties/{propertyId}/rate-plans/{ratePlanId}/calendar

Verify nightly prices and all restrictions for one active plan with the calendar:read scope. The response includes stop-sold nights, also those without a rate.

stopSell reports the stored flag. rate is null on a night without a rate, such as a stopped night written without one, and that night does not sell. minStayThrough is null when the night follows minStay. rate falls back to the plan base price when no night exists. Other defaults are minimum 1, maximum 14, and false flags. Maximum 0 means unlimited.

Pool availability subtracts reservations and property-local blocks. Closed pools return zero availability while their plan prices and restrictions remain visible.

Both dates are inclusive. The default range spans 31 days from today in the property time zone. The maximum is 92 days. The endpoint returns 404 for an unknown property, mismatched plan, inactive plan or inactive pool. It reads Supahost data and does not read the channel.

Send include=channel to add a channel object to each row. It says, per night, whether the channel has what Supahost holds for it, and why not. See Channel delivery state below. Without include the response and its cost are unchanged. Here restrictions is this rate plan and availability is its pool's room type.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
ratePlanIdstring (uuid)RequiredRate plan UUID on this property.
Query parameters
FieldTypeRequiredDescription
fromstring (date)OptionalFirst stay date, inclusive. The default is today in the property time zone.
tostring (date)OptionalLast stay date, inclusive. The default is 30 days after from; the range can span at most 92 days.
include'channel'OptionalSend channel to add a channel object to each row: whether the channel has what Supahost holds for that night, and why not. Without it the response is unchanged.
200 JSON response
FieldTypeRequiredDescription
dataRatePlanCalendarDay[]RequiredOne row per stay date for the selected rate plan.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data[].datestring (date)RequiredStay date in YYYY-MM-DD format.
data[].inventoryPoolobjectRequiredInventory pool this row describes.
data[].inventoryPool.idstringRequiredStable inventory pool ID.
data[].inventoryPool.codestringRequiredInventory pool code.
data[].inventoryPool.namestringRequiredInventory pool display name.
data[].inventoryPool.strategy'pooled' | 'fixed_unit' | 'entitlement'RequiredInventory strategy of the pool.
data[].inventoryPool.roomTypeIdstringRequiredRoom type the pool sells.
data[].availableUnitsintegerRequiredUnits left after reservations and blocks; 0 when the pool is closed.
data[].closedbooleanRequiredWhether the pool is closed on this date.
data[].stopSellbooleanRequiredStored stop-sell restriction for this plan; false when no night exists. A night with a null rate does not sell either.
data[].rateobject | nullRequiredStored nightly price with base-price fallback, also on stop-sold nights that have one. Null when the night has no rate: a stop-sold night written without a rate is kept that way, and it needs a rate before it can be reopened.
data[].rate.amountstringConditionalRequired when rate is an object. Amount in the currency unit with two decimals (325.00).
data[].rate.amountMinorstringConditionalRequired when rate is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data[].rate.currencystringConditionalRequired when rate is an object. Three-letter currency code.
data[].minStayintegerRequiredMinimum stay for an arrival on this date; defaults to 1 when no night exists.
data[].minStayThroughinteger | nullRequiredSeparate minimum stay for any stay that includes this date. Null means the night follows minStay.
data[].channelobjectOptionalWhether the channel has what Supahost holds for this night. Present only with include=channel.
data[].channel.availabilityobjectRequiredChannel state of the room type availability on this night.
data[].channel.availability.state'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent'Requiredsynced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why.
data[].channel.availability.reasonstring | nullRequiredWhy the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other.
data[].channel.availability.valueinteger | nullRequiredThe availability Supahost holds for the channel on this night: the room type total after holds and the close-out. It can differ from the row's availableUnits, which is one pool. 0 while held. Null when the night is not sent.
data[].channel.availability.observedValueintegerOptionalThe availability a read of the channel showed when it differed from value. Present only then.
data[].channel.availability.changedAtstring (date-time) | nullRequiredWhen Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent.
data[].channel.restrictionsobjectRequiredChannel state of the rates and stay rules on this night. On the rate plan calendar it is that plan. On the property calendar it sums up the pool's active rate plans: failed when one failed, else pending when one is pending, else synced when one reaches the channel, else not_sent (no_rate_plan when the pool has no active plan).
data[].channel.restrictions.state'synced' | 'pending' | 'failed' | 'held' | 'closed_by_channel' | 'not_sent'Requiredsynced: Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this. pending: A change is on its way to the channel, or Supahost is retrying one. failed: The last change failed and Supahost will not retry it. A person must resolve it in Supahost. held: Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there. closed_by_channel: The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again. not_sent: Supahost does not send this night to the channel. reason says why.
data[].channel.restrictions.reasonstring | nullRequiredWhy the night is not synced, or null. Current reasons: channel_rejected, channel_mismatch, channel_unreachable, confirmation_unavailable, connection_problem, closed_by_channel_cutoff, activation_unconfirmed, property_inactive, not_connected, derived_rate_plan, no_rate_plan, past_night, awaiting_value, awaiting_feed, other. Treat an unknown reason as other.
data[].channel.restrictions.changedAtstring (date-time) | nullRequiredWhen Supahost last recorded a change to the delivery behind this state: the queued or retried change, the failure, or the closure. For held, when the hold started (the hold.since of GET /properties/{propertyId}/channel-sync). Null for synced and not_sent.
data[].holdsobjectOptionalWith include=holds: what Supahost takes off this pool night’s count for held nights, and why.
data[].holds.countinteger | nullRequiredThe night’s own count before blocks and held nights come off: the stored sellable count less reservations. On a property whose calendar was moved from the retired supplier feed to the API, Supahost stores the availableUnits you write as sent, so count is your number. On every other property it stores your availableUnits plus the units blocks hold at that moment. Either way a block added or removed later changes blocked, not count. Null when the night has no count of its own and follows the pool capacity.
data[].holds.closedbooleanRequiredWhether the pool is closed on this date.
data[].holds.sentobject | nullRequiredThe times of the last count the API wrote for this pool night, or null when the API never wrote one.
data[].holds.sent.observedAtstring (date-time) | nullConditionalRequired when sent is an object. The observedAt you sent, or null when you sent observedAt: null.
data[].holds.sent.revisionAtstring (date-time)ConditionalRequired when sent is an object. The newest revisionAt Supahost accepted for this pool night.
data[].holds.sent.recordedAtstring (date-time)ConditionalRequired when sent is an object. When Supahost stored it.
data[].holds.observedAtUsedstring (date-time) | nullRequiredThe read time Supahost compares confirmations with, as stored. When your write stored it, it is 2 minutes before the observedAt you sent; when the retired supplier feed stored it, it is the feed’s own read time. Null when no read time belongs to the stored count.
data[].holds.blockedintegerRequiredUnits availability blocks hold on this date.
data[].holds.subtractedintegerRequiredUnits that come off the count for held nights not yet included in it: the sum of units over heldNights with reflected: false. Always 0 on a pool whose count no connected source sets, and on a night without its own count.
data[].holds.sendsinteger | nullRequiredThis pool’s part of the availability Supahost computes for the channel for the room type night: 0 when closed, otherwise the count (or the pool capacity less reservations) less blocked and subtracted, never below 0. The room type gets the sum over its active pools. Null when the channel receives nothing for this room type night: the night is in the past, the property or its room type is not connected to a channel, or the property’s calendar comes from a connected source and a pool of the room type has no count of its own that night. It is the value before Supahost holds a property closed on the channel, which sends 0 instead, and before the channel closes tonight at its own cut-off. What the channel has is in include=channel.
data[].holds.reflectableAfterstring (date-time) | nullRequiredThe earliest reflectedFromObservedAt among heldNights with reflected: false, or null when no such night has one. Sending the same count again with a later observedAt can change what the channel receives only when that observedAt is later than this, and only on a property whose calendar you write through the API (elsewhere the write is refused). On a closed night, or one already at 0 after the held nights that stay off, it changes nothing the channel receives: Supahost stores the new time and sends nothing.
data[].holds.heldNightsobject[]RequiredEach reservation holding units on this pool night, oldest allocation first. Empty where nothing comes off for held nights: a pool whose count no connected source sets, or a night without its own count.
data[].holds.heldNights[].reservationIdstringRequiredThe reservation that holds units on this pool night.
data[].holds.heldNights[].status'tentative' | 'confirmed'RequiredReservation status. Cancelled reservations hold nothing and are not listed.
data[].holds.heldNights[].unitsintegerRequiredUnits the reservation holds on this pool night.
data[].holds.heldNights[].allocatedAtstring (date-time)RequiredWhen the reservation got this pool night.
data[].holds.heldNights[].confirmationRecordedAtstring (date-time) | nullRequiredWhen Supahost recorded the newest confirmation from the connected source that covers this night, or null when there is none.
data[].holds.heldNights[].reflectedbooleanRequiredWhether your count already includes this night, so nothing comes off for it.
data[].holds.heldNights[].reason'no_observation' | 'count_changed_since_observation' | 'several_rooms' | 'no_confirmation' | 'confirmed_before_allocation' | 'confirmed_after_observation' | 'null'RequiredWhy the night still comes off your count, the first that applies: no_observation (no read time stands behind the count), count_changed_since_observation (the stored count is no longer the count that read time belongs to), several_rooms (the reservation holds more than one room that night), no_confirmation, confirmed_before_allocation (a confirmation is from before the reservation got this pool night), confirmed_after_observation (a confirmation is not earlier than the read time). Null when reflected is true.
data[].holds.heldNights[].reflectedFromObservedAtstring (date-time) | nullRequiredThe latest observedAt that still leaves this night off your count: sent with the same count, an observedAt later than this counts the night as included. It is the confirmation time plus the 2 minutes Supahost takes off every observedAt. Null when no read time can include the night: the reservation holds more than one room that night, it has no confirmation, or a confirmation is from before it got this pool night. reason names only the first cause, so this can be null under no_observation or count_changed_since_observation too.
data[].ratePlanIdstringRequiredRate plan ID this row describes.
data[].maxStayintegerRequiredMaximum stay; 0 means unlimited. Defaults to 14 when no night exists.
data[].closedToArrivalbooleanRequiredArrival restriction; defaults to false when no night exists.
data[].closedToDeparturebooleanRequiredDeparture restriction; defaults to false when no night exists.

GET /properties/{propertyId}/channel-sync

Read the channel sync state of one property in one object. This endpoint requires the calendar:read scope. It covers every night from today in the property time zone. Reading it queues or sends nothing.

state is not_sent when Supahost sends nothing for the property, then held when it holds the nights closed, then failing when a night failed, then pending when a change is on its way, else synced. availability and restrictions each have their own state, the number of changes Supahost is sending now (pendingDeliveries), the nights whose last change failed (failedNights), and when the channel last confirmed a change (lastConfirmedAt).

firstIssueDate and lastIssueDate are the first and last nights that are pending or failed. Read the calendar with include=channel between those dates to see each night. The calendar read spans at most 92 days, so a wide window takes more than one read.

hold is set while Supahost holds every night closed on the channel because it could not confirm the property calendar there. retriesExhausted is true when Supahost stopped retrying on its own. Then a person must reconnect the property or ask support.

lastCalendarWriteAt is when Supahost last accepted a calendar write for the property through the API (PUT /properties/{propertyId}/calendar without validateOnly), or null when it recorded none. A write that changed nothing counts. A write refused as a whole, such as a 400 or 409, and a replay of an Idempotency-Key do not. Writes accepted before 2026-11-12 are included only when they sent an available count. If your system writes the calendar, use it to check that your writer is still sending: when it stops, Supahost keeps the last values you sent and the channel keeps selling them.

Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
200 JSON response
FieldTypeRequiredDescription
dataChannelSyncRequiredThe channel sync state of the property.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.propertyIdstringRequiredProperty UUID.
data.state'synced' | 'pending' | 'failing' | 'held' | 'not_sent'Requirednot_sent when nothing is sent, else held when the nights are held closed, else failing when a night failed, else pending when a change is on its way, else synced.
data.reasonstring | nullRequiredWhy nothing is sent (property_inactive or not_connected), or null.
data.holdobject | nullRequiredSupahost holds every night closed on the channel (availability 0), or null.
data.hold.reason'activation_unconfirmed'ConditionalRequired when hold is an object. Why Supahost holds the nights closed.
data.hold.sincestring (date-time)ConditionalRequired when hold is an object. When the hold started.
data.hold.retriesExhaustedbooleanConditionalRequired when hold is an object. True when Supahost stopped retrying on its own. A person must reconnect the property or ask support.
data.availabilityobjectRequiredRoom type availability.
data.availability.state'synced' | 'pending' | 'failing' | 'held' | 'not_sent'Requiredsynced: nothing outstanding. pending: changes are on their way. failing: some nights failed. held: the nights are held closed. not_sent: nothing is sent.
data.availability.pendingDeliveriesintegerRequiredChanges Supahost is sending or retrying now.
data.availability.failedNightsintegerRequiredNights from today whose last change failed and that Supahost will not retry.
data.availability.firstIssueDatestring (date) | nullRequiredFirst night from today that is pending or failed, or null.
data.availability.lastIssueDatestring (date) | nullRequiredLast night that is pending or failed, or null. Read the calendar with include=channel between the two dates.
data.availability.lastConfirmedAtstring (date-time) | nullRequiredWhen the channel last confirmed a change of this kind, or null.
data.restrictionsobjectRequiredRates and stay rules.
data.restrictions.state'synced' | 'pending' | 'failing' | 'held' | 'not_sent'Requiredsynced: nothing outstanding. pending: changes are on their way. failing: some nights failed. held: the nights are held closed. not_sent: nothing is sent.
data.restrictions.pendingDeliveriesintegerRequiredChanges Supahost is sending or retrying now.
data.restrictions.failedNightsintegerRequiredNights from today whose last change failed and that Supahost will not retry.
data.restrictions.firstIssueDatestring (date) | nullRequiredFirst night from today that is pending or failed, or null.
data.restrictions.lastIssueDatestring (date) | nullRequiredLast night that is pending or failed, or null. Read the calendar with include=channel between the two dates.
data.restrictions.lastConfirmedAtstring (date-time) | nullRequiredWhen the channel last confirmed a change of this kind, or null.
data.checkedAtstring (date-time)RequiredWhen Supahost read this state. Supahost reads its own records, not the channel.
data.lastCalendarWriteAtstring (date-time) | nullRequiredWhen Supahost last accepted a calendar write for this property through the API (PUT /properties/{propertyId}/calendar, not validateOnly), or null when it recorded none. A write that changed nothing counts; a write refused as a whole (for example 400 or 409) and an Idempotency-Key replay do not. Writes accepted before 2026-11-12 are included only when they sent an available count. Use it to check that your writer is still sending.

Reservation endpoints require the reservations:read scope. Required response fields are always present; nullable fields include null in their type.

items lists the booked room lines of the reservation. Line totals use the currency recorded for the booked nights. An item without a recorded price returns total null, including older cancelled items.

An imported reservation without a known guest price also returns total null. A free stay returns an amount of "0.00". Owner payouts do not replace guest prices.

Money is a currency amount with two decimals, such as "325.00", and a 3-letter currency code. Supahost converts it for you. Send amount as a string or a number. amountMinor still works and will be removed.

GET /reservations

Return one stable page of reservations.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
propertyIdstring (uuid)OptionalReturn reservations for one public property UUID.
property_idstring (uuid)OptionalDeprecated: use propertyId.
arrivalFromstring (date)OptionalReturn arrivals on or after this YYYY-MM-DD date.
arrival_fromstring (date)OptionalDeprecated: use arrivalFrom.
arrivalTostring (date)OptionalReturn arrivals on or before this YYYY-MM-DD date.
arrival_tostring (date)OptionalDeprecated: use arrivalTo.
referencestringOptionalReturn only the reservation whose reference is exactly this value, whatever its status.
200 JSON response
FieldTypeRequiredDescription
dataReservation[]RequiredA stable page of reservation records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable reservation ID.
data[].confirmationCodestringRequiredGuest-facing confirmation code.
data[].status'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled'RequiredReservation lifecycle status.
data[].updatedAtstring (date-time)RequiredLast reservation change time.
data[].guestobjectRequiredGuest contact summary.
data[].guest.namestringRequiredGuest name.
data[].guest.emailstring | nullRequiredGuest email address, or null.
data[].guest.phonestring | nullRequiredGuest phone number, or null.
data[].propertyobjectRequiredReserved property summary.
data[].property.idstringRequiredPublic property UUID.
data[].property.namestringRequiredProperty name.
data[].stayobjectRequiredStay dates and length.
data[].stay.arrivalDatestring (date)RequiredArrival date in YYYY-MM-DD format.
data[].stay.departureDatestring (date)RequiredDeparture date in YYYY-MM-DD format.
data[].stay.nightsintegerRequiredNumber of nights.
data[].occupancyobjectRequiredGuest and room counts.
data[].occupancy.adultsintegerRequiredAdult count.
data[].occupancy.childrenintegerRequiredChild count.
data[].occupancy.roomsintegerRequiredBooked room quantity.
data[].totalobject | nullRequiredReservation total. Null when the imported guest price is unknown.
data[].total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data[].total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data[].total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data[].sourceobjectRequiredReservation origin.
data[].source.type'direct' | 'channel'RequiredWhether the reservation was direct or arrived from a channel.
data[].source.channelstringConditionalRequired when source.type is channel.
data[].itemsobject[]RequiredBooked room lines with per-line totals from their nightly rates.
data[].items[].idstringRequiredStable reservation item ID.
data[].items[].status'pending' | 'confirmed' | 'cancelled'RequiredItem lifecycle status.
data[].items[].checkInDatestring (date)RequiredCheck-in date in YYYY-MM-DD format.
data[].items[].checkOutDatestring (date)RequiredCheck-out date in YYYY-MM-DD format.
data[].items[].nightsintegerRequiredNumber of nights.
data[].items[].quantityintegerRequiredBooked room quantity.
data[].items[].adultsintegerRequiredAdult count.
data[].items[].childrenintegerRequiredChild count.
data[].items[].inventoryPoolIdstringRequiredInventory pool the item books.
data[].items[].ratePlanIdstringRequiredRate plan the item is priced with.
data[].items[].totalobject | nullRequiredBooked item total in the recorded currency; null when the price is unknown, including older cancelled items.
data[].items[].total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data[].items[].total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data[].items[].total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data[].referencestring | nullOptionalYour own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots.

GET /reservations/{reservationId}

Return one reservation from the API key workspace.

The response includes an ETag header that names this version of the reservation. Send it in If-None-Match to get 304 with no body when the reservation did not change. The tag names the whole response, so it also changes when a derived value, such as a line in items, changes.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-None-MatchstringOptionalThe ETag from your last read. Returns 304 with no body when the reservation did not change.
Path parameters
FieldTypeRequiredDescription
reservationIdstring (uuid)RequiredReservation UUID.
200 JSON response
FieldTypeRequiredDescription
dataReservationRequiredThe requested reservation.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable reservation ID.
data.confirmationCodestringRequiredGuest-facing confirmation code.
data.status'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled'RequiredReservation lifecycle status.
data.updatedAtstring (date-time)RequiredLast reservation change time.
data.guestobjectRequiredGuest contact summary.
data.guest.namestringRequiredGuest name.
data.guest.emailstring | nullRequiredGuest email address, or null.
data.guest.phonestring | nullRequiredGuest phone number, or null.
data.propertyobjectRequiredReserved property summary.
data.property.idstringRequiredPublic property UUID.
data.property.namestringRequiredProperty name.
data.stayobjectRequiredStay dates and length.
data.stay.arrivalDatestring (date)RequiredArrival date in YYYY-MM-DD format.
data.stay.departureDatestring (date)RequiredDeparture date in YYYY-MM-DD format.
data.stay.nightsintegerRequiredNumber of nights.
data.occupancyobjectRequiredGuest and room counts.
data.occupancy.adultsintegerRequiredAdult count.
data.occupancy.childrenintegerRequiredChild count.
data.occupancy.roomsintegerRequiredBooked room quantity.
data.totalobject | nullRequiredReservation total. Null when the imported guest price is unknown.
data.total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data.total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data.sourceobjectRequiredReservation origin.
data.source.type'direct' | 'channel'RequiredWhether the reservation was direct or arrived from a channel.
data.source.channelstringConditionalRequired when source.type is channel.
data.itemsobject[]RequiredBooked room lines with per-line totals from their nightly rates.
data.items[].idstringRequiredStable reservation item ID.
data.items[].status'pending' | 'confirmed' | 'cancelled'RequiredItem lifecycle status.
data.items[].checkInDatestring (date)RequiredCheck-in date in YYYY-MM-DD format.
data.items[].checkOutDatestring (date)RequiredCheck-out date in YYYY-MM-DD format.
data.items[].nightsintegerRequiredNumber of nights.
data.items[].quantityintegerRequiredBooked room quantity.
data.items[].adultsintegerRequiredAdult count.
data.items[].childrenintegerRequiredChild count.
data.items[].inventoryPoolIdstringRequiredInventory pool the item books.
data.items[].ratePlanIdstringRequiredRate plan the item is priced with.
data.items[].totalobject | nullRequiredBooked item total in the recorded currency; null when the price is unknown, including older cancelled items.
data.items[].total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data.items[].total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.items[].total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data.referencestring | nullOptionalYour own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots.

POST /reservations

Create one direct reservation. This endpoint requires the reservations:write scope. The body mirrors the read row: guest, stay, occupancy, and one items line with the ratePlanId to book.

The rate plan, its inventory pool, and the property must be active, and a channel-mapped (OTA) rate plan cannot take a direct booking. The total prices from the plan’s base rate for every night. Inventory allocates inside the same transaction and the availability change queues to the channel sync outbox asynchronously. Owner (entitlement) inventory cannot be booked through this endpoint.

Capacity failures return 400 insufficient_inventory. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns the original reservation instead of booking twice; the same key with a different payload fails with 409 idempotency_key_reused.

A reference also makes the create safe to repeat, with no time limit. If a reservation already has the reference, nothing is booked and no inventory is checked. When its guest, stay dates, occupancy and rate plan match the request, the answer is 200 with that reservation, also when it was cancelled since. When they differ, the answer is 409 reference_in_use. The Idempotency-Key is checked first. Find a booking by its reference with GET /reservations?reference=. Channel booking codes are never references.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes retries safe.
JSON body
FieldTypeRequiredDescription
guest.namestringRequiredGuest name, 2 to 120 characters.
guest.emailstring | nullRequiredGuest email address, or null.
stay.arrivalDatestring (date)RequiredArrival date in YYYY-MM-DD format.
stay.departureDatestring (date)RequiredDeparture date in YYYY-MM-DD format, 1 to 365 nights after arrival.
occupancy.adultsintegerRequiredAdult count, 1 to 500. Adults plus children must fit the room capacity.
occupancy.childrenintegerRequiredChild count, 0 to 500.
occupancy.roomsintegerRequiredBooked room quantity, 1 to 100.
items[].ratePlanIdstringRequiredRate plan the line books. Exactly one line; other read fields on items are ignored.
referencestring | nullOptionalYour own identifier for the booking, 1 to 128 characters, unique in the workspace. On replace, omit it to keep the stored value and send null to clear it.
201 JSON response
FieldTypeRequiredDescription
dataReservationRequiredThe stored reservation after the write.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable reservation ID.
data.confirmationCodestringRequiredGuest-facing confirmation code.
data.status'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled'RequiredReservation lifecycle status.
data.updatedAtstring (date-time)RequiredLast reservation change time.
data.guestobjectRequiredGuest contact summary.
data.guest.namestringRequiredGuest name.
data.guest.emailstring | nullRequiredGuest email address, or null.
data.guest.phonestring | nullRequiredGuest phone number, or null.
data.propertyobjectRequiredReserved property summary.
data.property.idstringRequiredPublic property UUID.
data.property.namestringRequiredProperty name.
data.stayobjectRequiredStay dates and length.
data.stay.arrivalDatestring (date)RequiredArrival date in YYYY-MM-DD format.
data.stay.departureDatestring (date)RequiredDeparture date in YYYY-MM-DD format.
data.stay.nightsintegerRequiredNumber of nights.
data.occupancyobjectRequiredGuest and room counts.
data.occupancy.adultsintegerRequiredAdult count.
data.occupancy.childrenintegerRequiredChild count.
data.occupancy.roomsintegerRequiredBooked room quantity.
data.totalobject | nullRequiredReservation total. Null when the imported guest price is unknown.
data.total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data.total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data.sourceobjectRequiredReservation origin.
data.source.type'direct' | 'channel'RequiredWhether the reservation was direct or arrived from a channel.
data.source.channelstringConditionalRequired when source.type is channel.
data.itemsobject[]RequiredBooked room lines with per-line totals from their nightly rates.
data.items[].idstringRequiredStable reservation item ID.
data.items[].status'pending' | 'confirmed' | 'cancelled'RequiredItem lifecycle status.
data.items[].checkInDatestring (date)RequiredCheck-in date in YYYY-MM-DD format.
data.items[].checkOutDatestring (date)RequiredCheck-out date in YYYY-MM-DD format.
data.items[].nightsintegerRequiredNumber of nights.
data.items[].quantityintegerRequiredBooked room quantity.
data.items[].adultsintegerRequiredAdult count.
data.items[].childrenintegerRequiredChild count.
data.items[].inventoryPoolIdstringRequiredInventory pool the item books.
data.items[].ratePlanIdstringRequiredRate plan the item is priced with.
data.items[].totalobject | nullRequiredBooked item total in the recorded currency; null when the price is unknown, including older cancelled items.
data.items[].total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data.items[].total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.items[].total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data.referencestring | nullOptionalYour own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots.

PUT /reservations/{reservationId}

Replace the writable fields of one direct reservation. This endpoint requires the reservations:write scope. The body is the same shape as the create body; the stored allocation moves to the new dates, rate plan, and room quantity, and the total reprices.

Channel reservations must be changed in the connected channel (400 channel_managed). Cancelled, started, or completed reservations cannot be changed, and reservations with assigned units or multiple item records need the dashboard.

A reference that another reservation holds fails with 409 reference_in_use.

To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the reservation changed since, the response is 412 precondition_failed and nothing is written. Read the reservation again and repeat the change. Without If-Match, the replacement always applies. A 412 can also come from a derived value that moved, such as a line in items: read the reservation again and repeat the change; it is not an error to show.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes retries safe.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the reservation changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
reservationIdstring (uuid)RequiredReservation UUID.
JSON body
FieldTypeRequiredDescription
guest.namestringRequiredGuest name, 2 to 120 characters.
guest.emailstring | nullRequiredGuest email address, or null.
stay.arrivalDatestring (date)RequiredArrival date in YYYY-MM-DD format.
stay.departureDatestring (date)RequiredDeparture date in YYYY-MM-DD format, 1 to 365 nights after arrival.
occupancy.adultsintegerRequiredAdult count, 1 to 500. Adults plus children must fit the room capacity.
occupancy.childrenintegerRequiredChild count, 0 to 500.
occupancy.roomsintegerRequiredBooked room quantity, 1 to 100.
items[].ratePlanIdstringRequiredRate plan the line books. Exactly one line; other read fields on items are ignored.
referencestring | nullOptionalYour own identifier for the booking, 1 to 128 characters, unique in the workspace. On replace, omit it to keep the stored value and send null to clear it.
200 JSON response
FieldTypeRequiredDescription
dataReservationRequiredThe stored reservation after the write.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable reservation ID.
data.confirmationCodestringRequiredGuest-facing confirmation code.
data.status'pending' | 'confirmed' | 'in_house' | 'completed' | 'cancelled'RequiredReservation lifecycle status.
data.updatedAtstring (date-time)RequiredLast reservation change time.
data.guestobjectRequiredGuest contact summary.
data.guest.namestringRequiredGuest name.
data.guest.emailstring | nullRequiredGuest email address, or null.
data.guest.phonestring | nullRequiredGuest phone number, or null.
data.propertyobjectRequiredReserved property summary.
data.property.idstringRequiredPublic property UUID.
data.property.namestringRequiredProperty name.
data.stayobjectRequiredStay dates and length.
data.stay.arrivalDatestring (date)RequiredArrival date in YYYY-MM-DD format.
data.stay.departureDatestring (date)RequiredDeparture date in YYYY-MM-DD format.
data.stay.nightsintegerRequiredNumber of nights.
data.occupancyobjectRequiredGuest and room counts.
data.occupancy.adultsintegerRequiredAdult count.
data.occupancy.childrenintegerRequiredChild count.
data.occupancy.roomsintegerRequiredBooked room quantity.
data.totalobject | nullRequiredReservation total. Null when the imported guest price is unknown.
data.total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data.total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data.sourceobjectRequiredReservation origin.
data.source.type'direct' | 'channel'RequiredWhether the reservation was direct or arrived from a channel.
data.source.channelstringConditionalRequired when source.type is channel.
data.itemsobject[]RequiredBooked room lines with per-line totals from their nightly rates.
data.items[].idstringRequiredStable reservation item ID.
data.items[].status'pending' | 'confirmed' | 'cancelled'RequiredItem lifecycle status.
data.items[].checkInDatestring (date)RequiredCheck-in date in YYYY-MM-DD format.
data.items[].checkOutDatestring (date)RequiredCheck-out date in YYYY-MM-DD format.
data.items[].nightsintegerRequiredNumber of nights.
data.items[].quantityintegerRequiredBooked room quantity.
data.items[].adultsintegerRequiredAdult count.
data.items[].childrenintegerRequiredChild count.
data.items[].inventoryPoolIdstringRequiredInventory pool the item books.
data.items[].ratePlanIdstringRequiredRate plan the item is priced with.
data.items[].totalobject | nullRequiredBooked item total in the recorded currency; null when the price is unknown, including older cancelled items.
data.items[].total.amountstringConditionalRequired when total is an object. Amount in the currency unit with two decimals (325.00).
data.items[].total.amountMinorstringConditionalRequired when total is an object. Deprecated: the same amount in hundredths (32500). Read amount.
data.items[].total.currencystringConditionalRequired when total is an object. Three-letter currency code.
data.referencestring | nullOptionalYour own identifier for the booking, set when you create or replace it through this API, or null. Channel booking codes are not references. Omitted only in older idempotent replay snapshots.

Properties, room types, and rate plans carry a sync object. It tells you whether the channel manager has the latest version of the record.

  • synced: the channel has the current record.
  • pending: a change is on its way to the channel, or Supahost is retrying one that failed. pendingSince is when the change was queued. Until it completes, writes to the record fail with 409 sync_in_progress.
  • failed: the change failed and Supahost will not retry it. A person must resolve it in Supahost. Until then, writes to the record fail with 409 sync_failed.
  • not_applicable: the record does not sync to a channel. For example, the property is a draft or has no channel connection.

sync.state is the answer a write to the record gets for the record's own sync. pending and failed are exactly the states in which that write fails with sync_in_progress or sync_failed, with the same reason. synced and not_applicable mean the record's own sync does not block a write.

A rate plan's sync shows only the plan's own sync, but a write to the plan can also be refused by the sync of its property or room type, which blockedBy names.

reason tells you why a sync is failing, and failedAt tells you when the last attempt failed. Both are null when nothing failed. A new reason can appear, so treat an unknown one as other.

  • channel_rejected: The channel refused the change.
  • channel_unreachable: Supahost could not reach the channel manager, or the channel manager asked it to slow down.
  • confirmation_unavailable: Supahost could not confirm that the channel saved the change.
  • connection_problem: The channel connection needs attention, for example a new credential.
  • setup_incomplete: The channel setup of the property is not finished.
  • other: Another cause. Ask a person in your workspace to look at the record in Supahost.

To find the records that need attention, send ?sync=failed or ?sync=failed,pending to the room type or rate plan list. The filter uses the same sync.state the records show, so every record on a filtered page has a sync.state in the filter. The filter is part of the cursor, so keep it on every page. A cursor from a different filter returns invalid_cursor.

Test keys read sandbox records, which sync to no channel. Their sync.state is always not_applicable, so a sync filter returns no sandbox records.

updatedAt and updatedAfter track the record itself, not its sync state. A sync that starts, fails, or completes does not change updatedAt, so an updatedAfter read does not return the record again. Use the sync filter to watch sync state.

Change: a write that meets a failed sync now fails with 409 sync_failed, with retryable no and no Retry-After header. Before, it failed with sync_in_progress and Retry-After: 30. If your client retries every 409 after Retry-After, stop when there is no Retry-After header, and ask a person to resolve the sync.

A calendar write changes Supahost first. Supahost then sends the change to the channel and checks that the channel saved it. The calendar reads with include=channel and the channel sync summary show where that stands. They read Supahost records only. They never queue, send or retry anything.

A night is one room type (availability) or one rate plan (restrictions) on one date. Each night has one state. Supahost checks the causes in this order and reports the first that applies:

  • not_sent: the property has no linked listing, has no live channel connection, the room type or rate plan has no channel mapping, the rate plan follows its parent plan, the pool has no active rate plan, the night is past, or nothing has written the night yet (awaiting_feed).
  • held (availability only): Supahost holds the night closed on the channel. value is 0, and changedAt is when the hold started.
  • pending: the newest change for the night is on its way, or Supahost is retrying it.
  • failed: the newest change failed, Supahost will not retry it, and no later change reached the channel.
  • closed_by_channel: the channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again.
  • synced: nothing else applies.

States: synced (Nothing is outstanding. The channel confirmed the last change, or no change was needed. Supahost does not read the channel again to report this.) pending (A change is on its way to the channel, or Supahost is retrying one.) failed (The last change failed and Supahost will not retry it. A person must resolve it in Supahost.) held (Supahost holds the night closed on the channel (availability 0) until it can confirm the property calendar there.) closed_by_channel (The channel closed tonight at its own same-day cut-off. Supahost expects this and does not send the night again.) not_sent (Supahost does not send this night to the channel. reason says why.)

synced means nothing is outstanding: the channel confirmed the last change, or no change was needed. It is not a new read of the channel. Supahost cannot see a change that someone made directly on the channel, so such a night still reads synced.

A failure stays failed until a later change for the night reaches the channel, the night passes, or a person in your workspace resolves the problem in Supahost. When a person resolves it, those nights read synced again.

The state covers every change to the night, from any source: your writes, bookings and the Supahost calendar. The question is what the channel has, whoever wrote it. There is no receipt for one write: one write can become several deliveries, and a later change can replace an earlier one before it is sent.

On the property calendar, restrictions sums up the pool's active rate plans: failed when one failed, else pending when one is pending, else synced when one reaches the channel, else not_sent.

value is the availability Supahost holds for the channel on the night: the total for the room type, after held nights and any close-out. It can differ from availableUnits, which is one inventory pool. observedValue appears only when a read of the channel showed a different number.

reason tells you why a night is not synced. A new reason can appear, so treat an unknown one as other.

  • channel_rejected: The channel refused the change.
  • channel_mismatch: The channel accepted the change, but a later read showed a different value.
  • channel_unreachable: Supahost could not reach the channel manager, or the channel manager asked it to slow down.
  • confirmation_unavailable: Supahost could not confirm that the channel saved the change.
  • connection_problem: The channel connection needs attention, for example a new credential.
  • closed_by_channel_cutoff: The channel closed tonight at its own same-day cut-off.
  • activation_unconfirmed: The property came back on the channel and Supahost could not confirm its calendar there, so it holds the nights closed.
  • property_inactive: The property has no linked listing, so Supahost sends nothing to the channel.
  • not_connected: The property, room type or rate plan has no channel connection or mapping.
  • derived_rate_plan: The rate plan follows its parent plan. The channel derives it, so Supahost does not send it.
  • no_rate_plan: The pool has no active rate plan to carry rates and stay rules.
  • past_night: The night is before today in the property time zone.
  • awaiting_value: The night has an available count and no rate for this rate plan, or a rate and no count. On a property whose calendar a connected source supplies, the channel sells a night only with both. Send the missing value.
  • awaiting_feed: Nothing has written this night yet, so Supahost has nothing to send for it. Write it with a calendar write. The reason keeps the name it had when a supplier feed wrote the calendar.
  • other: Another cause. Ask a person in your workspace to look at the property in Supahost.

Test keys read sandbox properties, which sync to no channel. Their nights are not_sent with not_connected.

A date block takes quantity units of one inventory pool out of the calendar for a range of nights, with a reason: a repair, an owner visit, a hold. It is the block that the dashboard calendar creates with Block dates. Reading needs calendar:read. Writing needs calendar:write, the scope that also writes nightly availability.

Dates are calendar dates in the property time zone. startsOn is the first blocked night. endsOn is the reopen date, exclusive: the first night the units are sellable again, so the last blocked night is the day before. A block spans 1 to 365 nights.

A block never cancels or changes a reservation. A write checks the pool’s base capacity and that every night in the range has enough unreserved inventory left; if a night has not, the response is 400 insufficient_inventory and the detail names the night. Channel availability updates asynchronously. Each write sends a calendar.updated webhook with kind availability_block, over the first to the last blocked night it affects.

An owner stay on an entitlement pool is not a date block. It is never listed, and its ID returns 404.

Test keys cannot create, replace or remove a date block (sandbox_read_only). Their list is an empty page.

GET /properties/{propertyId}/blocks

Return one stable page of the property’s date blocks, ordered by startsOn and then id. With from or to, only the blocks that have a blocked night in that inclusive range. With inventoryPoolId, only that pool’s blocks. An unknown property returns 404.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
inventoryPoolIdstring (uuid)OptionalReturn only the blocks of this inventory pool UUID.
fromstring (date)OptionalFirst night of the range, inclusive. A block is returned when any of its blocked nights falls in the range.
tostring (date)OptionalLast night of the range, inclusive. from must not be after to.
200 JSON response
FieldTypeRequiredDescription
dataDateBlock[]RequiredA stable page of date blocks.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredThe block UUID.
data[].propertyIdstringRequiredThe property UUID.
data[].inventoryPoolIdstringRequiredThe inventory pool whose units are blocked.
data[].startsOnstringRequiredThe first blocked night, YYYY-MM-DD, in the property time zone.
data[].endsOnstringRequiredThe reopen date, exclusive, YYYY-MM-DD.
data[].quantityintegerRequiredUnits blocked.
data[].reasonstringRequiredWhy the units are blocked.
data[].createdAtstring (date-time)RequiredWhen the block was created.
data[].updatedAtstring (date-time)RequiredWhen the block last changed.

POST /properties/{propertyId}/blocks

Needs calendar:write, the scope that also writes nightly availability. Create a date block and get 201 with it and its ETag. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original block and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused.

inventoryPoolId must name an active pool of this property that is not an entitlement pool, else 400 invalid_reference. A quantity above the pool’s base capacity returns 400 invalid_request on quantity.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes create retries safe.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
JSON body
FieldTypeRequiredDescription
inventoryPoolIdstringRequiredThe inventory pool whose units are blocked. It cannot change later.
startsOnstringRequiredThe first blocked night, in the property time zone.
endsOnstringRequiredThe reopen date, exclusive: the first night the units are sellable again. The last blocked night is the day before.
quantityintegerRequiredUnits of the inventory pool to block, 1 to 1000.
reasonstringRequiredWhy the units are blocked, 2 to 240 characters.
cURL
curl -X POST "https://supahost.io/api/v1/properties/$PROPERTY_ID/blocks" \
  -H "Authorization: Bearer $SUPAHOST_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: block-repair-1" \
  -d '{"inventoryPoolId":"$POOL_ID","startsOn":"2030-10-10","endsOn":"2030-10-13","quantity":1,"reason":"Plumbing repair"}'
201 JSON response
FieldTypeRequiredDescription
dataDateBlockRequiredThe date block.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredThe block UUID.
data.propertyIdstringRequiredThe property UUID.
data.inventoryPoolIdstringRequiredThe inventory pool whose units are blocked.
data.startsOnstringRequiredThe first blocked night, YYYY-MM-DD, in the property time zone.
data.endsOnstringRequiredThe reopen date, exclusive, YYYY-MM-DD.
data.quantityintegerRequiredUnits blocked.
data.reasonstringRequiredWhy the units are blocked.
data.createdAtstring (date-time)RequiredWhen the block was created.
data.updatedAtstring (date-time)RequiredWhen the block last changed.

GET /properties/{propertyId}/blocks/{blockId}

Return one date block of the property. A block of another property, another workspace, or an entitlement pool returns 404.

The response includes an ETag header that names this version of the date block. Send it in If-None-Match to get 304 with no body when the date block did not change.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-None-MatchstringOptionalThe ETag from your last read. Returns 304 with no body when the date block did not change.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
blockIdstring (uuid)RequiredDate block UUID.
200 JSON response
FieldTypeRequiredDescription
dataDateBlockRequiredThe date block.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredThe block UUID.
data.propertyIdstringRequiredThe property UUID.
data.inventoryPoolIdstringRequiredThe inventory pool whose units are blocked.
data.startsOnstringRequiredThe first blocked night, YYYY-MM-DD, in the property time zone.
data.endsOnstringRequiredThe reopen date, exclusive, YYYY-MM-DD.
data.quantityintegerRequiredUnits blocked.
data.reasonstringRequiredWhy the units are blocked.
data.createdAtstring (date-time)RequiredWhen the block was created.
data.updatedAtstring (date-time)RequiredWhen the block last changed.

PUT /properties/{propertyId}/blocks/{blockId}

Needs calendar:write, the scope that also writes nightly availability. Replace the block’s startsOn, endsOn, quantity and reason. PUT is a full replacement, and the pool cannot change: remove the block and create a new one to block another pool.

A block that has started (its startsOn is today or earlier in the property time zone) keeps its dates; send its current dates with a new quantity or reason. New dates for a started block return 409 date_block_started. A block that has not started can move only to a startsOn after today; an earlier one returns 400 invalid_request on startsOn. A change that needs more inventory than remains returns 400 insufficient_inventory, and the block keeps its old values.

To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the date block changed since, the response is 412 precondition_failed and nothing is written. Read the date block again and repeat the change. Without If-Match, the replacement always applies.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the date block changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
blockIdstring (uuid)RequiredDate block UUID.
JSON body
FieldTypeRequiredDescription
startsOnstringRequiredThe first blocked night, in the property time zone.
endsOnstringRequiredThe reopen date, exclusive: the first night the units are sellable again. The last blocked night is the day before.
quantityintegerRequiredUnits of the inventory pool to block, 1 to 1000.
reasonstringRequiredWhy the units are blocked, 2 to 240 characters.
200 JSON response
FieldTypeRequiredDescription
dataDateBlockRequiredThe date block.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredThe block UUID.
data.propertyIdstringRequiredThe property UUID.
data.inventoryPoolIdstringRequiredThe inventory pool whose units are blocked.
data.startsOnstringRequiredThe first blocked night, YYYY-MM-DD, in the property time zone.
data.endsOnstringRequiredThe reopen date, exclusive, YYYY-MM-DD.
data.quantityintegerRequiredUnits blocked.
data.reasonstringRequiredWhy the units are blocked.
data.createdAtstring (date-time)RequiredWhen the block was created.
data.updatedAtstring (date-time)RequiredWhen the block last changed.

DELETE /properties/{propertyId}/blocks/{blockId}

Needs calendar:write, the scope that also writes nightly availability. Remove the block. Its units go back to the calendar for its nights, and the response is 204 with no body. Send the ETag from your last read in If-Match to avoid removing a block that changed since: a block that changed returns 412 precondition_failed and stays.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the date block changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
propertyIdstring (uuid)RequiredProperty UUID.
blockIdstring (uuid)RequiredDate block UUID.

Read endpoints require the tasks:read scope; write endpoints require tasks:write. Required response fields are always present; nullable fields include null in their type.

Tasks embed stable IDs only, so list pages never go stale when a name changes: resolve property names through GET /properties. Tasks without a property link return property and reservationId as null. Tasks without an assignee return assignee as null.

Test keys cannot create or update tasks. Writes with a test key return sandbox_read_only.

GET /tasks

Return one stable page of tasks.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
status'open' | 'in_progress' | 'completed' | 'cancelled' | 'all'OptionalFilter by task status. The default is all.
propertyIdstring (uuid)OptionalReturn tasks for one public property UUID.
property_idstring (uuid)OptionalDeprecated: use propertyId.
200 JSON response
FieldTypeRequiredDescription
dataTask[]RequiredA stable page of task records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable task UUID.
data[].titlestringRequiredTask title.
data[].descriptionstring | nullRequiredTask description, or null.
data[].category'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations'RequiredTask category.
data[].priority'low' | 'normal' | 'high' | 'urgent'RequiredTask priority.
data[].status'open' | 'in_progress' | 'completed' | 'cancelled'RequiredTask status.
data[].source'manual' | 'automation'RequiredWhether the task was created manually or by an automation rule.
data[].dueAtstring (date-time) | nullRequiredWhen the task is due, or null.
data[].propertyobject | nullRequiredLinked property, or null. Resolve names via the properties endpoint.
data[].property.idstringConditionalRequired when property is an object. Public property UUID.
data[].reservationIdstring | nullRequiredLinked reservation ID, or null.
data[].assigneeobject | nullRequiredAssigned workspace member, or null.
data[].assignee.idstringConditionalRequired when assignee is an object. Workspace member user ID.
data[].createdAtstring (date-time)RequiredTask creation time.
data[].updatedAtstring (date-time)RequiredLast task change time.

POST /tasks

Create a task. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original task and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes create retries safe.
JSON body
FieldTypeRequiredDescription
titlestringRequiredTask title, 2 to 200 characters.
category'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations'RequiredTask category.
priority'low' | 'normal' | 'high' | 'urgent'RequiredTask priority.
descriptionstring | nullOptionalTask description, up to 2,000 characters.
dueAtstring (date-time) | nullOptionalWhen the task is due; a time-zone offset is allowed.
propertyIdstring | nullOptionalProperty UUID.
reservationIdstring | nullOptionalReservation UUID. Requires propertyId.
assigneeUserIdstring | nullOptionalAssigned workspace member user UUID.
201 JSON response
FieldTypeRequiredDescription
dataTaskRequiredThe created task.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable task UUID.
data.titlestringRequiredTask title.
data.descriptionstring | nullRequiredTask description, or null.
data.category'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations'RequiredTask category.
data.priority'low' | 'normal' | 'high' | 'urgent'RequiredTask priority.
data.status'open' | 'in_progress' | 'completed' | 'cancelled'RequiredTask status.
data.source'manual' | 'automation'RequiredWhether the task was created manually or by an automation rule.
data.dueAtstring (date-time) | nullRequiredWhen the task is due, or null.
data.propertyobject | nullRequiredLinked property, or null. Resolve names via the properties endpoint.
data.property.idstringConditionalRequired when property is an object. Public property UUID.
data.reservationIdstring | nullRequiredLinked reservation ID, or null.
data.assigneeobject | nullRequiredAssigned workspace member, or null.
data.assignee.idstringConditionalRequired when assignee is an object. Workspace member user ID.
data.createdAtstring (date-time)RequiredTask creation time.
data.updatedAtstring (date-time)RequiredLast task change time.

GET /tasks/{taskId}

Return one task from the API key workspace.

The response includes an ETag header that names this version of the task. Send it in If-None-Match to get 304 with no body when the task did not change.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-None-MatchstringOptionalThe ETag from your last read. Returns 304 with no body when the task did not change.
Path parameters
FieldTypeRequiredDescription
taskIdstring (uuid)RequiredTask UUID.
200 JSON response
FieldTypeRequiredDescription
dataTaskRequiredThe requested task.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable task UUID.
data.titlestringRequiredTask title.
data.descriptionstring | nullRequiredTask description, or null.
data.category'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations'RequiredTask category.
data.priority'low' | 'normal' | 'high' | 'urgent'RequiredTask priority.
data.status'open' | 'in_progress' | 'completed' | 'cancelled'RequiredTask status.
data.source'manual' | 'automation'RequiredWhether the task was created manually or by an automation rule.
data.dueAtstring (date-time) | nullRequiredWhen the task is due, or null.
data.propertyobject | nullRequiredLinked property, or null. Resolve names via the properties endpoint.
data.property.idstringConditionalRequired when property is an object. Public property UUID.
data.reservationIdstring | nullRequiredLinked reservation ID, or null.
data.assigneeobject | nullRequiredAssigned workspace member, or null.
data.assignee.idstringConditionalRequired when assignee is an object. Workspace member user ID.
data.createdAtstring (date-time)RequiredTask creation time.
data.updatedAtstring (date-time)RequiredLast task change time.

PUT /tasks/{taskId}

Replace one task. PUT is a full replacement: an omitted status resets the task to open.

To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the task changed since, the response is 412 precondition_failed and nothing is written. Read the task again and repeat the change. Without If-Match, the replacement always applies.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the task changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
taskIdstring (uuid)RequiredTask UUID.
JSON body
FieldTypeRequiredDescription
titlestringRequiredTask title, 2 to 200 characters.
category'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations'RequiredTask category.
priority'low' | 'normal' | 'high' | 'urgent'RequiredTask priority.
descriptionstring | nullOptionalTask description, up to 2,000 characters.
dueAtstring (date-time) | nullOptionalWhen the task is due; a time-zone offset is allowed.
propertyIdstring | nullOptionalProperty UUID.
reservationIdstring | nullOptionalReservation UUID. Requires propertyId.
assigneeUserIdstring | nullOptionalAssigned workspace member user UUID.
status'open' | 'in_progress' | 'completed' | 'cancelled'OptionalFull replacement: the default is open.
200 JSON response
FieldTypeRequiredDescription
dataTaskRequiredThe requested task.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable task UUID.
data.titlestringRequiredTask title.
data.descriptionstring | nullRequiredTask description, or null.
data.category'cleaning' | 'maintenance' | 'guest' | 'inspection' | 'listing' | 'operations'RequiredTask category.
data.priority'low' | 'normal' | 'high' | 'urgent'RequiredTask priority.
data.status'open' | 'in_progress' | 'completed' | 'cancelled'RequiredTask status.
data.source'manual' | 'automation'RequiredWhether the task was created manually or by an automation rule.
data.dueAtstring (date-time) | nullRequiredWhen the task is due, or null.
data.propertyobject | nullRequiredLinked property, or null. Resolve names via the properties endpoint.
data.property.idstringConditionalRequired when property is an object. Public property UUID.
data.reservationIdstring | nullRequiredLinked reservation ID, or null.
data.assigneeobject | nullRequiredAssigned workspace member, or null.
data.assignee.idstringConditionalRequired when assignee is an object. Workspace member user ID.
data.createdAtstring (date-time)RequiredTask creation time.
data.updatedAtstring (date-time)RequiredLast task change time.

A price adjustment raises or lowers selling prices by a percent, for every property or one property, and for every night or only the nights between two dates. Read endpoints require the rate-plans:read scope. Write endpoints require both the calendar:write and the rate-plans:write scope: a key with only one of them gets 403 insufficient_scope, and the detail names the missing one.

An adjustment changes the price where a rate is sold: on channels, in direct booking and on reservation nights. It never changes the stored rates. The calendar endpoints keep returning and accepting the stored rate, and removing an adjustment restores the stored prices exactly.

percent is a percent value, not a fraction: 10 is +10% and -5.5 is -5.5%. Adjustments that cover the same night add up: +10% and +5% sell at +15%. A workspace has at most 100 adjustments; a create past that fails with 409 price_adjustment_limit_reached.

startsOn and endsOn are both inclusive nights. endsOn is the last night covered. Either one can be null: an adjustment with no endsOn covers later nights as Supahost sends them to the channels. Nights more than 365 days out are refused.

A create, a change of anything other than name, and a removal queue the new selling prices to the channels for the properties and nights the adjustment covers, and send one calendar.updated webhook with kind rates for each property reached. A change of name alone queues nothing.

Test keys cannot create, change or remove price adjustments. Writes with a test key return sandbox_read_only. A test key reads an empty list.

GET /price-adjustments

Return one stable page of price adjustments, in the order they last changed. With propertyId, the page holds the adjustments for that property and the ones for every property; a property outside the workspace has none.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
propertyIdstring (uuid)OptionalReturn the adjustments that apply to one property: those for that property and those for every property. Without it, every adjustment of the workspace is returned.
200 JSON response
FieldTypeRequiredDescription
dataPriceAdjustment[]RequiredA stable page of price adjustments.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable price adjustment UUID.
data[].namestringRequiredName of the adjustment, 1 to 80 characters.
data[].percentnumberRequiredPercent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%).
data[].propertyIdstring | nullRequiredProperty UUID the adjustment covers, or null for every property in the workspace.
data[].startsOnstring (date) | nullRequiredFirst night covered, inclusive (YYYY-MM-DD), or null for no start.
data[].endsOnstring (date) | nullRequiredLast night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused.
data[].createdAtstring (date-time)RequiredWhen the adjustment was created.
data[].updatedAtstring (date-time)RequiredLast time the adjustment changed. The ETag follows it.

POST /price-adjustments

Create a price adjustment. Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original adjustment and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused. A propertyId outside the workspace fails with 400 invalid_reference.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes create retries safe.
JSON body
FieldTypeRequiredDescription
namestringRequiredName of the adjustment, 1 to 80 characters.
percentnumberRequiredA percent value from -50 through 200, with at most two decimals, never 0. 10 is +10% and -5.5 is -5.5%.
propertyIdstring (uuid) | nullOptionalProperty UUID. Omit it, or send null, to cover every property in the workspace.
startsOnstring (date) | nullOptionalFirst night covered, inclusive, as YYYY-MM-DD. Omit it, or send null, for no start.
endsOnstring (date) | nullOptionalLast night covered, inclusive (the night the guest sleeps), as YYYY-MM-DD. Omit it, or send null, for no end. It must be on or after startsOn, and no more than 365 days out.
201 JSON response
FieldTypeRequiredDescription
dataPriceAdjustmentRequiredThe created price adjustment.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable price adjustment UUID.
data.namestringRequiredName of the adjustment, 1 to 80 characters.
data.percentnumberRequiredPercent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%).
data.propertyIdstring | nullRequiredProperty UUID the adjustment covers, or null for every property in the workspace.
data.startsOnstring (date) | nullRequiredFirst night covered, inclusive (YYYY-MM-DD), or null for no start.
data.endsOnstring (date) | nullRequiredLast night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused.
data.createdAtstring (date-time)RequiredWhen the adjustment was created.
data.updatedAtstring (date-time)RequiredLast time the adjustment changed. The ETag follows it.

GET /price-adjustments/{adjustmentId}

Return one price adjustment from the API key workspace.

The response includes an ETag header that names this version of the price adjustment. Send it in If-None-Match to get 304 with no body when the price adjustment did not change.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-None-MatchstringOptionalThe ETag from your last read. Returns 304 with no body when the price adjustment did not change.
Path parameters
FieldTypeRequiredDescription
adjustmentIdstring (uuid)RequiredPrice adjustment UUID.
200 JSON response
FieldTypeRequiredDescription
dataPriceAdjustmentRequiredThe requested price adjustment.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable price adjustment UUID.
data.namestringRequiredName of the adjustment, 1 to 80 characters.
data.percentnumberRequiredPercent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%).
data.propertyIdstring | nullRequiredProperty UUID the adjustment covers, or null for every property in the workspace.
data.startsOnstring (date) | nullRequiredFirst night covered, inclusive (YYYY-MM-DD), or null for no start.
data.endsOnstring (date) | nullRequiredLast night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused.
data.createdAtstring (date-time)RequiredWhen the adjustment was created.
data.updatedAtstring (date-time)RequiredLast time the adjustment changed. The ETag follows it.

PATCH /price-adjustments/{adjustmentId}

Change a price adjustment. Send any of the fields; at least one is required. A field you leave out is unchanged, and null clears propertyId, startsOn or endsOn. A new name alone queues no prices. Any other change queues the prices for the nights the old and the new adjustment cover.

To avoid overwriting a change you did not see, send the ETag from your last read in If-Match. If the adjustment changed since, the response is 412 precondition_failed and nothing is written. Read it again and repeat the change. Without If-Match, the request always applies.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the price adjustment changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
adjustmentIdstring (uuid)RequiredPrice adjustment UUID.
JSON body
FieldTypeRequiredDescription
namestringOptionalName of the adjustment, 1 to 80 characters.
percentnumberOptionalA percent value from -50 through 200, with at most two decimals, never 0. 10 is +10% and -5.5 is -5.5%.
propertyIdstring (uuid) | nullOptionalProperty UUID. Send null to cover every property.
startsOnstring (date) | nullOptionalFirst night covered, inclusive, as YYYY-MM-DD. Send null for no start.
endsOnstring (date) | nullOptionalLast night covered, inclusive (the night the guest sleeps), as YYYY-MM-DD. Send null for no end. It must be on or after startsOn, and no more than 365 days out.
200 JSON response
FieldTypeRequiredDescription
dataPriceAdjustmentRequiredThe price adjustment after the change.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable price adjustment UUID.
data.namestringRequiredName of the adjustment, 1 to 80 characters.
data.percentnumberRequiredPercent change to every selling price it covers, from -50 through 200, at most two decimals, never 0. 10 raises prices 10% (+10%) and -5.5 lowers them 5.5% (-5.5%).
data.propertyIdstring | nullRequiredProperty UUID the adjustment covers, or null for every property in the workspace.
data.startsOnstring (date) | nullRequiredFirst night covered, inclusive (YYYY-MM-DD), or null for no start.
data.endsOnstring (date) | nullRequiredLast night covered, inclusive (YYYY-MM-DD; the guest sleeps that night), or null for no end. A night more than 365 days out is refused.
data.createdAtstring (date-time)RequiredWhen the adjustment was created.
data.updatedAtstring (date-time)RequiredLast time the adjustment changed. The ETag follows it.

DELETE /price-adjustments/{adjustmentId}

Remove a price adjustment. The nights it covered sell at their stored rates again, and Supahost queues those prices to the channels. The response is 204 with no body.

To avoid overwriting a change you did not see, send the ETag from your last read in If-Match. If the adjustment changed since, the response is 412 precondition_failed and nothing is written. Read it again and repeat the change. Without If-Match, the request always applies.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the price adjustment changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
adjustmentIdstring (uuid)RequiredPrice adjustment UUID.

Read endpoints require the conversations:read scope; replies require conversations:write. channel names the sales channel (airbnb, vrbo, direct, or other); internal channel manager identifiers are never exposed.

Test keys cannot send replies. Writes with a test key return sandbox_read_only.

GET /conversations

Return one stable page of conversations, newest activity first.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
status'open' | 'closed' | 'all'OptionalFilter by conversation status. The default is all.
propertyIdstring (uuid)OptionalReturn conversations for one public property UUID.
property_idstring (uuid)OptionalDeprecated: use propertyId.
200 JSON response
FieldTypeRequiredDescription
dataConversation[]RequiredA stable page of conversation records, newest activity first.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable conversation UUID.
data[].guestNamestringRequiredGuest name on the thread.
data[].subjectstring | nullRequiredThread subject, or null.
data[].status'open' | 'closed'RequiredThread status.
data[].channel'airbnb' | 'vrbo' | 'direct' | 'website' | 'other'RequiredSales channel the thread runs on.
data[].propertyobjectRequiredProperty the thread belongs to.
data[].property.idstringRequiredPublic property UUID.
data[].property.namestringRequiredProperty name.
data[].reservationIdstring | nullRequiredLinked reservation ID, or null.
data[].lastMessageAtstring (date-time)RequiredLast message time.
data[].lastMessageobjectRequiredLast message summary.
data[].lastMessage.direction'inbound' | 'outbound'RequiredDirection of the last message.
data[].lastMessage.snippetstringRequiredBody of the last message.
data[].updatedAtstring (date-time)RequiredLast conversation change time.

GET /conversations/{conversationId}/messages

Return one stable page of messages in chronological order.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
conversationIdstring (uuid)RequiredConversation UUID.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
200 JSON response
FieldTypeRequiredDescription
dataMessage[]RequiredA stable page of messages in chronological order.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable message UUID.
data[].direction'inbound' | 'outbound'RequiredMessage direction.
data[].senderType'guest' | 'staff' | 'system'RequiredWho sent the message.
data[].senderNamestring | nullRequiredStaff sender name, or null.
data[].bodystringRequiredMessage body.
data[].occurredAtstring (date-time)RequiredWhen the message was sent.

POST /conversations/{conversationId}/messages

Queue a reply for delivery through the channel connection. The 201 response returns the stored message. Replying fails with replies_not_supported when the connection cannot send messages, and with conversation_closed when the thread is closed.

Send an Idempotency-Key header to make retries safe: a repeated POST with the same key and the same payload returns 200 with the original message and queues nothing new; the same key with a different payload fails with 409 idempotency_key_reused.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes create retries safe.
Path parameters
FieldTypeRequiredDescription
conversationIdstring (uuid)RequiredConversation UUID.
JSON body
FieldTypeRequiredDescription
bodystringRequiredReply body, 1 to 10,000 characters.
201 JSON response
FieldTypeRequiredDescription
dataMessageRequiredThe queued reply.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable message UUID.
data.direction'inbound' | 'outbound'RequiredMessage direction.
data.senderType'guest' | 'staff' | 'system'RequiredWho sent the message.
data.senderNamestring | nullRequiredStaff sender name, or null.
data.bodystringRequiredMessage body.
data.occurredAtstring (date-time)RequiredWhen the message was sent.

Channel endpoints require the channels:read scope. Each connection carries its rate plan mappings; a mapping with null external codes is not linked on the sales channel yet.

Connection credentials are never returned. channelActive reports whether the connection is live on the sales channel, and syncState shows a queued or failed channel manager sync.

GET /channels

Return one stable page of channel connections.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
updatedAfterstring (date-time)OptionalReturn records changed after this ISO 8601 date and time.
updated_afterstring (date-time)OptionalDeprecated: use updatedAfter.
propertyIdstring (uuid)OptionalReturn channel connections for one public property UUID.
property_idstring (uuid)OptionalDeprecated: use propertyId.
200 JSON response
FieldTypeRequiredDescription
dataChannelConnection[]RequiredA stable page of channel connection records.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable channel connection UUID.
data[].titlestringRequiredConnection display name.
data[].channelstringRequiredSales channel this connection distributes through, or other.
data[].status'draft' | 'pending' | 'active' | 'error'RequiredConnection status.
data[].channelActivebooleanRequiredWhether the connection is live on the sales channel.
data[].syncState'pending' | 'failed' | 'null'RequiredPending channel manager sync state, or null when nothing is queued.
data[].currencystring | nullRequiredRate currency override, or null.
data[].propertyobjectRequiredStable primary associated property. Deprecated: use properties.
data[].property.idstringRequiredPublic property UUID.
data[].property.namestringRequiredProperty name.
data[].propertiesobject[]RequiredProperties this account-level connection distributes.
data[].properties[].idstringRequiredPublic property UUID.
data[].properties[].namestringRequiredProperty name.
data[].mappingsobject[]RequiredRate plan mappings for this connection.
data[].mappings[].idstringRequiredStable channel mapping UUID.
data[].mappings[].ratePlanIdstringRequiredMapped rate plan ID.
data[].mappings[].ratePlanNamestringRequiredMapped rate plan name.
data[].mappings[].roomTypeNamestringRequiredRoom type of the mapped rate plan.
data[].mappings[].externalRoomCodestring | nullRequiredRoom code on the sales channel, or null when unmapped.
data[].mappings[].externalRateCodestring | nullRequiredRate code on the sales channel, or null when unmapped.
data[].mappings[].primaryOccupancybooleanRequiredWhether the mapping drives the primary occupancy rate.
data[].createdAtstring (date-time)RequiredConnection creation time.
data[].updatedAtstring (date-time)RequiredLast connection change time.
data[].removedAtstring (date-time) | nullRequiredWhen the account was removed, or null. Only updatedAfter reads return removed accounts.

Webhook endpoints require the webhooks:manage scope. The signing secret appears exactly once, in the create response; list and get responses never return it.

Test keys cannot create, update, or delete webhook endpoints, or send a delivery again. Writes with a test key return sandbox_read_only.

GET /webhooks

Return one stable page of webhook endpoints, newest first.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
200 JSON response
FieldTypeRequiredDescription
dataWebhookEndpoint[]RequiredA stable page of webhook endpoint records, newest first.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable webhook endpoint UUID.
data[].urlstringRequiredEndpoint URL.
data[].descriptionstringRequiredEndpoint description, or an empty string.
data[].eventsstring[]RequiredSubscribed event types.
data[].status'active' | 'disabled'RequiredEndpoint status.
data[].disabledAtstring (date-time) | nullRequiredWhen the endpoint was turned off, or null while it is active.
data[].disabledReason'manual' | 'delivery_failures' | 'null'RequiredWhy the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active.
data[].createdAtstring (date-time)RequiredEndpoint creation time.

POST /webhooks

Create a webhook endpoint. The URL must be a public https:// address without embedded credentials: loopback, private, link-local, and reserved hosts are rejected at save time, and delivery re-checks DNS answers and every redirect hop before connecting.

Send an Idempotency-Key header to make retries safe. A repeated POST with the same key and the same payload returns 200 with the original endpoint and creates nothing new; the same key with a different payload fails with 409 idempotency_key_reused.

The 201 response is the only one that includes signingSecret. A replayed request returns 200 without the secret. Both include the ETag of the endpoint as GET /webhooks/{webhookId} returns it.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. Makes create retries safe.
JSON body
FieldTypeRequiredDescription
urlstringRequiredPublic https:// endpoint URL.
eventsstring[]RequiredSubscribed event types from the event catalog.
descriptionstringOptionalEndpoint description.
enabledbooleanOptionalSet false to turn the endpoint off. The default is true, which turns it on again and clears disabledReason.
201 JSON response
FieldTypeRequiredDescription
dataWebhookEndpointRequiredThe created webhook endpoint, including its signing secret.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable webhook endpoint UUID.
data.urlstringRequiredEndpoint URL.
data.descriptionstringRequiredEndpoint description, or an empty string.
data.eventsstring[]RequiredSubscribed event types.
data.status'active' | 'disabled'RequiredEndpoint status.
data.disabledAtstring (date-time) | nullRequiredWhen the endpoint was turned off, or null while it is active.
data.disabledReason'manual' | 'delivery_failures' | 'null'RequiredWhy the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active.
data.createdAtstring (date-time)RequiredEndpoint creation time.
data.signingSecretstringRequiredPayload signing secret. Returned only in the create response.

GET /webhooks/{webhookId}

Return one webhook endpoint from the API key workspace.

The response includes an ETag header that names this version of the webhook endpoint. Send it in If-None-Match to get 304 with no body when the webhook endpoint did not change. The tag names the whole response, so it also changes when a derived value, such as the status after Supahost turns the endpoint off, changes.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-None-MatchstringOptionalThe ETag from your last read. Returns 304 with no body when the webhook endpoint did not change.
Path parameters
FieldTypeRequiredDescription
webhookIdstring (uuid)RequiredWebhook endpoint UUID.
200 JSON response
FieldTypeRequiredDescription
dataWebhookEndpointRequiredThe requested webhook endpoint.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable webhook endpoint UUID.
data.urlstringRequiredEndpoint URL.
data.descriptionstringRequiredEndpoint description, or an empty string.
data.eventsstring[]RequiredSubscribed event types.
data.status'active' | 'disabled'RequiredEndpoint status.
data.disabledAtstring (date-time) | nullRequiredWhen the endpoint was turned off, or null while it is active.
data.disabledReason'manual' | 'delivery_failures' | 'null'RequiredWhy the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active.
data.createdAtstring (date-time)RequiredEndpoint creation time.

PUT /webhooks/{webhookId}

Replace one webhook endpoint. PUT is a full replacement: send every field that you want to keep. An omitted enabled sets the endpoint to enabled, so send enabled: false to keep a disabled endpoint disabled.

To avoid replacing a change that you did not see, send the ETag from your last read in If-Match. If the webhook endpoint changed since, the response is 412 precondition_failed and nothing is written. Read the webhook endpoint again and repeat the change. Without If-Match, the replacement always applies. A 412 can also come from a derived value that moved, such as the status after Supahost turns the endpoint off: read the webhook endpoint again and repeat the change; it is not an error to show.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the webhook endpoint changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
webhookIdstring (uuid)RequiredWebhook endpoint UUID.
JSON body
FieldTypeRequiredDescription
urlstringRequiredPublic https:// endpoint URL.
eventsstring[]RequiredSubscribed event types from the event catalog.
descriptionstringOptionalEndpoint description.
enabledbooleanOptionalSet false to turn the endpoint off. The default is true, which turns it on again and clears disabledReason.
200 JSON response
FieldTypeRequiredDescription
dataWebhookEndpointRequiredThe requested webhook endpoint.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable webhook endpoint UUID.
data.urlstringRequiredEndpoint URL.
data.descriptionstringRequiredEndpoint description, or an empty string.
data.eventsstring[]RequiredSubscribed event types.
data.status'active' | 'disabled'RequiredEndpoint status.
data.disabledAtstring (date-time) | nullRequiredWhen the endpoint was turned off, or null while it is active.
data.disabledReason'manual' | 'delivery_failures' | 'null'RequiredWhy the endpoint is off: manual when a person turned it off, delivery_failures when Supahost did after 5 days of failed deliveries. Null while it is active.
data.createdAtstring (date-time)RequiredEndpoint creation time.

DELETE /webhooks/{webhookId}

Delete one webhook endpoint. A successful delete returns 204 with no body. Send the ETag from your last read in If-Match to delete only the version that you read: if the endpoint changed since, the response is 412 precondition_failed and nothing is deleted.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
If-MatchstringOptionalThe ETag from your last read, quotes included. Returns 412 precondition_failed when the webhook endpoint changed since, and 400 when the value is not a tag.
Path parameters
FieldTypeRequiredDescription
webhookIdstring (uuid)RequiredWebhook endpoint UUID.

GET /webhooks/{webhookId}/deliveries

Return one stable page of deliveries for the endpoint, newest first. Each delivery lists its attempts, oldest first.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Path parameters
FieldTypeRequiredDescription
webhookIdstring (uuid)RequiredWebhook endpoint UUID.
Query parameters
FieldTypeRequiredDescription
limitintegerOptionalRecords per page, from 1 through 200. The default is 100.
cursorstringOptionalSend meta.page.nextCursor without changing any other filter.
200 JSON response
FieldTypeRequiredDescription
dataWebhookDelivery[]RequiredA stable page of delivery records, newest first.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
meta.pageobjectRequiredCursor pagination state.
meta.page.hasMorebooleanRequiredWhether another page is available.
meta.page.limitintegerRequiredThe page size applied to this response.
meta.page.nextCursorstring | nullRequiredThe cursor for the next page, or null when the page is final.
meta.page.snapshotAtstring (date-time)RequiredThe stable read boundary shared by every page in the cursor chain.
data[].idstringRequiredStable delivery UUID.
data[].eventIdstringRequiredThe envelope id the endpoint receives. A redelivery sends the same value as the first delivery.
data[].eventType'reservation.created' | 'reservation.updated' | 'reservation.cancelled' | 'message.received' | 'message.sent' | 'property.created' | 'property.updated' | 'property.lifecycle_changed' | 'task.created' | 'task.updated' | 'calendar.updated'RequiredDelivered event type.
data[].eventKeystringRequiredLogical event identity; repeated deliveries of one event share it.
data[].status'pending' | 'delivered' | 'failed' | 'exhausted'RequiredDelivery status.
data[].attemptCountintegerRequiredDelivery attempts so far, at most 10.
data[].responseStatusinteger | nullRequiredHTTP status the endpoint returned, or null.
data[].durationMsinteger | nullRequiredLast attempt duration in milliseconds, or null.
data[].nextAttemptAtstring (date-time) | nullRequiredWhen the next attempt is due, or null once the delivery is delivered or exhausted.
data[].completedAtstring (date-time) | nullRequiredWhen the delivery was delivered or exhausted, or null.
data[].redeliveryOfstring | nullRequiredThe first delivery of the same event when this one sends it again, or null.
data[].attemptsobject[]RequiredEvery recorded attempt, oldest first. Deliveries made before attempts were recorded list none.
data[].attempts[].numberintegerRequiredAttempt number, from 1.
data[].attempts[].outcome'in_progress' | 'delivered' | 'failed' | 'exhausted' | 'lost'Requiredin_progress while it runs, then delivered, failed (a retry follows), exhausted (the last attempt), or lost (the worker stopped before it saw an answer).
data[].attempts[].responseStatusinteger | nullRequiredHTTP status the endpoint returned, or null.
data[].attempts[].errorCode'http_error' | 'timeout' | 'network_error' | 'blocked_host' | 'too_many_redirects' | 'lost' | 'null'RequiredWhy the attempt failed, or null when it succeeded or is still running.
data[].attempts[].durationMsinteger | nullRequiredAttempt duration in milliseconds, or null.
data[].attempts[].startedAtstring (date-time)RequiredWhen the attempt started.
data[].attempts[].finishedAtstring (date-time) | nullRequiredWhen the attempt ended, or null while it runs.
data[].attempts[].nextAttemptAtstring (date-time) | nullRequiredWhen the next attempt is due after this one failed, or null.
data[].createdAtstring (date-time)RequiredDelivery creation time.

POST /webhooks/{webhookId}/deliveries/{deliveryId}/redeliver

Send the event of a delivered or exhausted delivery again. Supahost queues a new delivery with the same payload and envelope id, to the endpoint's current URL, signed with its current secret. The request has no body.

Send an Idempotency-Key header to make retries safe. A repeated request with the same key returns 200 with the first redelivery. The first request returns 201.

The request fails with 409 webhook_delivery_in_flight while a delivery of the same event is pending or failed, and with 409 webhook_endpoint_disabled while the endpoint is off. Neither is retryable as is: wait for the delivery to finish, or turn the endpoint on. A delivery that does not belong to the endpoint returns 404.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY.
Idempotency-KeystringOptional1 to 200 characters. A retried request returns the first redelivery instead of queuing a second.
Path parameters
FieldTypeRequiredDescription
webhookIdstring (uuid)RequiredWebhook endpoint UUID.
deliveryIdstring (uuid)RequiredWebhook delivery UUID.
201 JSON response
FieldTypeRequiredDescription
dataWebhookDeliveryRequiredThe new delivery, queued with the same event.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.idstringRequiredStable delivery UUID.
data.eventIdstringRequiredThe envelope id the endpoint receives. A redelivery sends the same value as the first delivery.
data.eventType'reservation.created' | 'reservation.updated' | 'reservation.cancelled' | 'message.received' | 'message.sent' | 'property.created' | 'property.updated' | 'property.lifecycle_changed' | 'task.created' | 'task.updated' | 'calendar.updated'RequiredDelivered event type.
data.eventKeystringRequiredLogical event identity; repeated deliveries of one event share it.
data.status'pending' | 'delivered' | 'failed' | 'exhausted'RequiredDelivery status.
data.attemptCountintegerRequiredDelivery attempts so far, at most 10.
data.responseStatusinteger | nullRequiredHTTP status the endpoint returned, or null.
data.durationMsinteger | nullRequiredLast attempt duration in milliseconds, or null.
data.nextAttemptAtstring (date-time) | nullRequiredWhen the next attempt is due, or null once the delivery is delivered or exhausted.
data.completedAtstring (date-time) | nullRequiredWhen the delivery was delivered or exhausted, or null.
data.redeliveryOfstring | nullRequiredThe first delivery of the same event when this one sends it again, or null.
data.attemptsobject[]RequiredEvery recorded attempt, oldest first. Deliveries made before attempts were recorded list none.
data.attempts[].numberintegerRequiredAttempt number, from 1.
data.attempts[].outcome'in_progress' | 'delivered' | 'failed' | 'exhausted' | 'lost'Requiredin_progress while it runs, then delivered, failed (a retry follows), exhausted (the last attempt), or lost (the worker stopped before it saw an answer).
data.attempts[].responseStatusinteger | nullRequiredHTTP status the endpoint returned, or null.
data.attempts[].errorCode'http_error' | 'timeout' | 'network_error' | 'blocked_host' | 'too_many_redirects' | 'lost' | 'null'RequiredWhy the attempt failed, or null when it succeeded or is still running.
data.attempts[].durationMsinteger | nullRequiredAttempt duration in milliseconds, or null.
data.attempts[].startedAtstring (date-time)RequiredWhen the attempt started.
data.attempts[].finishedAtstring (date-time) | nullRequiredWhen the attempt ended, or null while it runs.
data.attempts[].nextAttemptAtstring (date-time) | nullRequiredWhen the next attempt is due after this one failed, or null.
data.createdAtstring (date-time)RequiredDelivery creation time.

Start a flow from your own system. The flow must have a webhook trigger, and you must name a version that is published and turned on.

The key needs flows:write. A new key does not have this scope: add it when you create the key. The person who made the key must still have permission to manage automations.

Test keys cannot start a flow (sandbox_read_only).

POST /flows/{flowId}/events

Send one event to the flow. version is the published version to run. key is the event key that the flow’s webhook trigger names. data is your own JSON object. The flow reads it at details.webhook.data.

context is optional. It ties the run to one conversation, reservation or property of the workspace. The record must be inside the properties that the flow covers.

The response is a receipt. 202 means that Supahost saved the event and queued the run. It does not mean that the flow’s actions ran. A flow in shadow mode only records the actions it would take. A live flow follows the approval mode it was published with.

A body can be at most 32 KB, 16 levels deep, and 5,000 JSON values. A larger body returns 413. A version that is not published, a wrong event key, or a record outside the flow’s properties returns 409.

Headers
FieldTypeRequiredDescription
AuthorizationstringRequiredSend Bearer $SUPAHOST_API_KEY. The key must be a live key with flows:write.
Content-TypestringRequiredapplication/json.
Idempotency-KeystringRequired1 to 200 characters. Send the same key and the same body after a lost response to get the first run back. The same key with a different body returns 409.
Path parameters
FieldTypeRequiredDescription
flowIdstring (uuid)RequiredThe flow to start.
JSON body
FieldTypeRequiredDescription
versionintegerRequired
keystringRequired
contextobjectOptional
context.kind'conversation' | 'reservation' | 'property'Required
context.idstringRequired
dataobjectRequired
cURL
curl -X POST "https://supahost.io/api/v1/flows/$FLOW_ID/events" \
  -H "Authorization: Bearer $SUPAHOST_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: door-code-8841" \
  -d '{"version":3,"key":"door.code.changed","context":{"kind":"reservation","id":"$RESERVATION_ID"},"data":{"code":"4821"}}'
202 JSON response
FieldTypeRequiredDescription
dataFlowInvocationReceiptRequiredThe receipt of the queued run.
metaobjectRequiredResponse metadata.
meta.requestIdstringRequiredSupport identifier for this request.
data.flowIdstringRequired
data.versionintegerRequired
data.runIdstringRequired
data.eventIdstringRequired
data.sourceIdstringRequired
data.mode'live' | 'shadow'Required
data.status'queued'Required

A repeat of the same key and body returns 200 with the first receipt, even if the flow was paused after it.

List endpoints return 100 records by default. Set limit from 1 through 200.

If hasMore is true, send nextCursor as the next cursor. Keep all other filters unchanged.

The cursor holds a snapshot boundary. Records that change during a multi-page read do not move between its pages.

The names of query parameters are camelCase: updatedAfter, propertyId, arrivalFrom, arrivalTo, inventoryPoolId, skipLocked and validateOnly. The snake_case names they replace (updated_after, property_id, arrival_from, arrival_to, pool_id, skip_locked and validate_only) are deprecated and still work with the same meaning. Sending both names of one parameter with different values returns 400. A cursor works with either name.

A response to a request that used a deprecated name has a Deprecation header, a Sunset header and a Link header with rel="deprecation". The API changelog lists each deprecated name, its replacement and the day until which it works.

Each API key can make 120 requests per minute. Supahost does not combine second, minute, and hour quotas.

  • RateLimit-Limit shows the key limit.
  • RateLimit-Remaining shows the requests left in the current window.
  • RateLimit-Reset shows the seconds until the window resets.
  • Retry-After appears with a 429 response, and with any error whose retryable is after.

Supahost records each authenticated request. The record has the key, route, status, duration, and request ID.

Supahost does not store request bodies, response bodies, credentials, or URL query values in this audit record.