cURL

curl -X PUT https://maatstays.wtf/v1/properties/ota-prop-9001 \
  -H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Courtyard flat with the blue door",
    "property_type": "apartment",
    "address": {
      "line1": "14 Example Street",
      "city": "Alexandria",
      "country": "EG",
      "latitude": 31.2001,
      "longitude": 29.9187
    },
    "occupancy": { "max_guests": 4, "bedrooms": 2, "beds": 3, "bathrooms": 1 },
    "base_rate": { "value": "1250.00", "currency": "EGP" },
    "amenities": ["wifi", "air-conditioning"],
    "photos": [
      { "url": "https://images.example-partner.invalid/p/9001/1.jpg", "position": 0 }
    ],
    "status": "listed"
  }'

const property = {
    name: 'Courtyard flat with the blue door',
    property_type: 'apartment',
    address: {
        line1: '14 Example Street',
        city: 'Alexandria',
        country: 'EG',
        latitude: 31.2001,
        longitude: 29.9187,
    },
    occupancy: { max_guests: 4, bedrooms: 2, beds: 3, bathrooms: 1 },
    base_rate: { value: '1250.00', currency: 'EGP' },
    amenities: ['wifi', 'air-conditioning'],
    photos: [
        { url: 'https://images.example-partner.invalid/p/9001/1.jpg', position: 0 },
    ],
    status: 'listed',
};

const res = await fetch(
    'https://maatstays.wtf/v1/properties/ota-prop-9001',
    {
        method: 'PUT',
        headers: {
            Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(property),
    },
);

const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);

// photos_processing clears on its own — wait, do not re-send.
console.log(body.publishable, body.missing);

import os

import requests

property_payload = {
    "name": "Courtyard flat with the blue door",
    "property_type": "apartment",
    "address": {
        "line1": "14 Example Street",
        "city": "Alexandria",
        "country": "EG",
        "latitude": 31.2001,
        "longitude": 29.9187,
    },
    "occupancy": {"max_guests": 4, "bedrooms": 2, "beds": 3, "bathrooms": 1},
    "base_rate": {"value": "1250.00", "currency": "EGP"},
    "amenities": ["wifi", "air-conditioning"],
    "photos": [
        {"url": "https://images.example-partner.invalid/p/9001/1.jpg", "position": 0}
    ],
    "status": "listed",
}

res = requests.put(
    "https://maatstays.wtf/v1/properties/ota-prop-9001",
    headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
    json=property_payload,
    timeout=30,
)

body = res.json()
if res.status_code >= 400:
    raise RuntimeError(f"{body['code']}: {body.get('detail')}")

# photos_processing clears on its own — wait, do not re-send.
print(body["publishable"], body["missing"])

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]any{
        "name":          "Courtyard flat with the blue door",
        "property_type": "apartment",
        "address": map[string]any{
            "line1":     "14 Example Street",
            "city":      "Alexandria",
            "country":   "EG",
            "latitude":  31.2001,
            "longitude": 29.9187,
        },
        "occupancy": map[string]any{
            "max_guests": 4, "bedrooms": 2, "beds": 3, "bathrooms": 1,
        },
        "base_rate": map[string]string{"value": "1250.00", "currency": "EGP"},
        "amenities": []string{"wifi", "air-conditioning"},
        "photos": []map[string]any{
            {"url": "https://images.example-partner.invalid/p/9001/1.jpg", "position": 0},
        },
        "status": "listed",
    })

    req, _ := http.NewRequest(http.MethodPut,
        "https://maatstays.wtf/v1/properties/ota-prop-9001",
        bytes.NewReader(payload))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
    req.Header.Set("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer res.Body.Close()

    var body map[string]any
    if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
        log.Fatal(err)
    }
    if res.StatusCode >= 400 {
        log.Fatalf("%v: %v", body["code"], body["detail"])
    }

    // photos_processing clears on its own — wait, do not re-send.
    fmt.Println(body["publishable"], body["missing"])
}

{
  "provider_id": "ota-prop-9001",
  "result": "updated",
  "listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
  "status": "listed",
  "publishable": true,
  "missing": [],
  "unknown_amenities": [],
  "photos_rejected": []
}

{
  "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/workspace-scope-mismatch",
  "title": "Workspace scope mismatch",
  "status": 403,
  "detail": "This token is not valid for the requested workspace.",
  "instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
  "code": "workspace_scope_mismatch"
}

{
  "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 properties contract is enabled in the sandbox only. This request was authenticated and validated; no property was created or changed. Exchange a sandbox key to exercise the full loop.",
  "instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
  "code": "not_enabled"
}

properties

Create or replace a property

