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

listing_id
string<uuid>
required

Maat's identifier for the listing.

Body

application/json
rates
RateRange · object[]
required

Non-overlapping ranges, every night today or later and none more than 730 nights ahead, at most 730 nights in total across the whole request.

Required array length: 1 - 730 elements

Response

The rates were stored.

listing_id
string<uuid>
required

The listing the rates were written to.

nights_written
integer
required

Nights stored or replaced by this request.

Example:

43

currency
string
required

The listing's currency, which every rate you sent had to match.

Pattern: ^[A-Z]{3}$
Example:

"EGP"

mode
enum<string>
required
Available options:
rules,
partner,
external
Example:

"partner"

binding
boolean
required

true only when mode is partner and you own it — i.e. these rates are what a guest is quoted. false means they are stored and inert, which is the normal state before you take the pricing mode.

Example:

false

coverage_until
string<date> | null
required

Last night of the CONTIGUOUS run of your own rates that starts today, or null when you have not priced tonight. Not the furthest night you have priced: a horizon with a hole in it is not covered past the hole.

It describes YOUR calendar whether or not you hold the pricing mode — so a fill sent before you take the mode reports a real horizon, and reading it straight back with GET …/rates gives the same number. Whether those nights are in force is binding and mode.

Example:

"2027-01-31"

gap_nights_next_90_days
integer
required

Nights with no rate in the next 90. Every one of them is unquotable.

Example:

0