curl --fail-with-body -X PATCH https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24 \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Courtyard flat with the blue door", "status": "listed"}'// Partial: an absent field is untouched. Send at least one.
const res = await fetch(
'https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24',
{
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Courtyard flat with the blue door',
status: 'listed',
}),
},
);
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
// A `listed` request the gate refused is still a 200. Read the verdict.
if (!body.publishable) console.log('not published:', body.missing);
import os
import requests
# Partial: an absent field is untouched. Send at least one.
res = requests.patch(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
json={"title": "Courtyard flat with the blue door", "status": "listed"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
# A "listed" request the gate refused is still a 200. Read the verdict.
if not body["publishable"]:
print("not published:", body["missing"])
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type listing struct {
Status string `json:"status"`
Publishable *bool `json:"publishable"`
Missing []string `json:"missing"`
}
func main() {
// Partial: an absent field is untouched. Send at least one.
payload, _ := json.Marshal(map[string]any{
"title": "Courtyard flat with the blue door",
"status": "listed",
})
req, _ := http.NewRequest(http.MethodPatch,
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
log.Fatalf("listing patch failed: %d", res.StatusCode)
}
var body listing
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
// A "listed" request the gate refused is still a 200. Read the verdict.
if body.Publishable == nil || !*body.Publishable {
fmt.Println("not published:", body.Status, body.Missing)
}
}
{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"inventory_kind": "unit",
"title": "Courtyard flat with the blue door",
"description": "A two-bedroom flat one street back from the corniche.",
"status": "listed",
"base_rate": {
"value": "1250.00",
"currency": "EGP"
},
"cleaning_fee": {
"value": "200.00",
"currency": "EGP"
},
"instant_booking": true,
"is_exclusive": false,
"is_best_price": true,
"rating": {
"average": 4.8,
"count": 24
},
"publishable": true,
"missing": [],
"console_url": "https://maatstays.wtf/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7"
}Change a listing, and whether it is on sale
Changes the sellable view of a unit: its title, its description, its badges, and whether it is on sale.
Partial. An absent field is untouched. description is the one member that
accepts null, because “this listing has no description” is a real state you
must be able to reach. Send at least one field: an empty body is a 400.
status is not a column write.
listed runs Maat’s own validity gate — a price above zero, at least one
amenity, a cover photo and a minimum photo count — and publishes the listing only
if it passes. If it does not pass, the answer is still 200: the returned
listing’s publishable and missing say why, and nothing about whether the
listing is on sale is changed. Acceptance is not publication. A listing already
on sale is not taken off it as a side effect of a request that asked for the
opposite.
unlisted holds the listing off sale.
A listing Maat has suspended for its own reasons stays off sale through a
listed request. So publishable can read true while status reads
unlisted — that is not a contradiction, and it is not something this operation
can clear. Contact the workspace.
Text is normalised before it is stored, and its length is re-checked afterwards:
control characters, zero-width characters and bidirectional-override characters
are removed, and runs of whitespace are collapsed. A title that normalises to
nothing is a 400.
The body is strict. An undeclared field is a 400 validation_failed naming it,
never a silent drop, and a stray query string is refused the same way.
A property with more than one unit, or more than one listing, is refused with
409 property_not_simple; a listing that is not a stay with
409 inventory_not_supported. Nothing is written either way.
Live in a sandbox workspace. Returns 501 against a production one.
curl --fail-with-body -X PATCH https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24 \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Courtyard flat with the blue door", "status": "listed"}'// Partial: an absent field is untouched. Send at least one.
const res = await fetch(
'https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24',
{
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Courtyard flat with the blue door',
status: 'listed',
}),
},
);
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
// A `listed` request the gate refused is still a 200. Read the verdict.
if (!body.publishable) console.log('not published:', body.missing);
import os
import requests
# Partial: an absent field is untouched. Send at least one.
res = requests.patch(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
json={"title": "Courtyard flat with the blue door", "status": "listed"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
# A "listed" request the gate refused is still a 200. Read the verdict.
if not body["publishable"]:
print("not published:", body["missing"])
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type listing struct {
Status string `json:"status"`
Publishable *bool `json:"publishable"`
Missing []string `json:"missing"`
}
func main() {
// Partial: an absent field is untouched. Send at least one.
payload, _ := json.Marshal(map[string]any{
"title": "Courtyard flat with the blue door",
"status": "listed",
})
req, _ := http.NewRequest(http.MethodPatch,
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
log.Fatalf("listing patch failed: %d", res.StatusCode)
}
var body listing
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
// A "listed" request the gate refused is still a 200. Read the verdict.
if body.Publishable == nil || !*body.Publishable {
fmt.Println("not published:", body.Status, body.Missing)
}
}
{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"inventory_kind": "unit",
"title": "Courtyard flat with the blue door",
"description": "A two-bedroom flat one street back from the corniche.",
"status": "listed",
"base_rate": {
"value": "1250.00",
"currency": "EGP"
},
"cleaning_fee": {
"value": "200.00",
"currency": "EGP"
},
"instant_booking": true,
"is_exclusive": false,
"is_best_price": true,
"rating": {
"average": 4.8,
"count": 24
},
"publishable": true,
"missing": [],
"console_url": "https://maatstays.wtf/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7"
}Authorizations
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
Maat's identifier for the listing.
Body
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.
The listing's title, as guests see it.
1 - 120The one member that accepts null: "this listing has no description" is
a real state you must be able to reach.
4000Not 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.
listed, unlisted Whether a guest can book without the host confirming first.
A merchandising badge.
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.
Maat's id for the listing. The id every listing-scoped operation takes.
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.
unit, service, experience The listing's title, as guests see it.
The listing's description, as guests see it. Empty string when the host has written none.
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.
listed, unlisted 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.
Show child attributes
Show child attributes
null when the listing charges none. Never "0.00", which would read as
a price of zero.
Show child attributes
Show child attributes
Whether a guest can book without the host confirming first.
Whether the listing is part of Maat's curated collection. Set by Maat, not by this API.
A marketing badge. Not an amount, despite the name.
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.
Show child attributes
Show child attributes
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.
Reasons publishable is false. Empty otherwise.
See MissingReason.
Why a listing is not publishable. A closed vocabulary.
price, amenities, cover_photo, photos, photos_processing, unlisted The listing's page in the Maat host console.