curl --fail-with-body -X PUT https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos/order \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"photo_ids": ["0f2b9c81-4a7e-4d33-9b10-2c7e5a6f1d94", "9a4e77b0-1c2d-4e5f-8a91-3b6c0d7e2f45"]}'// Read first: the list has to be COMPLETE, so build it from what we hold.
const listed = await fetch(
'https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos',
{ headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` } },
).then((r) => r.json());
const ready = listed.items.filter((p) => p.state === 'ready').map((p) => p.photo_id);
const [promote, ...rest] = ready.reverse();
const res = await fetch(
'https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos/order',
{
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ photo_ids: [promote, ...rest] }),
},
);
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
console.log(body.items[0].photo_id, body.items[0].is_cover);
import os
import requests
base = "https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos"
auth = {"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"}
# Read first: the list has to be COMPLETE, so build it from what we hold.
listed = requests.get(base, headers=auth, timeout=30).json()
ready = [p["photo_id"] for p in listed["items"] if p["state"] == "ready"]
ordered = list(reversed(ready))
res = requests.put(
f"{base}/order", headers=auth, json={"photo_ids": ordered}, timeout=30
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
print(body["items"][0]["photo_id"], body["items"][0]["is_cover"])
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
const base = "https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos"
type photo struct {
PhotoID string `json:"photo_id"`
IsCover bool `json:"is_cover"`
State string `json:"state"`
}
type strip struct {
Items []photo `json:"items"`
}
func send(method, url string, payload []byte) strip {
req, _ := http.NewRequest(method, url, bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
if payload != nil {
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("%s %s failed: %d", method, url, res.StatusCode)
}
var body strip
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
return body
}
func main() {
// Read first: the list has to be COMPLETE, so build it from what we hold.
listed := send(http.MethodGet, base, nil)
ready := []string{}
for _, p := range listed.Items {
if p.State == "ready" {
ready = append(ready, p.PhotoID)
}
}
for i, j := 0, len(ready)-1; i < j; i, j = i+1, j-1 {
ready[i], ready[j] = ready[j], ready[i]
}
payload, _ := json.Marshal(map[string]any{"photo_ids": ready})
ordered := send(http.MethodPut, base+"/order", payload)
fmt.Println(ordered.Items[0].PhotoID, ordered.Items[0].IsCover)
}
{
"items": [
{
"photo_id": "0f2b9c81-4a7e-4d33-9b10-2c7e5a6f1d94",
"position": 0,
"is_cover": true,
"state": "ready",
"rejection_reason": null,
"url": "https://cdn.maatstays.wtf/c/0f2b9c81.webp"
},
{
"photo_id": "5d3a7e12-9b48-4c05-8f61-2a7d0e4b93c6",
"position": 1,
"is_cover": false,
"state": "pending",
"rejection_reason": null,
"url": null
}
]
}Arrange a property's photos
Put the property’s photos in the order guests should see them. Index 0 becomes the cover, everywhere it is shown.
Send the COMPLETE set of ready photos, each exactly once. A partial list is
refused rather than half-applied: the positions of everything you did not
mention would otherwise have to be invented by us. Omitting one, repeating one,
or naming one that is not ready are all refusals that write nothing, and each
names what was wrong.
Photos that are not ready are not orderable — they have no image yet, or they
have one nobody may see. They keep their places after the ordered ones and join
the sequence when they settle.
Answers with the whole strip as GET …/photos publishes it.
Reordering does not change whether the property is on sale, in either
direction. Publication is PATCH /v1/listings/{listing_id} with
status: "listed".
A property you create with PUT /properties/{provider_id} is refused with
409 conflict — your next push would undo the change. Send its photo URLs on the
push instead.
Live in a sandbox workspace. Returns 501 against a production one.
curl --fail-with-body -X PUT https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos/order \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"photo_ids": ["0f2b9c81-4a7e-4d33-9b10-2c7e5a6f1d94", "9a4e77b0-1c2d-4e5f-8a91-3b6c0d7e2f45"]}'// Read first: the list has to be COMPLETE, so build it from what we hold.
const listed = await fetch(
'https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos',
{ headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` } },
).then((r) => r.json());
const ready = listed.items.filter((p) => p.state === 'ready').map((p) => p.photo_id);
const [promote, ...rest] = ready.reverse();
const res = await fetch(
'https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos/order',
{
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ photo_ids: [promote, ...rest] }),
},
);
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
console.log(body.items[0].photo_id, body.items[0].is_cover);
import os
import requests
base = "https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos"
auth = {"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"}
# Read first: the list has to be COMPLETE, so build it from what we hold.
listed = requests.get(base, headers=auth, timeout=30).json()
ready = [p["photo_id"] for p in listed["items"] if p["state"] == "ready"]
ordered = list(reversed(ready))
res = requests.put(
f"{base}/order", headers=auth, json={"photo_ids": ordered}, timeout=30
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
print(body["items"][0]["photo_id"], body["items"][0]["is_cover"])
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
const base = "https://maatstays.wtf/v1/properties/3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7/photos"
type photo struct {
PhotoID string `json:"photo_id"`
IsCover bool `json:"is_cover"`
State string `json:"state"`
}
type strip struct {
Items []photo `json:"items"`
}
func send(method, url string, payload []byte) strip {
req, _ := http.NewRequest(method, url, bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
if payload != nil {
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("%s %s failed: %d", method, url, res.StatusCode)
}
var body strip
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
return body
}
func main() {
// Read first: the list has to be COMPLETE, so build it from what we hold.
listed := send(http.MethodGet, base, nil)
ready := []string{}
for _, p := range listed.Items {
if p.State == "ready" {
ready = append(ready, p.PhotoID)
}
}
for i, j := 0, len(ready)-1; i < j; i, j = i+1, j-1 {
ready[i], ready[j] = ready[j], ready[i]
}
payload, _ := json.Marshal(map[string]any{"photo_ids": ready})
ordered := send(http.MethodPut, base+"/order", payload)
fmt.Println(ordered.Items[0].PhotoID, ordered.Items[0].IsCover)
}
{
"items": [
{
"photo_id": "0f2b9c81-4a7e-4d33-9b10-2c7e5a6f1d94",
"position": 0,
"is_cover": true,
"state": "ready",
"rejection_reason": null,
"url": "https://cdn.maatstays.wtf/c/0f2b9c81.webp"
},
{
"photo_id": "5d3a7e12-9b48-4c05-8f61-2a7d0e4b93c6",
"position": 1,
"is_cover": false,
"state": "pending",
"rejection_reason": null,
"url": null
}
]
}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 property, as returned by GET /properties. Not your
own provider_id — the write endpoint is the one keyed on that, which is why
this read carries a by-id segment.
Body
The COMPLETE set of ready photos, in the order they should be shown. Index 0
becomes the cover.
Every photo on the property, in the order you want them shown. The first is the cover.
1 - 30 elementsResponse
The property's photos in their new order.
Every photo on the property, in display order, whatever state it is in.
Show child attributes
Show child attributes