Skip to main content
PATCH
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

A partial edit of one listing. An absent member is untouched.

Send at least one member. An empty body is a 400, not a silent no-op that reads as success.

title
string

The listing's title, as guests see it.

Required string length: 1 - 120
description
string | null

The one member that accepts null: "this listing has no description" is a real state you must be able to reach.

Maximum string length: 4000
status
enum<string>

Not a column write. listed runs Maat's validity gate and publishes only if it passes — a refusal is still a 200, with the returned listing's publishable and missing saying why and nothing about publication changed. unlisted holds the listing off sale.

See ListingStatus.

Available options:
listed,
unlisted
instant_booking
boolean

Whether a guest can book without the host confirming first.

is_exclusive
boolean

A merchandising badge.

is_best_price
boolean

A merchandising badge. Not an amount, despite the name.

Response

The listing, read back after the change. A listed request the validity gate refused lands here too — read publishable and missing.

The sellable view of one unit.

console_url is a deep link into the Maat host console. It is null for a listing with no property behind it.

listing_id
string<uuid>
required

Maat's id for the listing. The id every listing-scoped operation takes.

inventory_kind
enum<string>
required

What the listing sells. unit is a place somebody stays in; the other two are sold by the seat and are read-only through this contract.

See InventoryKind.

Available options:
unit,
service,
experience
title
string
required

The listing's title, as guests see it.

description
string
required

The listing's description, as guests see it. Empty string when the host has written none.

status
enum<string>
required

Whether it is on sale right now. unlisted covers every reason — asked for, held back by the validity gate, or suspended. missing says which.

See ListingStatus.

Available options:
listed,
unlisted
base_rate
Money · object
required

An amount and its currency, always together.

value is a decimal string, not a number. 1250.10 has no exact IEEE-754 representation, and a JSON parser that rounds it costs a cent on every booking. Parse it with a decimal type, not a float.

There is no bare amount anywhere in this API and no currency field sitting beside one. Two fields can be read separately; one object cannot.

cleaning_fee
Money · object | null
required

null when the listing charges none. Never "0.00", which would read as a price of zero.

instant_booking
boolean
required

Whether a guest can book without the host confirming first.

is_exclusive
boolean
required

Whether the listing is part of Maat's curated collection. Set by Maat, not by this API.

is_best_price
boolean
required

A marketing badge. Not an amount, despite the name.

rating
ListingRating · object
required

The review score, as one object. average is null until somebody has scored the listing — a zero would be a terrible score, and "nobody has stayed yet" is not one.

publishable
boolean | null
required

Whether the listing satisfies the platform's validity gate — a price above zero, at least one amenity, a cover photo and a minimum photo count.

null means nothing was assessed, and is not the same as false: the gate describes a place somebody stays in, so a service or experience listing has no answer to it.

missing
enum<string>[]
required

Reasons publishable is false. Empty otherwise.

See MissingReason.

Why a listing is not publishable. A closed vocabulary.

Available options:
price,
amenities,
cover_photo,
photos,
photos_processing,
unlisted
console_url
string<uri> | null

The listing's page in the Maat host console.