{
  "openapi": "3.1.0",
  "info": {
    "title": "api.villas",
    "version": "0.1.0",
    "description": "Lodging & Accommodation (NAICS 721, villa/short-stay sub-niche) substrate: the Booking record (schema.org Offer/Reservation), villa/short-stay Property inventory, night-audit reports, and guest folios — data face and headless Booking/PMS face from one definition, anonymous sandbox as the universal floor. Wave-zero surface; every sandbox record is labeled example data."
  },
  "servers": [
    {
      "url": "https://api.villas"
    }
  ],
  "paths": {
    "/bookings": {
      "get": {
        "operationId": "listBookings",
        "summary": "Bookings — the branching Booking collection (the row's schema.org Offer/Reservation record position): typed OK | EMPTY | BLOCKED | OFFER on one pathname",
        "description": "The keyless, branching collection (AXP Clauses 4 + 7): plain GET answers 200 OK with substantive typed content to an anonymous caller; a non-matching filter answers 200 EMPTY; a reserved scope answers 403 BLOCKED. Collection member name: \"bookings\".",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "filter the collection by status; a non-matching value answers a typed 200 EMPTY, never a fake success"
          },
          {
            "name": "property",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "filter the collection by property; a non-matching value answers a typed 200 EMPTY, never a fake success"
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "reserved scopes (admin, internal) answer a typed 403 BLOCKED"
          },
          {
            "name": "spend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "requested spend in the same unit as hardCeiling (25); above the ceiling answers a typed 402 OFFER re-authorization boundary"
          }
        ],
        "responses": {
          "200": {
            "description": "OK or EMPTY envelope",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/OkEnvelope"
                    },
                    {
                      "$ref": "#/components/schemas/EmptyEnvelope"
                    }
                  ]
                }
              }
            }
          },
          "402": {
            "description": "OFFER envelope — the hard-ceiling re-authorization boundary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfferEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "BLOCKED envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockedEnvelope"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createBooking",
        "summary": "createBooking — headless Booking/PMS door: capture a booking in the ephemeral anonymous sandbox workspace (isolate-lifetime retention, disclosed on every response; no real stay is reserved)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "property",
                  "guestName",
                  "checkIn",
                  "nights"
                ],
                "properties": {
                  "property": {
                    "type": "string",
                    "description": "a Property id, e.g. PRP-952-0001"
                  },
                  "guestName": {
                    "type": "string"
                  },
                  "checkIn": {
                    "type": "string",
                    "description": "ISO date"
                  },
                  "nights": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK envelope with the created (ephemeral, labeled) booking"
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "The Pricing Document (AXP Appendix A.2)",
        "description": "This API is metered with a hard ceiling of 25 (usd-per-month); the caller can never be metered past it without explicit re-authorization. This price is NOT bound by published terms: it is a stated intent, and the document says so in its `binding` and `statement` members. Budget against it; do not contract on it.",
        "responses": {
          "200": {
            "description": "the Pricing Document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingDocument"
                }
              }
            }
          }
        }
      }
    },
    "/offer": {
      "get": {
        "operationId": "getOffer",
        "summary": "The offer boundary (AXP Appendix A.5)",
        "description": "Always answers 402 with a typed OFFER body — the machine-readable start of the paid conversation.",
        "responses": {
          "402": {
            "description": "OFFER envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfferEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/bookings/{id}": {
      "get": {
        "operationId": "getBooking",
        "summary": "getBooking — one Booking record by id (data face read; same row the headless face operates on; seed ids look like BKG-952-0001)",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "id",
            "description": "the record id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK envelope with the record (references resolved as links)"
          },
          "404": {
            "description": "EMPTY envelope — no such record"
          }
        }
      }
    },
    "/properties": {
      "get": {
        "operationId": "listProperties",
        "summary": "listProperties — the villa/short-stay inventory grain (labeled demo units; native binding — first-party inventory, never scraped rate data), filterable by type",
        "parameters": [
          {
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "name": "type",
            "description": "filter by type; a non-matching value answers a typed 200 EMPTY"
          }
        ],
        "responses": {
          "200": {
            "description": "OK or EMPTY envelope"
          }
        }
      }
    },
    "/properties/{id}": {
      "get": {
        "operationId": "getProperty",
        "summary": "getProperty — one Property record by id (seed ids look like PRP-952-0001)",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "id",
            "description": "the record id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK envelope with the record"
          },
          "404": {
            "description": "EMPTY envelope — no such record"
          }
        }
      }
    },
    "/night-audit-reports": {
      "get": {
        "operationId": "listNightAuditReports",
        "summary": "listNightAuditReports — the typed operational artifact (generated binding: derived from the booking/folio corpus; the sector's wedge document), filterable by business date",
        "parameters": [
          {
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "name": "businessDate",
            "description": "filter by businessDate; a non-matching value answers a typed 200 EMPTY"
          }
        ],
        "responses": {
          "200": {
            "description": "OK or EMPTY envelope"
          }
        }
      },
      "post": {
        "operationId": "runNightAudit",
        "summary": "runNightAudit — headless PMS door: run the night audit over the caller's ephemeral workspace bookings for a business date and mint the report (the process the PMS ply automates)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "businessDate"
                ],
                "properties": {
                  "businessDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK envelope with the minted (ephemeral, labeled) night-audit report"
          }
        }
      }
    },
    "/night-audit-reports/{id}": {
      "get": {
        "operationId": "getNightAuditReport",
        "summary": "getNightAuditReport — one NightAuditReport by id (seed ids look like NAR-952-0001)",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "id",
            "description": "the record id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK envelope with the record"
          },
          "404": {
            "description": "EMPTY envelope — no such record"
          }
        }
      }
    },
    "/folios": {
      "get": {
        "operationId": "listFolios",
        "summary": "listFolios — guest folio / guest-ledger records ([UNVERIFIED — inferred] data-ply item, flag carried from the row), filterable by booking",
        "parameters": [
          {
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "name": "booking",
            "description": "filter by booking; a non-matching value answers a typed 200 EMPTY"
          }
        ],
        "responses": {
          "200": {
            "description": "OK or EMPTY envelope"
          }
        }
      }
    },
    "/bookings/{bookingId}/cancel": {
      "post": {
        "operationId": "cancelBooking",
        "summary": "cancelBooking — headless verb on the same collection: cancel a workspace booking (seed-tenant records are read-only and answer BLOCKED)",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "bookingId",
            "description": "the Booking id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK envelope with the cancelled booking"
          },
          "403": {
            "description": "BLOCKED envelope — the seed tenant is read-only"
          }
        }
      }
    },
    "/icp.json": {
      "get": {
        "operationId": "getIcp",
        "summary": "G2 coordinates: ICP (CompanyType × JobTypes), personas, and the System coordinate this substrate serves",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/substrate.json": {
      "get": {
        "operationId": "getSubstrate",
        "summary": "the G3 APIProduct instance: Nouns with schema + binding + verbs, the BookingPMS System coordinate, operations, sandbox spec, meters",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/verify": {
      "get": {
        "operationId": "getVerify",
        "summary": "the published public-contract test page — every claim on this surface as a runnable probe, not an adjective",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/projection.json": {
      "get": {
        "operationId": "getProjection",
        "summary": "this projection's G4 coordinates (hostname, substrate, brand, account/payments pointers)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OkEnvelope": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "const": "OK"
          }
        },
        "description": "200 — substantive content. The collection member name (results/items/events…) is this API's own choice, documented on the operation."
      },
      "EmptyEnvelope": {
        "type": "object",
        "required": [
          "type",
          "message"
        ],
        "properties": {
          "type": {
            "const": "EMPTY"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "200 — a truthful empty collection, never a bare [] masquerading as data."
      },
      "BlockedEnvelope": {
        "type": "object",
        "required": [
          "type",
          "reason"
        ],
        "properties": {
          "type": {
            "const": "BLOCKED"
          },
          "reason": {
            "type": "string"
          }
        },
        "description": "401/403 — a permission boundary with a worded reason."
      },
      "OfferEnvelope": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "const": "OFFER"
          },
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "price": {},
          "checkoutUrl": {
            "type": "string"
          },
          "alternatives": {
            "type": "array"
          }
        },
        "description": "402 — a payment or ceiling re-authorization boundary; an offer to proceed, never a refusal."
      },
      "PricingDocument": {
        "type": "object",
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "enum": [
              "free",
              "metered"
            ]
          },
          "hardCeiling": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "unit": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "rates": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "operation"
              ],
              "properties": {
                "operation": {
                  "type": "string",
                  "description": "The canonical camelCase-verb operationId this rate keys on (axp-ext/rates-g2 §1) — the ONE cross-face operation name: OpenAPI operationId = MCP tool name = suite coverage reference = SDK method name = this key."
                },
                "price": {
                  "description": "Scalar amount >= 0, or a §2 price object: compound {fixed?, percent?, basis, cap?, floor?, min_fee?} (A1, ad-valorem), {passthrough: {provider, reference?, markup?}} (A2, third-party-owned price plus markup), or {discovery: 'market', reference?, buyer_cap?} (A2, auction/spot). Absent or null ONLY under a non-published `disclosure` (A8).",
                  "oneOf": [
                    {
                      "type": "number",
                      "minimum": 0
                    },
                    {
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "unit": {
                  "type": "string"
                },
                "included": {
                  "description": "A5 — the allowance: quantity, \"unlimited\", or {qty, period: \"day\"|\"month\"|\"once\", rollover?, at_limit?}. `freeQuota` is the legacy shorthand for {qty, period: \"month\"} — never both."
                },
                "freeQuota": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "modifiers": {
                  "type": "array",
                  "description": "A3 — relative/derived pricing: [{op: 'multiply'|'add', value, scope?: 'rate'|'offer'|'card', condition?: {attribute, op?, value?}, stacking_order?}]. See also `derived_from`."
                },
                "derived_from": {
                  "type": "string",
                  "description": "A3 — the rate-card row this row's price derives from (an operationId on this same card)."
                },
                "meter": {
                  "type": "object",
                  "description": "G3 lite — {aggregation: 'sum'|'distinct'|'high-watermark'|'gauge'|'peak', basis?: 'consumed'|'provisioned'|'standing', reset_period?, definition_url?}: how the billable unit aggregates, so identical-looking rows cannot mean bills 10x apart."
                },
                "volume_breaks": {
                  "type": "object",
                  "description": "A7 — {mode: 'graduated'|'retroactive'|'reprice-offer' (REQUIRED), basis?: 'units'|'spend'|'instantaneous-rate', breaks: [{from, price|discount_percent}], formula_url?, approximate?}."
                },
                "disclosure": {
                  "enum": [
                    "published",
                    "calculator-only",
                    "quote-only",
                    "undisclosed"
                  ],
                  "description": "A8 — a meter may exist with its price withheld; 'priced on request' is distinguishable from 'no such meter'. Price may be absent/null only when this is present and not 'published'."
                },
                "estimate": {
                  "type": "object",
                  "description": "A8 — {low, high, provenance?}: third-party estimate, legal only under a withheld disclosure."
                },
                "note": {
                  "type": "string"
                }
              }
            },
            "description": "axp-ext/rates-g2 §2 — the operationId-keyed operation rate card, TOP-LEVEL in the Pricing Document. Additive and descriptive: `model` and `hardCeiling` keep answering Appendix A.2; every row names an operation this origin's own contract declares. Offer-level A4/A5 members (spend_cap, pooled allowances[]) ride monetization.offers. Deferred-amendment names (credits, base_fee, minimum, relations, entitlements, keys, payment, direction, recurrence, effective, eligibility, currencies) are RESERVED."
          },
          "binding": {
            "type": "boolean",
            "description": "Whether published terms bind this price. `model` answers what it costs; `binding` answers whether you can hold us to it. Absent means not declared — never assume bound."
          },
          "statement": {
            "type": "string",
            "description": "Present when binding is false: the stated intent, in the same words the human pages use."
          },
          "termsUrl": {
            "type": "string",
            "description": "Present when binding is true: the terms document that binds this price."
          },
          "ledgerUrl": {
            "type": "string",
            "description": "Where the open item to bind this price is tracked."
          }
        },
        "description": "AXP Appendix A.2 — closed model \"free\" | \"metered\"; hardCeiling required and > 0 when metered. `binding` is a descriptive member on an axis orthogonal to `model`: binding: true carries termsUrl, binding: false carries statement."
      }
    }
  }
}