curl --fail-with-body "https://maatstays.wtf/v1/bookings?status=confirmed&check_in_from=2026-09-01&page_size=100" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const headers = { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` };
for (let page = 1; ; page += 1) {
const url = new URL('https://maatstays.wtf/v1/bookings');
url.searchParams.set('status', 'confirmed');
url.searchParams.set('check_in_from', '2026-09-01');
url.searchParams.set('page', String(page));
url.searchParams.set('page_size', '100');
const res = await fetch(url, { headers });
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const booking of body.items) {
console.log(booking.booking_reference, booking.stay.check_in, booking.status);
}
if (!body.has_more) break;
}
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"}
page = 1
while True:
res = requests.get(
"https://maatstays.wtf/v1/bookings",
headers=headers,
params={
"status": "confirmed",
"check_in_from": "2026-09-01",
"page": page,
"page_size": 100,
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for booking in body["items"]:
print(booking["booking_reference"], booking["stay"]["check_in"], booking["status"])
if not body["has_more"]:
break
page += 1
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
"strconv"
)
type stay struct {
CheckIn string `json:"check_in"`
}
type booking struct {
BookingReference string `json:"booking_reference"`
Status string `json:"status"`
Stay stay `json:"stay"`
}
type page struct {
Items []booking `json:"items"`
HasMore bool `json:"has_more"`
}
func main() {
token := os.Getenv("MAAT_PARTNER_TOKEN")
for pageNum := 1; ; pageNum++ {
query := url.Values{}
query.Set("status", "confirmed")
query.Set("check_in_from", "2026-09-01")
query.Set("page", strconv.Itoa(pageNum))
query.Set("page_size", "100")
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/bookings?"+query.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+token)
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
var body page
err = json.NewDecoder(res.Body).Decode(&body)
res.Body.Close()
if err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("list failed: %d", res.StatusCode)
}
for _, b := range body.Items {
fmt.Println(b.BookingReference, b.Stay.CheckIn, b.Status)
}
if !body.HasMore {
break
}
}
}
{
"items": [
{
"booking_reference": "5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d",
"property": {
"provider_id": "my-prop-9001",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"unit_id": "8e4b2a17-5c39-4d61-b0f2-7a9c3e51d804",
"property_id": "3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7"
},
"inventory_kind": "unit",
"status": "confirmed",
"stay": {
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"check_in_time": "15:00",
"check_out_time": "12:00",
"guests": 3
},
"amount_paid": {
"value": "5000.00",
"currency": "EGP"
},
"instant_booking": true,
"cancellation": null,
"created_at": "2026-08-30T18:42:11.000Z",
"console_url": "https://maatstays.wtf/bookings/5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d"
}
],
"has_more": false
}List bookings on your inventory
One page of what is happening on your inventory, newest first.
There is NO guest identity anywhere in this response — not a name, not an
initial, not an email, not a reference you could join against another read. Every
field is a fact about a STAY. console_url on each booking is the honest pointer
to where a person IS seen: the host console, where an authenticated human sees who
is arriving. That is deliberately slower than a field on this wire, and it is the
point — an integration that wants an arrivals board builds one out of the
platform’s own access control, not out of a JSON key.
Filter with status, listing_id, check_in_from and check_in_to; page with
page and page_size, and keep asking while has_more is true. There is no
total. The two date bounds are inclusive, and an inverted range
(check_in_from after check_in_to) is refused rather than answered with an
empty page.
There is no cancellation over this API, on this operation or any other. Cancelling a confirmed stay creates refunds and penalties and belongs to a person in the app.
A 403 on this operation carries one of two codes — insufficient_scope (the
key lacks bookings:read) or workspace_scope_mismatch (a sandbox/production
mismatch). Branch on code.
Live in a sandbox workspace. Returns 501 against a production one.
curl --fail-with-body "https://maatstays.wtf/v1/bookings?status=confirmed&check_in_from=2026-09-01&page_size=100" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const headers = { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` };
for (let page = 1; ; page += 1) {
const url = new URL('https://maatstays.wtf/v1/bookings');
url.searchParams.set('status', 'confirmed');
url.searchParams.set('check_in_from', '2026-09-01');
url.searchParams.set('page', String(page));
url.searchParams.set('page_size', '100');
const res = await fetch(url, { headers });
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const booking of body.items) {
console.log(booking.booking_reference, booking.stay.check_in, booking.status);
}
if (!body.has_more) break;
}
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"}
page = 1
while True:
res = requests.get(
"https://maatstays.wtf/v1/bookings",
headers=headers,
params={
"status": "confirmed",
"check_in_from": "2026-09-01",
"page": page,
"page_size": 100,
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for booking in body["items"]:
print(booking["booking_reference"], booking["stay"]["check_in"], booking["status"])
if not body["has_more"]:
break
page += 1
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
"strconv"
)
type stay struct {
CheckIn string `json:"check_in"`
}
type booking struct {
BookingReference string `json:"booking_reference"`
Status string `json:"status"`
Stay stay `json:"stay"`
}
type page struct {
Items []booking `json:"items"`
HasMore bool `json:"has_more"`
}
func main() {
token := os.Getenv("MAAT_PARTNER_TOKEN")
for pageNum := 1; ; pageNum++ {
query := url.Values{}
query.Set("status", "confirmed")
query.Set("check_in_from", "2026-09-01")
query.Set("page", strconv.Itoa(pageNum))
query.Set("page_size", "100")
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/bookings?"+query.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+token)
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
var body page
err = json.NewDecoder(res.Body).Decode(&body)
res.Body.Close()
if err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("list failed: %d", res.StatusCode)
}
for _, b := range body.Items {
fmt.Println(b.BookingReference, b.Stay.CheckIn, b.Status)
}
if !body.HasMore {
break
}
}
}
{
"items": [
{
"booking_reference": "5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d",
"property": {
"provider_id": "my-prop-9001",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"unit_id": "8e4b2a17-5c39-4d61-b0f2-7a9c3e51d804",
"property_id": "3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7"
},
"inventory_kind": "unit",
"status": "confirmed",
"stay": {
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"check_in_time": "15:00",
"check_out_time": "12:00",
"guests": 3
},
"amount_paid": {
"value": "5000.00",
"currency": "EGP"
},
"instant_booking": true,
"cancellation": null,
"created_at": "2026-08-30T18:42:11.000Z",
"console_url": "https://maatstays.wtf/bookings/5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d"
}
],
"has_more": false
}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.
Query Parameters
1-based page number. Defaults to the first page.
x >= 1Rows per page. The same default and the same ceiling on every list in this API.
A page_size above the maximum is refused with validation_failed naming
the parameter — never silently clamped, because a caller who believes they asked
for 500 and received 200 will stop walking a set they have not finished.
1 <= x <= 200Only bookings in this status.
See BookingStatus.
Where a booking is in its life. A closed vocabulary; pending is the only status
confirm and reject accept.
pending, confirmed, checked_in, completed, cancelled, rejected Only bookings on this listing.
Only bookings whose check_in is on or after this date. Inclusive. Sending a check_in_from that is after check_in_to is refused with 400 validation_failed rather than answered with an empty page.
Only bookings whose check_in is on or before this date. Inclusive.
Response
One page of your bookings.
One page of bookings on your inventory, newest first.
Show child attributes
Show child attributes
Whether another page exists. There is no total: counting the whole set to answer one page is work neither of us needs.
Pages are numbered, and the list is newest first, so a row that lands while you are walking shifts the ones behind it. A long walk can therefore see a row twice or miss one. Key what you collect by its own id and treat the walk as eventually complete rather than exact, or narrow with the filters this operation offers so the set you are paging cannot move.