Glossary - Maat Stays

Most of this API says what it means. These are the words that do not, either because the platform uses them more narrowly than you would, or because the same English word covers more than one thing here.

The word `external`

Four things in this contract are spelled with some form of external, and they mean different things. This is the one place they are set beside each other.

Where	What it means
`external_uid` on a calendar block	Yours. Your own reservation identifier, which is what makes the push idempotent and what lets only you release the block.
`blocked_by: "ical"` on a calendar night	A calendar feed the workspace subscribed to on our side, e.g. from another platform.
`mode: "external"` on a pricing mode	A third-party pricer — somebody who is neither you nor Maat’s own rule engine. Which one is deliberately never named.
`unavailable_reason: "external_pricing"`	The same third-party pricer, as the reason a quick action cannot be applied right now.

If you learn only the first, the third will mislead you: external_uid is your own, and mode: "external" is precisely not yours.

Who is who

Term	What it means
You	A host, or a property company, managing its own Maat inventory from its own system. Issues its own keys from its own Maat account.
Workspace	One tenant on Maat — a host’s account and everything in it. A key is bound to exactly one, for its whole life.
Tenancy	Which kind of workspace: sandbox or production. Not a server, a region or a hostname — there is one host.

The resource model

Term	What it means
Property	The building or plot. Has an address, a time zone and building amenities. Addressed by `property_id`.
Unit	The physical thing somebody sleeps in — beds, bathrooms, door times, house rules. `unit_id`.
Listing	The sellable view of a unit: title, rate, badges, whether it is on sale. `listing_id`, and what you book, block and price.
`provider_id`	Your identifier for a property, 1–128 characters of your own choosing. Unique to your workspace: two workspaces can use the same one for different properties.
`inventory_kind`	What a listing sells: `unit` (a stay), or `service` / `experience` (sold by the seat). This contract manages stays; a write against the other two is `inventory_not_supported`.
Publishable	Every gate for going on sale is satisfied. `missing[]` names what is not, and publication is still a separate `PUT`.

Money, prices and rules

Term	What it means
Money	`{ "value": "1250.00", "currency": "EGP" }` — an amount and its currency, always one object. `value` is a decimal string; parse it with a decimal type, not a float.
Pricing mode	Who decides a listing’s nightly price: `rules` (Maat’s own engine), `partner` (an API credential), or `external` (a third-party pricer). One at a time.
Quick action	A named, pre-built rule you switch on with one call and at most one value — `booking.min_stay`, `pricing.cleaning_fee`.
Rule	What a quick action creates, and what a workspace can also draw by hand in the Maat app. Read-only over this API, and published without its logic.
Binding	Whether the rates you have pushed are what a guest is actually quoted. Rates can be stored and inert — that is the normal state before you take the pricing mode.
Coverage	The last night of the contiguous run of your own rates starting today. Not the furthest night you have priced: a horizon with a hole in it is not covered past the hole.

Blocks, holds and bookings

Term	What it means
Partner block	Nights you have told us are gone because they are taken in your own system. Keyed by your `external_uid`; released only through that id.
Host block	Nights the workspace closed — maintenance, an owner stay, a renovation. Keyed by date, from the Maat app or this API.
Held	A checkout in flight. It is a sale rather than a block, and it may expire.
Booked	A completed sale. It will not expire.
Credential	The thing a limit or a scope is counted against. On this API that is your API key, not the token minted from it — tokens are short-lived and a limit that reset with one would not be a limit.

Availability of the contract itself

Term	What it means
Sandbox	A real Maat tenancy with real endpoints and real writes, kept off every public surface. Where every contract does real work today.
Production	A live workspace. Every contract authenticates, rate-limits and validates in full there, then answers `501 not_enabled` — nothing written, read or delivered.
`501 not_enabled`	Not an error in your integration. It is the answer that says the request was correct and the contract is not switched on for that workspace yet.
`x-maat-availability`	The machine-readable form of the same fact, on every operation in the reference.