Creates the property if we have not seen this provider_id from you before, and replaces it otherwise. Your provider_id is yours: it is unique within your integration and never across the platform.

Replace, not merge. The payload you send is the whole property. An amenity you omit is removed; a photo you omit is dropped. This mirrors how listings are edited everywhere else on Maat, and it is the only version of “update” in which “remove this amenity” is expressible.

A property that cannot yet be sold — no price, no photos, no amenities — is accepted and held in an incomplete state rather than published at a placeholder price. publishable and missing tell you exactly what it is waiting for, and listing_id stays null until it can actually be shown to a guest.

Photos are fetched asynchronously, so the FIRST push of a complete property comes back publishable: false with photos_processing. That is not a failure and there is nothing to do: we fetch each URL, process it and publish the property on its own. Anything we could not turn into a photo is named in photos_rejected. Sending the same URL again is free — an unchanged URL is never re-fetched, so a nightly catalogue sync costs nothing for the photos that did not change. Change the bytes behind a URL and publish it at a new URL.

Send only the address fields listed here. Delivery detail (building, floor, apartment number, directions) is not part of this contract in either direction.

Enabled in the SANDBOX. A sandbox token creates real properties in your sandbox workspace; they are excluded from every public surface (search, the map, the guest feed) by design. A PRODUCTION token still receives 501 — the payload is authenticated and validated in full first, and nothing is written.

PUT

properties

{provider_id}

cURL

curl -X PUT https://maatstays.wtf/v1/properties/ota-prop-9001 \
  -H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Courtyard flat with the blue door",
    "property_type": "apartment",
    "address": {
      "line1": "14 Example Street",
      "city": "Alexandria",
      "country": "EG",
      "latitude": 31.2001,
      "longitude": 29.9187
    },
    "occupancy": { "max_guests": 4, "bedrooms": 2, "beds": 3, "bathrooms": 1 },
    "base_rate": { "value": "1250.00", "currency": "EGP" },
    "amenities": ["wifi", "air-conditioning"],
    "photos": [
      { "url": "https://images.example-partner.invalid/p/9001/1.jpg", "position": 0 }
    ],
    "status": "listed"
  }'

const property = {
    name: 'Courtyard flat with the blue door',
    property_type: 'apartment',
    address: {
        line1: '14 Example Street',
        city: 'Alexandria',
        country: 'EG',
        latitude: 31.2001,
        longitude: 29.9187,
    },
    occupancy: { max_guests: 4, bedrooms: 2, beds: 3, bathrooms: 1 },
    base_rate: { value: '1250.00', currency: 'EGP' },
    amenities: ['wifi', 'air-conditioning'],
    photos: [
        { url: 'https://images.example-partner.invalid/p/9001/1.jpg', position: 0 },
    ],
    status: 'listed',
};

const res = await fetch(
    'https://maatstays.wtf/v1/properties/ota-prop-9001',
    {
        method: 'PUT',
        headers: {
            Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(property),
    },
);

const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);

// photos_processing clears on its own — wait, do not re-send.
console.log(body.publishable, body.missing);

import os

import requests

property_payload = {
    "name": "Courtyard flat with the blue door",
    "property_type": "apartment",
    "address": {
        "line1": "14 Example Street",
        "city": "Alexandria",
        "country": "EG",
        "latitude": 31.2001,
        "longitude": 29.9187,
    },
    "occupancy": {"max_guests": 4, "bedrooms": 2, "beds": 3, "bathrooms": 1},
    "base_rate": {"value": "1250.00", "currency": "EGP"},
    "amenities": ["wifi", "air-conditioning"],
    "photos": [
        {"url": "https://images.example-partner.invalid/p/9001/1.jpg", "position": 0}
    ],
    "status": "listed",
}

res = requests.put(
    "https://maatstays.wtf/v1/properties/ota-prop-9001",
    headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
    json=property_payload,
    timeout=30,
)

body = res.json()
if res.status_code >= 400:
    raise RuntimeError(f"{body['code']}: {body.get('detail')}")

