curl --fail-with-body "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30', {
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 night of body.items) console.log(night.night, night.status, night.blocked_by);
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30",
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 night in body["items"]:
print(night["night"], night["status"], night["blocked_by"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
Items []struct {
Night string `json:"night"`
Status string `json:"status"`
} `json:"items"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30", 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 >= 400 {
log.Fatalf("read failed: %d", res.StatusCode)
}
var body payload
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
fmt.Println(len(body.Items))
}
{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"unit_id": "8e4b2a17-5c39-4d61-b0f2-7a9c3e51d804",
"items": [
{
"night": "2026-09-01",
"status": "blocked",
"blocked_by": "partner",
"external_uid": "my-res-55123"
},
{
"night": "2026-09-02",
"status": "booked",
"blocked_by": null,
"external_uid": null
},
{
"night": "2026-09-03",
"status": "available",
"blocked_by": null,
"external_uid": null
}
]
}Read availability, night by night
Every night in the window, with what is holding it.
status is available, booked, held or blocked. A booking and a hold are
deliberately different: a hold is a checkout in flight and may expire, a booking
will not. blocked_by says who put a block there — host, ical or partner —
and is null on every other status, because a sale is not a block.
external_uid comes back only on blocks you pushed with
PUT /blocks/{external_uid}. A night closed any other way — a host block, or an
imported calendar feed’s event — is reported as blocked with a null uid.
from and to are inclusive nights — unlike a block’s check_out, which is
the exclusive departure day. Send both or neither: sending one is refused rather
than half-defaulted. Omitting both gives you today plus the next 89 nights; the
window may not exceed 366.
Live in a sandbox workspace. Returns 501 against a production one, where no
availability is read and none is disclosed.
curl --fail-with-body "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30', {
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 night of body.items) console.log(night.night, night.status, night.blocked_by);
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30",
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 night in body["items"]:
print(night["night"], night["status"], night["blocked_by"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
Items []struct {
Night string `json:"night"`
Status string `json:"status"`
} `json:"items"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/listings/7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24/calendar?from=2026-09-01&to=2026-09-30", 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 >= 400 {
log.Fatalf("read failed: %d", res.StatusCode)
}
var body payload
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
fmt.Println(len(body.Items))
}
{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"unit_id": "8e4b2a17-5c39-4d61-b0f2-7a9c3e51d804",
"items": [
{
"night": "2026-09-01",
"status": "blocked",
"blocked_by": "partner",
"external_uid": "my-res-55123"
},
{
"night": "2026-09-02",
"status": "booked",
"blocked_by": null,
"external_uid": null
},
{
"night": "2026-09-03",
"status": "available",
"blocked_by": null,
"external_uid": 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 listing.
Query Parameters
First night of the window, inclusive. Send it together with to, or send
neither: one alone is refused rather than half-defaulted.
Last night of the window, inclusive — unlike a block's check_out, which is
the exclusive departure day. At most 366 nights from from.
Response
The window, night by night.
unit_id is the physical inventory availability is keyed on.
The listing these nights belong to.
One row per night in the window you asked for, in date order. Not paged — the window is the bound, so there is no has_more here.
Show child attributes
Show child attributes
The unit these nights are kept on.