Skip to main content
PUT
cURL

Authorizations

Authorization
string
header
required

A short-lived partner token, obtained by exchanging your API key at POST /token. Send it as Authorization: Bearer <access_token>.

Tokens live for fifteen minutes by default and never for more than an hour. Mint one per batch of work, not one per request.

The token carries the workspace and the environment its key was issued for. You cannot change either by asking: the exchange ignores everything in the request body for exactly that reason.

It also carries the key's scopes (scope, a list). Every operation names a scope as x-maat-scope, and a token whose key lacks it is refused with 403 insufficient_scope, naming the scope. Scopes are fixed when a key is issued and are re-read from the key on every request, so a key narrowed today is narrowed on its next call — the token's scope is what the key held at exchange time, for your own reading, never what authorizes a request.

x-maat-scope is the floor, and on the quick-action operations it is not the whole requirement. PUT and DELETE /listings/{listing_id}/quick-actions/{template_key} carry rules:write, and additionally require pricing:write when template_key begins pricing. — the capability depends on the template in the path, because a cleaning fee changes what a guest pays and a minimum stay does not. The refusal is the same 403 insufficient_scope, naming pricing:write. The two READS apply the same requirement without erroring: GET /listings/{listing_id}/quick-actions still lists the pricing.* rows but withholds their applied state, and GET /listings/{listing_id}/rules omits the pricing rules entirely and reports pricing_withheld in warnings. These four are the only operations in this document whose requirement is not exactly their x-maat-scope, and each of them says so machine-readably: x-maat-scope-additional lists the second scope it can require and x-maat-scope-additional-when says what happens without it.

Never send it as a cookie or in a query string, and never store it — store the API key, mint tokens from it.

Path Parameters

external_uid
string
required

Your own identifier for the block, typically your reservation id. Unique to you.

Required string length: 1 - 255

Body

application/json

A range of nights that are unavailable. Send exactly one of provider_id or listing_id.

No guest data of any kind is accepted here — an unrecognised field is an error, not something we quietly ignore.

provider_id
string
required

Your own property identifier.

Required string length: 1 - 128
check_in
string<date>
required

First night held.

Example:

"2026-09-01"

check_out
string<date>
required

Departure day, exclusive. The night before this is the last one held.

Example:

"2026-09-05"

listing_id
string<uuid>

Maat's listing identifier, for a property you did not push.

reason
enum<string>

A closed set, deliberately. There is no free-text alternative, because the obvious thing to write in one is a guest's name.

See BlockReason.

Available options:
reserved,
maintenance,
owner_stay,
other

Response

The nights are held.

external_uid
string
required

Your own identifier for the block, echoed back.

result
enum<string>
required

Whether this push created the block or replaced one you had already pushed. See WriteResult.

Available options:
created,
updated
nights
integer
required

Nights actually held, restated so you can check it.

Required range: 1 <= x <= 730
listing_id
string<uuid>
required

The Maat listing the block landed on. Useful when you addressed the property by your own identifier and want ours in return.