# photos_processing clears on its own — wait, do not re-send.
print(body["publishable"], body["missing"])

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]any{
        "name":          "Courtyard flat with the blue door",
        "property_type": "apartment",
        "address": map[string]any{
            "line1":     "14 Example Street",
            "city":      "Alexandria",
            "country":   "EG",
            "latitude":  31.2001,
            "longitude": 29.9187,
        },
        "occupancy": map[string]any{
            "max_guests": 4, "bedrooms": 2, "beds": 3, "bathrooms": 1,
        },
        "base_rate": map[string]string{"value": "1250.00", "currency": "EGP"},
        "amenities": []string{"wifi", "air-conditioning"},
        "photos": []map[string]any{
            {"url": "https://images.example-partner.invalid/p/9001/1.jpg", "position": 0},
        },
        "status": "listed",
    })

    req, _ := http.NewRequest(http.MethodPut,
        "https://maatstays.wtf/v1/properties/ota-prop-9001",
        bytes.NewReader(payload))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
    req.Header.Set("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer res.Body.Close()

    var body map[string]any
    if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
        log.Fatal(err)
    }
    if res.StatusCode >= 400 {
        log.Fatalf("%v: %v", body["code"], body["detail"])
    }

    // photos_processing clears on its own — wait, do not re-send.
    fmt.Println(body["publishable"], body["missing"])
}

{
  "provider_id": "ota-prop-9001",
  "result": "updated",
  "listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
  "status": "listed",
  "publishable": true,
  "missing": [],
  "unknown_amenities": [],
  "photos_rejected": []
}

{
  "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/workspace-scope-mismatch",
  "title": "Workspace scope mismatch",
  "status": 403,
  "detail": "This token is not valid for the requested workspace.",
  "instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
  "code": "workspace_scope_mismatch"
}

{
  "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 properties contract is enabled in the sandbox only. This request was authenticated and validated; no property was created or changed. Exchange a sandbox key to exercise the full loop.",
  "instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
  "code": "not_enabled"
}

Authorizations

Authorization

string

header

required

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.

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

provider_id

string

required

Your own identifier for the property. Unique to you — it never collides with another partner's.

Required string length: 1 - 128

Body

application/json

The whole property. Anything you omit is removed — this replaces rather than merges.

name

string

required

Required string length: 1 - 120

property_type

string

required

Maximum string length: 60

Pattern: ^[a-z0-9][a-z0-9_-]*$

Example:

"apartment"

address

Address · object

required

Where the property is. Delivery detail — building, floor, apartment number, directions — is deliberately not part of this contract, in either direction.

Show child attributes

occupancy

Occupancy · object

required

How many people the property sleeps, and in what.

Show child attributes

base_rate

Money · object

required

An amount and its currency, always together.

value is a decimal string, not a number. 1250.10 has no exact IEEE-754 representation, and a JSON parser that rounds it costs a cent on every booking. Parse it with a decimal type, not a float.

There is no bare amount anywhere in this API and no currency field sitting beside one. Two fields can be read separately; one object cannot.

Show child attributes

description

string

Maximum string length: 4000

amenities

string[]

Maximum array length: 60

Maximum string length: 60

Pattern: ^[a-z0-9][a-z0-9_-]*$

photos

Photo · object[]

Maximum array length: 30

Show child attributes

check_in_time

string

Local time, 24-hour.

Pattern: ^([01]\d|2[0-3]):[0-5]\d$

Example:

"15:00"

check_out_time

string

Pattern: ^([01]\d|2[0-3]):[0-5]\d$

Example:

"11:00"

status

enum<string>

Whether you want the property sellable on Maat right now.

Available options:

listed,

unlisted

Response

The property was created or replaced. Sandbox only — a production token receives 501.

provider_id

string

required

result

enum<string>

required

Available options:

created,

updated

listing_id

string<uuid> | null

required

Maat's listing identifier, once the property is complete enough to have one. null while it is not — never a placeholder.

status

enum<string>

required

Available options:

listed,

unlisted

publishable

boolean

required

Whether the property can be shown to guests as it stands.

missing

enum<string>[]

required

Machine-readable reasons publishable is false. Empty when it is true.

photos_processing is not a deficiency — your images are being fetched and processed, and it clears on its own. It is separate from photos precisely so you can tell "wait" from "send us more".

unlisted restates your own status, and it is reported alongside any real deficiency rather than instead of it, so you know whether the property is otherwise complete before you re-list it.

Available options:

price,

amenities,

cover_photo,

photos,

photos_processing,

unlisted

Example:

["cover_photo", "photos_processing"]

unknown_amenities

string[]

required

Amenity slugs we do not recognise, echoed back rather than silently dropped. They are not linked to the property. One unmapped slug does not fail the push — an otherwise-good property should not be blocked while you map your vocabulary onto ours.

Example:

["wi-fi"]

photos_rejected

PhotoRejection · object[]

required

Photo URLs that did not become photos. Empty when every one did.

missing: ["photos"] on its own is not actionable across a thirty-photo push, so each failure names your own URL and a reason. The reason vocabulary is deliberately coarse: a refused URL never says what the name resolved to.

Show child attributes

⌘I

Get started

Guides

Resources

API Reference

Create or replace a property

Authorizations

Path Parameters

Body

Response