curl --fail-with-body "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const rule of body.items) console.log(rule.family, rule.title, rule.source);
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules",
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')}")
for rule in body["items"]:
print(rule["family"], rule["title"], rule["source"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
Items []struct {
Family string `json:"family"`
Title string `json:"title"`
Source string `json:"source"`
} `json:"items"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules", 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))
}
{
"items": [
{
"id": "a41c9d70-6b28-4e33-95af-1c0d8e2f4b76",
"family": "booking",
"title": "Minimum stay",
"active": true,
"source": "quick_action",
"template_key": "booking.min_stay"
},
{
"id": "e0782b95-4d16-4a7c-b3e8-9f5c1a604d23",
"family": "pricing",
"title": "Cleaning fee",
"active": true,
"source": "authored",
"template_key": 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"
}Every rule attached to a listing
Read-only. The answer to “why is my price what it is”: every pricing and booking rule attached to this listing, whether it came from a quick action or was drawn by hand in the Maat app’s rule builder.
source tells you which. A quick_action rule names the template_key it came
from and can be changed through the quick-action endpoints; an authored one
cannot be changed here at all.
Rule authoring is not on this API, and there is no write here of any kind. No create, no link, no unlink, no pausing. A rule’s logic is a node graph drawn on a canvas, and publishing that graph would freeze an internal shape as a contract on the day it shipped — so this list carries the rule’s identity and its state, and nothing about what it does.
warnings follows the same rule as the quick-action list: a family whose service
is unreachable is reported, not silently omitted.
The pricing half needs pricing:write. Without it the pricing rules are
absent from items and warnings carries pricing_withheld — not
pricing_unavailable, which would send you into a retry loop against a refusal
no retry can change. A rule’s title is written by the host, and with active
it says what this workspace charges and when; a key that may not change pricing
is not thereby entitled to read it. The booking rules are unaffected.
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/rules" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const rule of body.items) console.log(rule.family, rule.title, rule.source);
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules",
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')}")
for rule in body["items"]:
print(rule["family"], rule["title"], rule["source"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
Items []struct {
Family string `json:"family"`
Title string `json:"title"`
Source string `json:"source"`
} `json:"items"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/rules", 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))
}
{
"items": [
{
"id": "a41c9d70-6b28-4e33-95af-1c0d8e2f4b76",
"family": "booking",
"title": "Minimum stay",
"active": true,
"source": "quick_action",
"template_key": "booking.min_stay"
},
{
"id": "e0782b95-4d16-4a7c-b3e8-9f5c1a604d23",
"family": "pricing",
"title": "Cleaning fee",
"active": true,
"source": "authored",
"template_key": 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 rules attached to this listing.
Every active rule attached to the listing, from either source.
Show child attributes
Show child attributes
Why part of this answer is missing. Two different causes, and they are deliberately not spelled the same:
booking_unavailable / pricing_unavailable — that service could not be
reached. Its rules are absent from items. Retryable.
pricing_withheld — your key does not carry pricing:write, so the
pricing rules are absent. A rule's title is written by the host and,
with active, says what this workspace charges and when; rules:write
alone does not grant it. Never retry this — ask whoever issued the
key for one that carries the scope.
See ListingRuleWarning.
Why part of a rules answer is missing.
A superset of QuickActionWarning, and deliberately not spelled the same: two of these
are outages worth retrying and one never is.
booking_unavailable, pricing_unavailable, pricing_withheld []