curl --fail-with-body "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
if (body.warnings.length) console.warn('partial:', body.warnings);
for (const item of body.items) {
console.log(item.template_key, item.available, item.applied?.value);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
if body["warnings"]:
print("partial:", body["warnings"])
for item in body["items"]:
print(item["template_key"], item["available"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
Items []struct {
TemplateKey string `json:"template_key"`
Family string `json:"family"`
Available bool `json:"available"`
} `json:"items"`
Warnings []string `json:"warnings"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
var problem struct {
Code string `json:"code"`
Detail string `json:"detail"`
}
_ = json.NewDecoder(res.Body).Decode(&problem)
log.Fatalf("%d %s: %s", res.StatusCode, problem.Code, problem.Detail)
}
var body payload
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
fmt.Println(len(body.Items), body.Warnings)
}
{
"items": [
{
"template_key": "booking.min_stay",
"family": "booking",
"category": "stay_length",
"param": {
"kind": "number",
"default": 2,
"min": 1,
"max": 365,
"step": 1
},
"applied": {
"value": 3,
"active": true
},
"available": true,
"unavailable_reason": null
},
{
"template_key": "pricing.cleaning_fee",
"family": "pricing",
"category": "fees",
"param": {
"kind": "currency",
"default": {
"value": "150.00",
"currency": "EGP"
}
},
"applied": null,
"available": true,
"unavailable_reason": null
}
],
"warnings": []
}{
"type": "https://developer.maatstays.wtf/errors/validation-failed",
"title": "Validation failed",
"status": 400,
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "validation_failed",
"errors": [
{
"field": "body.check_out",
"code": "custom"
}
]
}{
"type": "https://developer.maatstays.wtf/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "A valid partner token is required.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "unauthorized"
}{
"type": "https://developer.maatstays.wtf/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This key was not issued with the `pricing:write` scope. Ask whoever issued it to issue a key that carries it.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "insufficient_scope"
}{
"type": "https://developer.maatstays.wtf/errors/listing-not-found",
"title": "Listing not found",
"status": 404,
"detail": "No such listing in this workspace.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "listing_not_found"
}{
"type": "https://developer.maatstays.wtf/errors/inventory-not-supported",
"title": "Inventory kind not supported",
"status": 409,
"detail": "This listing is an experience, and this contract is stays-only. Nothing was read or written.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "inventory_not_supported"
}{
"type": "https://developer.maatstays.wtf/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Too many requests for this API key.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "rate_limited"
}{
"type": "https://developer.maatstays.wtf/errors/internal-error",
"title": "Internal error",
"status": 500,
"detail": "The request could not be completed.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "internal_error"
}{
"type": "https://developer.maatstays.wtf/errors/not-enabled",
"title": "Not implemented",
"status": 501,
"detail": "The calendar-blocks contract is published but not yet enabled. This request was authenticated and validated; no dates were blocked. Keep holding these dates on your own platform.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "not_enabled"
}The quick actions for a listing
Every quick action this listing can carry, with whatever it currently has switched on.
A quick action is a one-tap pricing or booking rule: a switch plus at most one
tunable value. template_key is a closed enum and every member of it is
permanent — a template that is ever withdrawn keeps its identifier and comes back
available: false, unavailable_reason: "retired", because a published identifier
never vanishes.
There is deliberately no label. The names in our own apps are admin copy with
no translation behind them; render your own from the template_key.
param describes the value the action takes: kind, a default, and the bounds
and step where the kind has them. For kind: "currency" the value is a Money
object in the LISTING’s currency, and it is the only currency that action can be
expressed in.
available: false means a PUT would be refused right now, and
unavailable_reason says why:
| Reason | Meaning |
|---|---|
external_pricing | The listing’s price is set by another source, so no rule on it would apply. |
retired | The template was withdrawn. Its identifier stays published; PUT refuses. |
inventory_kind | The action does not apply to this listing’s inventory kind. |
insufficient_scope | Your key lacks pricing:write, so this pricing.* row omits applied. |
warnings is not decoration. The two families come from two services that deploy
independently, so one being unreachable degrades ITS family to nothing and says
so here — a short list with no warning would be indistinguishable from a listing
with nothing switched on.
Scopes. Reading needs rules:write; there is no read-only scope for rules,
because seeing which rules price your listing is part of managing them. The
pricing.* half additionally needs pricing:write — with rules:write alone
you still get all eight catalogue entries, but every pricing.* row comes back
applied: null, available: false, unavailable_reason: "insufficient_scope". The
cleaning fee a host charges and the surcharges they run are commercial facts
about their business, and a key that may not change them is not thereby entitled
to read them.
Live in a sandbox workspace. Returns 501 against a production one, where
nothing is read.
curl --fail-with-body "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
if (body.warnings.length) console.warn('partial:', body.warnings);
for (const item of body.items) {
console.log(item.template_key, item.available, item.applied?.value);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
if body["warnings"]:
print("partial:", body["warnings"])
for item in body["items"]:
print(item["template_key"], item["available"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
Items []struct {
TemplateKey string `json:"template_key"`
Family string `json:"family"`
Available bool `json:"available"`
} `json:"items"`
Warnings []string `json:"warnings"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/quick-actions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
var problem struct {
Code string `json:"code"`
Detail string `json:"detail"`
}
_ = json.NewDecoder(res.Body).Decode(&problem)
log.Fatalf("%d %s: %s", res.StatusCode, problem.Code, problem.Detail)
}
var body payload
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
fmt.Println(len(body.Items), body.Warnings)
}
{
"items": [
{
"template_key": "booking.min_stay",
"family": "booking",
"category": "stay_length",
"param": {
"kind": "number",
"default": 2,
"min": 1,
"max": 365,
"step": 1
},
"applied": {
"value": 3,
"active": true
},
"available": true,
"unavailable_reason": null
},
{
"template_key": "pricing.cleaning_fee",
"family": "pricing",
"category": "fees",
"param": {
"kind": "currency",
"default": {
"value": "150.00",
"currency": "EGP"
}
},
"applied": null,
"available": true,
"unavailable_reason": null
}
],
"warnings": []
}{
"type": "https://developer.maatstays.wtf/errors/validation-failed",
"title": "Validation failed",
"status": 400,
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "validation_failed",
"errors": [
{
"field": "body.check_out",
"code": "custom"
}
]
}{
"type": "https://developer.maatstays.wtf/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "A valid partner token is required.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "unauthorized"
}{
"type": "https://developer.maatstays.wtf/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This key was not issued with the `pricing:write` scope. Ask whoever issued it to issue a key that carries it.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "insufficient_scope"
}{
"type": "https://developer.maatstays.wtf/errors/listing-not-found",
"title": "Listing not found",
"status": 404,
"detail": "No such listing in this workspace.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "listing_not_found"
}{
"type": "https://developer.maatstays.wtf/errors/inventory-not-supported",
"title": "Inventory kind not supported",
"status": 409,
"detail": "This listing is an experience, and this contract is stays-only. Nothing was read or written.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "inventory_not_supported"
}{
"type": "https://developer.maatstays.wtf/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Too many requests for this API key.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "rate_limited"
}{
"type": "https://developer.maatstays.wtf/errors/internal-error",
"title": "Internal error",
"status": 500,
"detail": "The request could not be completed.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "internal_error"
}{
"type": "https://developer.maatstays.wtf/errors/not-enabled",
"title": "Not implemented",
"status": 501,
"detail": "The calendar-blocks contract is published but not yet enabled. This request was authenticated and validated; no dates were blocked. Keep holding these dates on your own platform.",
"instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
"code": "not_enabled"
}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.
Response
The quick actions, both families in one list.
Every quick action the platform publishes, each with whether it is applied to this listing.
Show child attributes
Show child attributes
Families this read could not reach. Their actions are absent from items
entirely — NOT reported as retired, which would turn a five-minute deploy
into a permanent-looking withdrawal.
See QuickActionWarning.
Why part of a quick-action list is missing. Both are retryable — the actions of that
family are absent from items entirely rather than reported as retired, which would turn
a short outage into a permanent-looking withdrawal.
booking_unavailable, pricing_unavailable []