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

partner is the only value. Releasing is DELETE on the same path, not {"mode":"rules"} — one verb that both takes and releases is a verb a retry can get backwards.

mode
string
required

Always partner. There is one mode to take; releasing is a DELETE, not another mode.

Allowed value: "partner"
Example:

"partner"

fallback_to_base_price
boolean
default:false

What a night you have sent no rate for is worth.

false (the default) refuses to quote it — a gap means your feed is broken, and inventing a price for a peak night would under-charge it silently. true prices it at the host's own base price, so a listing stays bookable past the end of your horizon. Your rates always win on the nights you have sent.

A PUT states the whole mode, so omitting this field sets it to false — send it on every take, not only the one that turns it on. Changing it on a listing you already price is allowed and takes effect on the next quote.

Example:

true

Response

You now price this listing.

listing_id
string<uuid>
required

The listing whose pricing mode you now hold.

mode
string
required

Always partner — the mode you now hold.

Allowed value: "partner"
fallback_to_base_price
boolean
required

What is in force for this listing now — true when an unpriced night falls back to the host's base price, false when it is refused.

Example:

true

rules_deactivated
RulesDeactivated · object
required

The listing's own pricing rules this switched off. Booking rules are switched off too, a moment later, and are deliberately not counted here rather than reported as a number that could be stale by the time you read it.

coverage_until
string<date> | null
required

The last night you have sent a rate for, or null when you have sent none yet.

Example:

"2027-01-31"

warnings
enum<string>[]
required

no_rates_next_30_nights when the coming month is not fully priced. A warning, never a refusal. What those nights are worth depends on fallback_to_base_price: unquotable until you send a rate when it is false, the host's base price when it is true.

See PricingModeTakeWarning.

Something worth knowing about the mode you now hold. A warning, never a refusal.

Available options:
no_rates_next_30_nights
Example: