# Hostex.io OpenAPI Documentation

## API Reference
- [Overview](https://api-doc.hostex.io/reference/overview.md): Welcome to the Hostex API, where seamless integration meets comprehensive management of property and reservation systems. Our API provides a powerful suite of features for developers looking to automate and interact with the Hostex platform.
- [Quickstart](https://api-doc.hostex.io/reference/quickstart.md)
- [Query Properties](https://api-doc.hostex.io/reference/query-properties.md): You can query properties by making a request to this endpoint.
- [Query Groups](https://api-doc.hostex.io/reference/query-groups.md): You can query property groups by making a request to this endpoint.
- [Create Property](https://api-doc.hostex.io/reference/create-property.md): Create a new property (room) under the current operator. Hostex properties are physical room units; OTA listings can be attached to a property afterwards via the Hostex Host Portal. The newly created property has no address, channels or pictures and starts with the operator's default check-in / check-out time settings. Subject to the property quantity limit of the operator's subscription.
- [Query Tags](https://api-doc.hostex.io/reference/query-tags.md): You can query tags by making a request to this endpoint.
- [Create Group](https://api-doc.hostex.io/reference/create-group.md): Create a new property group. Optionally pre-attach properties at creation time via `property_ids`. The group name must be unique within the operator's account.
- [Update Group](https://api-doc.hostex.io/reference/update-group.md): Update a property group. Pass `name` to rename it; pass `property_ids` to **replace** the group's full property assignment with the supplied list (pass an empty array to detach all properties). Omitted fields are left unchanged.
- [Delete Group](https://api-doc.hostex.io/reference/delete-group.md): Delete a property group. All property-group pivot rows are removed automatically; the underlying properties themselves are unaffected.
- [Create Tag](https://api-doc.hostex.io/reference/create-tag.md): Create a new property tag. Optionally pre-attach properties via `property_ids` and / or room types via `room_type_ids`. The name must be unique within the operator's account (soft-deleted same-name tags are restored). Color is auto-assigned from the Hostex palette unless one of the allowed hex strings is supplied. Operators are capped at 500 property tags.
- [Update Tag](https://api-doc.hostex.io/reference/update-tag.md): Update a property tag. Pass `name` and / or `color` to change the tag itself; pass `property_ids` and / or `room_type_ids` to **replace** the tag's full assignment list. Pass an empty array to detach all properties / all room types. Omitted fields are left unchanged.
- [Delete Tag](https://api-doc.hostex.io/reference/delete-tag.md): Delete a property tag. All property-tag and room-type-tag pivot rows are removed automatically; the underlying properties / room types themselves are unaffected.
- [Query RoomTypes](https://api-doc.hostex.io/reference/query-room-types.md): You can query room types by making a request to this endpoint.
- [Create RoomType](https://api-doc.hostex.io/reference/create-room-type.md): Create a new room type under the current operator. A room type is a group of interchangeable properties (rooms) sold as a single inventory pool. Optionally link existing properties at creation time via `property_ids` — each linked property must not already belong to another room type. Subject to the room type quantity limit of the operator's subscription (capped by the property quantity limit) and not available on Basic editions.
- [Query Reservations](https://api-doc.hostex.io/reference/query-reservations.md): You can query reservations by making a request to this endpoint.
- [Create Reservation](https://api-doc.hostex.io/reference/create-reservation.md): Create a reservation (Direct Booking) in Hostex.
- [Cancel Reservation](https://api-doc.hostex.io/reference/cancel-reservation-1.md): Cancel a direct booking reservation in Hostex. Note that this endpoint does not support the cancellation of channel bookings.
- [Update Check-in Details](https://api-doc.hostex.io/reference/update-check-in-details.md): Update check-in details for a stay including lock code, arrival/departure times, and deposit information.
- [Update Reservation Basic Info](https://api-doc.hostex.io/reference/update-reservation-basic-info.md): Update basic information of a stay including guest details, dates, pricing, and other attributes.
- [Query Custom Channels](https://api-doc.hostex.io/reference/query-custom-channels.md): Query custom channels created from the [Custom Options Page](https://hostex.io/app/settings/custom-options).
- [Custom Fields Guide](https://api-doc.hostex.io/reference/custom-fields-guide.md)
- [Query Custom Fields](https://api-doc.hostex.io/reference/query-custom-fields.md): Query custom fields for a stay. For more information, please refer to the [Custom Fields Guide](/reference/custom-fields-guide).
- [Update Custom Fields](https://api-doc.hostex.io/reference/update-custom-fields.md): Update custom fields for a stay. For more information, please refer to the [Custom Fields Guide](/reference/custom-fields-guide)
- [Move to Box](https://api-doc.hostex.io/reference/move-reservation-to-box.md): Move a stay of the reservation to the reservation box. This action is typically used when you want to temporarily remove a reservation from the active calendar view.
- [Allocate to Property](https://api-doc.hostex.io/reference/allocate-reservation.md): Allocate a reservation to a specific property. This action is used to assign or reassign a reservation to a particular property. If there is already a stay for the target property, it will be marked as a conflicting stay and move to the reservation box.
- [Update Stay Status](https://api-doc.hostex.io/reference/update-stay-status.md): Update the stay status of a reservation. This endpoint allows you to change the status of a stay between different states such as check-in pending, in-house, and stay completed.
- [Approve Reservation](https://api-doc.hostex.io/reference/approve-reservation.md): Approve a pending reservation request. The reservation must be in `wait_accept` status. This endpoint communicates with the channel to confirm the booking.
- [Decline Reservation](https://api-doc.hostex.io/reference/decline-reservation.md): Decline a pending reservation request. The reservation must be in `wait_accept` status. This endpoint communicates with the channel to reject the booking.
- [Add Tag](https://api-doc.hostex.io/reference/add-tag.md): Add a tag to a reservation. If the tag does not exist, it will be created automatically.
- [Remove Tag](https://api-doc.hostex.io/reference/remove-tag.md): Remove a tag from a reservation.
- [Reservation Rate Details](https://api-doc.hostex.io/reference/reservation-rate-details.md)
- [Query Property Availabilities](https://api-doc.hostex.io/reference/query-availabilities.md): By sending a request to this endpoint, you can retrieve the availabilities of the properties.
- [Update Property Availabilities](https://api-doc.hostex.io/reference/update-availabilities.md): Use this endpoint to update property availabilities. <br><br>Please be aware that a successful response indicates only that we have initiated an asynchronous task to handle your submission; it <b>DOES NOT</b> ensure that the channel inventories have been modified successfully. If you wish to view detailed results of the task execution, please visit the [Host Portal](https://hostex.io/app/calendar).
- [Query Listing Calendars](https://api-doc.hostex.io/reference/query-listing-calendars.md): By sending a request to this endpoint, you can retrieve calendar information for multiple listings. This endpoint will return daily details on price, inventory, and restrictions for each listing.
- [Query Pricing Ratios](https://api-doc.hostex.io/reference/query-pricing-ratios.md): Return the per-channel pricing ratio of each OTA listing linked to a property (`property_id`) or a room type (`room_type_id`). Pricing ratio is the **percentage** Hostex multiplies a base (property/room-type level) price by to derive the actual price pushed to each listing. Use this endpoint at the skill layer to compose a 'change price by property / room type' workflow: read the ratios, compute `target_price = round(base_price * ratio / 100)` for every non-readonly listing, then call `POST /listings/prices` once per listing. Listings marked `readonly: true` are silently controlled by the channel (e.g. Airbnb child rate plans) and cannot be repriced via `POST /listings/prices`; skip them.
- [Update Listing Inventories](https://api-doc.hostex.io/reference/update-listing-inventories.md): Update the inventories of channel listings. <br><br>Please be aware that a successful response indicates only that we have initiated an asynchronous task to handle your submission; it <b>DOES NOT</b> ensure that the channel inventories have been modified successfully. If you wish to view detailed results of the task execution, please visit the [Host Portal](https://hostex.io/app/price). <br><br>Furthermore, you should be aware that this endpoint only modifies the listing's inventory and <b>DOES NOT</b> affect the property availability. If the property availability is modified, it may still result in the channel inventory being overwritten again.
- [Update Listing Prices](https://api-doc.hostex.io/reference/update-listing-prices.md): Update the prices of channel listings. <br><br>Please be aware that a successful response indicates only that we have initiated an asynchronous task to handle your submission; it <b>DOES NOT</b> ensure that the channel prices have been modified successfully. If you wish to view detailed results of the task execution, please visit the [Host Portal](https://hostex.io/app/price).
- [Update Listing Restrictions](https://api-doc.hostex.io/reference/update-listing-restrictions.md): Update the restrictions of channel listings. <br><br>Please be aware that a successful response indicates only that we have initiated an asynchronous task to handle your submission; it <b>DOES NOT</b> ensure that the channel restrictions have been modified successfully. If you wish to view detailed results of the task execution, please visit the [Host Portal](https://hostex.io/app/price).
- [Query Conversations](https://api-doc.hostex.io/reference/query-conversations.md): This endpoint is used to query the list of conversations regarding guest inquiries.
- [Get Conversation Details](https://api-doc.hostex.io/reference/get-conversation-details.md): This endpoint is used to retrieve the messages and details of a conversation. <br><br>We are constantly improving our API which could mean that message schema may change. In order to maintain a healthy integration, your Application must parse and ignore unexpected parameters instead of throwing errors.
- [Send Message](https://api-doc.hostex.io/reference/send-message.md): Send a text or image message to the guest.
- [Update Conversation Note](https://api-doc.hostex.io/reference/update-conversation-note.md): Set or clear the host's private note attached to a conversation thread. The note is stored only in Hostex (visible in the Hostex Inbox), is **never** sent to the guest or pushed to any channel, and is shared across operators inside the same account. Pass an empty string or `null` in `note` to clear the existing note.
- [Query Reviews](https://api-doc.hostex.io/reference/query-reviews.md): Query reviews like the [Reviews Page](https://hostex.io/app/reviews).
- [Create a review](https://api-doc.hostex.io/reference/create-review.md): Create review or reply for a reservation.
- [Query upcoming automation actions](https://api-doc.hostex.io/reference/query-automation-actions.md): Returns scheduled automation **actions** that are waiting to run: either automated **messages** (`type=message`, same scope as the in-app “upcoming message actions” list, within the next 30 days) or automated **reviews** (`type=review`). Filters mirror the internal automation plan lists (keyword, property IDs, time range, channel types, rule event filters). Pagination uses `offset` and `limit` like other v3 list endpoints.
- [Execute automation action now](https://api-doc.hostex.io/reference/execute-automation-action.md): Dispatches a **waiting** message or review automation plan immediately (same behavior as executing an upcoming action in the app). For **review** plans, the reservation must have reached check-out date in the operator timezone. Requires a **writable** access token. Only `send_message` and `review` plan types are supported.
- [Delete upcoming automation action](https://api-doc.hostex.io/reference/delete-automation-action.md): Removes a **waiting** message or review automation plan without running it (same as deleting an upcoming action in the app). Requires a **writable** access token. Only `send_message` and `review` plan types are supported.
- [Query Tasks](https://api-doc.hostex.io/reference/query-tasks.md): You can query schedule tasks (cleaning / maintain / reception / housekeeping / others) by making a request to this endpoint.
- [Create Task](https://api-doc.hostex.io/reference/create-task.md): Create a schedule task. The task may be linked to a property (`property_id`), to a specific stay (`stay_code`), and/or assigned to a staff (`staff_id`); all are optional. When `stay_code` is provided the task is linked to the reservation; `property_id` is inferred from the stay when omitted (and must match the stay's property when both are supplied). The `type` selects the task category and `level` is only meaningful for cleaning tasks.
- [Update Task](https://api-doc.hostex.io/reference/update-task.md): Update an existing task. All fields are optional; only the supplied fields are changed. Pass `property_id=0` or `staff_id=0` to detach the task from the related property or staff.
- [Delete Task](https://api-doc.hostex.io/reference/delete-task.md): Delete a task permanently. Returns 404 if the task does not exist or is not accessible to the current operator.
- [Query Staffs](https://api-doc.hostex.io/reference/query-staffs.md): You can query schedule staffs (cleaners / operators / receptionists, etc.) by making a request to this endpoint.
- [Create Staff](https://api-doc.hostex.io/reference/create-staff.md): Create a schedule staff. The staff is created as active by default. Use `property_ids` to limit the staff to specific properties; the staff will be created with access to all properties when omitted.  For international operators, `mobile` must be in `+<country code> <number>` format (e.g. `+86 13800138000`).
- [Update Staff](https://api-doc.hostex.io/reference/update-staff.md): Update an existing staff. All fields are optional; only the supplied fields are changed. Passing `property_ids` replaces the staff's full property assignment list (use an empty array to clear). Use `is_active` to enable or disable the staff.
- [Delete Staff](https://api-doc.hostex.io/reference/delete-staff.md): Delete a staff permanently along with their property assignments. Returns 404 if the staff does not exist or is not accessible to the current operator.
- [Query Incomes & Expenses](https://api-doc.hostex.io/reference/query-transactions.md): Query income and expense entries (also known as `transactions`) recorded against the operator, properties or reservations.  The response provides each entry with its categorization (`item_id` / `item_name`) and payment method (`payment_method_id` / `payment_method_name`). The values of `item_id` and `payment_method_id` reference the dictionaries returned by `GET /income_items`, `GET /expense_items`, `GET /income_methods` and `GET /expense_methods` (which dictionary applies depends on `direction`).
- [Create Transaction](https://api-doc.hostex.io/reference/create-transaction.md): Record a new income or expense entry. What the entry is linked to is inferred from the request: - provide `stay_code` to record an entry against a specific stay, - provide `property_id` to record an entry against a specific property, - provide neither to record an operator-level entry (not tied to any specific property or stay; only available to the master operator).  `stay_code` and `property_id` are mutually exclusive.  The `direction` field decides whether the entry is an `income` or an `expense`, which in turn determines which dictionaries are used for `item_id` (`GET /income_items` or `GET /expense_items`) and `payment_method_id` (`GET /income_methods` or `GET /expense_methods`). The `amount` is always provided as a positive number; the sign is derived from `direction`. The `currency` accompanies the amount and must be supplied unless `stay_code` is provided, in which case it is inherited from the reservation order and, if you do provide it, it must match the order's currency.
- [Delete Transaction](https://api-doc.hostex.io/reference/delete-transaction.md): Delete a transaction entry. The operation is irreversible. Returns 404 if the entry does not exist or is not accessible to the current operator.
- [Update Transaction](https://api-doc.hostex.io/reference/update-transaction.md): Update an existing transaction entry. Only the fields listed below can be modified. The entry's `direction`, link target (related property / reservation / operator) and `currency` are immutable; if you need to change any of these, delete the entry and create a new one.
- [Query Income Items](https://api-doc.hostex.io/reference/query-income-items.md): Query the dictionary of income item categorizations available to the operator. The returned `id` matches the `item_id` returned by `GET /transactions` for entries with `direction=income`.
- [Query Income Methods](https://api-doc.hostex.io/reference/query-income-methods.md): Query the dictionary of payment methods available to the operator for income entries. The returned `id` matches the `payment_method_id` returned by `GET /transactions` for entries with `direction=income`.
- [Query Expense Items](https://api-doc.hostex.io/reference/query-expense-items.md): Query the dictionary of expense item categorizations available to the operator. The returned `id` matches the `item_id` returned by `GET /transactions` for entries with `direction=expense`.
- [Query Expense Methods](https://api-doc.hostex.io/reference/query-expense-methods.md): Query the dictionary of payment methods available to the operator for expense entries. The returned `id` matches the `payment_method_id` returned by `GET /transactions` for entries with `direction=expense`.
- [Query Knowledge Bases](https://api-doc.hostex.io/reference/query-knowledge-bases.md): You can query knowledge base entries by making a request to this endpoint. Results are paginated and can be filtered by property or channel.
- [Create Knowledge Base](https://api-doc.hostex.io/reference/create-knowledge-base.md): Create a new knowledge base entry for the HostGPT automation assistant. The entry defines AI content and the property/channel scope where it applies.
- [Get Knowledge Base Detail](https://api-doc.hostex.io/reference/get-knowledge-base.md): Retrieve the full details of a single knowledge base entry by its ID.
- [Update Knowledge Base](https://api-doc.hostex.io/reference/update-knowledge-base.md): Replace an existing knowledge base entry. This endpoint performs a **full replacement** — `scope_property`, `scope_channel`, `contents` and `is_enable` must all be supplied. Use `GET /knowledge_bases/{id}` first if you only want to change one field.
- [Delete Knowledge Base](https://api-doc.hostex.io/reference/delete-knowledge-base.md): Delete a knowledge base entry by its ID.
- [Query Channel Accounts](https://api-doc.hostex.io/reference/query-channel-accounts.md): Query the third-party channel accounts (Airbnb, Booking.com, etc.) that the operator has connected. Each entry exposes the account identity and current authorization status. Use `id` to fetch a single account.
- [Query Listings](https://api-doc.hostex.io/reference/query-listings.md): Query the listings (third-party properties) synced from the operator's connected channel accounts. A listing is a property as it exists on a specific channel, identified by `listing_id` (the channel-side property id). Filter by `channel_account_id`, `listing_id` and/or `channel_type` to scope results.
- [Query Reservation Tags](https://api-doc.hostex.io/reference/query-reservation-tags.md): List the operator's reservation tag dictionary. Includes both system default tags (`is_default = true`, shared across all operators) and the operator's own custom tags. These are the tags that `POST /reservations/{stay_code}/tags` can attach to a reservation.
- [Create Reservation Tag](https://api-doc.hostex.io/reference/create-reservation-tag.md): Create a new reservation tag in the operator's dictionary. Color is auto-assigned from the Hostex palette. Names must be unique across both system default tags and the operator's own tags (a soft-deleted tag with the same name will be restored). Operators are capped at 500 tags.
- [Delete Reservation Tag](https://api-doc.hostex.io/reference/delete-reservation-tag.md): Delete one of the operator's custom reservation tags. System default tags (`is_default = true`) cannot be deleted via this API and will return 404. Deleting a tag also removes it from any reservations it had been applied to.
- [Query Calendar Share Links](https://api-doc.hostex.io/reference/query-calendar-share-links.md): List the operator's public calendar share links. Each link exposes a read-only calendar (and reservation list) of either every property (`scope = entire`) or a selected subset (`scope = partial`) and is reachable by anyone who has the URL.
- [Create Calendar Share Link](https://api-doc.hostex.io/reference/create-calendar-share-link.md): Create a new public calendar share link. `scope = entire` exposes every property in the operator's account; `scope = partial` exposes only the properties listed in `property_ids`. Each operator can have at most one entire-scope link: requesting one when it already exists simply returns the existing link.
- [Delete Calendar Share Link](https://api-doc.hostex.io/reference/delete-calendar-share-link.md): Permanently invalidate a calendar share link. The public URL will start returning a `share link invalid` error to anyone who tries to open it.
- [Authentication](https://api-doc.hostex.io/reference/authentication.md)
- [Errors](https://api-doc.hostex.io/reference/errors.md)
- [Rate Limits](https://api-doc.hostex.io/reference/rate-limits.md)
- [Supported Channels](https://api-doc.hostex.io/reference/supported-channels.md)
- [Supported Currencies](https://api-doc.hostex.io/reference/supported-currencies.md)
- [Usage Guide](https://api-doc.hostex.io/reference/webhook-useage-guide.md)
- [Event Types](https://api-doc.hostex.io/reference/webhook-event-types.md)
- [Query Webhooks](https://api-doc.hostex.io/reference/query-webhooks.md): Query Webhooks like the [Webhooks Page](https://hostex.io/app/api/web-hooks).
- [Create Webhook](https://api-doc.hostex.io/reference/create-webhook.md): Create a webhook.
- [Delete webhook](https://api-doc.hostex.io/reference/delete-webhook.md): You can only delete webhooks created by your own app if they are manageable. Attempting to delete non-manageable webhooks from other apps will result in a 403 error.
- [Update Webhook](https://api-doc.hostex.io/reference/update-webhook.md): Update the url or event subscriptions for a webhook. You can only update webhooks created by your own app.
- [Overview](https://api-doc.hostex.io/reference/oauth-overview.md)
- [How to Request OAuth Access](https://api-doc.hostex.io/reference/how-to-request-oauth-access.md)
- [Authorization Workflow](https://api-doc.hostex.io/reference/authorization-workflow.md)
- [Obtain/Refresh Tokens](https://api-doc.hostex.io/reference/obtain-token.md): This endpoint is used to obtain a new access token using various OAuth 2.0 grant types or refresh an existing token.
- [Delete/Revoke Tokens](https://api-doc.hostex.io/reference/revoke-token.md): This endpoint allows clients to revoke an access or refresh token. Deleting/revoking a token will disconnect the Host from your application.
- [Overview](https://api-doc.hostex.io/reference/mcp-overview.md)
- [Quickstart](https://api-doc.hostex.io/reference/mcp-quickstart.md)
- [Tools Reference](https://api-doc.hostex.io/reference/mcp-tools-reference.md)