API reference

GET /properties

Return one stable page of properties.

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. Legacy numeric property input is temporarily accepted, but responses always use UUIDs.

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 baseRateMinor. 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.

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.

PUT /properties/{propertyId}

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

The response is the updated property record. On a channel-connected property the change also queues to the channel sync outbox and propagates to connected channels asynchronously. An archived property must be restored in the dashboard before editing.

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. A write that lands while a channel sync is still in progress fails with 409 sync_in_progress; retry once the sync completes.

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.

GET /properties/{propertyId}/rate-plans

Return one stable page of rate plans for one property. This endpoint requires the rate-plans:read scope.

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.

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.

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 lands while a channel sync is still in progress fails with 409 sync_in_progress; retry once the sync completes.

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.

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.

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 -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"}'

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.

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"}'

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 pool_id.

availableUnits subtracts reservations and availability blocks from the sellable count and is 0 on closed dates. rate and minStay come from the lowest-priced sellable rate plan; both are null when no active plan sells the date, and stopSell is true when every active plan is stop-sold.

PUT /properties/{propertyId}/calendar

Bulk-update per-day availability, rates, and restrictions for one property. This endpoint requires the calendar:write scope. The body is an array of day entries shaped like the read rows.

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. Explicitly remove protection in the calendar or through the protection API first. Removing protection alone leaves the date closed.

Nights locked in the Supahost calendar cannot be written by this endpoint. A request that includes a locked night returns 409 calendar_night_locked and changes nothing. A night is locked when a person locks it, edits it in the calendar on a property the live RentShare feed writes, or when the feed finds it was changed outside the feed. On such a property, a night this endpoint writes is changed outside the feed too: the next feed update locks it, so it keeps your value and later writes to it return 409 until it is unlocked in the calendar. Unlock it in the calendar first.

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

Each entry is an upsert: days not mentioned stay untouched, and a null rate or minStay leaves the stored value unchanged. 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. A request can form at most 90 disjoint date ranges in total; batch genuinely sparse updates into multiple requests. Changes queue to the channel sync outbox and propagate to connected channels asynchronously.

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.

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 and zero-price nights.

stopSell reports the stored flag. A zero price also prevents sales. 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 verify channel delivery.

GET /reservations

Return one stable page of reservations.

GET /reservations/{reservationId}

Return one reservation from the API key workspace.

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.

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.

POST /reservations/{reservationId}/cancel

Cancel one direct reservation and release its inventory. This endpoint requires the reservations:write scope. Cancelling an already cancelled reservation succeeds without changing anything.

Channel reservations must be cancelled in the connected channel (400 channel_managed), and completed reservations cannot be cancelled (400 reservation_completed). The release queues to the channel sync outbox asynchronously.

GET /tasks

Return one stable page of tasks.

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.

GET /tasks/{taskId}

Return one task from the API key workspace.

PUT /tasks/{taskId}

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

GET /conversations

Return one stable page of conversations, newest activity first.

GET /conversations/{conversationId}/messages

Return one stable page of messages in chronological order.

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.

GET /channels

Return one stable page of channel connections.

GET /webhooks

Return one stable page of webhook endpoints, newest first.

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.

GET /webhooks/{webhookId}

Return one webhook endpoint from the API key workspace.

PUT /webhooks/{webhookId}

Replace the URL, description, and subscribed events of one webhook endpoint. Set enabled to change the status.

DELETE /webhooks/{webhookId}

Delete one webhook endpoint. A successful delete returns 204 with no body.

GET /webhooks/{webhookId}/deliveries

Return one stable page of delivery attempts for the endpoint, newest first.