{"openapi":"3.1.0","info":{"title":"Keyset Booking API","version":"2026-10-11","description":"## Server authentication\n\nUse Authorization: Bearer sk_test_ks1_… (or sk_live_ks1_… in production) on every /v1 operation. Keys are issued once in the operator SaaS under\nSettings → Developers. They authenticate a service principal with canonical Property permissions. A missing,\nexpired, revoked or wrong-environment key returns 401. A missing operation permission returns 403 only after Property\nread access is established; unknown or ungranted resources return the same 404. Never put secret keys in a browser.\nStaging/local databases are test; production is a separate live deployment. There is no per-Tenant test sandbox\ninside the live database. Publishable keys are not needed for the anonymous booking operations.\n\nRotate with up to 24 hours overlap, deploy the successor on your server, then revoke the predecessor. Listing never\nreveals either secret. A lost creation/rotation response cannot be recovered: inspect the credential list and revoke\nthe inaccessible credential. No webhook signing secret is an API credential.\n\nThe Keyset direct-booking API: the surface a third-party accommodation website uses to search\navailability, take an authoritative price and book a stay.\n\n## What this API guarantees, and what it deliberately does not\n\n- **Availability is advisory.** `searchAvailability` and `readAvailabilityCalendar` read a moving world and\n  reserve nothing. Only `startCheckout` competes for inventory.\n- **A quote is immutable and expires.** Later rate changes never alter an existing quote; they produce a new one.\n- **A redirect confirms nothing.** `readCheckoutStatus` is the only authority on whether a stay is booked.\n- **An unknown outcome is not a failure.** If a mutation's answer is lost, repeat the identical request with the\n  identical `Idempotency-Key`, or read the authoritative state. A fresh key is a new intent and can book twice.\n- **Payment, reservation and checkout are separate state dimensions.** Never collapse them into one status.\n\n## Wire formats\n\n| Concept | Representation | Example |\n|---|---|---|\n| Money | integer minor units as a decimal string, plus currency. Never a float. | `{ \"minorUnits\": \"24500\", \"currency\": \"EUR\" }` |\n| Calendar day | `YYYY-MM-DD` in the property's own timezone | `\"2027-02-01\"` |\n| Stay | half-open interval `[checkIn, checkOut)`; the departure day is not a booked night | `2027-02-01 → 2027-02-03` is 2 nights |\n| Instant | RFC 3339 UTC, no offset suffix | `\"2026-12-01T09:15:00.000Z\"` |\n| Reference | 22 to 64 characters of `A-Z a-z 0-9 _ -` | `\"public_checkout_7Js9Qm2Vx4ZaR3tB\"` |\n\n## Errors\n\nEvery failure is an RFC 9457 problem document at `application/problem+json` with a stable `code`, a\n`retryable` flag and, where the API asks for a specific delay, `retryAfter` in seconds. Branch on `code`,\nnever on `title`. The full catalogue and the safe recovery for each code are documented in the SDK guide.\nA code can be added without a new contract version: treat a code you do not know by its `status` and\n`retryable`.\n\n## Authentication\n\nThe booking surface carries no API key. A published property identifier is scoped to exactly one property, is safe\nto place in a website bundle and is never treated as a secret. A checkout is instead bound to the `HttpOnly`\ncapability cookie that `startCheckout` issues: that cookie, not the reference, authorizes reading it.\n\n## Rate limits\n\nRequests are budgeted per source and per property; the checkout budget is deliberately the tightest. An exhausted\nbudget answers `429 TOO_MANY_REQUESTS` with `retryAfter`. The per-operation budgets are stated on each\noperation.\n\n## Idempotency\n\n`createQuote` and `startCheckout` require an `Idempotency-Key` header. One key means one intent: persist it\nbefore the first attempt, reuse it for every retry of that intent, and never reuse it for a different body — that\nanswers `409 IDEMPOTENCY_KEY_REUSED`.\n\nOn `/v1`, `createDeveloperReservation` requires an `Idempotency-Key` and `cancelDeveloperReservation`\naccepts one. For 24 hours a cancellation repeated with its key answers what the first request answered; while the\nfirst request still runs the key answers `409 IDEMPOTENCY_IN_PROGRESS` (retryable), and when its outcome is unknown\n`409 IDEMPOTENCY_OUTCOME_UNKNOWN`: read the booking, never repeat with a new key.","contact":{"name":"Keyset developer support","url":"https://keyset.dev"}},"servers":[{"url":"https://api.keyset.cloud","description":"Production."},{"url":"https://api-staging.keyset.cloud","description":"Staging. Synthetic data only."}],"externalDocs":{"url":"https://keyset.dev","description":"Quickstart, SDK guide, concepts, errors and recovery."},"tags":[{"name":"Developer API","description":"Scoped server credentials and canonical Property permissions."},{"name":"Operator API","description":"What the host reads in the app, read with a secret key: bookings, calendar, requests, guests, conversations, tasks, the inbox, imports, analytics and every settings page. Each operation names the grants it needs; guest data needs guest.read."},{"name":"Booking","description":"The guest booking flow, in order: read the property, optionally read the nightly availability calendar for a date picker, search availability, take a quote, start a checkout, then read the authoritative status until it stops asking you to wait."}],"components":{"securitySchemes":{"SecretApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Keyset secret API key"}},"schemas":{"ApiAccountingSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"],"description":"`unchanged`: what was sent is what was stored; nothing changed."}},"required":["outcome"]},"ApiAccountingSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`version` of getAccountingSettings."},"chart":{"type":"string","enum":["SKR03","SKR04"],"description":"The chart of accounts (Kontenrahmen)."},"advisorNumber":{"type":["integer","null"],"minimum":1001,"maximum":9999999,"description":"The tax adviser’s number (Beraternummer)."},"clientNumber":{"type":["integer","null"],"minimum":1,"maximum":99999,"description":"The business’s number at the adviser (Mandantennummer)."},"clearingAccount":{"type":["integer","null"],"minimum":1,"maximum":9999,"description":"The account every line is booked against."},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^(accommodation|cleaning|fee|tourist_tax|extra:[a-z0-9-]{1,40})$","description":"`accommodation`, `cleaning`, `fee`, `tourist_tax` or `extra:<id>` of an extra."},"rate":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[7]},{"type":"number","enum":[19]}],"description":"VAT rate in percent."},"account":{"type":"integer","minimum":1,"maximum":9999}},"required":["kind","rate","account"],"additionalProperties":false},"maxItems":60,"description":"One account per kind of item and VAT rate; the list replaces the stored one."}},"required":["expectedVersion","chart","advisorNumber","clientNumber","clearingAccount","items"],"additionalProperties":false},"ApiAccountingSettings":{"type":"object","properties":{"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."},"chart":{"type":"string","enum":["SKR03","SKR04"]},"smallBusiness":{"type":"boolean"},"advisorNumber":{"type":["integer","null"],"description":"The tax adviser’s number (Beraternummer)."},"clientNumber":{"type":["integer","null"],"description":"The business’s number at the adviser (Mandantennummer)."},"clearingAccount":{"type":["integer","null"],"description":"The account every line is booked against."},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"accommodation, cleaning, fee, tourist_tax or `extra:<id>`; an unknown value is \"other\"."},"rate":{"type":"integer","description":"The VAT rate in percent: 0, 7 or 19."},"account":{"type":"integer","description":"The revenue account."}},"required":["kind","rate","account"]}},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"description":"The extras the apartments offer now."}},"required":["version","chart","smallBusiness","advisorNumber","clientNumber","clearingAccount","items","extras"]},"ApiAgentAccess":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether AI assistants may find and read the published booking page (MCP)."}},"required":["enabled"]},"ApiAttentionCase":{"type":"object","properties":{"caseId":{"type":"string","pattern":"^(refund|payment|dispute)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it."},"kind":{"type":"string","enum":["refund","payment","dispute"]},"outcome":{"type":"string","enum":["failed","unknown","delayed","in_progress","resolved"]},"severity":{"type":"string","enum":["critical","high","medium","info"]},"impact":{"type":"string","enum":["payment_captured_without_inventory","refund_not_executed","refund_outcome_unknown","refund_pending","payment_outcome_unknown","payment_pending","payment_needs_attention","dispute_needs_response","dispute_under_review","dispute_lost","resolved"]},"nextAction":{"type":"string","enum":["reconcile_now","wait_for_reconciliation","wait_for_provider","manual_provider_check","respond_to_dispute","none_resolved"]},"reconcileAvailable":{"type":"boolean","description":"Whether the app would offer “Jetzt abgleichen” for this case right now."},"firstSeenAt":{"type":"string","format":"date-time"},"lastChangedAt":{"type":"string","format":"date-time"},"reservation":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"confirmationReference":{"type":"string","pattern":"^[A-Z0-9]{12}$"},"number":{"type":"integer","minimum":1001},"state":{"type":"string","enum":["confirmed","cancelled","no_show"]}},"required":["id","confirmationReference","number","state"]},"unit":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1}},"required":["id","name"]},"stay":{"type":["object","null"],"properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1}},"required":["checkIn","checkOut","nights"]},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["created","requires_customer_action","processing","succeeded","failed","cancelled"]},"provider":{"type":"string","enum":["fake","stripe"]},"amount":{"$ref":"#/components/schemas/ApiMoney"},"createdAt":{"type":"string","format":"date-time"},"succeededAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"providerReferenceKnown":{"type":"boolean","description":"Whether the provider has answered with a reference; never the reference."}},"required":["id","state","provider","amount","createdAt","succeededAt","failedAt","providerReferenceKnown"]},"checkout":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lifecycle":{"type":"string","enum":["created","awaiting_payment","requires_customer_action","processing","resolving","completed","expired","failed","needs_attention"]},"terminalReason":{"type":["string","null"]},"terminalAt":{"type":["string","null"],"format":"date-time"}},"required":["id","lifecycle","terminalReason","terminalAt"]},"refund":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["requested","processing","unknown","succeeded","failed","needs_attention"]},"reason":{"type":"string","description":"Why the money goes back. Currently payment_inventory_conflict, operator_cancellation, operator_goodwill, reservation_change, guest_cancellation, duplicate_payment, split_incomplete or provider_dashboard; treat an unknown value as “other”."},"amount":{"$ref":"#/components/schemas/ApiMoney"},"requestedAt":{"type":"string","format":"date-time"},"terminalAt":{"type":["string","null"],"format":"date-time"},"providerReferenceKnown":{"type":"boolean"}},"required":["id","state","reason","amount","requestedAt","terminalAt","providerReferenceKnown"]},"cancellation":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"cancelledAt":{"type":"string","format":"date-time"}},"required":["id","cancelledAt"]},"dispute":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["warning_needs_response","warning_under_review","warning_closed","needs_response","under_review","won","lost"]},"amount":{"$ref":"#/components/schemas/ApiMoney"},"reason":{"type":"string","description":"The provider’s reason code, `fraudulent` for example."},"evidenceDueBy":{"type":["string","null"],"format":"date-time"},"openedAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","status","amount","reason","evidenceDueBy","openedAt","closedAt"]},"operation":{"type":["object","null"],"properties":{"destination":{"type":"string"},"state":{"type":"string","enum":["pending","retry_wait","unknown_outcome","succeeded","quarantined"]},"attemptCount":{"type":"integer","minimum":0},"reconcileAttemptCount":{"type":"integer","minimum":0},"firstAttemptAt":{"type":["string","null"],"format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"unknownSince":{"type":["string","null"],"format":"date-time"},"reconcileAfter":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"quarantinedAt":{"type":["string","null"],"format":"date-time"},"quarantineReason":{"type":["string","null"]},"lastErrorCode":{"type":["string","null"]}},"required":["destination","state","attemptCount","reconcileAttemptCount","firstAttemptAt","lastAttemptAt","unknownSince","reconcileAfter","deliveredAt","quarantinedAt","quarantineReason","lastErrorCode"],"description":"The delivery bookkeeping of the money movement behind the case; no payload."},"attentionItem":{"type":["object","null"],"properties":{"state":{"type":"string","enum":["open","resolved"]},"firstSeenAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["state","firstSeenAt","resolvedAt"]},"quarantinedInboxMessages":{"type":"integer","minimum":0},"closure":{"type":["object","null"],"properties":{"reason":{"type":"string"},"closedAt":{"type":"string","format":"date-time"}},"required":["reason","closedAt"],"description":"Set when the host closed the case by hand, with the reason they gave."},"closable":{"type":"boolean","description":"Whether the app would offer “Als erledigt markieren” now."}},"required":["caseId","kind","outcome","severity","impact","nextAction","reconcileAvailable","firstSeenAt","lastChangedAt","reservation","unit","stay","payment","checkout","refund","cancellation","dispute","operation","attentionItem","quarantinedInboxMessages","closure","closable"]},"ApiAttentionCaseDetails":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"case":{"$ref":"#/components/schemas/ApiAttentionCase"},"history":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"event":{"type":"string","description":"What happened, for example payment_created, refund_requested or attention_resolved."},"kind":{"type":"string","enum":["created","payment","confirmed","cancelled","refund_requested","provider_attempt","provider_answer","resolved"]},"detail":{"type":["string","null"]}},"required":["at","event","kind","detail"]},"description":"The story of the case in causal order, derived from stored timestamps."}},"required":["asOf","case","history"]},"ApiAttentionClosed":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"case":{"$ref":"#/components/schemas/ApiAttentionCase"}},"required":["asOf","case"]},"ApiAttentionCloseRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":300,"description":"Why the host closes it (“Im Stripe-Dashboard erstattet”); stored with the closure, never logged."}},"required":["reason"],"additionalProperties":false},"ApiAttentionList":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"openCount":{"type":"integer","minimum":0},"needsYouCount":{"type":"integer","minimum":0,"description":"Open cases whose next step is the host’s (“Braucht dich”)."},"cases":{"type":"array","items":{"$ref":"#/components/schemas/ApiAttentionCase"},"description":"Open cases first (severity, outcome, newest first), then the resolved history."}},"required":["asOf","openCount","needsYouCount","cases"]},"ApiAttentionReconciled":{"type":"object","properties":{"outcome":{"type":"string","enum":["scheduled","already_due","in_progress","not_unknown"],"description":"`scheduled`: the provider is asked again now; `already_due` and `in_progress`: it is asked or being asked; `not_unknown`: the case has no lost answer to look for."},"asOf":{"type":"string","format":"date-time"},"case":{"$ref":"#/components/schemas/ApiAttentionCase"}},"required":["outcome","asOf","case"]},"ApiBlock":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"kind":{"type":"string","enum":["owner_block","maintenance"],"description":"owner_block (Sperre) or maintenance (Wartung)."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date","description":"Exclusive: the block holds the nights [checkIn, checkOut)."},"nights":{"type":"integer","minimum":1},"state":{"type":"string","enum":["active","released"],"description":"active holds the nights; released is history."},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"note":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"releasedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","unit","kind","checkIn","checkOut","nights","state","version","note","createdAt","releasedAt"]},"ApiBlockChange":{"type":"object","properties":{"outcome":{"type":"string","enum":["changed","unchanged"],"description":"changed: the block was replaced by `block`; unchanged: it already was as asked."},"block":{"$ref":"#/components/schemas/ApiBlock"},"replacedBlockId":{"type":["string","null"],"format":"uuid","description":"The block that was replaced, now released; null when unchanged."}},"required":["outcome","block","replacedBlockId"]},"ApiBlockChangeRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"kind":{"type":"string","enum":["owner_block","maintenance"],"description":"owner_block (Sperre) or maintenance (Wartung)."},"note":{"type":["string","null"],"maxLength":80,"description":"null or empty removes the note."}},"required":["expectedVersion","checkIn","checkOut","kind","note"],"additionalProperties":false},"ApiBlockConflict":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["reservation"]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"reservationId":{"type":["string","null"],"format":"uuid","description":"Null unless the key also holds reservation.read."},"number":{"type":["integer","null"],"minimum":1001,"description":"Null unless the key also holds reservation.read."}},"required":["kind","checkIn","checkOut","reservationId","number"]},{"type":"object","properties":{"kind":{"type":"string","enum":["hold"]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date-time"}},"required":["kind","checkIn","checkOut","expiresAt"]},{"type":"object","properties":{"kind":{"type":"string","enum":["owner_block","maintenance"],"description":"owner_block (Sperre) or maintenance (Wartung)."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"blockId":{"type":"string","format":"uuid"}},"required":["kind","checkIn","checkOut","blockId"]}]},"ApiBlockCreateRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"kind":{"type":"string","enum":["owner_block","maintenance"],"description":"owner_block (Sperre) or maintenance (Wartung)."},"note":{"type":["string","null"],"maxLength":80,"description":"The host’s reason for the block (\"Malerarbeiten\"), at most 80 characters; empty is none."}},"required":["unitId","checkIn","checkOut","kind"],"additionalProperties":false},"ApiBlockPeriod":{"type":"object","properties":{"units":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["blocked"]},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/ApiBlock"}}},"required":["unitId","outcome","blocks"]},{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["conflict"]},"conflicts":{"type":"array","items":{"$ref":"#/components/schemas/ApiBlockConflict"}}},"required":["unitId","outcome","conflicts"],"description":"Nothing was blocked in this apartment: something now holds a night of its runs."},{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["unavailable"]}},"required":["unitId","outcome"]}]}}},"required":["units"]},"ApiBlockPeriodPreview":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1},"units":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["found"]},"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"occupied":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["reservation"]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"reservationId":{"type":["string","null"],"format":"uuid","description":"Null unless the key also holds reservation.read."},"number":{"type":["integer","null"],"minimum":1001,"description":"Null unless the key also holds reservation.read."},"guestName":{"type":["string","null"],"minLength":1,"description":"Only with guest.read; PostgreSQL withholds it otherwise."}},"required":["kind","checkIn","checkOut","reservationId","number","guestName"]},{"type":"object","properties":{"kind":{"type":"string","enum":["hold"]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date-time"}},"required":["kind","checkIn","checkOut","expiresAt"]},{"type":"object","properties":{"kind":{"type":"string","enum":["owner_block","maintenance"],"description":"owner_block (Sperre) or maintenance (Wartung)."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"blockId":{"type":"string","format":"uuid"}},"required":["kind","checkIn","checkOut","blockId"]}]}},"free":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1}},"required":["checkIn","checkOut","nights"]},"description":"The runs of nights nothing held at asOf, in order; send exactly these."}},"required":["unitId","outcome","unit","occupied","free"]},{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["unavailable"]}},"required":["unitId","outcome"],"description":"Takes no block now: not an apartment of the Property, switched off or archived."}]}}},"required":["asOf","checkIn","checkOut","nights","units"]},"ApiBlockPeriodPreviewRequest":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"unitIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50}},"required":["checkIn","checkOut","unitIds"],"additionalProperties":false},"ApiBlockPeriodRequest":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"kind":{"type":"string","enum":["owner_block","maintenance"],"description":"owner_block (Sperre) or maintenance (Wartung)."},"note":{"type":["string","null"],"maxLength":80,"description":"The host’s reason for the block (\"Malerarbeiten\"), at most 80 characters; empty is none."},"units":{"type":"array","items":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"runs":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"}},"required":["checkIn","checkOut"],"additionalProperties":false},"minItems":1,"maxItems":200,"description":"Exactly the free runs the preview gave, in order, each inside the period."}},"required":["unitId","runs"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["checkIn","checkOut","kind","units"],"additionalProperties":false},"ApiBlockPreview":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1},"available":{"type":"boolean","description":"Nothing held the nights at asOf. A block can still meet a booking made later."},"conflicts":{"type":"array","items":{"$ref":"#/components/schemas/ApiBlockConflict"}}},"required":["asOf","unit","checkIn","checkOut","nights","available","conflicts"]},"ApiBlockPreviewRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date","description":"Exclusive, after checkIn; at most 400 nights."},"exceptBlockId":{"type":"string","format":"uuid","description":"Previewing a change of this block: its own nights are no conflict."}},"required":["unitId","checkIn","checkOut"],"additionalProperties":false},"ApiBlockReleaseRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."}},"required":["expectedVersion"],"additionalProperties":false},"ApiBookingChanged":{"type":"object","properties":{"outcome":{"type":"string","enum":["changed","unchanged"],"description":"`unchanged`: the stay, apartment and total were already so."},"reservationVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"change":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer","minimum":1},"from":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"total":{"$ref":"#/components/schemas/ApiMoney"}},"required":["unitId","checkIn","checkOut","total"]},"to":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"total":{"$ref":"#/components/schemas/ApiMoney"}},"required":["unitId","checkIn","checkOut","total"]},"listPrice":{"$ref":"#/components/schemas/ApiMoney"},"priceReason":{"type":["string","null"]},"changedAt":{"type":"string","format":"date-time"}},"required":["id","sequence","from","to","listPrice","priceReason","changedAt"],"additionalProperties":false}},"required":["outcome","reservationVersion","change"],"additionalProperties":false},"ApiBookingChangePreview":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether no other booking, hold or block held a night of the stay on that apartment when read."},"price":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["priced"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"nights":{"type":"integer","exclusiveMinimum":0},"lines":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200},"amount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["label","amount"],"additionalProperties":false},"maxItems":50,"description":"The price’s lines in order; they add up to `total`."},"touristTaxOnSite":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"The tourist tax paid on arrival, outside `total`; null when it is in the price or there is none."}},"required":["type","total","nights","lines","touristTaxOnSite"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["ineligible"]},"reason":{"type":"string","enum":["minimum_stay_not_satisfied","maximum_stay_exceeded","arrival_day_not_allowed","departure_day_not_allowed"]},"requiredNights":{"type":"integer","exclusiveMinimum":0},"maximumNights":{"type":"integer","exclusiveMinimum":0},"actualNights":{"type":"integer","minimum":0},"allowedDays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7}},"required":["type","reason"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["unpriced"]}},"required":["type"],"additionalProperties":false}],"description":"priced: the new stay at the published rates, for the booking’s party, extras and rate plan; ineligible: the rule it breaks; unpriced: no published rates, so the host agrees a price."}},"required":["available","price"],"additionalProperties":false},"ApiBookingChangePreviewRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid","description":"The apartment the booking would move to; the same one to keep it."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"}},"required":["unitId","checkIn","checkOut"],"additionalProperties":false},"ApiBookingChangeRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The booking’s `version` as getReservation gave it."},"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"totalMinorUnits":{"type":"string","pattern":"^(0|[1-9]\\d{0,11})$","description":"The new agreed total, as in the app: the host’s own figure, never derived by Keyset."},"listPriceMinorUnits":{"type":["string","null"],"pattern":"^(0|[1-9]\\d{0,11})$","description":"The list price the preview showed for the new stay, kept beside the change; null or absent is none."},"priceReason":{"type":["string","null"],"maxLength":1200,"description":"Why the agreed total differs from the list price; at least 3 characters and required for such a total: without it PRICE_REASON_REQUIRED. The guest never reads it."},"notifyGuest":{"type":"boolean","description":"Whether Keyset mails the guest about the change; absent is true. False is recorded with the change."}},"required":["expectedVersion","unitId","checkIn","checkOut","totalMinorUnits"],"additionalProperties":false},"ApiBookingContent":{"type":"object","properties":{"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The version of the Property’s texts."},"locality":{"type":["string","null"]},"description":{"type":["string","null"]},"location":{"type":["string","null"]},"amenities":{"type":"array","items":{"type":"string"},"description":"Amenity codes such as wifi, parking, kitchen, sauna; Keyset names them on the page."},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]}},"translations":{"type":"object","properties":{"en":{"type":["object","null"],"properties":{"locality":{"type":["string","null"]},"description":{"type":["string","null"]},"location":{"type":["string","null"]},"faq":{"type":["array","null"],"items":{"type":["object","null"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]},"description":"Entry n translates German question n; null leaves that one in German."}},"required":["locality","description","location","faq"]}},"required":["en"]},"units":{"type":"array","items":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The version of this apartment’s texts."},"description":{"type":["string","null"]},"amenities":{"type":"array","items":{"type":"string"}},"sleepingArrangement":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"bedroom or living_room."},"beds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"double, single, sofa_bed or bunk."},"count":{"type":"integer"}},"required":["kind","count"]}}},"required":["kind","beds"]}},"floorArea":{"type":["integer","null"],"description":"Whole square metres; null when not given."},"translations":{"type":"object","properties":{"en":{"type":["object","null"],"properties":{"description":{"type":["string","null"]}},"required":["description"]}},"required":["en"]}},"required":["unitId","code","name","version","description","amenities","sleepingArrangement","floorArea","translations"]}}},"required":["version","locality","description","location","amenities","faq","translations","units"]},"ApiBookingContentSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The `version` the read gave; \"0\" before anything was saved. A newer one answers VERSION_CONFLICT."},"content":{"type":"object","properties":{"locality":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"The place shown under the name."},"description":{"type":["string","null"],"minLength":1,"maxLength":400},"location":{"type":["string","null"],"minLength":1,"maxLength":1000,"description":"Lage."},"amenities":{"type":"array","items":{"type":"string","enum":["wifi","parking","ev_charging","kitchen","dishwasher","coffee_machine","washing_machine","dryer","tv","workspace","heating","air_conditioning","balcony","terrace","garden","barbecue","sauna","pool","bed_linen","towels","baby_cot","high_chair","step_free","elevator","bike_storage","pets_allowed","non_smoking"]},"maxItems":40,"description":"Amenity codes of getBookingContent."},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":200},"answer":{"type":"string","minLength":1,"maxLength":1000}},"required":["question","answer"],"additionalProperties":false},"maxItems":10,"description":"Questions and answers, in the page’s order."},"translations":{"type":"object","properties":{"en":{"type":["object","null"],"properties":{"locality":{"type":["string","null"],"minLength":1,"maxLength":120},"description":{"type":["string","null"],"minLength":1,"maxLength":400},"location":{"type":["string","null"],"minLength":1,"maxLength":1000},"faq":{"type":["array","null"],"items":{"type":["object","null"],"properties":{"question":{"type":"string","minLength":1,"maxLength":200},"answer":{"type":"string","minLength":1,"maxLength":1000}},"required":["question","answer"],"additionalProperties":false},"maxItems":10,"description":"Entry n translates German question n; null leaves that one in German."}},"additionalProperties":false,"description":"The host’s English; null or absent leaves the page German."}},"additionalProperties":false}},"required":["locality","description","location","amenities","faq","translations"],"additionalProperties":false}},"required":["expectedVersion","content"],"additionalProperties":false},"ApiBookingMode":{"type":"object","properties":{"bookingMode":{"type":"string","enum":["instant","request","both"],"description":"How guests book on the page: instantly, by request, or both."}},"required":["bookingMode"]},"ApiBookingModeSaveRequest":{"type":"object","properties":{"bookingMode":{"type":"string","enum":["instant","request","both"],"description":"instant books at once, request asks the host first, both offers the guest either."},"expectedBookingMode":{"type":"string","enum":["instant","request","both"],"description":"`bookingMode` of getBookingMode; another one stored since answers VERSION_CONFLICT with the stored mode in `detail`."}},"required":["bookingMode","expectedBookingMode"],"additionalProperties":false},"ApiBookingRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["open","accepted","declined","expired","withdrawn"]},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"unit":{"$ref":"#/components/schemas/ApiUnitRef"},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","exclusiveMinimum":0}},"required":["checkIn","checkOut","nights"]},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":0},"children":{"type":"integer","minimum":0}},"required":["adults","children"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"guest":{"type":["object","null"],"properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1}},"required":["firstName","lastName"]},"language":{"type":"string","enum":["de","en"]},"hasNote":{"type":"boolean"},"submittedAt":{"type":"string","format":"date-time"},"answerBy":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"erased":{"type":"boolean","description":"The guest's data of an ended request was erased."},"reservation":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001}},"required":["id","number"]},"paymentWay":{"type":["string","null"],"description":"card_link, outside, transfer or card_link_and_transfer."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"note":{"type":["string","null"]},"declineMessage":{"type":["string","null"]},"ratePlanName":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["kind","label","amount"]}},"earlierBookings":{"type":"integer","minimum":0},"overlaps":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["reservation","hold","owner_block","maintenance","part","request"]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"reservationNumber":{"type":["integer","null"]},"bookingRequestId":{"type":["string","null"],"format":"uuid"}},"required":["kind","checkIn","checkOut","reservationNumber","bookingRequestId"]}},"acceptable":{"type":"boolean"}},"required":["id","state","version","unit","stay","occupancy","total","guest","language","hasNote","submittedAt","answerBy","endedAt","erased","reservation","paymentWay","email","phone","note","declineMessage","ratePlanName","lines","earlierBookings","overlaps","acceptable"]},"ApiBookingRequestAccepted":{"type":"object","properties":{"bookingRequestId":{"type":"string","format":"uuid"},"reservationId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["accepted"]},"paymentWay":{"type":"string","enum":["card_link","outside","transfer","card_link_and_transfer"],"description":"How the guest pays: a card link, outside Keyset (the host collects), a bank transfer with the Property’s bank details, or the card link and the transfer."},"guestMail":{"type":"string","enum":["requested","no_address","test"],"description":"What became of the guest’s confirmation; absent on a repeat of an acceptance that went through."}},"required":["bookingRequestId","reservationId","outcome","paymentWay"],"additionalProperties":false},"ApiBookingRequestAcceptRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The request’s `version` as the request read gave it."},"paymentWay":{"type":"string","enum":["card_link","outside","transfer","card_link_and_transfer"],"description":"How the guest pays: a card link, outside Keyset (the host collects), a bank transfer with the Property’s bank details, or the card link and the transfer."}},"required":["expectedVersion","paymentWay"],"additionalProperties":false},"ApiBookingRequestDeclined":{"type":"object","properties":{"bookingRequestId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["declined"]}},"required":["bookingRequestId","outcome"],"additionalProperties":false},"ApiBookingRequestDeclineRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The request’s `version` as the request read gave it."},"message":{"type":"string","maxLength":1000,"description":"A message for the guest’s mail, at most 1000 characters."}},"required":["expectedVersion"],"additionalProperties":false},"ApiBookingRequestList":{"type":"object","properties":{"canAnswer":{"type":"boolean","description":"Whether this key could answer requests (reservation.create_manual)."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["open","accepted","declined","expired","withdrawn"]},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"unit":{"$ref":"#/components/schemas/ApiUnitRef"},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","exclusiveMinimum":0}},"required":["checkIn","checkOut","nights"]},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":0},"children":{"type":"integer","minimum":0}},"required":["adults","children"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"guest":{"type":["object","null"],"properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1}},"required":["firstName","lastName"]},"language":{"type":"string","enum":["de","en"]},"hasNote":{"type":"boolean"},"submittedAt":{"type":"string","format":"date-time"},"answerBy":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"erased":{"type":"boolean","description":"The guest's data of an ended request was erased."},"reservation":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001}},"required":["id","number"]},"paymentWay":{"type":["string","null"],"description":"card_link, outside, transfer or card_link_and_transfer."}},"required":["id","state","version","unit","stay","occupancy","total","guest","language","hasNote","submittedAt","answerBy","endedAt","erased","reservation","paymentWay"]},"description":"Open requests first, then those ended in 30 days."}},"required":["canAnswer","data"]},"ApiBookingSite":{"type":"object","properties":{"publicId":{"type":"string","description":"The public key of the booking site, as it appears in the page address."},"state":{"type":"string","enum":["draft","published","paused"]},"bookableUnits":{"type":"integer","minimum":0,"description":"Active apartments with a published price."},"activeUnits":{"type":"integer","minimum":0},"publishedUnits":{"type":"integer","minimum":0,"description":"What a guest can see today; below bookableUnits after an apartment was priced post go-live."},"pausedAt":{"type":["string","null"],"format":"date-time","description":"Since when a paused site is paused; null in every other state."}},"required":["publicId","state","bookableUnits","activeUnits","publishedUnits","pausedAt"]},"ApiBookingSiteChanged":{"type":"object","properties":{"outcome":{"type":"string","enum":["published","paused","already_paused"],"description":"`already_paused`: the site was paused before; nothing changed."},"site":{"$ref":"#/components/schemas/ApiBookingSite"},"subscription":{"type":"object","properties":{"apartmentsBefore":{"type":"integer","minimum":0},"apartmentsAfter":{"type":"integer","minimum":0}},"required":["apartmentsBefore","apartmentsAfter"],"description":"The apartments the Keyset subscription counts before and after this change (the billing rule’s own count, for the whole business). The subscription itself follows through Keyset’s own billing; amounts stay in the app with the owner."}},"required":["outcome","site","subscription"]},"ApiBookingSiteEffect":{"type":"object","properties":{"action":{"type":"string","enum":["publish","pause"]},"refusal":{"type":["string","null"],"enum":["not_ready","legal_information_missing","billing_required","not_published",null],"description":"What the change would answer right now; null when it would go through."},"subscription":{"type":["object","null"],"properties":{"apartmentsNow":{"type":"integer","minimum":0},"apartmentsAfter":{"type":"integer","minimum":0}},"required":["apartmentsNow","apartmentsAfter"],"description":"The apartments the Keyset subscription counts now and after the change; null when the change would be refused."}},"required":["action","refusal","subscription"]},"ApiCalendar":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"units":{"type":"array","items":{"$ref":"#/components/schemas/ApiUnitRef"}},"entries":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["reservation"]},"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"reservationId":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001},"source":{"type":["string","null"],"enum":["direct","manual","import",null]},"guestName":{"type":["string","null"],"minLength":1,"description":"Only with guest.read."},"adults":{"type":["integer","null"],"minimum":0},"children":{"type":["integer","null"],"minimum":0},"paymentState":{"type":["string","null"],"enum":["created","requires_customer_action","processing","succeeded","failed","cancelled",null]}},"required":["kind","unitId","checkIn","checkOut","reservationId","number","source","guestName","adults","children","paymentState"]},{"type":"object","properties":{"kind":{"type":"string","enum":["owner_block","maintenance"]},"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"blockId":{"type":"string","format":"uuid"},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"note":{"type":["string","null"]}},"required":["kind","unitId","checkIn","checkOut","blockId","version","note"]},{"type":"object","properties":{"kind":{"type":"string","enum":["hold"]},"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date-time"}},"required":["kind","unitId","checkIn","checkOut","expiresAt"]}]}},"unplaced":{"type":"array","items":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001},"guestName":{"type":["string","null"],"minLength":1},"unitId":{"type":["string","null"],"format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"reason":{"type":"string","enum":["conflict","unmapped"]},"source":{"type":"string","enum":["direct","manual","import"]}},"required":["reservationId","number","guestName","unitId","checkIn","checkOut","reason","source"]},"description":"Bookings that hold no apartment: imported ones that conflict or name no known apartment."},"asOf":{"type":"string","format":"date-time"}},"required":["from","to","units","entries","unplaced","asOf"]},"ApiCalendarConnected":{"type":"object","properties":{"outcome":{"type":"string","enum":["created"]},"connectionId":{"type":"string","format":"uuid","description":"`connections[].id` of getCalendarConnections; its first read follows within minutes."}},"required":["outcome","connectionId"]},"ApiCalendarConnections":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"property":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"timezone":{"type":"string"}},"required":["id","name","timezone"]},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]}},"required":["id","name","status"]}},"connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"provider":{"type":"string","enum":["ical"]},"sourceHost":{"type":"string","description":"The host name of the portal’s calendar, never its full link."},"lifecycle":{"type":"string","enum":["active","revoked"]},"health":{"type":"string","enum":["pending","healthy","degraded","error"],"description":"`degraded`: a read failed after an earlier one succeeded, or stays are in conflict."},"unit":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"lastErrorCode":{"type":["string","null"],"description":"Why the last read failed: FEED_UNAVAILABLE, FEED_TIMEOUT, MALFORMED_CALENDAR, INVALID_EVENT, DUPLICATE_EVENT_ID, MAPPING_REQUIRED or STALE_OBSERVATION; an unknown value is \"other\"."},"lastErrorAt":{"type":["string","null"],"format":"date-time"},"activeEventCount":{"type":"integer","minimum":0},"conflictCount":{"type":"integer","minimum":0,"description":"Its stays in conflict that are not over by today."}},"required":["id","name","provider","sourceHost","lifecycle","health","unit","lastAttemptAt","lastSuccessAt","lastErrorCode","lastErrorAt","activeEventCount","conflictCount"]}},"exports":{"type":"array","items":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"unitName":{"type":"string"},"lifecycle":{"type":"string","enum":["active","revoked","not_created"],"description":"Whether Keyset’s calendar link for the apartment exists. The link itself is never part of the API."},"createdAt":{"type":["string","null"],"format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":["unitId","unitName","lifecycle","createdAt","rotatedAt"]},"description":"Keyset’s own calendar link per apartment, as presence only."}},"required":["asOf","property","units","connections","exports"]},"ApiCalendarConnectRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid","description":"The apartment the portal’s calendar belongs to, an active apartment of the Property."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"What the host calls it, such as the portal’s name."},"sourceUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"The calendar link the portal gives for the apartment (https, or webcal as calendar apps write it; an http link is fetched over https). Never returned, logged or shown again: reads name its host only."}},"required":["unitId","name","sourceUrl"],"additionalProperties":false},"ApiCalendarLink":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"url":{"type":["string","null"],"description":"The link a portal reads, on the address of the Keyset app; null in a replay, and where the deployment names no app address."},"token":{"type":["string","null"],"description":"The link’s secret part (`/calendar/<token>.ics`); null in a replay. It is never shown again."}},"required":["unitId","url","token"]},"ApiCalendarLinkRevoked":{"type":"object","properties":{"outcome":{"type":"string","enum":["revoked"]}},"required":["outcome"]},"ApiCalendarLinkRotated":{"type":"object","properties":{"outcome":{"type":"string","enum":["rotated"]},"link":{"$ref":"#/components/schemas/ApiCalendarLink"}},"required":["outcome","link"]},"ApiCalendarLinksEnsured":{"type":"object","properties":{"outcome":{"type":"string","enum":["ensured"]},"created":{"type":"integer","minimum":0},"links":{"type":"array","items":{"$ref":"#/components/schemas/ApiCalendarLink"},"description":"The links this call made, one per apartment that had none; an apartment whose link was active already is not listed (its link is not shown again: renew it to get a new one)."}},"required":["outcome","created","links"]},"ApiCalendarLinksEnsureRequest":{"type":"object","properties":{"unitIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200,"description":"Apartments of the Property; each gets a link where it has none or only a withdrawn one."}},"required":["unitIds"],"additionalProperties":false},"ApiCalendarProbeRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid","description":"The apartment the portal’s calendar belongs to, an active apartment of the Property."},"sourceUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"The calendar link the portal gives for the apartment (https, or webcal as calendar apps write it; an http link is fetched over https). Never returned, logged or shown again: reads name its host only."}},"required":["unitId","sourceUrl"],"additionalProperties":false},"ApiCalendarProbeResult":{"oneOf":[{"type":"object","properties":{"outcome":{"type":"string","enum":["found"]},"stays":{"type":"integer","minimum":0,"description":"Stays in the calendar that are not over by today at the Property."},"lastCheckOut":{"type":["string","null"],"format":"date","description":"The last departure among them."},"conflicts":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"keyset":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["booking"]},"reservationNumber":{"type":["integer","null"],"minimum":1,"description":"Only with reservation.read; PostgreSQL withholds it otherwise."},"guestName":{"type":["string","null"],"minLength":1,"description":"Only with guest.read; PostgreSQL withholds it otherwise."}},"required":["kind","reservationNumber","guestName"]},{"type":"object","properties":{"kind":{"type":"string","enum":["imported"]},"connectionName":{"type":"string","description":"The connected calendar that brought the stay in."}},"required":["kind","connectionName"]},{"type":"object","properties":{"kind":{"type":"string","enum":["block"]}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["hold"],"description":"A guest is paying for these nights right now."}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["same_calendar"],"description":"Two stays of this calendar overlap each other."}},"required":["kind"]}]}},"required":["checkIn","checkOut","keyset"]},"description":"Stays the first sync would bring in on nights Keyset already holds: each becomes a conflict."}},"required":["outcome","stays","lastCheckOut","conflicts"]},{"type":"object","properties":{"outcome":{"type":"string","enum":["already_connected"]},"unitId":{"type":"string","format":"uuid"}},"required":["outcome","unitId"],"description":"The same link is connected already, for this apartment."},{"type":"object","properties":{"outcome":{"type":"string","enum":["failed"]},"code":{"type":"string","enum":["INVALID_URL","OWN_CALENDAR","FEED_UNAVAILABLE","FEED_TIMEOUT","MALFORMED_CALENDAR","INVALID_EVENT","DUPLICATE_EVENT_ID"],"description":"Not a link Keyset fetches (INVALID_URL) or Keyset’s own calendar link of this Property (OWN_CALENDAR); the portal did not answer (FEED_UNAVAILABLE, also for an address outside the public internet) or not in time (FEED_TIMEOUT); or its answer is no calendar Keyset can read (MALFORMED_CALENDAR, INVALID_EVENT, DUPLICATE_EVENT_ID)."}},"required":["outcome","code"],"description":"Nothing was fetched or nothing usable came back; nothing was kept."}]},"ApiCalendarRefreshResult":{"oneOf":[{"type":"object","properties":{"outcome":{"type":"string","enum":["applied"]},"revision":{"type":"integer","minimum":0,"description":"The connection’s observation, counted up by every changed read."},"imported":{"type":"integer","minimum":0},"unchanged":{"type":"integer","minimum":0},"modified":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0},"conflicted":{"type":"integer","minimum":0,"description":"Stays brought in on nights Keyset already holds."}},"required":["outcome","revision","imported","unchanged","modified","cancelled","conflicted"]},{"type":"object","properties":{"outcome":{"type":"string","enum":["failed"]},"code":{"type":"string","enum":["FEED_UNAVAILABLE","FEED_TIMEOUT","MALFORMED_CALENDAR","INVALID_EVENT","DUPLICATE_EVENT_ID"]}},"required":["outcome","code"],"description":"The read failed and is recorded as the connection’s last error; nothing else changed."},{"type":"object","properties":{"outcome":{"type":"string","enum":["mapping_required"]},"code":{"type":"string","enum":["MAPPING_REQUIRED"]}},"required":["outcome","code"],"description":"The connection serves no apartment any more; nothing was taken in."},{"type":"object","properties":{"outcome":{"type":"string","enum":["stale"]},"code":{"type":"string","enum":["STALE_OBSERVATION"]}},"required":["outcome","code"],"description":"Another read of the same calendar finished first; its result stands."}]},"ApiCalendarRemoval":{"type":"object","properties":{"futureStays":{"type":"array","items":{"type":"object","properties":{"reservationId":{"type":["string","null"],"format":"uuid","description":"The booking’s id; null without reservation.read."},"reservationNumber":{"type":["integer","null"],"minimum":1,"description":"Its number; null without reservation.read."},"ref":{"type":"string","format":"uuid","description":"An opaque reference of the stay’s booking: send it in `futureStays` to release. It names no booking anywhere else."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"}},"required":["reservationId","reservationNumber","ref","checkIn","checkOut"]},"description":"Stays the calendar brought in that arrive after today at the Property: removing the connection keeps them unless `releaseFutureStays` frees their nights."},"otherStays":{"type":"integer","minimum":0,"description":"Current and past stays it brought in: history, kept either way."}},"required":["futureStays","otherStays"]},"ApiCalendarRemoved":{"type":"object","properties":{"outcome":{"type":"string","enum":["removed","already_removed"]},"released":{"type":"integer","minimum":0,"description":"Future stays whose nights were freed."}},"required":["outcome","released"]},"ApiCalendarRemoveRequest":{"type":"object","properties":{"releaseFutureStays":{"type":"boolean","description":"true frees the nights of the future stays the calendar brought in; false keeps them (the app’s default)."},"futureStays":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500,"description":"With `releaseFutureStays` true, required: the `futureStays[].ref` of getCalendarRemoval you are releasing (a stay’s `reservationId` counts as well). If the stays have changed since, nothing happens and the answer is CALENDAR_STAYS_CHANGED."}},"required":["releaseFutureStays"],"additionalProperties":false},"ApiCancellationPolicyExample":{"type":"object","properties":{"total":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"The booking total the example is worked on, in the Property’s currency."},"cases":{"type":"array","items":{"type":"object","properties":{"daysBefore":{"type":"integer","minimum":0,"description":"Days before arrival the guest cancels; 0 is the arrival day."},"refund":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What the terms asked about refund then."},"currentRefund":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What the terms in force refund then; null while none are saved."}},"required":["daysBefore","refund","currentRefund"]},"description":"Well ahead, closer and on the arrival day, in this order."}},"required":["total","cases"]},"ApiCancellationPolicySaveRequest":{"type":"object","properties":{"expectedVersion":{"type":["string","null"],"pattern":"^[1-9]\\d{0,8}$","description":"`cancellationPolicy.version` of getPaymentSettings as a string; null while `cancellationPolicy` is null. A newer one answers VERSION_CONFLICT."},"freeCancellationDays":{"type":"integer","minimum":0,"maximum":365,"description":"Days before arrival up to which a cancellation is free, 0 to 365."},"lateRefundPercent":{"type":"integer","minimum":0,"maximum":100,"description":"Whole percent of the booking refunded after that, 0 to 100."}},"required":["expectedVersion","freeCancellationDays","lateRefundPercent"],"additionalProperties":false},"ApiCheckIn":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether online check-in is switched on for the business."},"open":{"type":"boolean","description":"Whether the guest can still submit or change it."},"partySize":{"type":"integer","minimum":0},"checkIn":{"type":["object","null"],"properties":{"arrivalTime":{"type":["string","null"]},"submittedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"eraseAfter":{"type":"string","format":"date","description":"The day Keyset erases the data."},"persons":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"birthDate":{"type":"string","format":"date"},"nationality":{"type":"string","minLength":1},"documentNumber":{"type":["string","null"]},"address":{"type":["object","null"],"properties":{"street":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"}},"required":["street","postalCode","city","country"]}},"required":["firstName","lastName","birthDate","nationality","documentNumber","address"]}}},"required":["arrivalTime","submittedAt","updatedAt","eraseAfter","persons"],"description":"Null while the guest has not checked in."}},"required":["enabled","open","partySize","checkIn"]},"ApiCheckInErased":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["erased"]}},"required":["reservationId","outcome"]},"ApiCheckInSettings":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether guests are asked for their online check-in."},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."}},"required":["enabled","version"]},"ApiCheckInSettingsSaveRequest":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether guests are asked for their online check-in."},"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`version` of getCheckInSettings as a string (\"0\" before the first save). A newer one answers VERSION_CONFLICT."}},"required":["enabled","expectedVersion"],"additionalProperties":false},"ApiConfiguredUnit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1,"description":"The apartment’s import code; it never changes after creation."},"name":{"type":"string","minLength":1},"maxOccupancy":{"type":"integer","minimum":1},"status":{"type":"string","enum":["active","inactive"],"description":"`inactive`: switched off („Buchbar“ off), takes no new booking."},"futureAllocations":{"type":"integer","minimum":0,"description":"Holds, booked stays and blocks that end after the Property’s local today."},"bookedOccupancy":{"type":["integer","null"],"description":"The largest guest count among those future allocations; null when nothing is booked."},"onBookingSite":{"type":"boolean","description":"True when a guest can find the apartment on the booking site: published, active and priced."},"componentUnitIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The apartments a composite (the whole house) is made of; empty for a single apartment."}},"required":["id","code","name","maxOccupancy","status","futureAllocations","bookedOccupancy","onBookingSite","componentUnitIds"]},"ApiContentSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"]},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The new version; the next write sends it as expectedVersion."}},"required":["outcome","version"]},"ApiConversation":{"type":"object","properties":{"canAnswer":{"type":"boolean","description":"Whether the host can answer this booking in Keyset."},"hasEmail":{"type":"boolean","description":"Whether an answer reaches the guest by e-mail as well as in the guest portal."},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"direction":{"type":"string","enum":["guest","host"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","direction","body","createdAt"]}}},"required":["canAnswer","hasEmail","messages"]},"ApiConversationAnswered":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["sent"]},"mailed":{"type":"boolean","description":"Whether the guest also got it by e-mail; false where the booking has no address."}},"required":["reservationId","outcome","mailed"]},"ApiConversationAnswerRequest":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":2000,"description":"The answer, 1–2000 characters after trimming, without control characters; shown in the guest page."}},"required":["body"],"additionalProperties":false},"ApiConversationPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiConversationSummary"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."}},"required":["data","hasMore","nextCursor"]},"ApiConversationSummary":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"reservationNumber":{"type":"integer","minimum":1001},"unitName":{"type":["string","null"],"minLength":1},"checkIn":{"type":["string","null"],"format":"date"},"checkOut":{"type":["string","null"],"format":"date"},"guestName":{"type":["string","null"],"minLength":1},"lastDirection":{"type":"string","enum":["guest","host"]},"lastBody":{"type":"string"},"lastAt":{"type":"string","format":"date-time"},"messages":{"type":"integer","minimum":1},"unanswered":{"type":"boolean","description":"The guest wrote last and the host has not answered."}},"required":["reservationId","reservationNumber","unitName","checkIn","checkOut","guestName","lastDirection","lastBody","lastAt","messages","unanswered"]},"ApiDepositPolicy":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether guests pay a deposit now and the rest later."},"depositPercent":{"type":"number","minimum":0,"maximum":100},"balanceDueDays":{"type":"integer","minimum":0,"description":"Days before arrival the rest is due."},"version":{"type":["string","null"],"pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion; null before the first save."}},"required":["enabled","depositPercent","balanceDueDays","version"]},"ApiDepositPolicySaveRequest":{"type":"object","properties":{"expectedVersion":{"type":["string","null"],"pattern":"^[1-9]\\d{0,8}$","description":"`version` of getDepositPolicy; null while it is null. A newer one answers VERSION_CONFLICT."},"enabled":{"type":"boolean","description":"Whether guests pay a deposit at booking and the rest later."},"depositPercent":{"type":"integer","minimum":10,"maximum":90,"description":"The deposit in whole percent of the booking, 10 to 90; sent also while the rule is off."},"balanceDueDays":{"type":"integer","minimum":1,"maximum":180,"description":"Days before arrival the rest is due, 1 to 180; sent also while the rule is off."}},"required":["expectedVersion","enabled","depositPercent","balanceDueDays"],"additionalProperties":false},"ApiDiscountCodeCreated":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]},"ApiDiscountCodeEnded":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ended":{"type":"boolean","enum":[true]}},"required":["id","ended"]},"ApiDiscountCodeRequest":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"As a guest types it; stored in capitals without spaces, 6 to 24 of A–Z, 0–9 and -."},"basisPoints":{"type":"integer","minimum":1,"maximum":9000},"validFrom":{"type":["string","null"],"format":"date","description":"First booking day it counts on, in the Property’s calendar; null is open."},"validUntil":{"type":["string","null"],"format":"date"}},"required":["code","basisPoints","validFrom","validUntil"],"additionalProperties":false},"ApiDiscountCodes":{"type":"object","properties":{"canManage":{"type":"boolean","description":"Whether this key may create and end codes (rates.publish)."},"codes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","description":"What a guest types to get the discount; treat it as a shared secret."},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."},"validFrom":{"type":["string","null"],"format":"date","description":"First booking day it counts on, in the Property’s calendar; null is open."},"validUntil":{"type":["string","null"],"format":"date"},"bookings":{"type":"integer","minimum":0,"description":"How many bookings were made with it."}},"required":["id","code","basisPoints","validFrom","validUntil","bookings"]}}},"required":["canManage","codes"]},"ApiFurtherPropertyCreated":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reachableByThisKey":{"type":"boolean","enum":[false],"description":"Always false: this key cannot reach the new Property. Keys do not widen their own reach; issue a key for it in the app."},"subscriptionChanged":{"type":"boolean","enum":[false],"description":"Always false: the subscription counts bookable apartments, and a new Property has none. It changes when an apartment of the new Property becomes bookable."}},"required":["propertyId","name","reachableByThisKey","subscriptionChanged"]},"ApiFurtherPropertyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"timezone":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z][A-Za-z0-9_+-]*(\\/[A-Za-z0-9_+-]+)*$","description":"An IANA time zone, e.g. Europe/Berlin; one PostgreSQL does not know answers INVALID_REQUEST."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217; Keyset offers EUR. Another answers INVALID_REQUEST."},"locale":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"The language the booking page and guest mails start in, e.g. de-DE."}},"required":["name","timezone","currency","locale"],"additionalProperties":false},"ApiGuest":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{32}$"},"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"email":{"type":["string","null"],"minLength":1},"phone":{"type":["string","null"],"minLength":1},"stays":{"type":"integer","minimum":0,"description":"Confirmed stays."},"lastCheckIn":{"type":["string","null"],"format":"date"},"nextCheckIn":{"type":["string","null"],"format":"date"},"reservations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001},"state":{"type":"string","enum":["confirmed","cancelled","no_show"]},"source":{"type":"string","enum":["direct","manual","import"]},"bookedVia":{"type":["string","null"],"enum":["request",null]},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"unitName":{"type":["string","null"],"minLength":1},"total":{"$ref":"#/components/schemas/ApiMoney"}},"required":["id","number","state","source","bookedVia","checkIn","checkOut","unitName","total"]}},"note":{"type":["object","null"],"properties":{"body":{"type":["string","null"]},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"updatedAt":{"type":"string","format":"date-time"}},"required":["body","version","updatedAt"],"description":"The host's note about the guest; null when none was ever written."}},"required":["id","firstName","lastName","email","phone","stays","lastCheckIn","nextCheckIn","reservations","note"]},"ApiGuestCancellationMail":{"type":"object","properties":{"requestBookings":{"type":"boolean","description":"Whether the guest of a booking made from a request is written when it is cancelled."},"manualBookings":{"type":"string","enum":["always","after_confirmation","never"],"description":"For a manual booking: always, only when Keyset sent that guest the confirmation, or never."},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."}},"required":["requestBookings","manualBookings","version"]},"ApiGuestCancellationMailSaveRequest":{"type":"object","properties":{"requestBookings":{"type":"boolean","description":"Whether the guest of a booking made from a request is written when it is cancelled."},"manualBookings":{"type":"string","enum":["always","after_confirmation","never"],"description":"For a manual booking: always, only when Keyset sent that guest the confirmation, or never."},"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`version` of getGuestCancellationMail as a string (\"0\" before the first save). A newer one answers VERSION_CONFLICT."}},"required":["requestBookings","manualBookings","expectedVersion"],"additionalProperties":false},"ApiGuestConfirmationRequest":{"type":"object","properties":{"sequence":{"type":"integer","minimum":1,"maximum":10000,"description":"Which confirmation this is for the booking (1 for the first); a repeat of a number sends nothing."},"paymentLink":{"type":"boolean","description":"true adds a link to pay what is open by card; it needs reservation.cancel as well."},"language":{"type":"string","enum":["de","en"],"description":"The mail’s language; the guest’s own where omitted."}},"required":["sequence","paymentLink"],"additionalProperties":false},"ApiGuestConfirmationSent":{"type":"object","properties":{"outcome":{"type":"string","enum":["requested","already_requested"]},"paymentLink":{"type":"boolean","description":"Whether the mail carries a payment link; false for `already_requested`."}},"required":["outcome","paymentLink"]},"ApiGuestContactChanged":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The contact’s new version; the contact itself is not echoed."},"outcome":{"type":"string","enum":["saved","unchanged"]}},"required":["reservationId","version","outcome"]},"ApiGuestContactChangeRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The contact’s `guest.version` as getReservationDetails gave it."},"firstName":{"type":"string","maxLength":200},"lastName":{"type":"string","maxLength":200},"email":{"type":["string","null"],"maxLength":400,"description":"A direct booking keeps an e-mail address."},"phone":{"type":["string","null"],"maxLength":80}},"required":["expectedVersion","firstName","lastName","email","phone"],"additionalProperties":false},"ApiGuestInfo":{"type":"object","properties":{"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before anything was saved."},"hostName":{"type":["string","null"]},"email":{"type":["string","null"],"description":"The host’s contact line on the booking page, not a guest’s."},"phone":{"type":["string","null"]},"imprintUrl":{"type":["string","null"]},"imprintText":{"type":["string","null"]},"privacyUrl":{"type":["string","null"]},"privacyText":{"type":["string","null"]},"cancellation":{"type":["object","null"],"properties":{"version":{"type":"integer","exclusiveMinimum":0},"origin":{"type":"string","description":"synthetic (Keyset’s default) or operator_decision."},"freeCancellationDays":{"type":"integer","minimum":0},"lateRefundBasisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["version","origin","freeCancellationDays","lateRefundBasisPoints"],"description":"The active cancellation terms the booking page states; read-only here."}},"required":["version","hostName","email","phone","imprintUrl","imprintText","privacyUrl","privacyText","cancellation"]},"ApiGuestInfoSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"]},"guestInfo":{"$ref":"#/components/schemas/ApiGuestInfo"}},"required":["outcome","guestInfo"]},"ApiGuestInfoSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,14})$","description":"The `version` the read gave; \"0\" before anything was saved. A newer one answers VERSION_CONFLICT."},"hostName":{"type":["string","null"],"maxLength":400,"description":"Who the guest books with; at most 120 characters once trimmed. Null or empty removes it."},"email":{"type":["string","null"],"maxLength":400,"description":"The host’s contact address on the booking page."},"phone":{"type":["string","null"],"maxLength":100,"description":"The host’s phone number, 5 to 30 characters."},"imprintUrl":{"type":["string","null"],"maxLength":1000,"description":"An https link to the Impressum (`www.…` is read as https); or imprintText, not both."},"imprintText":{"type":["string","null"],"maxLength":8000,"description":"The Impressum as text, at most 4000 characters."},"privacyUrl":{"type":["string","null"],"maxLength":1000,"description":"An https link to the privacy notice; or privacyText, not both."},"privacyText":{"type":["string","null"],"maxLength":60000,"description":"The privacy notice as text, at most 30000 characters."}},"required":["expectedVersion","hostName","email","phone","imprintUrl","imprintText","privacyUrl","privacyText"],"additionalProperties":false},"ApiGuestMailSenders":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["confirmation","cancellation","change","refund"],"description":"The kind of guest mail Keyset can write."},"sender":{"type":"string","enum":["keyset","own"],"description":"Who writes it: Keyset, or the business’s own system."},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."},"receiverReady":{"type":"boolean","description":"Whether an active webhook endpoint of the Property receives this kind’s event right now."},"fallbacks":{"type":"integer","minimum":0,"description":"Mails Keyset wrote itself in the last 30 days because none of an event’s deliveries arrived."}},"required":["kind","sender","version","receiverReady","fallbacks"]}}},"required":["kinds"]},"ApiGuestMailSenderSaveRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["confirmation","cancellation","change","refund"],"description":"The kind of guest mail, `kinds[].kind` of getGuestMailSenders."},"sender":{"type":"string","enum":["keyset","own"],"description":"Who writes it: Keyset, or the business’s own system through the kind’s webhook event (`own` needs an active endpoint receiving it)."},"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`kinds[].version` of getGuestMailSenders for this kind, as a string. A newer one answers VERSION_CONFLICT."}},"required":["kind","sender","expectedVersion"],"additionalProperties":false},"ApiGuestMessageSettings":{"type":"object","properties":{"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."},"property":{"type":"object","properties":{"name":{"type":"string"},"checkInTime":{"type":["string","null"]},"checkOutTime":{"type":["string","null"]}},"required":["name","checkInTime","checkOutTime"]},"preArrival":{"type":"object","properties":{"enabled":{"type":"boolean"},"daysBefore":{"type":"integer","minimum":1,"maximum":14,"description":"Days before arrival; sent at 10:00 at the Property."},"de":{"type":["string","null"],"description":"The host’s German text; null when none."},"en":{"type":["string","null"],"description":"The host’s English text; null when none."}},"required":["enabled","daysBefore","de","en"]},"postDeparture":{"type":"object","properties":{"enabled":{"type":"boolean"},"de":{"type":["string","null"]},"en":{"type":["string","null"]},"reviewUrl":{"type":["string","null"],"description":"The review link the thank-you carries; null when none."}},"required":["enabled","de","en","reviewUrl"]}},"required":["version","property","preArrival","postDeparture"]},"ApiGuestMessageSettingsSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"],"description":"`unchanged`: the texts were stored already and no `units` were sent; no new version. A save that sends `units` always answers `saved` with a new version, so the answer never tells whether a line equalled the stored one."},"version":{"type":"string","pattern":"^[1-9]\\d{0,17}$","description":"The version now in force, to send as the next `expectedVersion` (getGuestMessageSettings asks reservation.read). Always answered; optional in this schema only because it was added after the answer was first published."}},"required":["outcome"]},"ApiGuestMessageSettingsSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`version` of getGuestMessageSettings as a string (\"0\" before the first save). A newer one answers VERSION_CONFLICT."},"preArrival":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the message before arrival goes out; on needs a German text."},"daysBefore":{"type":"integer","minimum":1,"maximum":14,"description":"Days before arrival, 1 to 14; sent at 10:00 at the Property."},"de":{"type":["string","null"],"maxLength":4000,"description":"Up to 4000 characters; trimmed, line breaks kept; empty or null is none."},"en":{"type":["string","null"],"maxLength":4000,"description":"Up to 4000 characters; trimmed, line breaks kept; empty or null is none."}},"required":["enabled","daysBefore","de","en"],"additionalProperties":false},"postDeparture":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the thank-you after departure goes out; on needs a German text."},"de":{"type":["string","null"],"maxLength":4000,"description":"Up to 4000 characters; trimmed, line breaks kept; empty or null is none."},"en":{"type":["string","null"],"maxLength":4000,"description":"Up to 4000 characters; trimmed, line breaks kept; empty or null is none."},"reviewUrl":{"type":["string","null"],"maxLength":500,"description":"An https address the thank-you asks for a review at; empty or null is none."}},"required":["enabled","de","en","reviewUrl"],"additionalProperties":false},"units":{"type":"array","items":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid","description":"An apartment of this Property, `units[].id` of getPropertyConfiguration."},"de":{"type":["string","null"],"maxLength":1000,"description":"The line this apartment adds to the arrival message, up to 1000 characters; null removes the line."},"en":{"type":["string","null"],"maxLength":1000,"description":"Its English line; only beside a German one."}},"required":["unitId","de","en"],"additionalProperties":false},"maxItems":200,"description":"The apartment lines to set, each apartment once. An apartment not listed keeps its line; absent keeps them all."}},"required":["expectedVersion","preArrival","postDeparture"],"additionalProperties":false},"ApiGuestNoteRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^\\d{1,19}$","description":"The note’s version as getGuest gave it; \"0\" for a guest without a note."},"body":{"type":"string","maxLength":2000,"description":"The note; empty clears it. Preferences and arrangements, never health or payment data."}},"required":["expectedVersion","body"],"additionalProperties":false},"ApiGuestNoteSaved":{"type":"object","properties":{"guestId":{"type":"string","pattern":"^[0-9a-f]{32}$"},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The note’s new version; the note itself is not echoed."},"outcome":{"type":"string","enum":["saved","unchanged"]}},"required":["guestId","version","outcome"]},"ApiGuestPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiGuestSummary"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."}},"required":["data","hasMore","nextCursor"]},"ApiGuestPortal":{"type":"object","properties":{"canEdit":{"type":"boolean","description":"Whether this key may issue and revoke links (reservation.create_manual)."},"available":{"type":"boolean","description":"A link can be issued: a confirmed booking that is not an import."},"expiresOn":{"type":"string","format":"date","description":"The last day a link is valid, 30 days after departure."},"expired":{"type":"boolean"},"active":{"type":"integer","minimum":0,"description":"How many links are active; never the links themselves."},"lastIssuedAt":{"type":["string","null"],"format":"date-time"}},"required":["canEdit","available","expiresOn","expired","active","lastIssuedAt"]},"ApiGuestPortalLink":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"url":{"type":["string","null"],"description":"The guest’s link, shown once and never stored; null in a replay and where there is no guest site."},"token":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{43}$","description":"The link’s secret token, shown once and never stored; null in a replay."}},"required":["reservationId","url","token"]},"ApiGuestPortalRevoked":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"revoked":{"type":"integer","minimum":0,"description":"How many links stopped working."}},"required":["reservationId","revoked"]},"ApiGuestRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["cancelled","cancellation_request","message"]},"state":{"type":"string","enum":["open","closed"]},"reservationId":{"type":"string","format":"uuid"},"reservationNumber":{"type":"integer"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"unitName":{"type":["string","null"]},"guestName":{"type":["string","null"],"description":"Only with guest.read; null without it."},"note":{"type":["string","null"],"description":"What the guest wrote; only with guest.read, null without it."},"refund":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What a cancellation refunds; null for other kinds."},"createdAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"closedReason":{"type":["string","null"],"enum":["host","cancelled","answered",null]}},"required":["id","kind","state","reservationId","reservationNumber","checkIn","checkOut","unitName","guestName","note","refund","createdAt","closedAt","closedReason"]},"ApiGuestRequestClosed":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["closed","already_closed"]}},"required":["id","outcome"]},"ApiGuestRequestList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiGuestRequest"},"description":"The app’s “Zu erledigen”: open entries and recently closed ones."}},"required":["data"]},"ApiGuestSummary":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{32}$"},"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"email":{"type":["string","null"],"minLength":1},"phone":{"type":["string","null"],"minLength":1},"stays":{"type":"integer","minimum":0,"description":"Confirmed stays."},"lastCheckIn":{"type":["string","null"],"format":"date"},"nextCheckIn":{"type":["string","null"],"format":"date"},"bookings":{"type":"integer","minimum":0}},"required":["id","firstName","lastName","email","phone","stays","lastCheckIn","nextCheckIn","bookings"]},"ApiImportBatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["dry_run","committed"]},"format":{"type":"string","enum":["keyset.import.v1+json","keyset.import.v1+csv"]},"sourceSystem":{"type":"string"},"sourceReference":{"type":"string","description":"The file the batch came from."},"sourceDigest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the assessed bytes."},"summary":{"type":"object","properties":{"recordCount":{"type":"integer","minimum":0},"ready":{"type":"integer","minimum":0},"duplicate":{"type":"integer","minimum":0},"conflict":{"type":"integer","minimum":0},"unmapped":{"type":"integer","minimum":0},"invalid":{"type":"integer","minimum":0},"review":{"type":"integer","minimum":0},"ignored":{"type":"integer","minimum":0}},"required":["recordCount","ready","duplicate","conflict","unmapped","invalid","review","ignored"]},"reconciliation":{"type":["object","null"],"properties":{"imported":{"type":"integer","minimum":0},"idempotent":{"type":"integer","minimum":0},"conflicted":{"type":"integer","minimum":0},"skippedByDecision":{"type":"integer","minimum":0},"unresolved":{"type":"integer","minimum":0},"committedAt":{"type":"string","format":"date-time"},"stillOpen":{"type":"integer","minimum":0}},"required":["imported","idempotent","conflicted","skippedByDecision","unresolved","committedAt","stillOpen"],"description":"Present once the batch was committed."}},"required":["id","createdAt","state","format","sourceSystem","sourceReference","sourceDigest","summary","reconciliation"]},"ApiImportBatchDetails":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"batch":{"$ref":"#/components/schemas/ApiImportBatch"},"records":{"type":"array","items":{"$ref":"#/components/schemas/ApiImportRecord"},"description":"One row per source record, with the findings behind it."}},"required":["asOf","batch","records"]},"ApiImportBatchList":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"batches":{"type":"array","items":{"$ref":"#/components/schemas/ApiImportBatch"},"description":"Newest first."},"openDecisions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"batchId":{"type":"string","format":"uuid"},"recordId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer","minimum":1},"sourceReference":{"type":"string"},"checkIn":{"type":["string","null"],"format":"date"},"checkOut":{"type":["string","null"],"format":"date"},"unitReference":{"type":["string","null"]},"unitName":{"type":["string","null"]},"classification":{"type":"string","enum":["conflict","unmapped"]},"openedAt":{"type":"string","format":"date-time"}},"required":["id","batchId","recordId","rowNumber","sourceReference","checkIn","checkOut","unitReference","unitName","classification","openedAt"]},"description":"Bookings the host left unticked that still wait in Eingang. The guest’s name is not part of it."}},"required":["asOf","batches","openDecisions"]},"ApiImportCommitRequest":{"type":"object","properties":{"approvedDigest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"`batch.sourceDigest` of the report reviewed: a different file answers IMPORT_DIGEST_MISMATCH."},"approvedRecordIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":1000,"description":"The `recordId`s of the rows to take over („Übernehmen“ ticked), each once; a duplicate, invalid or ignored row is refused. A row left out is not taken over; a real booking left out that clashes or names no apartment waits in Eingang."}},"required":["approvedDigest","approvedRecordIds"],"additionalProperties":false},"ApiImportCommitted":{"type":"object","properties":{"outcome":{"type":"string","enum":["committed"]},"replayed":{"type":"boolean","description":"The batch was taken over before with exactly this approval; the counts are those of that commit."},"reconciliation":{"type":"object","properties":{"imported":{"type":"integer","minimum":0,"description":"Bookings and blocks created."},"idempotent":{"type":"integer","minimum":0,"description":"Rows an earlier import took over already, unchanged."},"conflicted":{"type":"integer","minimum":0,"description":"Bookings created on nights already taken or without an apartment: each opened a conflict."},"skippedByDecision":{"type":"integer","minimum":0,"description":"Rows not approved."},"unresolved":{"type":"integer","minimum":0,"description":"Rows that could not be taken over as they stand; nothing created."}},"required":["imported","idempotent","conflicted","skippedByDecision","unresolved"]}},"required":["outcome","replayed","reconciliation"]},"ApiImportDecisionDismissed":{"type":"object","properties":{"outcome":{"type":"string","enum":["dismissed","already_resolved"],"description":"`already_resolved`: a later import took the booking over, or it was let go before."}},"required":["outcome"]},"ApiImportDryRun":{"oneOf":[{"type":"object","properties":{"outcome":{"type":"string","enum":["staged"]},"asOf":{"type":"string","format":"date-time"},"batch":{"$ref":"#/components/schemas/ApiImportBatch"},"records":{"type":"array","items":{"$ref":"#/components/schemas/ApiImportRecord"},"description":"One row per source record, with the findings behind it."}},"required":["outcome","asOf","batch","records"]},{"type":"object","properties":{"outcome":{"type":"string","enum":["rejected"]},"asOf":{"type":"string","format":"date-time"},"rejections":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"EMPTY_SOURCE, MALFORMED_SOURCE, UNSUPPORTED_FORMAT, SOURCE_TOO_LARGE, TOO_MANY_RECORDS, MISSING_COLUMN, DUPLICATE_COLUMN or NO_RECORDS; treat an unknown value as “other”."},"detail":{"type":["string","null"],"description":"A column name, a count or a record position; never a value."}},"required":["code","detail"]},"minItems":1}},"required":["outcome","asOf","rejections"],"description":"The file cannot be read as a whole; nothing was kept."}]},"ApiImportDryRunRemoved":{"type":"object","properties":{"outcome":{"type":"string","enum":["removed"]}},"required":["outcome"]},"ApiImportDryRunRequest":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":200,"description":"The file’s name; the report names the batch after it."},"format":{"type":"string","enum":["keyset.import.v1+json","keyset.import.v1+csv"],"description":"Keyset’s import format, as JSON or as CSV."},"content":{"type":"string","minLength":1,"maxLength":524288,"description":"The file’s text, at most 512 KiB as UTF-8."}},"required":["filename","format","content"],"additionalProperties":false},"ApiImportRecord":{"type":"object","properties":{"recordId":{"type":["string","null"],"format":"uuid"},"row":{"type":"integer","minimum":1},"kind":{"type":["string","null"],"enum":["reservation","block",null]},"sourceId":{"type":"string"},"unitReference":{"type":["string","null"]},"unit":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"stay":{"type":["object","null"],"properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1}},"required":["checkIn","checkOut","nights"]},"status":{"type":["string","null"]},"blockKind":{"type":["string","null"],"enum":["owner_block","maintenance",null]},"amount":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":["string","null"]}},"required":["minorUnits","currency"]},"confirmationCode":{"type":["string","null"]},"occupancy":{"type":["object","null"],"properties":{"adults":{"type":["integer","null"]},"children":{"type":["integer","null"]}},"required":["adults","children"]},"guestContactSupplied":{"type":"object","properties":{"email":{"type":"boolean"},"phone":{"type":"boolean"}},"required":["email","phone"],"description":"Whether the file carried an e-mail address or a phone number; never the values."},"classification":{"type":"string","enum":["ready","duplicate","conflict","unmapped","invalid","review","ignored"]},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"For example UNKNOWN_UNIT, OVERLAPS_EXISTING_RESERVATION or PAST_STAY; treat an unknown value as “other”."},"severity":{"type":"string","enum":["blocking","decision","notice"]},"field":{"type":["string","null"]},"detail":{"type":["object","null"],"properties":{"unitReference":{"type":"string"},"unitId":{"type":"string","format":"uuid"},"reservationId":{"type":"string","format":"uuid"},"confirmationCode":{"type":"string"},"allocationId":{"type":"string","format":"uuid"},"blockId":{"type":"string","format":"uuid"},"batchId":{"type":"string","format":"uuid"},"row":{"type":"integer"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"value":{"type":"string"}}}},"required":["code","severity","field","detail"]}},"commitOutcome":{"type":["string","null"],"enum":["imported","idempotent","conflicted","skipped_by_decision","unresolved",null]},"businessObject":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["reservation","block"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"committedAt":{"type":["string","null"],"format":"date-time"},"laterState":{"type":["string","null"],"enum":["open","taken_over","let_go",null],"description":"For a booking the commit left out: waiting in Eingang, taken over by a later import, or let go."}},"required":["recordId","row","kind","sourceId","unitReference","unit","stay","status","blockKind","amount","confirmationCode","occupancy","guestContactSupplied","classification","findings","commitOutcome","businessObject","committedAt","laterState"]},"ApiInvoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["invoice","cancellation"],"description":"`cancellation` is the credit note of an invoice."},"number":{"type":"string"},"issueDate":{"type":"string","format":"date"},"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Gross; a credit note’s is negative."},"cancelsInvoiceId":{"type":["string","null"],"format":"uuid"},"cancelledBy":{"type":["string","null"],"description":"The number of the credit note that cancelled this invoice."},"mail":{"type":["string","null"],"enum":["pending","sent","failed","unknown",null],"description":"Its last mail; null when never sent."},"xrechnung":{"type":"boolean","description":"Whether getInvoiceXRechnung has a file for it."}},"required":["id","kind","number","issueDate","amount","cancelsInvoiceId","cancelledBy","mail","xrechnung"]},"ApiInvoiceIssued":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string","description":"The number PostgreSQL took, gapless per business."}},"required":["id","number"]},"ApiInvoiceIssueRequest":{"type":"object","properties":{"recipient":{"$ref":"#/components/schemas/ApiInvoiceRecipient"}},"required":["recipient"],"additionalProperties":false},"ApiInvoiceIssuerSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`version` of getInvoiceSettings (the issuer’s version)."},"issuerName":{"type":"string","minLength":1,"maxLength":120,"description":"The name on every invoice („Name auf der Rechnung“)."},"street":{"type":"string","minLength":1,"maxLength":120,"description":"Up to 120 characters, not only spaces."},"postalCode":{"type":"string","minLength":1,"maxLength":12,"description":"Up to 12 characters, not only spaces."},"city":{"type":"string","minLength":1,"maxLength":80,"description":"Up to 80 characters, not only spaces."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2."},"taxNumber":{"type":["string","null"],"minLength":1,"maxLength":40,"description":"The tax number (Steuernummer); null for none."},"vatId":{"type":["string","null"],"pattern":"^[A-Z]{2}[0-9A-Z+*.]{2,13}$","description":"The VAT id (USt-IdNr.); null for none."}},"required":["expectedVersion","issuerName","street","postalCode","city","country","taxNumber","vatId"],"additionalProperties":false},"ApiInvoiceMailRequested":{"type":"object","properties":{"outcome":{"type":"string","enum":["requested"],"description":"Queued; the mail goes out after the answer."}},"required":["outcome"]},"ApiInvoiceNumberingSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`numberingVersion` of getInvoiceSettings; every invoice issued moves it on."},"prefix":{"type":"string","pattern":"^[A-Za-z0-9/_-]{0,16}$","description":"Up to 16 letters, digits, `/`, `_` or `-`; the number follows with four digits: `RE-2026-0001`."},"nextNumber":{"type":"integer","minimum":1,"maximum":99999999,"description":"The number the next invoice gets."},"gapAcknowledged":{"type":"boolean","description":"That numbers are skipped on purpose. A next number beyond the one the numbering would give answers INVOICE_NUMBER_GAP without it; with it, the skipped numbers are recorded."}},"required":["expectedVersion","prefix","nextNumber","gapAcknowledged"],"additionalProperties":false},"ApiInvoiceRecipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"company":{"type":["string","null"],"minLength":1,"maxLength":120},"street":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":12},"city":{"type":"string","maxLength":80},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"vatId":{"type":["string","null"],"pattern":"^[A-Z]{2}[0-9A-Z+*.]{2,13}$"}},"required":["name","company","street","postalCode","city","country","vatId"],"additionalProperties":false},"ApiInvoiceSettings":{"type":"object","properties":{"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The issuer’s version."},"issuerName":{"type":["string","null"]},"street":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."},"taxNumber":{"type":["string","null"]},"vatId":{"type":["string","null"]},"prefix":{"type":"string"},"nextNumber":{"type":"integer","minimum":1},"issued":{"type":"integer","minimum":0,"description":"How many invoices and cancellations the business has issued."},"minimumNext":{"type":"integer","minimum":1,"description":"The smallest next number the numbering accepts with this prefix."},"numberingVersion":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."},"smallBusiness":{"type":"boolean","description":"Whether § 19 UStG (Kleinunternehmer) applies from the next invoice on."},"taxVersion":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."},"lastIssued":{"type":["object","null"],"properties":{"number":{"type":"string"},"kind":{"type":"string","enum":["invoice","cancellation"]},"issueDate":{"type":"string","format":"date"},"issuedAt":{"type":"string","format":"date-time"}},"required":["number","kind","issueDate","issuedAt"]}},"required":["version","issuerName","street","postalCode","city","country","taxNumber","vatId","prefix","nextNumber","issued","minimumNext","numberingVersion","smallBusiness","taxVersion","lastIssued"]},"ApiInvoiceSettingsSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"],"description":"`unchanged`: what was sent is what was stored; nothing changed."}},"required":["outcome"]},"ApiMediaGallery":{"type":"object","properties":{"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The gallery version a later write sends back as expectedVersion."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid"},"assetKey":{"type":"string","description":"The public key of the image; its variants live under /media/{assetKey}/."},"alt":{"type":"string"},"role":{"type":"string","enum":["cover","gallery"]},"sortOrder":{"type":"integer","minimum":0},"width":{"type":"integer","exclusiveMinimum":0},"height":{"type":"integer","exclusiveMinimum":0},"url":{"type":"string","description":"Path of the medium variant, `/media/{assetKey}/medium.webp`; no host."},"thumbnailUrl":{"type":"string","description":"Path of the thumbnail variant, `/media/{assetKey}/thumbnail.webp`."},"availability":{"type":"string","enum":["available","missing"]},"resolution":{"type":"string","enum":["sufficient","low"],"description":"`low`: narrower than the guest pages need, so they show it enlarged and soft."}},"required":["assetId","assetKey","alt","role","sortOrder","width","height","url","thumbnailUrl","availability","resolution"]},"description":"Cover first as the host ordered them; at most 20."}},"required":["version","images"]},"ApiMediaGalleryUpdateRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,14})$","description":"The `version` the read gave; \"0\" before anything was saved. A newer one answers VERSION_CONFLICT."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid","description":"A photo of this gallery, `images[].assetId` of its read."},"role":{"type":"string","enum":["cover","gallery"],"description":"Exactly one cover when there are photos."},"alt":{"type":"string","minLength":1,"maxLength":160,"description":"What the photo shows, for guests who cannot see it."}},"required":["assetId","role","alt"],"additionalProperties":false},"maxItems":20,"description":"The whole gallery in the order guests see it; a photo left out is removed from it."}},"required":["expectedVersion","images"],"additionalProperties":false},"ApiMediaUploaded":{"type":"object","properties":{"outcome":{"type":"string","enum":["created","existing"],"description":"`existing`: this upload intent was already placed; nothing was stored twice."},"assetId":{"type":"string","format":"uuid","description":"The uploaded photo, `images[].assetId` of the gallery."},"gallery":{"$ref":"#/components/schemas/ApiMediaGallery"}},"required":["outcome","assetId","gallery"]},"ApiMoney":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Integer minor units as a decimal string, plus the ISO 4217 currency."},"ApiMoved":{"type":"object","properties":{"outcome":{"type":"string","enum":["moved","already_moved"],"description":"`already_moved`: the first answer of the same key."},"reservationId":{"type":"string","format":"uuid"},"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"previousUnitId":{"type":["string","null"],"format":"uuid"},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"}},"required":["checkIn","checkOut"],"additionalProperties":false}},"required":["outcome","reservationId","unit","previousUnitId","stay"],"additionalProperties":false},"ApiMoveRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid","description":"One of the `targets` the read gave."}},"required":["unitId"],"additionalProperties":false},"ApiMoveTargets":{"type":"object","properties":{"reservation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1,"maximum":365}},"required":["checkIn","checkOut","nights"],"additionalProperties":false},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":0,"maximum":99},"children":{"type":"integer","minimum":0,"maximum":99},"known":{"type":"boolean","description":"False for a channel booking that carried no guest count."}},"required":["adults","children","known"],"additionalProperties":false},"placement":{"type":"string","enum":["unplaced","placed","cancelled"],"description":"Only an `unplaced` booking can be moved; the others come back with no targets."},"unit":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]}},"required":["id","number","stay","occupancy","placement","unit"],"additionalProperties":false},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"maxOccupancy":{"type":"integer","minimum":1,"maximum":99},"requested":{"type":"boolean","description":"The apartment the import or calendar named, free again."}},"required":["id","code","name","maxOccupancy","requested"]},"description":"Active apartments with no booking in any night of the stay when read. Advice, not a promise."},"asOf":{"type":"string","format":"date-time"}},"required":["reservation","targets","asOf"],"additionalProperties":false},"ApiNoShowAnswered":{"type":"object","properties":{"outcome":{"type":"string","enum":["marked","already_marked","reverted","already_confirmed"],"description":"A repeat of what already happened answers `already_…` with the current version."},"reservationVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The booking’s version after the change."}},"required":["outcome","reservationVersion"]},"ApiNoShowMarkRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The booking’s `version` as getReservationDetails gave it."},"note":{"type":["string","null"],"maxLength":500,"description":"What the host wants to remember; never shown to the guest and never echoed in an answer."}},"required":["expectedVersion"],"additionalProperties":false},"ApiNoShowRevertRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The booking’s `version` as getReservationDetails gave it."}},"required":["expectedVersion"],"additionalProperties":false},"ApiPaymentCurrencySaveRequest":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"An ISO 4217 code Keyset admits for a Property (today EUR); any other answers INVALID_REQUEST."},"expectedCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"`currency` of getPaymentSettings: the currency is its own version. Another one stored answers VERSION_CONFLICT."}},"required":["currency","expectedCurrency"],"additionalProperties":false},"ApiPaymentMethod":{"type":"string","enum":["cash","transfer","other"],"description":"How the money reached the host outside Keyset."},"ApiPaymentRecorded":{"type":"object","properties":{"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"receivedOn":{"type":"string","format":"date"},"method":{"$ref":"#/components/schemas/ApiPaymentMethod"}},"required":["id","amount","receivedOn","method"]},"receivedAmount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Every recorded payment of the booking that stands."},"outstandingAmount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What is still open after this payment."}},"required":["payment","receivedAmount","outstandingAmount"]},"ApiPaymentSettings":{"type":"object","properties":{"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["not_connected","processing","needs_information","in_review","ready","restricted","disconnected","currency_unsupported"],"description":"The state of the business’s payment account, as the app’s Zahlungen page shows it."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"country":{"type":["string","null"],"description":"The account’s country (ISO 3166-1 alpha-2); null while none is connected."},"chargesEnabled":{"type":"boolean"},"payoutsEnabled":{"type":"boolean"},"currencies":{"type":"array","items":{"type":"string"},"description":"The currencies the connected account can charge in."},"acceptsBookings":{"type":"boolean","description":"Whether a booking made now would find its payment account ready: guests can pay online."},"cancellationPolicy":{"type":["object","null"],"properties":{"version":{"type":"integer","minimum":1},"freeCancellationDays":{"type":"integer","minimum":0},"lateRefundPercent":{"type":"number","minimum":0,"maximum":100}},"required":["version","freeCancellationDays","lateRefundPercent"],"description":"The Property’s cancellation terms for card payments; null before they are saved."}},"required":["environment","status","currency","country","chargesEnabled","payoutsEnabled","currencies","acceptsBookings","cancellationPolicy"]},"ApiPaymentVoided":{"type":"object","properties":{"outcome":{"type":"string","enum":["voided","already_voided"]},"receivedAmount":{"$ref":"#/components/schemas/ApiMoney"},"outstandingAmount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["outcome","receivedAmount","outstandingAmount"]},"ApiPortalCommissionSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["configured","unchanged"]}},"required":["outcome"]},"ApiPortalCommissionSaveRequest":{"type":"object","properties":{"basisPoints":{"type":"integer","minimum":0,"maximum":5000,"description":"The commission a booking portal would take, in basis points (1500 = 15 %), at most 50 %."}},"required":["basisPoints"],"additionalProperties":false},"ApiPropertyConfiguration":{"type":"object","properties":{"property":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1},"timezone":{"type":"string","minLength":1},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"locale":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","disabled"]},"checkInTime":{"type":["string","null"]},"checkOutTime":{"type":["string","null"]},"businessProfile":{"type":"string","description":"The kind of business: holiday_apartments, guesthouse or holiday_home. It changes words, never rules."},"address":{"type":["object","null"],"properties":{"street":{"type":["string","null"]},"postalCode":{"type":"string"},"locality":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2; only DE for now."}},"required":["street","postalCode","locality","country"]}},"required":["id","name","timezone","currency","locale","status","checkInTime","checkOutTime","businessProfile","address"]},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"maxOccupancy":{"type":"integer","minimum":1},"status":{"type":"string","enum":["active","inactive"]},"futureAllocations":{"type":"integer","minimum":0,"description":"Holds, booked stays and blocks that end after the Property’s local today."},"bookedOccupancy":{"type":["integer","null"],"description":"The largest guest count among those future allocations; null when nothing is booked."},"onBookingSite":{"type":"boolean","description":"True when a guest can find the apartment on the booking site: published, active and priced."},"componentUnitIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The apartments a composite (the whole house) is made of; empty for a single apartment."}},"required":["id","code","name","maxOccupancy","status","futureAllocations","bookedOccupancy","onBookingSite","componentUnitIds"]},"description":"The apartments in use; an archived one is listed under archivedUnits."},"archivedUnits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"archivedAt":{"type":"string","format":"date-time"}},"required":["id","code","name","archivedAt"]}},"today":{"type":"string","format":"date","description":"The Property’s local date the unit facts were computed for."},"asOf":{"type":"string","format":"date-time"}},"required":["property","units","archivedUnits","today","asOf"]},"ApiPropertyConfigurationUpdateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The Property’s name, 1 to 120 characters."},"timezone":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z][A-Za-z0-9_+-]*(\\/[A-Za-z0-9_+-]+)*$","description":"An IANA time zone such as Europe/Berlin; an unknown zone answers INVALID_REQUEST."},"locale":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"The language Keyset writes to guests in, such as de-DE or en-GB."},"checkInTime":{"type":["string","null"],"pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"Anreise ab. Send it together with checkOutTime or neither: neither keeps both, null clears one."},"checkOutTime":{"type":["string","null"],"pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"Abreise bis. Sent together with checkInTime."},"businessProfile":{"type":"string","enum":["holiday_apartments","guesthouse","holiday_home"],"description":"Art des Betriebs; it changes words, never rules. Absent keeps it."},"address":{"type":["object","null"],"properties":{"street":{"type":["string","null"],"maxLength":120},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"locality":{"type":"string","minLength":1,"maxLength":80},"country":{"type":"string","enum":["DE"],"description":"Only DE for now."}},"required":["street","postalCode","locality","country"],"additionalProperties":false,"description":"Absent keeps the address, null clears it, an address replaces it whole."}},"required":["name","timezone","locale"],"additionalProperties":false},"ApiPropertyList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiPropertyListEntry"},"description":"At most 100 Properties, live ones first."}},"required":["data"]},"ApiPropertyListEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1},"timezone":{"type":"string","minLength":1},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"locale":{"type":"string","minLength":1},"checkInTime":{"type":["string","null"],"description":"Local time `HH:MM`; null when the host has not set one."},"checkOutTime":{"type":["string","null"],"description":"Local time `HH:MM`; null when the host has not set one."},"permissions":{"type":"array","items":{"type":"string"},"description":"The grants this key holds on the Property, e.g. property.read, property.configure, reservation.read, rates.publish, guest.read."},"business":{"type":"object","properties":{"name":{"type":"string","minLength":1},"mode":{"type":"string","enum":["live","test"],"description":"`test` for the business’s test twin."}},"required":["name","mode"]}},"required":["id","name","timezone","currency","locale","checkInTime","checkOutTime","permissions","business"]},"ApiProviderRefundRequest":{"type":"object","properties":{"amountMinorUnits":{"type":"string","pattern":"^[1-9]\\d{0,11}$","description":"What goes back, at most what the booking’s Keyset payments may still give back (EXCEEDS_REFUNDABLE names it)."},"note":{"type":"string","minLength":3,"maxLength":300,"description":"Why, in the host’s words (“Kulanz”, “Kurtaxe erstattet”); stored with the refund, never logged."},"notifyGuest":{"type":"boolean","description":"Whether Keyset mails the guest when the refund ends; absent is true."}},"required":["amountMinorUnits","note"],"additionalProperties":false},"ApiProviderRefundRequested":{"type":"object","properties":{"refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"state":{"type":"string","enum":["requested"],"description":"The provider is asked after the answer; follow it in getReservationDetails `refunds[]`."}},"required":["id","amount","state"]},"refundableAmount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What may still go back after this refund."}},"required":["refund","refundableAmount"]},"ApiPublishedRatesPreview":{"type":"object","properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$","description":"A published version of the apartment’s prices."},"evaluatorVersion":{"type":"string"},"evaluatedAt":{"type":"string","format":"date-time"},"scenarios":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1},"occupancy":{"type":"object","properties":{"adults":{"type":"integer"},"children":{"type":"integer"}},"required":["adults","children"]},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["priced"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"nightly_accommodation, weekend_adjustment, guest_surcharge, cleaning_fee, percentage_fee, discount, extra or tourist_tax."},"serviceDate":{"type":["string","null"],"format":"date","description":"The night a nightly line is for; null for a line of the stay."},"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["kind","serviceDate","label","amount"]}}},"required":["type","total","lines"]},{"type":"object","properties":{"type":{"type":"string","enum":["ineligible"]},"reason":{"type":"string","description":"minimum_stay_not_satisfied, maximum_stay_exceeded, arrival_day_not_allowed or departure_day_not_allowed."},"requiredNights":{"type":["integer","null"]},"maximumNights":{"type":["integer","null"]},"allowedDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."}}},"required":["type","reason","requiredNights","maximumNights","allowedDays"]},{"type":"object","properties":{"type":{"type":"string","enum":["invalid_configuration"]},"reason":{"type":"string"}},"required":["type","reason"]},{"type":"object","properties":{"type":{"type":"string","enum":["invalid_scenario"]}},"required":["type"]}],"description":"priced: the guest would pay `total`; ineligible: a stay rule refuses the stay; or why nothing is priced."}},"required":["checkIn","checkOut","nights","occupancy","outcome"]}}},"required":["version","evaluatorVersion","evaluatedAt","scenarios"]},"ApiPublishedRatesPreviewRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,9}$","description":"A published version of the apartment’s prices."},"scenarios":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date","description":"Exclusive, after checkIn; at most 31 nights."},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":99},"children":{"type":"integer","minimum":0,"maximum":99}},"required":["adults","children"],"additionalProperties":false}},"required":["checkIn","checkOut","occupancy"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"Up to 20 sample stays to price."},"stayRules":{"type":"string","enum":["apply","ignore"],"description":"ignore prices nights without minimum stay and arrival rules, as the editor’s price sheet does."}},"required":["expectedVersion","scenarios"],"additionalProperties":false},"ApiRateConfiguration":{"type":"object","properties":{"baseNightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."},"weekendDays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."}},"weekendAdjustmentMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Added to the base price on a weekend night; may be negative."},"absoluteOverrides":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date","description":"Exclusive: the period covers the nights [start, end)."},"nightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."},"label":{"type":["string","null"],"description":"The host’s name for the period, e.g. \"Herbstferien\"."}},"required":["ruleId","start","end","nightlyMinorUnits","label"]},"description":"Price periods: a nightly price that replaces the base price on those nights."},"cleaningFee":{"type":"object","properties":{"ruleId":{"type":"string"},"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."}},"required":["ruleId","minorUnits"]},"percentageFee":{"type":"object","properties":{"ruleId":{"type":"string"},"label":{"type":"string"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."},"bases":{"type":"array","items":{"type":"string"},"description":"nightly_accommodation, weekend_adjustment and/or cleaning_fee."},"roundingMode":{"type":"string","description":"down, half_up or up."}},"required":["ruleId","label","basisPoints","bases","roundingMode"]},"minimumStayNights":{"type":"integer"},"maximumStayNights":{"type":["integer","null"]},"arrivalDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"description":"Allowed weekdays; null is every day."},"departureDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"description":"Allowed weekdays; null is every day."},"minimumStayByArrivalDay":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"minimumStayNights":{"type":"integer"}},"required":["weekday","minimumStayNights"]},"description":"The minimum stay of an arrival on a weekday where it differs; empty for none."},"stayRulePeriods":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date","description":"Exclusive."},"minimumStayNights":{"type":"integer"},"maximumStayNights":{"type":["integer","null"]},"arrivalDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"description":"Allowed weekdays; null is every day."},"departureDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"description":"Allowed weekdays; null is every day."},"minimumStayByArrivalDay":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"minimumStayNights":{"type":"integer"}},"required":["weekday","minimumStayNights"]},"description":"The minimum stay of an arrival on a weekday where it differs; empty for none."},"label":{"type":["string","null"]}},"required":["ruleId","start","end","minimumStayNights","maximumStayNights","arrivalDays","departureDays","minimumStayByArrivalDay","label"]},"description":"Stay rules per period of nights, independent of the price periods."},"guestSurcharge":{"type":["object","null"],"properties":{"ruleId":{"type":"string"},"includedGuests":{"type":"integer"},"nightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Per further person and night."},"freeChildrenUnderAge":{"type":["integer","null"]},"childBands":{"type":"array","items":{"type":"object","properties":{"underAge":{"type":"integer"},"nightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."}},"required":["underAge","nightlyMinorUnits"]}}},"required":["ruleId","includedGuests","nightlyMinorUnits","freeChildrenUnderAge","childBands"]},"discounts":{"type":["object","null"],"properties":{"ruleId":{"type":"string"},"lengthOfStay":{"type":"array","items":{"type":"object","properties":{"minimumNights":{"type":"integer"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["minimumNights","basisPoints"]}},"earlyBird":{"type":["object","null"],"properties":{"minimumDaysBeforeArrival":{"type":"integer"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["minimumDaysBeforeArrival","basisPoints"]},"lastMinute":{"type":["object","null"],"properties":{"maximumDaysBeforeArrival":{"type":"integer"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["maximumDaysBeforeArrival","basisPoints"]}},"required":["ruleId","lengthOfStay","earlyBird","lastMinute"],"description":"Only the highest applicable discount counts."},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"pricing":{"type":"string","description":"per_stay, per_night or per_person_night."},"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."}},"required":["id","name","pricing","minorUnits"]}},"quoteLifetimeSeconds":{"type":"integer"}},"required":["baseNightlyMinorUnits","weekendDays","weekendAdjustmentMinorUnits","absoluteOverrides","cleaningFee","percentageFee","minimumStayNights","maximumStayNights","arrivalDays","departureDays","minimumStayByArrivalDay","stayRulePeriods","guestSurcharge","discounts","extras","quoteLifetimeSeconds"]},"ApiRateConfigurationInput":{"type":"object","properties":{"baseNightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."},"weekendDays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"maxItems":7},"weekendAdjustmentMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."},"absoluteOverrides":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string","minLength":1,"maxLength":200},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date","description":"Exclusive."},"nightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."},"label":{"type":["string","null"],"minLength":1,"maxLength":60}},"required":["ruleId","start","end","nightlyMinorUnits"],"additionalProperties":false},"maxItems":400,"description":"Price periods: a nightly price that replaces the base price on those nights."},"cleaningFee":{"type":"object","properties":{"ruleId":{"type":"string","minLength":1,"maxLength":200},"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."}},"required":["ruleId","minorUnits"],"additionalProperties":false},"percentageFee":{"type":"object","properties":{"ruleId":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."},"bases":{"type":"array","items":{"type":"string","enum":["nightly_accommodation","weekend_adjustment","cleaning_fee"]},"maxItems":3},"roundingMode":{"type":"string","enum":["down","half_up","up"]}},"required":["ruleId","label","basisPoints","bases","roundingMode"],"additionalProperties":false},"minimumStayNights":{"type":"integer"},"maximumStayNights":{"type":["integer","null"]},"arrivalDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"maxItems":7},"departureDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"maxItems":7},"minimumStayByArrivalDay":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"minimumStayNights":{"type":"integer"}},"required":["weekday","minimumStayNights"],"additionalProperties":false},"maxItems":7},"stayRulePeriods":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string","minLength":1,"maxLength":200},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date","description":"Exclusive."},"minimumStayNights":{"type":"integer"},"maximumStayNights":{"type":["integer","null"]},"arrivalDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"maxItems":7},"departureDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"maxItems":7},"minimumStayByArrivalDay":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."},"minimumStayNights":{"type":"integer"}},"required":["weekday","minimumStayNights"],"additionalProperties":false},"maxItems":7},"label":{"type":["string","null"],"minLength":1,"maxLength":60}},"required":["ruleId","start","end","minimumStayNights"],"additionalProperties":false},"maxItems":100},"guestSurcharge":{"type":["object","null"],"properties":{"ruleId":{"type":"string","minLength":1,"maxLength":200},"includedGuests":{"type":"integer"},"nightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."},"freeChildrenUnderAge":{"type":["integer","null"]},"childBands":{"type":"array","items":{"type":"object","properties":{"underAge":{"type":"integer"},"nightlyMinorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."}},"required":["underAge","nightlyMinorUnits"],"additionalProperties":false},"maxItems":2}},"required":["ruleId","includedGuests","nightlyMinorUnits","freeChildrenUnderAge"],"additionalProperties":false},"discounts":{"type":["object","null"],"properties":{"ruleId":{"type":"string","minLength":1,"maxLength":200},"lengthOfStay":{"type":"array","items":{"type":"object","properties":{"minimumNights":{"type":"integer"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["minimumNights","basisPoints"],"additionalProperties":false},"maxItems":2},"earlyBird":{"type":["object","null"],"properties":{"minimumDaysBeforeArrival":{"type":"integer"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["minimumDaysBeforeArrival","basisPoints"],"additionalProperties":false},"lastMinute":{"type":["object","null"],"properties":{"maximumDaysBeforeArrival":{"type":"integer"},"basisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["maximumDaysBeforeArrival","basisPoints"],"additionalProperties":false}},"required":["ruleId","lengthOfStay","earlyBird","lastMinute"],"additionalProperties":false},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9-]{1,40}$"},"name":{"type":"string","minLength":1,"maxLength":60},"pricing":{"type":"string","enum":["per_stay","per_night","per_person_night"]},"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$","description":"Integer minor units as a decimal string, in the Property's currency."}},"required":["id","name","pricing","minorUnits"],"additionalProperties":false},"maxItems":10},"quoteLifetimeSeconds":{"type":"integer"}},"required":["baseNightlyMinorUnits","weekendDays","weekendAdjustmentMinorUnits","absoluteOverrides","cleaningFee","percentageFee","minimumStayNights","quoteLifetimeSeconds"],"additionalProperties":false},"ApiRateDraft":{"type":"object","properties":{"revision":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The draft’s revision; every later draft write sends it back as expectedRevision."},"configuration":{"$ref":"#/components/schemas/ApiRateConfiguration"},"valid":{"type":"boolean","description":"False while the draft cannot be published; `invalidReason` says why."},"invalidReason":{"type":["string","null"]},"lastPublished":{"type":["object","null"],"properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$","description":"A published version of the apartment’s prices."},"revision":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The draft’s revision; every later draft write sends it back as expectedRevision."},"at":{"type":"string","format":"date-time"}},"required":["version","revision","at"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["revision","configuration","valid","invalidReason","lastPublished","createdAt","updatedAt"]},"ApiRateDraftDiscard":{"type":"object","properties":{"outcome":{"type":"string","enum":["discarded","reset","unchanged"],"description":"discarded: a never-published draft is gone (draft null). reset: the unpublished changes are gone and the draft holds the published rules again. unchanged: it already did."},"draft":{"allOf":[{"$ref":"#/components/schemas/ApiRateDraft"},{"type":["object","null"]}]}},"required":["outcome","draft"]},"ApiRateDraftDiscardRequest":{"type":"object","properties":{"expectedRevision":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The draft’s revision; every later draft write sends it back as expectedRevision."}},"required":["expectedRevision"],"additionalProperties":false},"ApiRateDraftPreview":{"type":"object","properties":{"revision":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The draft’s revision; every later draft write sends it back as expectedRevision."},"evaluatorVersion":{"type":"string"},"evaluatedAt":{"type":"string","format":"date-time"},"valid":{"type":"boolean"},"invalidReason":{"type":["string","null"]},"scenarios":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1},"occupancy":{"type":"object","properties":{"adults":{"type":"integer"},"children":{"type":"integer"}},"required":["adults","children"]},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["priced"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"nightly_accommodation, weekend_adjustment, guest_surcharge, cleaning_fee, percentage_fee, discount, extra or tourist_tax."},"serviceDate":{"type":["string","null"],"format":"date","description":"The night a nightly line is for; null for a line of the stay."},"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["kind","serviceDate","label","amount"]}}},"required":["type","total","lines"]},{"type":"object","properties":{"type":{"type":"string","enum":["ineligible"]},"reason":{"type":"string","description":"minimum_stay_not_satisfied, maximum_stay_exceeded, arrival_day_not_allowed or departure_day_not_allowed."},"requiredNights":{"type":["integer","null"]},"maximumNights":{"type":["integer","null"]},"allowedDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."}}},"required":["type","reason","requiredNights","maximumNights","allowedDays"]},{"type":"object","properties":{"type":{"type":"string","enum":["invalid_configuration"]},"reason":{"type":"string"}},"required":["type","reason"]},{"type":"object","properties":{"type":{"type":"string","enum":["invalid_scenario"]}},"required":["type"]}],"description":"priced: the guest would pay `total`; ineligible: a stay rule refuses the stay; or why nothing is priced."}},"required":["checkIn","checkOut","nights","occupancy","outcome"]}}},"required":["revision","evaluatorVersion","evaluatedAt","valid","invalidReason","scenarios"]},"ApiRateDraftPreviewRequest":{"type":"object","properties":{"expectedRevision":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The draft’s revision; every later draft write sends it back as expectedRevision."},"scenarios":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date","description":"Exclusive, after checkIn; at most 31 nights."},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":99},"children":{"type":"integer","minimum":0,"maximum":99}},"required":["adults","children"],"additionalProperties":false}},"required":["checkIn","checkOut","occupancy"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"Up to 20 sample stays to price."},"stayRules":{"type":"string","enum":["apply","ignore"],"description":"ignore prices nights without minimum stay and arrival rules, as the editor’s price sheet does."}},"required":["expectedRevision","scenarios"],"additionalProperties":false},"ApiRateDraftSaveRequest":{"type":"object","properties":{"expectedRevision":{"type":["string","null"],"pattern":"^[1-9]\\d{0,18}$","description":"null creates the draft; otherwise the revision you read."},"configuration":{"$ref":"#/components/schemas/ApiRateConfigurationInput"}},"required":["expectedRevision","configuration"],"additionalProperties":false},"ApiRateOverview":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"units":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"rateContextId":{"type":["string","null"],"description":"The rate context to read the apartment’s rates with; null while it was never priced."},"current":{"type":["object","null"],"properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$"},"publishedAt":{"type":"string","format":"date-time"},"baseNightly":{"$ref":"#/components/schemas/ApiMoney"},"minimumStayNights":{"type":"integer"},"weekendNightly":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Base plus the weekend adjustment; null without a weekend day or adjustment."},"seasonNightly":{"type":["object","null"],"properties":{"min":{"$ref":"#/components/schemas/ApiMoney"},"max":{"$ref":"#/components/schemas/ApiMoney"}},"required":["min","max"],"description":"Lowest and highest nightly price among the price periods not yet over; null without one."}},"required":["version","publishedAt","baseNightly","minimumStayNights","weekendNightly","seasonNightly"],"description":"The published price a guest pays today."},"draft":{"type":["object","null"],"properties":{"revision":{"type":"string","pattern":"^[1-9]\\d{0,18}$"},"updatedAt":{"type":"string","format":"date-time"},"baseNightly":{"$ref":"#/components/schemas/ApiMoney"},"valid":{"type":"boolean","description":"False while the draft cannot be published; `invalidReason` says why."},"invalidReason":{"type":["string","null"]},"unpublishedChanges":{"type":"boolean","description":"True while this exact revision is not published; guests still pay `current`."},"weekendNightly":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Base plus the weekend adjustment; null without a weekend day or adjustment."},"seasonNightly":{"type":["object","null"],"properties":{"min":{"$ref":"#/components/schemas/ApiMoney"},"max":{"$ref":"#/components/schemas/ApiMoney"}},"required":["min","max"],"description":"Lowest and highest nightly price among the price periods not yet over; null without one."}},"required":["revision","updatedAt","baseNightly","valid","invalidReason","unpublishedChanges","weekendNightly","seasonNightly"]}},"required":["unit","rateContextId","current","draft"]},"description":"The active apartments in code order."},"inactiveUnits":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"rateContextId":{"type":["string","null"]},"current":{"type":["object","null"],"properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$"},"publishedAt":{"type":"string","format":"date-time"},"baseNightly":{"$ref":"#/components/schemas/ApiMoney"},"minimumStayNights":{"type":"integer"},"weekendNightly":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Base plus the weekend adjustment; null without a weekend day or adjustment."},"seasonNightly":{"type":["object","null"],"properties":{"min":{"$ref":"#/components/schemas/ApiMoney"},"max":{"$ref":"#/components/schemas/ApiMoney"}},"required":["min","max"],"description":"Lowest and highest nightly price among the price periods not yet over; null without one."}},"required":["version","publishedAt","baseNightly","minimumStayNights","weekendNightly","seasonNightly"]}},"required":["unit","rateContextId","current"]},"description":"Apartments switched off, with the price they last published."},"evaluatorVersion":{"type":"string"},"asOf":{"type":"string","format":"date-time"}},"required":["currency","units","inactiveUnits","evaluatorVersion","asOf"]},"ApiRatePlanArchived":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"archived":{"type":"boolean","enum":[true]}},"required":["id","archived"]},"ApiRatePlanArchiveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."}},"required":["expectedVersion"],"additionalProperties":false},"ApiRatePlanRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"basisPoints":{"type":"integer","minimum":0,"maximum":9000,"description":"The discount on the accommodation in basis points."},"terms":{"type":"object","properties":{"freeCancellationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Days before arrival a guest cancels for free; null: never free."},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000,"description":"What is refunded after that."}},"required":["freeCancellationDays","lateRefundBasisPoints"],"additionalProperties":false},"excludedUnitIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":200,"description":"Apartments the plan is not offered for."}},"required":["name","basisPoints","terms","excludedUnitIds"],"additionalProperties":false},"ApiRatePlans":{"type":"object","properties":{"canManage":{"type":"boolean","description":"Whether this key may change them (rates.publish)."},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"standardTerms":{"type":["object","null"],"properties":{"freeCancellationDays":{"type":"integer","minimum":0},"lateRefundBasisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["freeCancellationDays","lateRefundBasisPoints"],"description":"The Property’s own cancellation terms, which the standard rate keeps; null when it has none."},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"name":{"type":"string"},"basisPoints":{"type":"integer","description":"The discount on the accommodation in basis points."},"version":{"type":"string","pattern":"^\\d{1,18}$"},"terms":{"type":"object","properties":{"freeCancellationDays":{"type":["integer","null"],"minimum":0,"description":"Null: the rate never allows free cancellation."},"lateRefundBasisPoints":{"type":"integer","description":"Basis points: 100 is one percent."}},"required":["freeCancellationDays","lateRefundBasisPoints"]},"excludedUnitIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Apartments the plan is not offered for."}},"required":["id","reference","name","basisPoints","version","terms","excludedUnitIds"]}}},"required":["canManage","units","standardTerms","plans"]},"ApiRatePlanSaved":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."}},"required":["id","version"]},"ApiRatePlanUpdateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"basisPoints":{"type":"integer","minimum":0,"maximum":9000,"description":"The discount on the accommodation in basis points."},"terms":{"type":"object","properties":{"freeCancellationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Days before arrival a guest cancels for free; null: never free."},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000,"description":"What is refunded after that."}},"required":["freeCancellationDays","lateRefundBasisPoints"],"additionalProperties":false},"excludedUnitIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":200,"description":"Apartments the plan is not offered for."},"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."}},"required":["name","basisPoints","terms","excludedUnitIds","expectedVersion"],"additionalProperties":false},"ApiRateProposalPreview":{"type":"object","properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$","description":"A published version of the apartment’s prices."},"evaluatorVersion":{"type":"string"},"evaluatedAt":{"type":"string","format":"date-time"},"valid":{"type":"boolean"},"invalidReason":{"type":["string","null"]},"scenarios":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1},"occupancy":{"type":"object","properties":{"adults":{"type":"integer"},"children":{"type":"integer"}},"required":["adults","children"]},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["priced"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"nightly_accommodation, weekend_adjustment, guest_surcharge, cleaning_fee, percentage_fee, discount, extra or tourist_tax."},"serviceDate":{"type":["string","null"],"format":"date","description":"The night a nightly line is for; null for a line of the stay."},"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["kind","serviceDate","label","amount"]}}},"required":["type","total","lines"]},{"type":"object","properties":{"type":{"type":"string","enum":["ineligible"]},"reason":{"type":"string","description":"minimum_stay_not_satisfied, maximum_stay_exceeded, arrival_day_not_allowed or departure_day_not_allowed."},"requiredNights":{"type":["integer","null"]},"maximumNights":{"type":["integer","null"]},"allowedDays":{"type":["array","null"],"items":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday."}}},"required":["type","reason","requiredNights","maximumNights","allowedDays"]},{"type":"object","properties":{"type":{"type":"string","enum":["invalid_configuration"]},"reason":{"type":"string"}},"required":["type","reason"]},{"type":"object","properties":{"type":{"type":"string","enum":["invalid_scenario"]}},"required":["type"]}],"description":"priced: the guest would pay `total`; ineligible: a stay rule refuses the stay; or why nothing is priced."}},"required":["checkIn","checkOut","nights","occupancy","outcome"]}}},"required":["version","evaluatorVersion","evaluatedAt","valid","invalidReason","scenarios"]},"ApiRateProposalPreviewRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,9}$","description":"The published version the proposal is evaluated on top of."},"configuration":{"$ref":"#/components/schemas/ApiRateConfigurationInput"},"scenarios":{"type":"array","items":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date","description":"Exclusive, after checkIn; at most 31 nights."},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":99},"children":{"type":"integer","minimum":0,"maximum":99}},"required":["adults","children"],"additionalProperties":false}},"required":["checkIn","checkOut","occupancy"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"Up to 20 sample stays to price."},"stayRules":{"type":"string","enum":["apply","ignore"],"description":"ignore prices nights without minimum stay and arrival rules, as the editor’s price sheet does."}},"required":["expectedVersion","configuration","scenarios"],"additionalProperties":false},"ApiRatePublication":{"type":"object","properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$","description":"The new published version; guests are quoted it from now on."},"previousVersion":{"type":["string","null"],"pattern":"^[1-9]\\d{0,9}$","description":"A published version of the apartment’s prices."},"publishedAt":{"type":"string","format":"date-time"},"draft":{"$ref":"#/components/schemas/ApiRateDraft"}},"required":["version","previousVersion","publishedAt","draft"]},"ApiRatePublishRequest":{"type":"object","properties":{"expectedRevision":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The draft revision you previewed."},"expectedCurrentVersion":{"type":["string","null"],"pattern":"^[1-9]\\d{0,9}$","description":"The version guests are quoted now; null for none."}},"required":["expectedRevision","expectedCurrentVersion"],"additionalProperties":false},"ApiRateScope":{"type":"object","properties":{"unit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"rateContextId":{"type":"string"},"evaluatorVersion":{"type":"string"},"current":{"type":["object","null"],"properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$"},"publishedAt":{"type":"string","format":"date-time"},"configuration":{"$ref":"#/components/schemas/ApiRateConfiguration"}},"required":["version","publishedAt","configuration"],"description":"The published rules; null while the apartment was never priced."},"draft":{"type":["object","null"],"properties":{"revision":{"type":"string","pattern":"^[1-9]\\d{0,18}$"},"configuration":{"$ref":"#/components/schemas/ApiRateConfiguration"},"valid":{"type":"boolean"},"invalidReason":{"type":["string","null"]},"lastPublished":{"type":["object","null"],"properties":{"version":{"type":"string","pattern":"^[1-9]\\d{0,9}$"},"revision":{"type":"string","pattern":"^[1-9]\\d{0,18}$"},"at":{"type":"string","format":"date-time"}},"required":["version","revision","at"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["revision","configuration","valid","invalidReason","lastPublished","createdAt","updatedAt"],"description":"The host’s working copy; never changes what a guest pays until it is published."}},"required":["unit","rateContextId","evaluatorVersion","current","draft"]},"ApiRecordedRefundVoided":{"type":"object","properties":{"outcome":{"type":"string","enum":["voided","already_voided"]},"refundableAmount":{"$ref":"#/components/schemas/ApiMoney"},"owedAmount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["outcome","refundableAmount","owedAmount"]},"ApiRecordPaymentRequest":{"type":"object","properties":{"amountMinorUnits":{"type":"string","pattern":"^[1-9]\\d{0,11}$","description":"Integer minor units of the booking’s currency as a decimal string, greater than zero."},"method":{"type":"string","enum":["cash","transfer","other"],"description":"`transfer` also marks an open bank transfer as received."},"receivedOn":{"type":"string","format":"date","description":"The Property’s local day the money arrived; absent is today, never later."}},"required":["amountMinorUnits","method"],"additionalProperties":false},"ApiRecordRefundRequest":{"type":"object","properties":{"amountMinorUnits":{"type":"string","pattern":"^[1-9]\\d{0,11}$","description":"Integer minor units of the booking’s currency as a decimal string, greater than zero."},"method":{"type":"string","enum":["cash","transfer","other"],"description":"Where the money went back."},"refundedOn":{"type":"string","format":"date","description":"The Property’s local day the money went back; absent is today."},"note":{"type":["string","null"],"maxLength":300,"description":"For the host; never echoed in an answer."}},"required":["amountMinorUnits","method"],"additionalProperties":false},"ApiRefundRecorded":{"type":"object","properties":{"refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"refundedOn":{"type":"string","format":"date"},"method":{"$ref":"#/components/schemas/ApiPaymentMethod"}},"required":["id","amount","refundedOn","method"]},"refundableAmount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What may still go back: what the guest still holds with the host."},"owedAmount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What a cancellation still owes back after this refund."}},"required":["refund","refundableAmount","owedAmount"]},"ApiReservationDetails":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001},"confirmationReference":{"type":"string","pattern":"^[A-Z0-9]{12}$"},"state":{"type":"string","enum":["confirmed","cancelled","no_show"]},"source":{"type":"string","enum":["direct","manual","import"]},"bookedVia":{"type":["string","null"],"enum":["request",null]},"importSource":{"type":["string","null"],"enum":["file","ical",null]},"inventoryResolution":{"type":"string","enum":["allocated","conflicted","unmapped","not_required"]},"unit":{"$ref":"#/components/schemas/ApiUnitRef"},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","exclusiveMinimum":0}},"required":["checkIn","checkOut","nights"]},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":0},"children":{"type":"integer","minimum":0},"known":{"type":"boolean"}},"required":["adults","children","known"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"paymentState":{"type":["string","null"],"enum":["created","requires_customer_action","processing","succeeded","failed","cancelled",null],"description":"The card payment of a direct booking; null for any other source."},"refundState":{"type":["string","null"],"enum":["requested","processing","unknown","succeeded","failed","needs_attention",null]},"receivedAmount":{"$ref":"#/components/schemas/ApiMoney"},"receivedOn":{"type":["string","null"],"format":"date","description":"The day the agreed total was reached; null while money is open."},"openAmount":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What a change left open of a direct booking, never below zero."},"transferDueOn":{"type":["string","null"],"format":"date"},"refundOwed":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What the host still owes back after a cancellation."},"guestName":{"type":["string","null"],"minLength":1,"description":"Only with guest.read; null without it, and for a booking that carries no guest name."},"confirmedAt":{"type":"string","format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"version":{"type":["string","null"],"pattern":"^[1-9]\\d{0,18}$","description":"Null for an imported booking, which is changed at its source."},"createdAt":{"type":"string","format":"date-time"},"guest":{"type":["object","null"],"properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"email":{"type":["string","null"],"minLength":1},"phone":{"type":["string","null"],"minLength":1},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The contact’s version, sent back as expectedVersion by changeGuestContact."}},"required":["firstName","lastName","email","phone"],"description":"Only with guest.read; null without it, and for a booking that carries no contact."},"price":{"type":"object","properties":{"total":{"$ref":"#/components/schemas/ApiMoney"},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["nightly_accommodation","weekend_adjustment","guest_surcharge","cleaning_fee","percentage_fee","discount","extra","tourist_tax"]},"label":{"type":"string","minLength":1},"serviceDate":{"type":["string","null"],"format":"date"},"amount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["kind","label","serviceDate","amount"]},"description":"The immutable quote a direct booking was taken at; empty for other sources."},"ratePlanName":{"type":["string","null"],"minLength":1},"discountCode":{"type":["string","null"],"minLength":1}},"required":["total","lines","ratePlanName","discountCode"]},"payment":{"type":["object","null"],"properties":{"state":{"type":"string","enum":["created","requires_customer_action","processing","succeeded","failed","cancelled"]},"succeededAt":{"type":["string","null"],"format":"date-time"}},"required":["state","succeededAt"],"description":"The card payment of a direct booking; null for other sources."},"recordedPayments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"receivedOn":{"type":"string","format":"date"},"method":{"type":"string","description":"cash, transfer or other."},"voided":{"type":"boolean"}},"required":["id","amount","receivedOn","method","voided"]}},"cardPayments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"receivedOn":{"type":"string","format":"date"},"refundedAmount":{"$ref":"#/components/schemas/ApiMoney"}},"required":["id","amount","receivedOn","refundedAmount"]},"description":"A manual booking's card payments through the host's payment link."},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reason":{"type":"string","description":"operator_cancellation, guest_cancellation, operator_goodwill, reservation_change, …"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"state":{"type":"string","enum":["requested","processing","unknown","succeeded","failed","needs_attention"]},"note":{"type":["string","null"]},"requestedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","reason","amount","state","note","requestedAt","completedAt"]}},"recordedRefunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"refundedOn":{"type":"string","format":"date"},"method":{"type":"string"},"note":{"type":["string","null"]},"forCancellation":{"type":"boolean"},"voided":{"type":"boolean"}},"required":["id","amount","refundedOn","method","note","forCancellation","voided"]},"description":"Money the host gave back outside Keyset."},"disputes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string"},"amount":{"$ref":"#/components/schemas/ApiMoney"},"reason":{"type":["string","null"]},"evidenceDueBy":{"type":["string","null"],"format":"date-time"},"openedAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","status","amount","reason","evidenceDueBy","openedAt","closedAt"]}},"balance":{"type":"object","properties":{"paidAmount":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Paid by card through Keyset (direct bookings)."},"refundableAmount":{"$ref":"#/components/schemas/ApiMoney"},"refundedAmount":{"$ref":"#/components/schemas/ApiMoney"},"owedAmount":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What the host still owes back outside Keyset."},"dueOn":{"type":["string","null"],"format":"date","description":"The day the rest of a deposit booking is charged."},"state":{"type":["string","null"],"enum":["scheduled","charging","paid","action_required","failed","cancelled",null]}},"required":["paidAmount","refundableAmount","refundedAmount","owedAmount","dueOn","state"]},"cancellation":{"type":["object","null"],"properties":{"cancelledAt":{"type":"string","format":"date-time"},"reason":{"type":"string"},"paymentHandling":{"type":"string","enum":["keyset","external"]},"policyLabel":{"type":["string","null"]},"refundAmount":{"$ref":"#/components/schemas/ApiMoney"},"feeAmount":{"$ref":"#/components/schemas/ApiMoney"},"refundState":{"type":["string","null"],"enum":["requested","processing","unknown","succeeded","failed","needs_attention",null]}},"required":["cancelledAt","reason","paymentHandling","policyLabel","refundAmount","feeAmount","refundState"]},"changes":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","exclusiveMinimum":0},"changedAt":{"type":"string","format":"date-time"},"from":{"type":"object","properties":{"unitId":{"type":["string","null"],"format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"total":{"$ref":"#/components/schemas/ApiMoney"}},"required":["unitId","checkIn","checkOut","total"]},"to":{"type":"object","properties":{"unitId":{"type":["string","null"],"format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"total":{"$ref":"#/components/schemas/ApiMoney"}},"required":["unitId","checkIn","checkOut","total"]},"priceReason":{"type":["string","null"]}},"required":["sequence","changedAt","from","to","priceReason"]}},"noShowMarkedAt":{"type":["string","null"],"format":"date-time"},"arrivedAt":{"type":["string","null"],"format":"date-time"},"departedAt":{"type":["string","null"],"format":"date-time"},"stayVersion":{"type":"string","pattern":"^\\d{1,19}$","description":"The recorded stay’s version, sent back as expectedVersion by recordStay; \"0\" while nothing is recorded."}},"required":["id","number","confirmationReference","state","source","bookedVia","importSource","inventoryResolution","unit","stay","occupancy","total","paymentState","refundState","receivedAmount","receivedOn","openAmount","transferDueOn","refundOwed","guestName","confirmedAt","cancelledAt","version","createdAt","guest","price","payment","recordedPayments","cardPayments","refunds","recordedRefunds","disputes","balance","cancellation","changes","noShowMarkedAt","arrivedAt","departedAt"]},"ApiReservationGuestMessages":{"type":"object","properties":{"canEdit":{"type":"boolean","description":"Whether this key may switch the messages (reservation.create_manual)."},"source":{"type":"string","enum":["direct","manual","import"]},"lifecycle":{"type":"string","enum":["confirmed","cancelled","no_show"]},"timezone":{"type":"string","description":"The Property’s time zone the due times belong to."},"hasEmail":{"type":"boolean","description":"Whether the booking has an address a message can go to; the address is not shown."},"off":{"type":"boolean","description":"The host switched this booking’s automatic messages off."},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The next `expectedVersion` of setReservationGuestMessages."},"messages":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["pre_arrival","post_departure"]},"enabled":{"type":"boolean","description":"Whether the Property sends this kind at all."},"dueAt":{"type":"string","format":"date-time"},"scheduledAt":{"type":["string","null"],"format":"date-time"},"state":{"type":["string","null"],"enum":["pending","retry_wait","unknown_outcome","succeeded","quarantined",null]},"sentAt":{"type":["string","null"],"format":"date-time"}},"required":["kind","enabled","dueAt","scheduledAt","state","sentAt"]}}},"required":["canEdit","source","lifecycle","timezone","hasEmail","off","version","messages"]},"ApiReservationGuestMessagesSaved":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["saved","unchanged"]}},"required":["reservationId","outcome"]},"ApiReservationGuestMessagesSetRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^\\d{1,19}$","description":"The `version` of getReservationGuestMessages."},"off":{"type":"boolean","description":"true switches this booking’s automatic messages off, false on."}},"required":["expectedVersion","off"],"additionalProperties":false},"ApiReservationInvoices":{"type":"object","properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/ApiInvoice"},"description":"Every invoice and credit note of the booking, oldest first."},"contactName":{"type":["string","null"],"description":"The guest’s name from the booking, to prefill the recipient."},"missing":{"type":"array","items":{"type":"string"},"description":"What an invoice still needs apart from the recipient: `issuer:<field>`, `issuer:tax`, `item:<kind>`."},"canIssue":{"type":"boolean","description":"Confirmed and without an invoice that is not cancelled."},"canMail":{"type":"boolean","description":"The booking has a guest address an invoice can be sent to."},"previousRecipient":{"type":["object","null"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"company":{"type":["string","null"],"minLength":1,"maxLength":120},"street":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":12},"city":{"type":"string","maxLength":80},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"vatId":{"type":["string","null"],"pattern":"^[A-Z]{2}[0-9A-Z+*.]{2,13}$"},"number":{"type":"string"},"issueDate":{"type":"string","format":"date"}},"required":["name","company","street","postalCode","city","country","vatId","number","issueDate"],"additionalProperties":false,"description":"The recipient of the guest’s newest earlier invoice at this Property, to prefill the next one."}},"required":["invoices","contactName","missing","canIssue","canMail","previousRecipient"]},"ApiReservationPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiReservationSummary"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."}},"required":["data","hasMore","nextCursor"]},"ApiReservationSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1001},"confirmationReference":{"type":"string","pattern":"^[A-Z0-9]{12}$"},"state":{"type":"string","enum":["confirmed","cancelled","no_show"]},"source":{"type":"string","enum":["direct","manual","import"]},"bookedVia":{"type":["string","null"],"enum":["request",null]},"importSource":{"type":["string","null"],"enum":["file","ical",null]},"inventoryResolution":{"type":"string","enum":["allocated","conflicted","unmapped","not_required"]},"unit":{"$ref":"#/components/schemas/ApiUnitRef"},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","exclusiveMinimum":0}},"required":["checkIn","checkOut","nights"]},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":0},"children":{"type":"integer","minimum":0},"known":{"type":"boolean"}},"required":["adults","children","known"]},"total":{"$ref":"#/components/schemas/ApiMoney"},"paymentState":{"type":["string","null"],"enum":["created","requires_customer_action","processing","succeeded","failed","cancelled",null],"description":"The card payment of a direct booking; null for any other source."},"refundState":{"type":["string","null"],"enum":["requested","processing","unknown","succeeded","failed","needs_attention",null]},"receivedAmount":{"$ref":"#/components/schemas/ApiMoney"},"receivedOn":{"type":["string","null"],"format":"date","description":"The day the agreed total was reached; null while money is open."},"openAmount":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What a change left open of a direct booking, never below zero."},"transferDueOn":{"type":["string","null"],"format":"date"},"refundOwed":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What the host still owes back after a cancellation."},"guestName":{"type":["string","null"],"minLength":1,"description":"Only with guest.read; null without it, and for a booking that carries no guest name."},"confirmedAt":{"type":"string","format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"}},"required":["id","number","confirmationReference","state","source","bookedVia","importSource","inventoryResolution","unit","stay","occupancy","total","paymentState","refundState","receivedAmount","receivedOn","openAmount","transferDueOn","refundOwed","guestName","confirmedAt","cancelledAt"]},"ApiReservationTouristTax":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"canEdit":{"type":"boolean","description":"Whether this key may change the party (reservation.create_manual)."},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The host’s party’s version, sent back by saveReservationTouristTax; \"0\" before."},"source":{"type":"string","enum":["direct","manual","import"]},"party":{"type":["object","null"],"properties":{"adults":{"type":"integer","minimum":0},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17}},"exempt":{"type":"integer","minimum":0},"reason":{"type":["string","null"],"enum":["disability","business","resident","other",null]},"note":{"type":["string","null"]},"fromHost":{"type":"boolean","description":"false: the booking’s own party counts, nothing was entered."}},"required":["adults","childAges","exempt","reason","note","fromHost"]},"persons":{"type":["object","null"],"properties":{"adultRate":{"type":"integer","minimum":0},"childRate":{"type":"integer","minimum":0},"free":{"type":"integer","minimum":0},"exempt":{"type":"integer","minimum":0}},"required":["adultRate","childRate","free","exempt"]},"hasRules":{"type":"boolean"},"collection":{"type":"string","enum":["in_price","on_site"]},"due":{"$ref":"#/components/schemas/ApiMoney"},"paid":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"The tourist tax paid with the booking (its quote line)."},"refundSuggestion":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What an exemption took off a tax paid with the booking, less what was already given back, at most what may still be refunded: the amount to send with refundThroughProvider."},"refunded":{"$ref":"#/components/schemas/ApiMoney"},"refundOpen":{"type":["object","null"],"properties":{"amount":{"$ref":"#/components/schemas/ApiMoney"},"state":{"type":"string","enum":["requested","unknown"]}},"required":["amount","state"],"description":"A tourist tax refund whose outcome is open; send none while it is."}},"required":["currency","canEdit","version","source","party","persons","hasRules","collection","due","paid","refundSuggestion","refunded","refundOpen"]},"ApiReservationTouristTaxSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"]}},"required":["outcome"]},"ApiReservationTouristTaxSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^\\d{1,19}$"},"adults":{"type":"integer","minimum":0,"maximum":99},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":99},"exempt":{"type":"integer","minimum":0,"maximum":198},"reason":{"type":["string","null"],"enum":["disability","business","resident","other",null]},"note":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Required for `other`, else null."}},"required":["expectedVersion","adults","childAges","exempt","reason","note"],"additionalProperties":false},"ApiReservationTransferInstruction":{"type":"object","properties":{"instruction":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"reservationId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["issued","settled","superseded","cancelled"]},"holder":{"type":"string","minLength":1},"ibanMasked":{"type":"string","minLength":5,"description":"The IBAN the guest is told, masked to its first and last digits as getTransferDetails shows it."},"detailsChanged":{"type":"boolean","description":"The Property’s bank details changed since; the guest still pays to these."},"reference":{"type":"string","minLength":1,"maxLength":140,"description":"`KS-<booking number> <last name>` in the SEPA character set."},"issuedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"instalments":{"type":"array","items":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/ApiMoney"},"dueOn":{"type":"string","format":"date"},"open":{"$ref":"#/components/schemas/ApiMoney"}},"required":["amount","dueOn","open"]},"minItems":1,"maxItems":2},"expected":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What it still asks for."},"dueOn":{"type":["string","null"],"format":"date"},"overdue":{"type":"boolean"},"outdated":{"type":"boolean","description":"The booking now has more open than it asks for; issue it again."}},"required":["id","reservationId","state","holder","ibanMasked","detailsChanged","reference","issuedAt","endedAt","instalments","expected","dueOn","overdue","outdated"],"description":"The current instruction, else the one the cancellation ended; null when the booking never had one."}},"required":["instruction"]},"ApiSearchIndexing":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether search engines may list the published booking page."}},"required":["enabled"]},"ApiSmallBusinessExample":{"type":"object","properties":{"example":{"type":["object","null"],"properties":{"bookingNumber":{"type":"integer","minimum":1},"invoiceNumber":{"type":["string","null"],"description":"The invoice the example is made from; null for a booking without one."},"smallBusiness":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"The line as the invoice prints it (the apartment and nights, a fee, an extra)."},"rate":{"type":["integer","null"],"description":"VAT rate in percent; null on a small-business invoice."},"gross":{"$ref":"#/components/schemas/ApiMoney"},"touristTax":{"type":"boolean","description":"The tourist tax, passed through (durchlaufender Posten)."}},"required":["description","rate","gross","touristTax"]}},"taxGroups":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"integer"},"gross":{"$ref":"#/components/schemas/ApiMoney"},"net":{"$ref":"#/components/schemas/ApiMoney"},"tax":{"$ref":"#/components/schemas/ApiMoney"}},"required":["rate","gross","net","tax"]}},"total":{"$ref":"#/components/schemas/ApiMoney"},"tax":{"$ref":"#/components/schemas/ApiMoney"},"notes":{"type":"array","items":{"type":"string"},"description":"The notes the invoice prints, such as the § 19 UStG sentence."}},"required":["lines","taxGroups","total","tax","notes"],"description":"The invoice as a small business."},"withTax":{"type":["object","null"],"properties":{"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"The line as the invoice prints it (the apartment and nights, a fee, an extra)."},"rate":{"type":["integer","null"],"description":"VAT rate in percent; null on a small-business invoice."},"gross":{"$ref":"#/components/schemas/ApiMoney"},"touristTax":{"type":"boolean","description":"The tourist tax, passed through (durchlaufender Posten)."}},"required":["description","rate","gross","touristTax"]}},"taxGroups":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"integer"},"gross":{"$ref":"#/components/schemas/ApiMoney"},"net":{"$ref":"#/components/schemas/ApiMoney"},"tax":{"$ref":"#/components/schemas/ApiMoney"}},"required":["rate","gross","net","tax"]}},"total":{"$ref":"#/components/schemas/ApiMoney"},"tax":{"$ref":"#/components/schemas/ApiMoney"},"notes":{"type":"array","items":{"type":"string"},"description":"The notes the invoice prints, such as the § 19 UStG sentence."}},"required":["lines","taxGroups","total","tax","notes"],"description":"The invoice with VAT; null while an item has no rate (`missing`)."},"missing":{"type":"array","items":{"type":"string"},"description":"`item:<kind>` for every item of the booking without a VAT rate."}},"required":["bookingNumber","invoiceNumber","smallBusiness","withTax","missing"],"description":"Null while the Property has no confirmed booking with a price."}},"required":["example"]},"ApiSmallBusinessSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"`taxVersion` of getInvoiceSettings."},"smallBusiness":{"type":"boolean","description":"Whether § 19 UStG (Kleinunternehmer) applies from the next invoice issued."}},"required":["expectedVersion","smallBusiness"],"additionalProperties":false},"ApiSplitPaymentPolicy":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether guests may split the payment between them."},"version":{"type":["string","null"],"pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion; null before the first save."}},"required":["enabled","version"]},"ApiSplitPaymentPolicySaveRequest":{"type":"object","properties":{"expectedVersion":{"type":["string","null"],"pattern":"^[1-9]\\d{0,8}$","description":"`version` of getSplitPaymentPolicy; null while it is null. A newer one answers VERSION_CONFLICT."},"enabled":{"type":"boolean","description":"Whether guests may split the payment of a booking between them."}},"required":["expectedVersion","enabled"],"additionalProperties":false},"ApiStayAnalytics":{"type":"object","properties":{"month":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"previousMonth":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"nextMonth":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Null 24 months after the Property’s current month."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"commissionBasisPoints":{"type":"integer","minimum":0,"maximum":5000},"months":{"type":"array","items":{"$ref":"#/components/schemas/ApiStayAnalyticsMonth"},"description":"The twelve months up to `month`, oldest first."}},"required":["month","previousMonth","nextMonth","currency","commissionBasisPoints","months"]},"ApiStayAnalyticsMonth":{"type":"object","properties":{"month":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"blockedNights":{"type":"integer","minimum":0},"availableNights":{"type":"integer"},"soldNights":{"type":"integer","minimum":0},"occupancyBasisPoints":{"type":["integer","null"],"minimum":0,"description":"Sold ÷ available in basis points; null without an available night."},"revenue":{"type":"object","properties":{"direct":{"$ref":"#/components/schemas/ApiMoney"},"manual":{"$ref":"#/components/schemas/ApiMoney"},"import":{"$ref":"#/components/schemas/ApiMoney"},"total":{"$ref":"#/components/schemas/ApiMoney"}},"required":["direct","manual","import","total"]},"averageNightly":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Revenue ÷ the priced bookings’ nights; null without such a night."},"revenuePerAvailableNight":{"$ref":"#/components/schemas/ApiMoney"},"directShareBasisPoints":{"type":["integer","null"],"minimum":0,"maximum":10000},"savedCommission":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Direct revenue × the commission rate: what a portal would have taken."},"cancellationFees":{"$ref":"#/components/schemas/ApiMoney"},"arrivals":{"type":"integer","minimum":0}},"required":["month","blockedNights","availableNights","soldNights","occupancyBasisPoints","revenue","averageNightly","revenuePerAvailableNight","directShareBasisPoints","savedCommission","cancellationFees","arrivals"]},"ApiStayRecorded":{"type":"object","properties":{"outcome":{"type":"string","enum":["recorded","unchanged"],"description":"`unchanged`: the stay already said so; the answer shows it as it stands."},"stay":{"type":"object","properties":{"arrivedAt":{"type":["string","null"],"format":"date-time"},"departedAt":{"type":["string","null"],"format":"date-time"},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The next `expectedVersion`."}},"required":["arrivedAt","departedAt","version"]}},"required":["outcome","stay"]},"ApiStayRecordRequest":{"type":"object","properties":{"action":{"type":"string","enum":["arrived","departed","undo_arrival","undo_departure"],"description":"What the host saw, or which recorded fact to take back."},"expectedVersion":{"type":"string","pattern":"^\\d{1,19}$","description":"The booking’s `stayVersion` as getReservationDetails gave it; \"0\" while nothing is recorded."}},"required":["action","expectedVersion"],"additionalProperties":false},"ApiSwitchRequest":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"ApiTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["cleaning","maintenance","custom"]},"title":{"type":"string"},"note":{"type":["string","null"],"description":"The host’s own note on the task."},"dueOn":{"type":"string","format":"date"},"state":{"type":"string","enum":["open","done","cancelled"]},"unitId":{"type":["string","null"],"format":"uuid"},"unitName":{"type":["string","null"]},"reservationId":{"type":["string","null"],"format":"uuid","description":"The booking a cleaning follows."},"reservationNumber":{"type":["integer","null"]},"nextArrival":{"type":["object","null"],"properties":{"date":{"type":"string","format":"date"},"time":{"type":["string","null"]}},"required":["date","time"],"description":"The next confirmed arrival in the same apartment: the deadline for a cleaning."},"assignee":{"type":["object","null"],"properties":{"membershipId":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["membershipId","name"],"description":"A team member."},"helper":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"description":"A helper without an account."},"checks":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","minimum":0},"label":{"type":"string"},"done":{"type":"boolean"}},"required":["position","label","done"]}},"version":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"The optimistic version a later write sends back as expectedVersion."},"doneAt":{"type":["string","null"],"format":"date-time"},"canManage":{"type":"boolean"},"canComplete":{"type":"boolean"}},"required":["id","kind","title","note","dueOn","state","unitId","unitName","reservationId","reservationNumber","nextArrival","assignee","helper","checks","version","doneAt","canManage","canComplete"]},"ApiTaskBoard":{"type":"object","properties":{"canManage":{"type":"boolean"},"today":{"type":"string","format":"date","description":"The Property’s local today."},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"assignees":{"type":"array","items":{"type":"object","properties":{"membershipId":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["membershipId","name"]},"description":"Who can be assigned."},"helpers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"linkIssuedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","name","linkIssuedAt"]}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/ApiTask"}}},"required":["canManage","today","units","assignees","helpers","tasks"]},"ApiTaskChecked":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0,"maximum":49},"done":{"type":"boolean"},"outcome":{"type":"string","enum":["saved"]}},"required":["id","position","done","outcome"]},"ApiTaskChecklists":{"type":"object","properties":{"default":{"type":["array","null"],"items":{"type":"string"},"description":"The Property’s default cleaning checklist; null when none."},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"items":{"type":["array","null"],"items":{"type":"string"},"description":"This apartment’s own checklist; null when it uses the default."}},"required":["id","name","items"]}}},"required":["default","units"]},"ApiTaskChecklistSaveRequest":{"type":"object","properties":{"unitId":{"type":["string","null"],"format":"uuid","description":"The apartment whose own list this is, `units[].id` of getTaskChecklists; null for the default list."},"items":{"type":"array","items":{"type":"string","maxLength":400},"maxItems":50,"description":"The points in order, up to 50, each 1 to 200 characters once trimmed (another answers INVALID_REQUEST). An empty list removes the list: the apartment then follows the default list."}},"required":["unitId","items"],"additionalProperties":false},"ApiTaskCheckRequest":{"type":"object","properties":{"done":{"type":"boolean","description":"true ticks the checklist item, false clears it."}},"required":["done"],"additionalProperties":false},"ApiTaskCompleted":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"done":{"type":"boolean"},"outcome":{"type":"string","enum":["saved"]}},"required":["id","done","outcome"]},"ApiTaskCompleteRequest":{"type":"object","properties":{"done":{"type":"boolean","description":"true completes the task, false reopens it."}},"required":["done"],"additionalProperties":false},"ApiTaskCreated":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]},"ApiTaskCreateRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["maintenance","custom"],"description":"A cleaning task is made by Keyset after each departure, never here."},"title":{"type":"string","minLength":1,"maxLength":400,"description":"The task’s title, at most 400 characters."},"note":{"type":["string","null"],"maxLength":4000,"description":"The host’s own note on the task; null is none."},"dueOn":{"type":"string","format":"date"},"unitId":{"type":["string","null"],"format":"uuid","description":"An apartment of the Property; null is a task for the whole Property."},"assigneeMembershipId":{"type":["string","null"],"format":"uuid","description":"A team member from the board’s `assignees`; null is none. A task has a member or a helper, never both."},"helperId":{"type":["string","null"],"format":"uuid","description":"A helper from the board’s `helpers`; null is none."},"checklist":{"type":"array","items":{"type":"string","maxLength":400},"maxItems":50,"description":"The checklist items in order; at most 50."}},"required":["kind","title","note","dueOn","unitId","assigneeMembershipId","helperId","checklist"],"additionalProperties":false},"ApiTaskDeleted":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["deleted"]}},"required":["id","outcome"]},"ApiTaskHelperAddRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The helper’s name, 1–80 characters."}},"required":["name"],"additionalProperties":false},"ApiTaskHelperLink":{"type":"object","properties":{"helperId":{"type":"string","format":"uuid"},"url":{"type":["string","null"],"description":"The helper’s link, shown once and never stored; null in a replay and where there is no guest site."},"token":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{43}$","description":"The link’s secret token, shown once and never stored; null in a replay."}},"required":["helperId","url","token"]},"ApiTaskHelperRemoved":{"type":"object","properties":{"helperId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["removed"]}},"required":["helperId","outcome"]},"ApiTaskProblem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"taskId":{"type":"string","format":"uuid"},"taskTitle":{"type":"string"},"taskKind":{"type":"string","enum":["cleaning","maintenance","custom"]},"dueOn":{"type":"string","format":"date"},"unitName":{"type":["string","null"]},"text":{"type":["string","null"],"description":"What was reported; null for a key without guest.read."},"reportedAt":{"type":"string","format":"date-time"},"reporterName":{"type":["string","null"],"description":"Who reported it; null for a key without guest.read."},"closedAt":{"type":["string","null"],"format":"date-time","description":"Null while the problem is open."}},"required":["id","taskId","taskTitle","taskKind","dueOn","unitName","text","reportedAt","reporterName","closedAt"]},"ApiTaskProblemClosed":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["closed"]}},"required":["id","outcome"]},"ApiTaskProblemReported":{"type":"object","properties":{"taskId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["reported"]}},"required":["taskId","outcome"]},"ApiTaskProblemReportRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4000,"description":"What is wrong, 1–4000 characters."}},"required":["text"],"additionalProperties":false},"ApiTaskProblems":{"type":"object","properties":{"canClose":{"type":"boolean","description":"Whether this key may close a problem (closeTaskProblem)."},"problems":{"type":"array","items":{"$ref":"#/components/schemas/ApiTaskProblem"},"description":"The open problems and those closed in the last 30 days, as the app lists them."}},"required":["canClose","problems"]},"ApiTaskSaved":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["saved"]}},"required":["id","outcome"]},"ApiTaskUpdateRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^\\d{1,18}$","description":"The task’s `version` as the board gave it; PostgreSQL checks it again under its row lock."},"title":{"type":"string","minLength":1,"maxLength":400,"description":"The task’s title, at most 400 characters."},"note":{"type":["string","null"],"maxLength":4000,"description":"The host’s own note on the task; null is none."},"dueOn":{"type":"string","format":"date","description":"Ignored for a cleaning task, whose day follows its booking."},"assigneeMembershipId":{"type":["string","null"],"format":"uuid","description":"A team member from the board’s `assignees`; null is none. A task has a member or a helper, never both."},"helperId":{"type":["string","null"],"format":"uuid","description":"A helper from the board’s `helpers`; null is none."}},"required":["expectedVersion","title","note","dueOn","assigneeMembershipId","helperId"],"additionalProperties":false},"ApiTeam":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"description":"The business’s Properties this key reads; the team is shown on these only."},"members":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid","description":"Stable per person and business; no account or sign-in identifier."},"role":{"type":"string","enum":["owner","manager","staff","viewer"]},"name":{"type":["string","null"],"description":"The display name the person gave; null when none."},"propertyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Which of `properties` the person works on."}},"required":["memberId","role","name","propertyIds"]},"description":"The active people of the business on those Properties, owners first. No e-mail address, invitation or link."}},"required":["properties","members"]},"ApiTestConflictCreated":{"type":"object","properties":{"outcome":{"type":"string","enum":["created"]},"reservationId":{"type":"string","format":"uuid","description":"The booking from outside; the conflict case and its attention item point at it."}},"required":["outcome","reservationId"]},"ApiTestScenarioArmRequest":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ApiTestScenarioKind"}},"required":["kind"],"additionalProperties":false},"ApiTestScenarioKind":{"type":"string","enum":["payment_unknown","refund_failed","webhook_failure"],"description":"`payment_unknown`: the next payment’s answer is lost and stays unknown until reconciliation; `refund_failed`: the next refund is refused by the provider; `webhook_failure`: the next event’s deliveries are answered 500 on their first three attempts."},"ApiTestScenarioOutcome":{"type":"object","properties":{"outcome":{"type":"string","enum":["armed","already_armed","withdrawn","not_armed"]}},"required":["outcome"]},"ApiTestTwin":{"type":"object","properties":{"mode":{"type":"string","enum":["live","test"],"description":"Whether this Property’s business is the live one or its test twin."},"twinExists":{"type":"boolean","description":"Whether the live business has an active test twin (in the twin: always true)."},"canArm":{"type":"boolean","description":"Whether this key may arm and withdraw cases and make a conflict here: a test key with configure."},"canReset":{"type":"boolean","description":"Whether this key may reset the twin: a test key with configure whose creator still owns the live business."},"armed":{"type":"array","items":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ApiTestScenarioKind"},"armedAt":{"type":"string","format":"date-time"}},"required":["kind","armedAt"]},"description":"The cases armed for the twin’s next matching operation; empty in the live business."}},"required":["mode","twinExists","canArm","canReset","armed"]},"ApiTestTwinReset":{"type":"object","properties":{"outcome":{"type":"string","enum":["created"]},"propertyId":{"type":"string","format":"uuid","description":"The fresh twin’s copy of the live business’s first Property its creator owns."},"reachableByThisKey":{"type":"boolean","enum":[false],"description":"Always false: this key cannot reach the new Property. Keys do not widen their own reach; issue a key for it in the app."}},"required":["outcome","propertyId","reachableByThisKey"]},"ApiTouristTax":{"type":"object","properties":{"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before anything was saved."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"canConfigure":{"type":"boolean","description":"Whether this key may change it (property.configure)."},"settings":{"type":["object","null"],"properties":{"collection":{"type":"string","enum":["in_price","on_site"],"description":"`in_price`: a line of the booking’s price; `on_site`: shown to the guest, paid on arrival."},"childAgeLimits":{"type":"array","items":{"type":"integer"},"description":"Ascending exclusive upper age limits of the child bands; at or above the last, the adult rate."},"rates":{"type":"object","properties":{"adult":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Per adult and night."},"children":{"type":"array","items":{"$ref":"#/components/schemas/ApiMoney"},"description":"Per child and night, one per age band in `childAgeLimits`’ order."}},"required":["adult","children"]},"season":{"type":["object","null"],"properties":{"from":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$","description":"`MM-DD`, inclusive; may wrap the year end."},"to":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"},"rates":{"type":"object","properties":{"adult":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Per adult and night."},"children":{"type":"array","items":{"$ref":"#/components/schemas/ApiMoney"},"description":"Per child and night, one per age band in `childAgeLimits`’ order."}},"required":["adult","children"]}},"required":["from","to","rates"],"description":"The main season; null is one rate all year."},"maximumNights":{"type":["integer","null"],"description":"Only the first this many nights are taxed; null for all."},"change":{"type":["object","null"],"properties":{"from":{"type":"string","format":"date"},"rates":{"type":"object","properties":{"adult":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Per adult and night."},"children":{"type":"array","items":{"$ref":"#/components/schemas/ApiMoney"},"description":"Per child and night, one per age band in `childAgeLimits`’ order."}},"required":["adult","children"]},"season":{"type":["object","null"],"properties":{"from":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$","description":"`MM-DD`, inclusive; may wrap the year end."},"to":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"},"rates":{"type":"object","properties":{"adult":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"Per adult and night."},"children":{"type":"array","items":{"$ref":"#/components/schemas/ApiMoney"},"description":"Per child and night, one per age band in `childAgeLimits`’ order."}},"required":["adult","children"]}},"required":["from","to","rates"]}},"required":["from","rates","season"],"description":"A planned new rate: every night from `from` pays these rates and this season."}},"required":["collection","childAgeLimits","rates","season","maximumNights","change"],"description":"Null while the Property charges no tourist tax."},"changeDroppable":{"type":"boolean","description":"Whether the planned change’s day is still ahead and it may be dropped."}},"required":["version","currency","canConfigure","settings","changeDroppable"]},"ApiTouristTaxChangeDiscarded":{"type":"object","properties":{"outcome":{"type":"string","enum":["discarded"]},"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"The version now in force, to send as the next `expectedVersion`; \"0\" while it was never saved. Always answered; optional in this schema only because it was added after the answer was first published."}},"required":["outcome"]},"ApiTouristTaxChangeDiscardRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,8}$","description":"`version` of getTouristTax. A newer one answers VERSION_CONFLICT."}},"required":["expectedVersion"],"additionalProperties":false},"ApiTouristTaxSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"],"description":"`unchanged`: the rates stored already; no new version."},"version":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"The version now in force, to send as the next `expectedVersion`; \"0\" while it was never saved. Always answered; optional in this schema only because it was added after the answer was first published."}},"required":["outcome"]},"ApiTouristTaxSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})$","description":"`version` of getTouristTax; \"0\" before the first save. A newer one answers VERSION_CONFLICT."},"settings":{"type":["object","null"],"properties":{"collection":{"type":"string","enum":["in_price","on_site"],"description":"`in_price`: a line of the booking’s price; `on_site`: shown to the guest, paid on arrival."},"childAgeLimits":{"type":"array","items":{"type":"integer","minimum":1,"maximum":18},"maxItems":3,"description":"Ascending exclusive upper age limits of the child bands, each 1 to 18; 18 is „under 18“."},"rates":{"type":"object","properties":{"adultMinorUnits":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Per adult and night; greater than zero."},"childMinorUnits":{"type":"array","items":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Integer minor units of the Property’s currency as a decimal string, such as \"250\" for 2.50 EUR."},"maxItems":3,"description":"Per child and night, one per band of `childAgeLimits` in its order; \"0\" frees the band."}},"required":["adultMinorUnits","childMinorUnits"],"additionalProperties":false,"description":"The rates all year, or outside the main season."},"season":{"type":["object","null"],"properties":{"from":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$","description":"`MM-DD`, inclusive; the season may wrap the year end."},"to":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$","description":"`MM-DD`, inclusive; the season may wrap the year end."},"rates":{"type":"object","properties":{"adultMinorUnits":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Per adult and night; greater than zero."},"childMinorUnits":{"type":"array","items":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Integer minor units of the Property’s currency as a decimal string, such as \"250\" for 2.50 EUR."},"maxItems":3,"description":"Per child and night, one per band of `childAgeLimits` in its order; \"0\" frees the band."}},"required":["adultMinorUnits","childMinorUnits"],"additionalProperties":false}},"required":["from","to","rates"],"additionalProperties":false,"description":"The main season and its rates; null is one rate all year."},"maximumNights":{"type":["integer","null"],"minimum":1,"maximum":3650,"description":"Only the first this many nights are taxed; null taxes every night."},"change":{"type":["object","null"],"properties":{"from":{"type":"string","format":"date","description":"The Property’s local day the new rates start („Gilt ab“)."},"rates":{"type":"object","properties":{"adultMinorUnits":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Per adult and night; greater than zero."},"childMinorUnits":{"type":"array","items":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Integer minor units of the Property’s currency as a decimal string, such as \"250\" for 2.50 EUR."},"maxItems":3,"description":"Per child and night, one per band of `childAgeLimits` in its order; \"0\" frees the band."}},"required":["adultMinorUnits","childMinorUnits"],"additionalProperties":false},"season":{"type":["object","null"],"properties":{"from":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$","description":"`MM-DD`, inclusive; the season may wrap the year end."},"to":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$","description":"`MM-DD`, inclusive; the season may wrap the year end."},"rates":{"type":"object","properties":{"adultMinorUnits":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Per adult and night; greater than zero."},"childMinorUnits":{"type":"array","items":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})$","description":"Integer minor units of the Property’s currency as a decimal string, such as \"250\" for 2.50 EUR."},"maxItems":3,"description":"Per child and night, one per band of `childAgeLimits` in its order; \"0\" frees the band."}},"required":["adultMinorUnits","childMinorUnits"],"additionalProperties":false}},"required":["from","to","rates"],"additionalProperties":false}},"required":["from","rates","season"],"additionalProperties":false,"description":"A planned new rate: every night from `from` pays these rates and this season; the bands stay. Null or absent plans none."}},"required":["collection","childAgeLimits","rates","season","maximumNights"],"additionalProperties":false,"description":"Null switches the tourist tax off."}},"required":["expectedVersion","settings"],"additionalProperties":false},"ApiTransferDetails":{"type":"object","properties":{"configured":{"type":"boolean","description":"Whether the host’s bank details for transfers are set."},"holder":{"type":["string","null"]},"ibanMasked":{"type":["string","null"],"description":"The IBAN as the app shows it, first and last digits only."},"version":{"type":"string","pattern":"^\\d{1,19}$","description":"The optimistic version a later write sends back as expectedVersion; \"0\" before the first save."},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["configured","holder","ibanMasked","version","updatedAt"]},"ApiTransferInstruction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reservationId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["issued","settled","superseded","cancelled"]},"holder":{"type":"string","minLength":1},"ibanMasked":{"type":"string","minLength":5,"description":"The IBAN the guest is told, masked to its first and last digits as getTransferDetails shows it."},"detailsChanged":{"type":"boolean","description":"The Property’s bank details changed since; the guest still pays to these."},"reference":{"type":"string","minLength":1,"maxLength":140,"description":"`KS-<booking number> <last name>` in the SEPA character set."},"issuedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"instalments":{"type":"array","items":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/ApiMoney"},"dueOn":{"type":"string","format":"date"},"open":{"$ref":"#/components/schemas/ApiMoney"}},"required":["amount","dueOn","open"]},"minItems":1,"maxItems":2},"expected":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^-?(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"description":"What it still asks for."},"dueOn":{"type":["string","null"],"format":"date"},"overdue":{"type":"boolean"},"outdated":{"type":"boolean","description":"The booking now has more open than it asks for; issue it again."}},"required":["id","reservationId","state","holder","ibanMasked","detailsChanged","reference","issuedAt","endedAt","instalments","expected","dueOn","overdue","outdated"]},"ApiTransferInstructionIssued":{"type":"object","properties":{"instruction":{"$ref":"#/components/schemas/ApiTransferInstruction"}},"required":["instruction"]},"ApiTransferInstructionRequest":{"type":"object","properties":{"expectedInstructionId":{"type":["string","null"],"format":"uuid","description":"The current instruction’s id as getReservationTransferInstruction gave it; null when there was none."},"dueOn":{"type":["string","null"],"format":"date","description":"A manual booking’s due date; absent, seven days from today. A re-issue keeps its bank details."}},"required":["expectedInstructionId"],"additionalProperties":false},"ApiUnitArchive":{"type":"object","properties":{"archived":{"type":"boolean"},"openBookings":{"type":"integer","minimum":0,"description":"Holds, bookings and parts of a composite booking on it that are not cancelled and end after today."},"partOf":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"description":"The apartments not archived that it is part of („Besteht aus“)."}},"required":["archived","openBookings","partOf"]},"ApiUnitArchived":{"type":"object","properties":{"outcome":{"type":"string","enum":["archived","unchanged"]}},"required":["outcome"]},"ApiUnitBookable":{"type":"object","properties":{"status":{"type":"string","enum":["active","inactive"],"description":"`active` is „Buchbar“ on."},"bookings":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"],"format":"uuid","description":"The booking’s id; null without reservation.read."},"number":{"type":["integer","null"],"minimum":1,"description":"The booking number; null without reservation.read."},"ref":{"type":"string","format":"uuid","description":"An opaque reference of this booking, the same for every key and every read: send it in `seen`. It names no booking anywhere else."},"guestName":{"type":["string","null"],"description":"The guest’s name; null without guest.read, and for a booking that carries none (an import)."},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"via":{"type":["string","null"],"description":"The composite booked, where the apartment is booked as a part of it („Ganzes Haus“)."}},"required":["id","number","ref","guestName","checkIn","checkOut","via"]},"description":"The bookings ahead on the apartment. They stay whatever the switch says; send their refs as `seen`."},"holds":{"type":"integer","minimum":0,"description":"Holds still running on the apartment; they may still become bookings."},"blocks":{"type":"integer","minimum":0,"description":"Blocks ahead on the apartment; they stay."},"partOf":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"description":"The bookable apartments this one is part of: they take no booking either while it is off."},"partsOff":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"description":"The parts of this composite that are off: it takes no booking while they are."},"published":{"type":"boolean","description":"On a published booking page."},"priced":{"type":"boolean","description":"With a published price."},"siteEmptied":{"type":"boolean","description":"Switching it off leaves the published booking page with no apartment a guest can book."},"subscription":{"type":"object","properties":{"apartmentsNow":{"type":"integer","minimum":0},"apartmentsAfter":{"type":"integer","minimum":0}},"required":["apartmentsNow","apartmentsAfter"],"description":"The apartments the Keyset subscription counts now and after the switch (the billing rule’s own count), as the app shows a team member who is not the owner. Amounts, the plan and every change to the subscription stay in the app with the owner."}},"required":["status","bookings","holds","blocks","partOf","partsOff","published","priced","siteEmptied","subscription"]},"ApiUnitBookableRequest":{"type":"object","properties":{"status":{"type":"string","enum":["active","inactive"]},"seen":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":2000,"description":"The `ref` of every booking in `bookings` from getUnitBookable (a booking’s `id` counts as well). Switching off is refused (BOOKINGS_CHANGED) while a booking ahead stands that is not in it."}},"required":["status","seen"],"additionalProperties":false},"ApiUnitBookableSwitched":{"type":"object","properties":{"outcome":{"type":"string","enum":["switched","unchanged"]}},"required":["outcome"]},"ApiUnitComponentsRequest":{"type":"object","properties":{"componentUnitIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"The active single apartments this one is made of („Besteht aus“); empty makes it single again."}},"required":["componentUnitIds"],"additionalProperties":false},"ApiUnitComponentsSaved":{"type":"object","properties":{"outcome":{"type":"string","enum":["saved","unchanged"]}},"required":["outcome"]},"ApiUnitContentSaveRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,18})$","description":"The `version` the read gave; \"0\" before anything was saved. A newer one answers VERSION_CONFLICT."},"content":{"type":"object","properties":{"description":{"type":["string","null"],"minLength":1,"maxLength":400},"amenities":{"type":"array","items":{"type":"string","enum":["wifi","parking","ev_charging","kitchen","dishwasher","coffee_machine","washing_machine","dryer","tv","workspace","heating","air_conditioning","balcony","terrace","garden","barbecue","sauna","pool","bed_linen","towels","baby_cot","high_chair","step_free","elevator","bike_storage","pets_allowed","non_smoking"]},"maxItems":40},"sleepingArrangement":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["bedroom","living_room"]},"beds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["double","single","sofa_bed","bunk"]},"count":{"type":"integer","minimum":1,"maximum":8}},"required":["kind","count"],"additionalProperties":false},"minItems":1,"maxItems":4}},"required":["kind","beds"],"additionalProperties":false},"maxItems":8,"description":"Räume: each room with its beds."},"floorArea":{"type":["integer","null"],"minimum":1,"maximum":2000,"description":"Wohnfläche in whole square metres."},"translations":{"type":"object","properties":{"en":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"minLength":1,"maxLength":400}},"additionalProperties":false,"description":"The host’s English; null or absent leaves it German."}},"additionalProperties":false}},"required":["description","amenities","sleepingArrangement","floorArea","translations"],"additionalProperties":false}},"required":["expectedVersion","content"],"additionalProperties":false},"ApiUnitCreated":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/ApiConfiguredUnit"}},"required":["unit"]},"ApiUnitCreateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The apartment’s name, 1 to 120 characters."},"maxOccupancy":{"type":"integer","minimum":1,"maximum":99,"description":"The most guests the apartment takes, 1 to 99."},"code":{"type":"string","maxLength":40,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"The import code. Absent: derived from the name (`Haus am See` → `haus-am-see`, the next free suffix if taken). Named: exactly this code, or UNIT_CODE_TAKEN."}},"required":["name","maxOccupancy"],"additionalProperties":false},"ApiUnitRef":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["id","code","name"]},"ApiUnitRestored":{"type":"object","properties":{"outcome":{"type":"string","enum":["restored","unchanged"]}},"required":["outcome"]},"ApiUnitUpdated":{"type":"object","properties":{"outcome":{"type":"string","enum":["configured","unchanged"]},"unit":{"$ref":"#/components/schemas/ApiConfiguredUnit"}},"required":["outcome","unit"]},"ApiUnitUpdateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The apartment’s name, 1 to 120 characters."},"maxOccupancy":{"type":"integer","minimum":1,"maximum":99,"description":"The most guests the apartment takes, 1 to 99."}},"required":["name","maxOccupancy"],"additionalProperties":false},"ApiWebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string","pattern":"^evt_[a-f0-9]{32}$","description":"The message’s `webhook-id`; a resend keeps it, so a receiver can drop a repeat."},"type":{"type":"string","pattern":"^[a-z_]+\\.[a-z_]+$","description":"An event type of the catalogue, or `webhook.test` for a test delivery."},"state":{"type":"string","enum":["pending","retry_wait","succeeded","failed"],"description":"`retry_wait`: an attempt failed and the next is planned; `failed`: 8 attempts or 24 hours were spent."},"attemptCount":{"type":"integer","minimum":0},"lastStatus":{"type":["integer","null"],"description":"The receiver’s last HTTP status; never its body."},"lastError":{"type":["string","null"],"description":"Why it did not arrive: http_status, timeout, network, unsafe_address, retry_budget_exhausted, endpoint_disabled or key_inactive (made with a key that was revoked, expired or may not read the event); an unknown value is \"other\"."},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"nextAttemptAt":{"type":["string","null"],"format":"date-time"},"resendOf":{"type":["string","null"],"format":"uuid","description":"The delivery this one resends."},"reservationNumber":{"type":["integer","null"],"description":"The booking the event is about; null for an event about none. A key sees only the deliveries of events it may receive."}},"required":["id","eventId","type","state","attemptCount","lastStatus","lastError","createdAt","lastAttemptAt","deliveredAt","nextAttemptAt","resendOf","reservationNumber"]},"ApiWebhookDeliveryPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiWebhookDelivery"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."}},"required":["data","hasMore","nextCursor"]},"ApiWebhookDeliveryQueued":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid","description":"The new delivery; it goes out within seconds, signed as every delivery."}},"required":["deliveryId"]},"ApiWebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","description":"The receiving address: in full only in the answer of the request that added it; everywhere else (reads, changes, a renewed secret, a replay) its scheme and host with the path and query masked as `/…`, since an address can carry a token."},"host":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string","pattern":"^[a-z_]+\\.[a-z_]+$","description":"One of the catalogue’s event types (`ApiWebhookEventType`); read an unknown one as a type added later."},"minItems":1},"description":{"type":["string","null"]},"secretHint":{"type":"string","description":"The signing secret’s last four characters, to tell two apart; never the secret."},"state":{"type":"string","enum":["active","disabled"]},"version":{"type":"string","pattern":"^[1-9]\\d{0,17}$","description":"The endpoint’s version; send it back as `expectedVersion` to change the endpoint."},"createdAt":{"type":"string","format":"date-time"},"previousSecretUntil":{"type":["string","null"],"format":"date-time","description":"After a rotation: until when the replaced secret still signs beside the new one (24 hours)."},"lastDelivery":{"type":["object","null"],"properties":{"state":{"type":"string","enum":["pending","retry_wait","succeeded","failed"],"description":"`retry_wait`: an attempt failed and the next is planned; `failed`: 8 attempts or 24 hours were spent."},"at":{"type":"string","format":"date-time"}},"required":["state","at"]},"failedLastDay":{"type":"integer","minimum":0,"description":"Deliveries that ended `failed` in the last 24 hours."}},"required":["id","url","host","eventTypes","description","secretHint","state","version","createdAt","previousSecretUntil","lastDelivery","failedLastDay"]},"ApiWebhookEndpointCreateRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2000,"description":"An https address on a public host; no user name or password, no fragment."},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/ApiWebhookEventType"},"minItems":1,"maxItems":25},"description":{"type":["string","null"],"maxLength":100}},"required":["url","eventTypes"],"additionalProperties":false},"ApiWebhookEndpointDeleted":{"type":"object","properties":{"outcome":{"type":"string","enum":["deleted"]}},"required":["outcome"]},"ApiWebhookEndpointList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiWebhookEndpoint"},"maxItems":10}},"required":["data"]},"ApiWebhookEndpointUpdateRequest":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9]\\d{0,17}$","description":"The endpoint’s version; send it back as `expectedVersion` to change the endpoint."},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/ApiWebhookEventType"},"minItems":1,"maxItems":25},"description":{"type":["string","null"],"maxLength":100},"state":{"type":"string","enum":["active","disabled"],"description":"`disabled` pauses the endpoint; its open deliveries end `failed`."}},"required":["expectedVersion","eventTypes","description","state"],"additionalProperties":false},"ApiWebhookEventType":{"type":"string","enum":["reservation.confirmed","reservation.changed","reservation.cancelled","payment.received","refund.succeeded","refund.failed","block.created","block.released","rate.published","rate_plan.changed","discount_code.changed","booking_request.received","booking_request.closed","guest_message.received","task.changed","task.problem_reported","invoice.issued","invoice.cancelled","unit.created","unit.changed","unit.archived","unit.restored","booking_site.published","booking_site.paused","settings.changed"]},"ApiWebhookSecretReveal":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/ApiWebhookEndpoint"},"secret":{"type":["string","null"],"pattern":"^whsec_[A-Za-z0-9+/]{43}=$","description":"The signing secret, shown this once. Store it now; null in a replay of this request, and no read shows it again."}},"required":["endpoint","secret"]},"DeveloperBooking":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"confirmationReference":{"type":"string"},"source":{"type":"string","enum":["manual","direct","import"]},"state":{"type":"string","enum":["confirmed","cancelled","no_show"]},"unitId":{"type":["string","null"],"format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"}},"required":["id","confirmationReference","source","state","unitId","checkIn","checkOut"]},"DeveloperCancellation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reservationVersion":{"type":"string","pattern":"^[1-9][0-9]*$"},"cancelledAt":{"type":"string","format":"date-time"},"paymentHandling":{"type":"string","enum":["external","keyset"]},"refundState":{"type":["string","null"],"enum":["requested","processing","unknown","succeeded","failed","needs_attention",null]}},"required":["id","reservationVersion","cancelledAt","paymentHandling","refundState"]},"DeveloperCancellationPreview":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid"},"version":{"type":"string","pattern":"^[1-9][0-9]*$"},"source":{"type":"string","enum":["manual","direct"]},"paymentHandling":{"type":"string","enum":["external","keyset"]},"refundMinor":{"type":["string","null"],"pattern":"^[0-9]+$"},"feeMinor":{"type":["string","null"],"pattern":"^[0-9]+$"},"refundState":{"type":["string","null"],"enum":["requested","processing","unknown","succeeded","failed","needs_attention",null]},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"blocker":{"type":["string","null"],"enum":["already_cancelled","policy_missing","payment_not_succeeded",null]},"guestNotification":{"type":"string","enum":["keyset","own","none"]}},"required":["reservationId","version","source","paymentHandling","refundMinor","feeMinor","refundState","currency","blocker"]},"DeveloperEvent":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[a-f0-9]{32}$"},"type":{"type":"string","enum":["reservation.confirmed","reservation.changed","reservation.cancelled","payment.received","refund.succeeded","refund.failed","block.created","block.released"]},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":{}}},"required":["id","type","createdAt","data"]},"DeveloperEventList":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperEvent"}},"hasMore":{"type":"boolean"}},"required":["events","hasMore"]},"DeveloperProblem":{"type":"object","properties":{"type":{"type":"string","enum":["about:blank"]},"title":{"type":"string"},"status":{"type":"integer"},"retryable":{"type":"boolean"},"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","NOT_FOUND","INVALID_REQUEST","INVENTORY_CONFLICT","IDEMPOTENCY_KEY_REUSED","TOO_MANY_REQUESTS","INTERNAL_ERROR","VERSION_CONFLICT","PREVIEW_STALE","POLICY_MISSING","NOT_CANCELLABLE","IDEMPOTENCY_IN_PROGRESS","IDEMPOTENCY_OUTCOME_UNKNOWN","LIVE_KEY","BLOCK_ALREADY_RELEASED","RATE_REVISION_ALREADY_PUBLISHED","RATE_CONFIGURATION_INVALID","DUPLICATE_DISCOUNT_CODE","LIMIT_REACHED","TOO_EARLY","STAY_NOT_RECORDABLE","NO_SHOW_NOT_POSSIBLE","GUEST_EMAIL_REQUIRED","GUEST_CONTACT_NOT_EDITABLE","NOT_MANUAL_BOOKING","GUEST_HAS_NO_EMAIL","TEST_MODE_NO_MAIL","PAYMENT_LINK_UNAVAILABLE","BELOW_RECEIVED","PRICE_REASON_REQUIRED","NOT_CHANGEABLE","NOT_MOVABLE","GUEST_PORTAL_UNAVAILABLE","BOOKING_REQUEST_NOT_OPEN","BOOKING_REQUEST_EXPIRED","UNIT_UNAVAILABLE","TRANSFER_UNAVAILABLE","NOTHING_OPEN","TASK_NOT_DELETABLE","EXCEEDS_OUTSTANDING","EXCEEDS_REFUNDABLE","NOT_RECORDABLE","PAYMENT_REFUNDED","NOT_REFUNDABLE","TOURIST_TAX_NOT_EDITABLE","BOOKING_NOT_CONFIRMED","INVOICE_INCOMPLETE","INVOICE_ALREADY_ISSUED","INVOICE_ALREADY_CANCELLED","MAIL_PENDING","MAIL_LIMIT_REACHED","XRECHNUNG_UNAVAILABLE","SETTINGS_INCOMPLETE","UNSUPPORTED_CURRENCY","TOO_MANY_ROWS","CASE_ALREADY_CLOSED","CASE_NOT_CLOSABLE","UNIT_CODE_TAKEN","OCCUPANCY_BELOW_BOOKINGS","INVALID_COMPONENTS","UNIT_IN_USE","BOOKINGS_CHANGED","MEDIA_TOO_LARGE","MEDIA_TYPE_UNSUPPORTED","MEDIA_UNREADABLE","MEDIA_DIMENSIONS_TOO_LARGE","GALLERY_FULL","BOOKING_SITE_NOT_READY","BOOKING_SITE_LEGAL_MISSING","BOOKING_SITE_ALREADY_PUBLISHED","BOOKING_SITE_BILLING_REQUIRED","BOOKING_SITE_NOT_PUBLISHED","CURRENCY_LOCKED","TOURIST_TAX_CHANGE_NOT_PLANNED","WEBHOOK_RECEIVER_MISSING","CALENDAR_LINK_INVALID","CALENDAR_OWN_LINK","CALENDAR_ALREADY_CONNECTED","CALENDAR_STAYS_CHANGED","INVOICE_NUMBER_TAKEN","INVOICE_NUMBER_GAP","IMPORT_TOO_LARGE","IMPORT_DIGEST_MISMATCH","IMPORT_APPROVAL_MISMATCH","IMPORT_NOT_REMOVABLE","WEBHOOK_URL_INVALID","WEBHOOK_LIMIT_REACHED","TEST_CONFLICT_NO_BOOKING"]},"detail":{"type":"string","maxLength":500}},"required":["type","title","status","retryable","code"]},"DeveloperProperty":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"timezone":{"type":"string"},"currency":{"type":"string"},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"maxOccupancy":{"type":"integer"},"status":{"type":"string","enum":["active","inactive"]}},"required":["id","code","name","maxOccupancy","status"]}}},"required":["id","name","timezone","currency","units"]},"DeveloperReservation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"confirmationReference":{"type":"string"},"source":{"type":"string","enum":["manual"]},"paymentHandling":{"type":"string","enum":["external"]},"createdAt":{"type":"string","format":"date-time"},"guestMail":{"type":"string","enum":["requested","not_requested","no_address","test","payment_link_unavailable"]}},"required":["id","confirmationReference","source","paymentHandling","createdAt"]},"ManualReservationCreateRequest":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":99},"children":{"type":"integer","minimum":0,"maximum":99}},"required":["adults","children"],"additionalProperties":false},"contact":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":["string","null"],"maxLength":254,"format":"email"},"phone":{"type":["string","null"],"maxLength":80,"description":"The guest’s phone number, a note for the host."},"language":{"type":"string","enum":["de","en"],"description":"The language Keyset writes the guest in; German when absent."}},"required":["firstName","lastName"],"additionalProperties":false},"agreedTotalMinor":{"type":"string","pattern":"^\\d{1,12}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"notifyGuest":{"type":"boolean","description":"true: Keyset sends the guest the booking confirmation (needs the contact’s e-mail address); absent or false sends nothing. This counts against the lower budget of requests that mail guests."},"paymentLink":{"type":"boolean","description":"With notifyGuest: the confirmation carries a link to pay the open amount by card. The key then needs reservation.cancel as well. Ignored without notifyGuest."}},"required":["unitId","checkIn","checkOut","occupancy","contact","agreedTotalMinor","currency"],"additionalProperties":false},"MediaProblem":{"type":"object","properties":{"type":{"type":"string","enum":["about:blank"]},"title":{"type":"string","minLength":1,"maxLength":160},"status":{"type":"integer","minimum":400,"maximum":599},"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","ORIGIN_NOT_TRUSTED","PROPERTY_NOT_FOUND","INVALID_MEDIA","MEDIA_TOO_LARGE","MEDIA_DIMENSIONS_TOO_LARGE","MEDIA_TYPE_UNSUPPORTED","GALLERY_FULL","VERSION_CONFLICT","IDEMPOTENCY_KEY_REUSED","MEDIA_NOT_FOUND","INTERNAL_ERROR"]}},"required":["type","title","status","code"],"additionalProperties":false},"PublicAvailabilityCalendarResponse":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"inventoryGuarantee":{"type":"string","enum":["none"]},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"integer","minimum":0,"maximum":20},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":20,"description":"One age per child, in years. Optional; when given it must hold exactly `children` entries. A host's surcharge for further persons leaves children under the host's free age uncounted; a child whose age is not given is counted."}},"required":["adults","children"],"additionalProperties":false},"nights":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"The night, `YYYY-MM-DD` in the property timezone."},"available":{"type":"boolean","description":"At least one bookable apartment that fits the party is free this night and has a published price for it. A hint, not a hold."},"fromPrice":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"The lowest nightly price among those apartments: the night itself including its weekend adjustment, before stay-level fees such as cleaning and service fees. `null` exactly when `available` is false. Only a Quote states what a stay costs."},"minimumStayNights":{"type":["integer","null"],"minimum":1,"maximum":3650,"description":"The shortest minimum stay, in nights, of a stay arriving this night among those apartments that take an arrival this night (among all of them when none does). `null` exactly when `available` is false."},"arrivalAllowed":{"type":["boolean","null"],"description":"At least one of those apartments takes an arrival this night under the host's stay rules (arrival weekdays of the period the night falls in). `null` exactly when `available` is false. A hint: only a Quote decides."},"maximumStayNights":{"type":["integer","null"],"minimum":1,"maximum":3650,"description":"The longest maximum stay, in nights, of a stay arriving this night among the same apartments. `null` when `available` is false or when one of them sets no maximum."},"departureAllowed":{"type":"boolean","description":"A stay may end on this day for at least one apartment that fits the party, under the departure weekdays of the period of the stay's last night (the night before). Answered whether or not this night itself is free. A hint: only a Quote decides."}},"required":["date","available","fromPrice","minimumStayNights","arrivalAllowed","maximumStayNights","departureAllowed"],"additionalProperties":false},"minItems":1,"maxItems":62}},"required":["asOf","inventoryGuarantee","occupancy","nights"],"additionalProperties":false},"PublicBookingProblem":{"type":"object","properties":{"type":{"type":"string","enum":["about:blank"]},"title":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"integer","minimum":400,"maximum":599},"code":{"type":"string","enum":["BOOKING_NOT_AVAILABLE","INVALID_BOOKING_DETAILS","TOO_MANY_REQUESTS","QUOTE_EXPIRED","IDEMPOTENCY_KEY_REUSED","APARTMENT_NO_LONGER_AVAILABLE","CHECKOUT_EXPIRED","PAYMENT_SESSION_UNAVAILABLE","SERVICE_UNAVAILABLE","INTERNAL_ERROR"]},"retryable":{"type":"boolean"},"retryAfter":{"type":"integer","exclusiveMinimum":0},"unavailable":{"type":"object","properties":{"state":{"type":"string","enum":["paused","empty"]},"publicPropertyId":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"shortId":{"type":"string","pattern":"^[0-9a-hjkmnp-tv-z]{8}$"},"displayName":{"type":"string","minLength":1,"maxLength":160},"host":{"$ref":"#/components/schemas/PublicHost"},"legal":{"$ref":"#/components/schemas/PublicLegal"}},"required":["state","publicPropertyId","displayName","host","legal"],"additionalProperties":false,"description":"With `BOOKING_NOT_AVAILABLE` on getBookingProperty only, when the page exists but takes no booking: `paused` or `empty`, with the name, the host's published contact and the legal texts. Absent when no booking page answers to the identifier, and from servers that predate it."},"stayRule":{"type":"object","properties":{"reason":{"type":"string","enum":["minimum_stay_not_satisfied","maximum_stay_exceeded","arrival_day_not_allowed","departure_day_not_allowed"]},"requiredNights":{"type":"integer","exclusiveMinimum":0},"maximumNights":{"type":"integer","exclusiveMinimum":0},"allowedDays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7}},"required":["reason"],"additionalProperties":false,"description":"With `INVALID_BOOKING_DETAILS` when the dates break the apartment's stay rules: which rule (the period of the arrival decides minimum stay, maximum stay and arrival weekday; the period of the last night the departure weekday) and the figures that explain it — `requiredNights`, `maximumNights`, or `allowedDays` as ISO weekdays (1 = Monday)."},"discountCode":{"type":"string","enum":["not_valid"],"description":"With `INVALID_BOOKING_DETAILS` on createQuote when the `discountCode` does not count: the same answer whether no such code exists, the host ended it, it is not valid on the day of booking, or it is malformed. Ask the guest to check the code, or quote without it."}},"required":["type","title","status","code","retryable"],"additionalProperties":false},"PublicBookingPropertyResponse":{"type":"object","properties":{"publicPropertyId":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"shortId":{"type":"string","pattern":"^[0-9a-hjkmnp-tv-z]{8}$","description":"A short, stable alias of `publicPropertyId` for addresses people read and type: a page at `/p/<shortId>`. getBookingProperty accepts it in place of `publicPropertyId`; every other operation takes the long id this response returns."},"displayName":{"type":"string","minLength":1,"maxLength":160},"locale":{"type":"string","minLength":2,"maxLength":35},"timezone":{"type":"string","minLength":1,"maxLength":100},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"presentation":{"type":"object","properties":{"locality":{"type":["string","null"],"minLength":1,"maxLength":120},"description":{"type":["string","null"],"minLength":1,"maxLength":400},"images":{"type":"array","items":{"type":"object","properties":{"assetKey":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{2,63}$"},"alt":{"type":"string","minLength":1,"maxLength":160},"role":{"type":"string","enum":["cover","gallery"]},"sortOrder":{"type":"integer","minimum":0,"maximum":19},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/medium\\.webp$"},"variants":{"type":"object","properties":{"thumbnail":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false},"small":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false},"medium":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false},"large":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false}},"required":["thumbnail","small","medium","large"],"additionalProperties":false}},"required":["assetKey","alt","role","sortOrder","width","height","url","variants"],"additionalProperties":false},"maxItems":20},"location":{"type":["string","null"],"minLength":1,"maxLength":1000},"amenities":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z_]{1,39}$","description":"A code of Keyset's amenity catalogue, e.g. `wifi` or `pets_allowed`. New codes may appear; show the ones you know."},"maxItems":40},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":200},"answer":{"type":"string","minLength":1,"maxLength":1000}},"required":["question","answer"],"additionalProperties":false},"maxItems":10}},"required":["locality","description","images"],"additionalProperties":false},"host":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":120},"email":{"type":["string","null"],"minLength":3,"maxLength":254},"phone":{"type":["string","null"],"minLength":5,"maxLength":30}},"required":["name","email","phone"],"additionalProperties":false,"description":"Who the guest books with — name, email and phone, each only when the host published it. The host is the merchant of record; Keyset is not the contact for a stay."},"legal":{"type":"object","properties":{"imprint":{"$ref":"#/components/schemas/PublicLegalDocument"},"privacy":{"$ref":"#/components/schemas/PublicLegalDocument"},"cancellation":{"type":["object","null"],"properties":{"version":{"type":"integer","exclusiveMinimum":0},"freeCancellationDays":{"type":"integer","minimum":0,"maximum":365},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000},"testOnly":{"type":"boolean"}},"required":["version","freeCancellationDays","lateRefundBasisPoints","testOnly"],"additionalProperties":false}},"required":["imprint","privacy","cancellation"],"additionalProperties":false,"description":"The host's Impressum and privacy notice, each a link or the text itself, and the active cancellation terms. A booking page links them where the guest accepts the booking."},"checkInTime":{"type":["string","null"],"pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"The earliest local time a guest can arrive, `HH:MM` on a 24-hour clock in the property timezone. `null` when the host has not set one; a booking page then states no time rather than a guessed one."},"checkOutTime":{"type":["string","null"],"pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"The latest local time a guest leaves on the departure day, `HH:MM` on a 24-hour clock in the property timezone. `null` when the host has not set one."},"businessProfile":{"type":"string","pattern":"^[a-z_]{1,40}$","description":"The kind of business: `holiday_apartments`, `guesthouse` or `holiday_home` so far, and possibly more later. It chooses the word for a unit — apartment, room, house — and nothing else; treat an unknown value as `holiday_apartments`."},"testMode":{"type":"boolean","enum":[true],"description":"`true` on the booking page of a business's test twin: payments are simulated, no guest is written to and nothing booked here is real. Say so on every page and keep the page out of search engines. Absent for a real business."},"onlineBooking":{"type":"boolean","enum":[false],"description":"`false` while the host's payments are not set up: availability and prices read as usual, but startCheckout answers `SERVICE_UNAVAILABLE`. Show the stay and offer the host's contact instead of asking for the guest's details. Absent when the property takes bookings online."},"noIndex":{"type":"boolean","enum":[true],"description":"`true` when the host keeps this booking page out of search engines (and on every test twin): mark the page `noindex`. Absent when it may be indexed."},"discountCodes":{"type":"boolean","enum":[true],"description":"`true` when the host has a discount code on offer: show a field for one and send it as createQuote's `discountCode`. Absent otherwise. It never says which code."},"ratePlans":{"type":"array","items":{"type":"object","properties":{"ratePlan":{"type":"string","pattern":"^[A-Za-z0-9_-]{22}$"},"name":{"type":"string","minLength":1,"maxLength":60},"discountBasisPoints":{"type":"integer","minimum":0,"maximum":9000},"freeCancellationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Free cancellation up to this many days before arrival; `null` when this rate never allows it."},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000,"description":"The share refunded on a cancellation outside the free period, in basis points."},"excludedUnits":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"description":"The `publicUnitReference` of every unit this rate is not offered for."}},"required":["ratePlan","name","discountBasisPoints","freeCancellationDays","lateRefundBasisPoints","excludedUnits"],"additionalProperties":false},"maxItems":10,"description":"The host's rates besides the standard rate, in the host's order: each a discount on the accommodation (nights, weekend and season prices, extra guests; never cleaning, extras or tourist tax) with its own cancellation terms. Pass `ratePlan` to createQuote to book one; without it a stay is quoted at the standard rate under `legal.cancellation`. Absent or empty when the host offers only the standard rate."},"units":{"type":"array","items":{"type":"object","properties":{"publicUnitReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"displayName":{"type":"string","minLength":1,"maxLength":160},"maxOccupancy":{"type":"integer","minimum":1,"maximum":20},"presentation":{"type":"object","properties":{"description":{"type":["string","null"],"minLength":1,"maxLength":400},"sleepingArrangement":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["bedroom","living_room"]},"beds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["double","single","sofa_bed","bunk"]},"count":{"type":"integer","minimum":1,"maximum":8}},"required":["kind","count"],"additionalProperties":false},"minItems":1,"maxItems":4}},"required":["kind","beds"],"additionalProperties":false},"maxItems":8},"images":{"type":"array","items":{"type":"object","properties":{"assetKey":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{2,63}$"},"alt":{"type":"string","minLength":1,"maxLength":160},"role":{"type":"string","enum":["cover","gallery"]},"sortOrder":{"type":"integer","minimum":0,"maximum":19},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/medium\\.webp$"},"variants":{"type":"object","properties":{"thumbnail":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false},"small":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false},"medium":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false},"large":{"type":"object","properties":{"url":{"type":"string","pattern":"^\\/media\\/[a-z0-9][a-z0-9-]{2,63}\\/(thumbnail|small|medium|large)\\.webp$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["url","width","height"],"additionalProperties":false}},"required":["thumbnail","small","medium","large"],"additionalProperties":false}},"required":["assetKey","alt","role","sortOrder","width","height","url","variants"],"additionalProperties":false},"maxItems":20},"amenities":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z_]{1,39}$","description":"A code of Keyset's amenity catalogue, e.g. `wifi` or `pets_allowed`. New codes may appear; show the ones you know."},"maxItems":40},"floorArea":{"type":"integer","minimum":1,"maximum":2000,"description":"The apartment's floor area in whole square metres, as the host gave it. Absent when the host has not given one."}},"required":["description","sleepingArrangement","images"],"additionalProperties":false},"leadPrice":{"type":["object","null"],"properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"The unit's lowest nightly price over the bookable horizon (from the property's local today up to the booking horizon) under its current published prices: the night itself including its weekend adjustment, before stay-level fees such as cleaning and service fees — the same figure the availability calendar calls `fromPrice`. For a \"from X per night\" label; it ignores availability and minimum stay, and only a Quote states what a stay costs. `null` when the unit has no usable published price."},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9-]{1,40}$"},"name":{"type":"string","minLength":1,"maxLength":60},"pricing":{"type":"string","enum":["per_stay","per_night","per_person_night"]},"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false}},"required":["id","name","pricing","amount"],"additionalProperties":false},"maxItems":10,"description":"Extras the guest may add to a stay in this unit, in the host's order: `amount` once per stay, per night, or per person and night. Absent when there are none."}},"required":["publicUnitReference","displayName","maxOccupancy"],"additionalProperties":false}}},"required":["publicPropertyId","displayName","locale","timezone","currency","units"],"additionalProperties":false},"PublicCheckoutPaymentSessionResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["stripe_embedded_checkout","stripe_checkout_elements"]},"publishableKey":{"type":"string","minLength":1,"maxLength":255},"accountId":{"type":"string","minLength":1,"maxLength":255},"clientSecret":{"type":"string","minLength":1,"maxLength":2048},"expiresAt":{"type":"string","format":"date-time"}},"required":["kind","publishableKey","accountId","clientSecret","expiresAt"],"additionalProperties":false},"PublicCheckoutRequest":{"type":"object","properties":{"publicQuoteReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"bookingContact":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":254,"format":"email"}},"required":["firstName","lastName","email"],"additionalProperties":false},"language":{"type":"string","enum":["de","en"],"description":"The language the guest booked in; the confirmation e-mail is written in it. German when absent. It changes no price, rule or state."},"returnUrl":{"type":"string","minLength":1,"maxLength":1000,"description":"Where the guest returns after paying, when the checkout is started on the business's own website: an absolute `https` address (loopback `http` for development) without credentials or fragment, whose origin is listed on one of the business's active publishable keys. Keyset adds `keyset_checkout=<publicCheckoutReference>` to it. Absent: Keyset's own booking page.","example":"https://www.example.com/buchen"},"paymentUi":{"type":"string","enum":["stripe_embedded_checkout","stripe_checkout_elements"],"description":"How the website shows the payment form. `stripe_embedded_checkout` (the default) mounts Stripe's complete embedded Checkout page. `stripe_checkout_elements` lets the website build the form itself from Stripe's Checkout Elements in its own design; it requires `returnUrl`, because the website confirms the payment and reads the outcome itself. The amount, currency, expiry and payment methods are the same either way.","example":"stripe_checkout_elements"},"acceptance":{"type":"object","properties":{"termsVersion":{"type":"string","minLength":1,"maxLength":100},"cancellationPolicyVersion":{"type":"string","minLength":1,"maxLength":100},"privacyNoticeVersion":{"type":"string","minLength":1,"maxLength":100},"accepted":{"type":"boolean","enum":[true]}},"required":["termsVersion","cancellationPolicyVersion","privacyNoticeVersion","accepted"],"additionalProperties":false}},"required":["publicQuoteReference","bookingContact","acceptance"],"additionalProperties":false},"PublicCheckoutResponse":{"type":"object","properties":{"publicCheckoutReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"expiresAt":{"type":"string","format":"date-time"},"checkoutState":{"type":"string","enum":["awaiting_payment","requires_customer_action"]},"paymentState":{"type":"string","enum":["created","requires_customer_action","processing"]},"reservationState":{"type":"string","enum":["pending"]},"safeNextAction":{"type":"string","enum":["wait","complete_payment"]}},"required":["publicCheckoutReference","expiresAt","checkoutState","paymentState","reservationState","safeNextAction"],"additionalProperties":false},"PublicCheckoutStatusResponse":{"type":"object","properties":{"publicCheckoutReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"expiresAt":{"type":"string","format":"date-time"},"property":{"type":"object","properties":{"publicPropertyId":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"displayName":{"type":"string","minLength":1,"maxLength":160}},"required":["publicPropertyId","displayName"],"additionalProperties":false},"unit":{"type":"object","properties":{"publicUnitReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"displayName":{"type":"string","minLength":1,"maxLength":160}},"required":["publicUnitReference","displayName"],"additionalProperties":false},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1,"maximum":90}},"required":["checkIn","checkOut","nights"],"additionalProperties":false},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"integer","minimum":0,"maximum":20},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":20,"description":"One age per child, in years. Optional; when given it must hold exactly `children` entries. A host's surcharge for further persons leaves children under the host's free age uncounted; a child whose age is not given is counted."}},"required":["adults","children"],"additionalProperties":false},"total":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false},"lineItems":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["nightly_accommodation","weekend_adjustment","guest_surcharge","cleaning_fee","percentage_fee","discount","extra","tourist_tax"]},"serviceDate":{"type":["string","null"],"format":"date"},"label":{"type":"string","minLength":1,"maxLength":120,"description":"Ready to show to the guest. Keyset's own labels are written in the property's language (German for a `de` locale, else English); a percentage fee, an extra and a rate plan carry the host's own words. A label is fixed when the quote is made."},"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|-?[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"Negative for a `discount` line; the lines sum to the total."},"discountKind":{"type":"string","enum":["length_of_stay","early_booking","last_minute","rate_plan","discount_code"],"description":"Which discount a `discount` line is: a stay of some length, booked early, booked late, the rate plan the guest chose, or the host's discount code the guest entered (its label names the code). Present only on a `discount` line. New kinds may appear; show the label for one you do not know."}},"required":["kind","serviceDate","label","amount"],"additionalProperties":false}},"checkoutState":{"type":"string","enum":["awaiting_payment","requires_customer_action","processing","resolving","completed","expired","failed","needs_attention"]},"paymentState":{"type":"string","enum":["created","requires_customer_action","processing","succeeded","failed","cancelled"]},"reservationState":{"type":"string","enum":["pending","confirmed","not_confirmed","recovery_required"],"description":"Whether this checkout produced a booking. `confirmed` stays once it did, also after the booking was cancelled or the guest did not arrive: whether the booking still stands is `bookingState`."},"confirmationReference":{"type":"string","pattern":"^[A-Z0-9]{12}$"},"reservationNumber":{"type":"integer","minimum":1001,"description":"The booking's number, counted per Property from 1001 — the one the host sees in their workspace and the one to quote when asking about the stay. Present exactly when `confirmationReference` is."},"paymentUi":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["stripe_embedded_checkout"]}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["stripe_checkout_elements"]}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["none"]}},"required":["kind"],"additionalProperties":false}]},"safeNextAction":{"type":"string","enum":["wait","complete_payment","start_new_search","booking_confirmed","contact_support","none"],"description":"What the page should offer the guest now. `booking_confirmed` only while the booking stands; once it is cancelled or the guest did not arrive it is `none`, and `bookingState`, `cancelledAt` and `refund` say what happened."},"retryAfter":{"type":"integer","exclusiveMinimum":0},"supportReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"paymentPreparing":{"type":"boolean","description":"`true` while the payment form for this checkout is still being prepared: the guest has not been asked to pay yet, so nothing can have been paid for it. `safeNextAction` is `wait` meanwhile; show a neutral loading state, never 'payment processing', and poll until `complete_payment`. `false` otherwise. Absent from servers that predate it."},"heldUntil":{"type":["string","null"],"format":"date-time","description":"When the hold that keeps the apartment for this checkout runs out, while it is active and nothing is confirmed yet: the countdown beside the payment form. `null` once the booking is confirmed or the hold has ended."},"confirmationMail":{"type":["string","null"],"enum":["pending","sent","failed","unknown",null],"description":"Once the booking is confirmed, whether its confirmation e-mail went out: `pending` (queued or retrying), `sent` (accepted by the mail server, not proof of mailbox delivery), `failed` (provably not sent) or `unknown` (an ambiguous outcome that is never resent automatically). `null` before confirmation and when no e-mail was sent for this booking."},"changedAt":{"type":["string","null"],"format":"date-time","description":"When the host last changed the confirmed booking (dates, apartment or total). Once it is set, `stay`, `unit` and `total` are the booking as changed and `lineItems` is empty, because the original price lines no longer describe it. `null` while the booking is as booked."},"bookingState":{"type":["string","null"],"enum":["confirmed","cancelled","no_show",null],"description":"Whether the booking this checkout produced still stands: `confirmed`, `cancelled` (by the guest or the host; see `cancelledAt`, `cancelledBy` and `refund`) or `no_show` (the guest did not arrive; nothing is refunded by that alone). Read it whenever `reservationState` is `confirmed`, and never show a booking as confirmed unless this is `confirmed`. `null` before the checkout produced a booking. Absent from servers that predate it."},"cancelledAt":{"type":["string","null"],"format":"date-time","description":"When the booking was cancelled; `null` unless `bookingState` is `cancelled`."},"cancelledBy":{"type":["string","null"],"enum":["guest","host",null],"description":"Who cancelled: `guest` (in the guest portal) or `host`. `null` unless `bookingState` is `cancelled`."},"refund":{"type":["object","null"],"properties":{"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"Everything being or already returned to the guest for this booking, across all its payments."},"refunded":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"The part of `amount` the payment provider has confirmed as refunded. A refund can take a few days to reach the card."},"state":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending` while any part is on its way or its outcome is not yet known, `succeeded` once all of `amount` is refunded, `failed` when a part could not be refunded automatically: the host has been told and sorts it out, so tell the guest to contact the host."}},"required":["amount","refunded","state"],"additionalProperties":false,"description":"Money returned to the guest: after a cancellation under the booking's terms, after the host lowered the price, as a goodwill refund, or when a paid checkout could not become a booking. `null` when nothing was refunded. Absent from servers that predate it."},"ratePlan":{"type":"object","properties":{"ratePlan":{"type":"string","pattern":"^[A-Za-z0-9_-]{22}$"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["ratePlan","name"],"additionalProperties":false,"description":"The rate this booking was priced at, when the guest chose one; absent for the standard rate. Its discount is a `discount` line named after it."},"cancellation":{"type":"object","properties":{"freeUntil":{"type":["string","null"],"format":"date","description":"The last day, `YYYY-MM-DD` in the property timezone, on which this booking can be cancelled free of charge: arrival minus `freeCancellationDays`. `null` when the terms never allow it."},"freeCancellationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Free cancellation up to this many days before arrival; `null` when never free."},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000,"description":"The share refunded on a cancellation outside the free period, in basis points."}},"required":["freeUntil","freeCancellationDays","lateRefundBasisPoints"],"additionalProperties":false,"description":"The cancellation terms this booking binds: the chosen rate's, otherwise the host's terms in force when it was quoted. A later change of the host's terms does not alter them. Absent when the host had published none."},"deposit":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"Present when the host took a deposit: what the guest paid at booking. `total` stays the whole booking."},"balance":{"type":"object","properties":{"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false},"dueOn":{"type":"string","format":"date","description":"The day the rest is charged, `YYYY-MM-DD` in the property timezone."}},"required":["amount","dueOn"],"additionalProperties":false,"description":"Present when the host takes a deposit: `dueNow` is then the deposit, and this is the rest, charged on `dueOn` from the card the guest pays the deposit with. If that charge fails, the guest is asked by e-mail to pay it. Absent when the whole `total` is due now."},"guestPortalUrl":{"type":["string","null"],"maxLength":512,"format":"uri","description":"The guest's personal page for this booking — the stay, the payment, the host's contact, cancelling under the booking's terms and writing to the host — for a link on the confirmation page. It is a bearer link: give it to the guest who booked and nobody else, never put it in a URL, log or analytics event of your own. It is derived from this checkout's capability, so only a reader of this checkout receives it, and the same link on every read. Only asked for with `include=guestPortalUrl`. Present once `reservationState` is `confirmed`, for one day after confirmation; `null` before, after that day (the guest's e-mails carry the link) and once the host has ended the booking's links. Absent when not asked for, and from servers that predate it or do not serve the guest portal."}},"required":["publicCheckoutReference","expiresAt","property","unit","stay","occupancy","total","lineItems","checkoutState","paymentState","reservationState","paymentUi","safeNextAction"],"additionalProperties":false},"PublicHost":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":120},"email":{"type":["string","null"],"minLength":3,"maxLength":254},"phone":{"type":["string","null"],"minLength":5,"maxLength":30}},"required":["name","email","phone"],"additionalProperties":false},"PublicLegal":{"type":"object","properties":{"imprint":{"$ref":"#/components/schemas/PublicLegalDocument"},"privacy":{"$ref":"#/components/schemas/PublicLegalDocument"},"cancellation":{"type":["object","null"],"properties":{"version":{"type":"integer","exclusiveMinimum":0},"freeCancellationDays":{"type":"integer","minimum":0,"maximum":365},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000},"testOnly":{"type":"boolean"}},"required":["version","freeCancellationDays","lateRefundBasisPoints","testOnly"],"additionalProperties":false}},"required":["imprint","privacy","cancellation"],"additionalProperties":false},"PublicLegalDocument":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["link"]},"url":{"type":"string","maxLength":500,"pattern":"^https:\\/\\/\\S+$"}},"required":["kind","url"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"maxLength":30000}},"required":["kind","text"],"additionalProperties":false},{"type":"null"}]},"PublicQuoteRequest":{"type":"object","properties":{"publicUnitReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"integer","minimum":0,"maximum":20},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":20,"description":"One age per child, in years. Optional; when given it must hold exactly `children` entries. A host's surcharge for further persons leaves children under the host's free age uncounted; a child whose age is not given is counted."}},"required":["adults","children"],"additionalProperties":false},"extras":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9-]{1,40}$"},"maxItems":10,"description":"The ids of the unit's extras the guest chose, from the property read's `units[].extras`; each at most once. Each becomes its own `extra` price line."},"ratePlan":{"type":"string","pattern":"^[A-Za-z0-9_-]{22}$","description":"One of the property read's `ratePlans[].ratePlan`, offered for this unit. Absent for the standard rate. A rate the host has meanwhile withdrawn is refused with `BOOKING_NOT_AVAILABLE`; read the property again."},"discountCode":{"type":"string","minLength":1,"maxLength":40,"description":"A discount code the host gave the guest, as the guest typed it: case and spaces do not matter. Its discount takes part in the stay's one discount — the highest of the host's discounts counts — and becomes a `discount` line with `discountKind` `discount_code`. A code that does not count is refused with `INVALID_BOOKING_DETAILS` and `discountCode: not_valid`. Every quote with a code also counts against a separate hourly budget per source (`TOO_MANY_REQUESTS`). Never send an amount: the code's discount is the host's."}},"required":["publicUnitReference","checkIn","checkOut","occupancy"],"additionalProperties":false},"PublicQuoteResponse":{"type":"object","properties":{"publicQuoteReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"expiresAt":{"type":"string","format":"date-time"},"unit":{"type":"object","properties":{"publicUnitReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"displayName":{"type":"string","minLength":1,"maxLength":160}},"required":["publicUnitReference","displayName"],"additionalProperties":false},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1,"maximum":90}},"required":["checkIn","checkOut","nights"],"additionalProperties":false},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"integer","minimum":0,"maximum":20},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":20,"description":"One age per child, in years. Optional; when given it must hold exactly `children` entries. A host's surcharge for further persons leaves children under the host's free age uncounted; a child whose age is not given is counted."}},"required":["adults","children"],"additionalProperties":false},"total":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false},"dueNow":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false},"lineItems":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["nightly_accommodation","weekend_adjustment","guest_surcharge","cleaning_fee","percentage_fee","discount","extra","tourist_tax"]},"serviceDate":{"type":["string","null"],"format":"date"},"label":{"type":"string","minLength":1,"maxLength":120,"description":"Ready to show to the guest. Keyset's own labels are written in the property's language (German for a `de` locale, else English); a percentage fee, an extra and a rate plan carry the host's own words. A label is fixed when the quote is made."},"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|-?[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"Negative for a `discount` line; the lines sum to the total."},"discountKind":{"type":"string","enum":["length_of_stay","early_booking","last_minute","rate_plan","discount_code"],"description":"Which discount a `discount` line is: a stay of some length, booked early, booked late, the rate plan the guest chose, or the host's discount code the guest entered (its label names the code). Present only on a `discount` line. New kinds may appear; show the label for one you do not know."}},"required":["kind","serviceDate","label","amount"],"additionalProperties":false}},"authoritative":{"type":"boolean","enum":[true]},"cancellation":{"type":"object","properties":{"freeUntil":{"type":["string","null"],"format":"date","description":"The last day, `YYYY-MM-DD` in the property timezone, on which this stay can be cancelled free of charge under the cancellation terms this quote binds: arrival minus their free-cancellation days. `null` when the host has published no terms, and when the chosen rate never allows free cancellation (then `freeCancellationDays` is `null` too)."},"freeCancellationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"The bound terms: free up to this many days before arrival; `null` when never free."},"lateRefundBasisPoints":{"type":"integer","minimum":0,"maximum":10000,"description":"The bound terms: the share refunded outside the free period, in basis points."}},"required":["freeUntil"],"additionalProperties":false,"description":"The cancellation terms applied to this stay. Optional on the wire; the API always sends it."},"ratePlan":{"type":"object","properties":{"ratePlan":{"type":"string","pattern":"^[A-Za-z0-9_-]{22}$"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["ratePlan","name"],"additionalProperties":false,"description":"The rate this quote was priced at, when one was chosen; absent for the standard rate. Its discount is a `discount` line named after it."},"discountCode":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z0-9-]{6,24}$"},"applied":{"type":"boolean","description":"Whether its discount is a line of this quote. `false` when a higher discount of the host counts instead: a stay gets one discount, the highest."}},"required":["code","applied"],"additionalProperties":false,"description":"The host's discount code this quote was priced with, as the host wrote it; absent without one."},"ratePlanTotals":{"type":"array","items":{"type":"object","properties":{"ratePlan":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{22}$","description":"One of the property read's `ratePlans[].ratePlan`; `null` for the standard rate."},"total":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"This stay's `total` at that rate: the same unit, dates, party and extras, priced by the same evaluation."}},"required":["ratePlan","total"],"additionalProperties":false},"maxItems":11,"description":"Present when the unit is offered at rates of the host's own: what this same stay costs at each rate offered for the unit, the standard rate first, then the host's order, so a rate choice can show amounts. The chosen rate's entry is this quote's `total`; every other entry is the `total` a quote with that `ratePlan` would carry if made now. A rate that cannot be priced for this stay is left out. Nothing is held at those amounts: choosing a rate means creating a quote with it. Absent when only the standard rate is offered."},"payableOnSite":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["tourist_tax"]},"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false}},"required":["kind","amount"],"additionalProperties":false},"maxItems":1,"description":"What the guest pays the host on arrival, outside `total` and `dueNow`: the tourist tax when the host collects it on site. Absent when nothing is due on site."},"balance":{"type":"object","properties":{"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false},"dueOn":{"type":"string","format":"date","description":"The day the rest is charged, `YYYY-MM-DD` in the property timezone."}},"required":["amount","dueOn"],"additionalProperties":false,"description":"Present when the host takes a deposit: `dueNow` is then the deposit, and this is the rest, charged on `dueOn` from the card the guest pays the deposit with. If that charge fails, the guest is asked by e-mail to pay it. Absent when the whole `total` is due now."}},"required":["publicQuoteReference","expiresAt","unit","stay","occupancy","total","dueNow","lineItems","authoritative"],"additionalProperties":false},"PublicSearchRequest":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"integer","minimum":0,"maximum":20},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":20,"description":"One age per child, in years. Optional; when given it must hold exactly `children` entries. A host's surcharge for further persons leaves children under the host's free age uncounted; a child whose age is not given is counted."}},"required":["adults","children"],"additionalProperties":false}},"required":["checkIn","checkOut","occupancy"],"additionalProperties":false},"PublicSearchResponse":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"inventoryGuarantee":{"type":"string","enum":["none"]},"offers":{"type":"array","items":{"type":"object","properties":{"publicUnitReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$"},"displayName":{"type":"string","minLength":1,"maxLength":160},"maxOccupancy":{"type":"integer","minimum":1,"maximum":20},"stay":{"type":"object","properties":{"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer","minimum":1,"maximum":90}},"required":["checkIn","checkOut","nights"],"additionalProperties":false},"occupancy":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"integer","minimum":0,"maximum":20},"childAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":20,"description":"One age per child, in years. Optional; when given it must hold exactly `children` entries. A host's surcharge for further persons leaves children under the host's free age uncounted; a child whose age is not given is counted."}},"required":["adults","children"],"additionalProperties":false},"pricePreview":{"type":"object","properties":{"total":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false},"lineItems":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["nightly_accommodation","weekend_adjustment","guest_surcharge","cleaning_fee","percentage_fee","discount","extra","tourist_tax"]},"serviceDate":{"type":["string","null"],"format":"date"},"label":{"type":"string","minLength":1,"maxLength":120,"description":"Ready to show to the guest. Keyset's own labels are written in the property's language (German for a `de` locale, else English); a percentage fee, an extra and a rate plan carry the host's own words. A label is fixed when the quote is made."},"amount":{"type":"object","properties":{"minorUnits":{"type":"string","pattern":"^(0|-?[1-9]\\d*)$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["minorUnits","currency"],"additionalProperties":false,"description":"Negative for a `discount` line; the lines sum to the total."},"discountKind":{"type":"string","enum":["length_of_stay","early_booking","last_minute","rate_plan","discount_code"],"description":"Which discount a `discount` line is: a stay of some length, booked early, booked late, the rate plan the guest chose, or the host's discount code the guest entered (its label names the code). Present only on a `discount` line. New kinds may appear; show the label for one you do not know."}},"required":["kind","serviceDate","label","amount"],"additionalProperties":false}}},"required":["total","lineItems"],"additionalProperties":false}},"required":["publicUnitReference","displayName","maxOccupancy","stay","occupancy","pricePreview"],"additionalProperties":false}}},"required":["asOf","inventoryGuarantee","offers"],"additionalProperties":false}},"parameters":{}},"paths":{"/public/booking-properties/{publicPropertyId}":{"get":{"operationId":"getBookingProperty","summary":"Read a bookable property","tags":["Booking"],"description":"Returns the published property, its bookable units and the guest-facing content Keyset serves. The property may be named by its long `publicPropertyId` or by its eight-character `shortId`; an unpublished or unknown one is the same 404 either way, and so is one without a bookable apartment or paused by its host, except that this 404 then carries `unavailable` (`paused` or `empty`, with the name, the host's contact and the legal texts) so a booking page can say which. Calendar days everywhere in this API are expressed in the returned `timezone`, and money everywhere is integer minor units of the returned `currency`. Image URLs are stable relative paths to immutable Hono-served variants. `host` and `legal` carry what the host chose to publish about themselves — contact, Impressum, privacy notice — and the active cancellation terms; a booking page shows them and links them where the guest accepts the booking. `checkInTime` and `checkOutTime` are the host's local times of day, or `null` when the host has not set them. `lang=en` answers the host's own texts in English where the host wrote them.","parameters":[{"schema":{"type":"string","pattern":"^(?:[A-Za-z0-9_-]{22,64}|[0-9a-hjkmnp-tv-z]{8})$","description":"The public property identifier Keyset issued for one published booking page, or its eight-character `shortId`.","example":"public_property_e2e_customer_zero_01"},"required":true,"description":"The public property identifier Keyset issued for one published booking page, or its eight-character `shortId`.","name":"publicPropertyId","in":"path"},{"schema":{"type":"string","enum":["de","en"],"description":"The language of the host's own texts (`presentation` and the apartments' descriptions): `en` answers the host's English where they wrote one and the German where they did not; `de`, the default, answers the German. Names, prices, rules and legal texts are the same in every language."},"required":false,"description":"The language of the host's own texts (`presentation` and the apartments' descriptions): `en` answers the host's English where they wrote one and the German where they did not; `de`, the default, answers the German. Names, prices, rules and legal texts are the same in every language.","name":"lang","in":"query"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call."},"required":false,"description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call.","name":"keyset-session","in":"header"}],"responses":{"200":{"description":"The published property and its bookable units.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}},"keyset-session":{"description":"With a publishable key only, on the call that starts a guest session: the session to send back in the `keyset-session` request header.","schema":{"type":"string"}}},"content":{"application/json":{"example":{"publicPropertyId":"public_property_e2e_customer_zero_01","shortId":"trk3svz8","displayName":"Customer Zero Apartments","locale":"de-DE","timezone":"Europe/Berlin","currency":"EUR","presentation":{"locality":"Haßfurt","description":"Fünf eigenständige Wohnungen im Ortskern.","images":[]},"host":{"name":"Familie Huber","email":"gastgeber@example.com","phone":"+49 9521 12345"},"legal":{"imprint":{"kind":"link","url":"https://example.com/impressum"},"privacy":{"kind":"link","url":"https://example.com/datenschutz"},"cancellation":{"version":1,"freeCancellationDays":14,"lateRefundBasisPoints":5000,"testOnly":false}},"checkInTime":"15:00","checkOutTime":"10:00","businessProfile":"holiday_apartments","units":[{"publicUnitReference":"public_unit_e2e_apartment_1_000","displayName":"Apartment 1","maxOccupancy":4,"leadPrice":{"minorUnits":"8500","currency":"EUR"},"presentation":{"description":"Wohnung im Erdgeschoss mit Blick in den Garten.","sleepingArrangement":[{"kind":"bedroom","beds":[{"kind":"double","count":1}]}],"floorArea":34,"images":[{"assetKey":"m-0123456789abcdef0123456789abcdef","alt":"Wohnbereich mit Sofa und Esstisch","role":"cover","sortOrder":0,"width":1800,"height":1200,"url":"/media/m-0123456789abcdef0123456789abcdef/medium.webp","variants":{"thumbnail":{"url":"/media/m-0123456789abcdef0123456789abcdef/thumbnail.webp","width":320,"height":213},"small":{"url":"/media/m-0123456789abcdef0123456789abcdef/small.webp","width":640,"height":427},"medium":{"url":"/media/m-0123456789abcdef0123456789abcdef/medium.webp","width":1280,"height":853},"large":{"url":"/media/m-0123456789abcdef0123456789abcdef/large.webp","width":1800,"height":1200}}}]}}]},"schema":{"$ref":"#/components/schemas/PublicBookingPropertyResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business. No CORS is granted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"No published booking page answers to this identifier, or the identifier is malformed (BOOKING_NOT_AVAILABLE). The answer is deliberately identical in both cases so identifiers cannot be enumerated. A page that exists but takes no booking answers the same code with `unavailable`: `paused` by the host, or `empty` with no apartment switched on for booking.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/public/booking-properties/{publicPropertyId}/availability":{"get":{"operationId":"readAvailabilityCalendar","summary":"Read nightly availability and prices for a date picker","tags":["Booking"],"description":"For each night of a window of up to 62 nights: whether at least one apartment that fits the party is free and priced, the lowest nightly price among those apartments, and the shortest minimum stay among them — so a date picker can show a guest where a stay is possible before they search. It is a hint, not a commitment. `inventoryGuarantee` is always `none`: availability is read from the same moving world as searchAvailability and reserves nothing, a free night does not mean every stay through it is free, and `fromPrice` is one night before stay-level fees. Only a Quote is authoritative for a price, and only startCheckout competes for inventory. Prices come from the published rates through the same evaluator a Quote uses. With `publicUnitReference` every night answers for that one apartment instead of the whole property — for a calendar beside one apartment, so a guest sees its own booked nights; an apartment the booking page does not offer is answered exactly like an unknown property, so a reference reveals nothing about another property. Budgeted together with searchAvailability at 30 reads per 300 seconds per source.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"The public property identifier Keyset issued for one published booking page.","example":"public_property_e2e_customer_zero_01"},"required":true,"description":"The public property identifier Keyset issued for one published booking page.","name":"publicPropertyId","in":"path"},{"schema":{"type":"string","format":"date","description":"The first night of the window, `YYYY-MM-DD` in the property timezone. Not before today and not beyond the booking horizon.","example":"2027-02-05"},"required":true,"description":"The first night of the window, `YYYY-MM-DD` in the property timezone. Not before today and not beyond the booking horizon.","name":"from","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":62,"description":"How many consecutive nights the window holds, 1 to 62.","example":4},"required":true,"description":"How many consecutive nights the window holds, 1 to 62.","name":"nights","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"description":"Adults in the party.","example":2},"required":true,"description":"Adults in the party.","name":"adults","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":20,"default":0,"description":"Children in the party; infants count as children. Without it, no children.","example":0},"required":false,"description":"Children in the party; infants count as children. Without it, no children.","name":"children","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"One apartment instead of all of them: a `publicUnitReference` from getBookingProperty. Every night then answers for that apartment alone — its own free nights, price and stay rules. An apartment this booking page does not offer answers 404, exactly like an unknown property.","example":"public_unit_e2e_apartment_1_000"},"required":false,"description":"One apartment instead of all of them: a `publicUnitReference` from getBookingProperty. Every night then answers for that apartment alone — its own free nights, price and stay rules. An apartment this booking page does not offer answers 404, exactly like an unknown property.","name":"publicUnitReference","in":"query"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call."},"required":false,"description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call.","name":"keyset-session","in":"header"},{"schema":{"type":"string","pattern":"^sk_(test|live)_ks1_[a-f0-9]{32}_[A-Za-z0-9_-]{43}$","description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option."},"required":false,"description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option.","name":"keyset-relay-key","in":"header"},{"schema":{"type":"string","description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored."},"required":false,"description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored.","name":"keyset-relay-guest","in":"header"}],"responses":{"200":{"description":"One entry per night of the window, in date order. A night that reads unavailable has no price and no minimum stay.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}},"keyset-session":{"description":"With a publishable key only, on the call that starts a guest session: the session to send back in the `keyset-session` request header.","schema":{"type":"string"}}},"content":{"application/json":{"example":{"asOf":"2026-12-01T09:15:00.000Z","inventoryGuarantee":"none","occupancy":{"adults":2,"children":0},"nights":[{"date":"2027-02-05","available":true,"fromPrice":{"minorUnits":"11500","currency":"EUR"},"arrivalAllowed":true,"minimumStayNights":2,"maximumStayNights":14,"departureAllowed":true},{"date":"2027-02-06","available":false,"fromPrice":null,"arrivalAllowed":null,"minimumStayNights":null,"maximumStayNights":null,"departureAllowed":true},{"date":"2027-02-07","available":true,"fromPrice":{"minorUnits":"9500","currency":"EUR"},"arrivalAllowed":false,"minimumStayNights":2,"maximumStayNights":14,"departureAllowed":true},{"date":"2027-02-08","available":true,"fromPrice":{"minorUnits":"9500","currency":"EUR"},"arrivalAllowed":true,"minimumStayNights":2,"maximumStayNights":14,"departureAllowed":false}]},"schema":{"$ref":"#/components/schemas/PublicAvailabilityCalendarResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business (no CORS is granted), or a relay key was sent that is not active or cannot read this booking page's Property.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"No published booking page answers to this identifier, or it offers no apartment with this `publicUnitReference` (BOOKING_NOT_AVAILABLE). The two cases answer identically.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"422":{"description":"The window or party is not valid (INVALID_BOOKING_DETAILS): `from` is in the past or beyond the booking horizon, `nights` is outside 1 to 62, or the party is outside the search bounds. Correct the input; repeating it unchanged cannot succeed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"429":{"description":"The request budget for this source is exhausted (TOO_MANY_REQUESTS). The body carries retryAfter in seconds; wait at least that long before repeating.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/public/booking-properties/{publicPropertyId}/search":{"post":{"operationId":"searchAvailability","summary":"Search availability and preview pricing","tags":["Booking"],"description":"Advisory availability for one stay and occupancy. `inventoryGuarantee` is always `none`: this is a read of a moving world and reserves nothing. `pricePreview` is advisory too — only a Quote is authoritative, and only startCheckout competes for inventory. Budgeted at 30 searches per 300 seconds per source.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"The public property identifier Keyset issued for one published booking page.","example":"public_property_e2e_customer_zero_01"},"required":true,"description":"The public property identifier Keyset issued for one published booking page.","name":"publicPropertyId","in":"path"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call."},"required":false,"description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call.","name":"keyset-session","in":"header"},{"schema":{"type":"string","pattern":"^sk_(test|live)_ks1_[a-f0-9]{32}_[A-Za-z0-9_-]{43}$","description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option."},"required":false,"description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option.","name":"keyset-relay-key","in":"header"},{"schema":{"type":"string","description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored."},"required":false,"description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored.","name":"keyset-relay-guest","in":"header"}],"requestBody":{"required":true,"description":"The stay as a half-open interval [checkIn, checkOut) in the property timezone, plus occupancy.","content":{"application/json":{"example":{"checkIn":"2027-02-01","checkOut":"2027-02-03","occupancy":{"adults":2,"children":0}},"schema":{"$ref":"#/components/schemas/PublicSearchRequest"}}}},"responses":{"200":{"description":"Advisory availability. An empty `offers` array means nothing is available, not that the read failed.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}},"keyset-session":{"description":"With a publishable key only, on the call that starts a guest session: the session to send back in the `keyset-session` request header.","schema":{"type":"string"}}},"content":{"application/json":{"example":{"asOf":"2026-12-01T09:15:00.000Z","inventoryGuarantee":"none","offers":[{"publicUnitReference":"public_unit_e2e_apartment_1_000","displayName":"Apartment 1","maxOccupancy":4,"stay":{"checkIn":"2027-02-01","checkOut":"2027-02-03","nights":2},"occupancy":{"adults":2,"children":0},"pricePreview":{"total":{"minorUnits":"24500","currency":"EUR"},"lineItems":[{"kind":"nightly_accommodation","serviceDate":"2027-02-01","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2027-02-02","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"4500","currency":"EUR"}},{"kind":"percentage_fee","serviceDate":null,"label":"Servicegebühr (10 %)","amount":{"minorUnits":"1000","currency":"EUR"}}]}}]},"schema":{"$ref":"#/components/schemas/PublicSearchResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business (no CORS is granted), or a relay key was sent that is not active or cannot read this booking page's Property.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"No published booking page answers to this identifier (BOOKING_NOT_AVAILABLE).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"413":{"description":"The request body exceeded 16 KiB (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"415":{"description":"The request was not application/json (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"422":{"description":"The stay or occupancy is not valid (INVALID_BOOKING_DETAILS). Correct the input; repeating it unchanged cannot succeed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"429":{"description":"The request budget for this source is exhausted (TOO_MANY_REQUESTS). The body carries retryAfter in seconds; wait at least that long before repeating.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/public/booking-properties/{publicPropertyId}/quotes":{"post":{"operationId":"createQuote","summary":"Create an authoritative quote","tags":["Booking"],"description":"Creates the immutable, server-calculated price for one stay in one unit. Show this total to the guest; a preview total is never a commitment. A Quote expires at `expiresAt` and is never repriced in place — a later rate change produces a new Quote, never a different total on this one. Requires an `Idempotency-Key`; budgeted at 10 quotes per 600 seconds per guest session and source.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"The public property identifier Keyset issued for one published booking page.","example":"public_property_e2e_customer_zero_01"},"required":true,"description":"The public property identifier Keyset issued for one published booking page.","name":"publicPropertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Required. Identifies one immutable intent, 16 to 128 characters of A-Z a-z 0-9 _ -. Persist it before the first attempt and send the identical key for every retry; the same key with a different body is refused with IDEMPOTENCY_KEY_REUSED.","example":"ada-checkout-2027-02-01-9Qm2Vx4Z"},"required":true,"description":"Required. Identifies one immutable intent, 16 to 128 characters of A-Z a-z 0-9 _ -. Persist it before the first attempt and send the identical key for every retry; the same key with a different body is refused with IDEMPOTENCY_KEY_REUSED.","name":"idempotency-key","in":"header"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call."},"required":false,"description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call.","name":"keyset-session","in":"header"},{"schema":{"type":"string","pattern":"^sk_(test|live)_ks1_[a-f0-9]{32}_[A-Za-z0-9_-]{43}$","description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option."},"required":false,"description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option.","name":"keyset-relay-key","in":"header"},{"schema":{"type":"string","description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored."},"required":false,"description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored.","name":"keyset-relay-guest","in":"header"}],"requestBody":{"required":true,"description":"One unit from a search offer, plus the same stay and occupancy.","content":{"application/json":{"example":{"publicUnitReference":"public_unit_e2e_apartment_1_000","checkIn":"2027-02-01","checkOut":"2027-02-03","occupancy":{"adults":2,"children":0}},"schema":{"$ref":"#/components/schemas/PublicQuoteRequest"}}}},"responses":{"200":{"description":"The authoritative price for this stay.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}},"keyset-session":{"description":"With a publishable key only, on the call that starts a guest session: the session to send back in the `keyset-session` request header.","schema":{"type":"string"}}},"content":{"application/json":{"example":{"publicQuoteReference":"public_quote_4ZaR3tB7Js9Qm2Vx","expiresAt":"2026-12-01T09:30:00.000Z","unit":{"publicUnitReference":"public_unit_e2e_apartment_1_000","displayName":"Apartment 1"},"stay":{"checkIn":"2027-02-01","checkOut":"2027-02-03","nights":2},"occupancy":{"adults":2,"children":0},"total":{"minorUnits":"24500","currency":"EUR"},"dueNow":{"minorUnits":"24500","currency":"EUR"},"lineItems":[{"kind":"nightly_accommodation","serviceDate":"2027-02-01","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2027-02-02","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"4500","currency":"EUR"}},{"kind":"percentage_fee","serviceDate":null,"label":"Servicegebühr (10 %)","amount":{"minorUnits":"1000","currency":"EUR"}}],"authoritative":true,"cancellation":{"freeUntil":"2027-01-18"},"ratePlanTotals":[{"ratePlan":null,"total":{"minorUnits":"24500","currency":"EUR"}},{"ratePlan":"Fq7Lw2Xc9Rt4Vb8Nm3Kd6P","total":{"minorUnits":"22140","currency":"EUR"}}]},"schema":{"$ref":"#/components/schemas/PublicQuoteResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business (no CORS is granted), or a relay key was sent that is not active or cannot read this booking page's Property.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"The booking page or the unit is not available (BOOKING_NOT_AVAILABLE).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"409":{"description":"The Idempotency-Key was already used for a different request (IDEMPOTENCY_KEY_REUSED). This is a recovery conflict, not permission to start a new intent with a fresh key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"413":{"description":"The request body exceeded 16 KiB (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"415":{"description":"The request was not application/json (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"422":{"description":"The request is not valid (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"429":{"description":"The request budget for this source is exhausted (TOO_MANY_REQUESTS). The body carries retryAfter in seconds; wait at least that long before repeating.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/public/booking-properties/{publicPropertyId}/checkouts":{"post":{"operationId":"startCheckout","summary":"Start a checkout for an accepted quote","tags":["Booking"],"description":"The one operation that competes for inventory: it acquires a hold and starts a payment. `201` means the attempt is durable, **not** that a reservation is confirmed — `reservationState` is `pending` and only readCheckoutStatus decides the outcome. The response sets an `HttpOnly` capability cookie scoped to `/public/checkouts`; every later read of this checkout needs it. If the answer is lost, repeat the identical request with the identical `Idempotency-Key`: never a fresh key, or a guest can be charged twice. Budgeted at 5 checkouts per 1800 seconds per source and 20 per 300 seconds per property, with one active checkout per guest session. A checkout started on the business's own website sends `returnUrl`: the payment form then completes in the page where it can, and a payment that has to leave the page returns the guest to that address with `keyset_checkout=<publicCheckoutReference>`, so the page can read the status again. The address is accepted only when its origin is listed on one of the business's active publishable keys — the business decides where its guests may be sent, never the request — and it is recorded with the checkout: a repeat under the same `Idempotency-Key` answers with the address first recorded. Without it the guest returns to Keyset's own booking page. With `returnUrl`, `paymentUi: stripe_checkout_elements` lets the website build the payment form itself from Stripe's Checkout Elements, in its own design, instead of mounting the embedded Checkout page: readCheckoutStatus and readPaymentSession then answer `stripe_checkout_elements`, the website confirms the payment itself, and the outcome is still only what readCheckoutStatus says. The choice is recorded with the checkout like the address.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"The public property identifier Keyset issued for one published booking page.","example":"public_property_e2e_customer_zero_01"},"required":true,"description":"The public property identifier Keyset issued for one published booking page.","name":"publicPropertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Required. Identifies one immutable intent, 16 to 128 characters of A-Z a-z 0-9 _ -. Persist it before the first attempt and send the identical key for every retry; the same key with a different body is refused with IDEMPOTENCY_KEY_REUSED.","example":"ada-checkout-2027-02-01-9Qm2Vx4Z"},"required":true,"description":"Required. Identifies one immutable intent, 16 to 128 characters of A-Z a-z 0-9 _ -. Persist it before the first attempt and send the identical key for every retry; the same key with a different body is refused with IDEMPOTENCY_KEY_REUSED.","name":"idempotency-key","in":"header"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call."},"required":false,"description":"Optional, with a publishable key only. The guest session the API returned in a `keyset-session` response header; send it back unchanged. Absent on the first call.","name":"keyset-session","in":"header"},{"schema":{"type":"string","pattern":"^sk_(test|live)_ks1_[a-f0-9]{32}_[A-Za-z0-9_-]{43}$","description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option."},"required":false,"description":"Optional, from your own server only, never from a browser. A secret key of this booking page's business whose service may read the Property (Settings > Developers > Keys). It lets the request name its guest in `keyset-relay-guest`. A key that is not active or cannot read this Property is refused with 403. `createBookingRelay` sends it when you pass its `relay` option.","name":"keyset-relay-key","in":"header"},{"schema":{"type":"string","description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored."},"required":false,"description":"Optional, only with `keyset-relay-key`. An opaque name for the guest this request is relayed for: 64 lowercase hex characters, such as an HMAC of the guest's address under a key of yours, never the address itself. The request then counts against that guest's own budgets instead of the relay's, and every guest named for one booking page shares one ceiling of 300 budgeted requests per 300 seconds. Anything else in it, and the header without a valid key, is ignored.","name":"keyset-relay-guest","in":"header"}],"requestBody":{"required":true,"description":"An unexpired quote reference, the booking contact, the exact document versions the guest accepted and, from the business's own website, where the guest returns after paying.","content":{"application/json":{"example":{"publicQuoteReference":"public_quote_4ZaR3tB7Js9Qm2Vx","bookingContact":{"firstName":"Ada","lastName":"Example","email":"ada@example.invalid"},"acceptance":{"termsVersion":"terms-v1","cancellationPolicyVersion":"cancellation-v1","privacyNoticeVersion":"privacy-v1","accepted":true},"returnUrl":"https://www.example.com/buchen"},"schema":{"$ref":"#/components/schemas/PublicCheckoutRequest"}}}},"responses":{"201":{"description":"The checkout is durably started. A reservation is not confirmed yet.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}},"keyset-session":{"description":"With a publishable key only, on the call that starts a guest session: the session to send back in the `keyset-session` request header.","schema":{"type":"string"}},"keyset-checkout-capability":{"description":"With a publishable key only, instead of the cookie: this checkout's capability, for the `keyset-checkout-capability` request header of readCheckoutStatus and readPaymentSession. Bearer-equivalent.","schema":{"type":"string"}},"set-cookie":{"description":"The checkout capability, as `keyset_checkout_<reference>`. HttpOnly, SameSite=Lax, Secure over HTTPS, Path=/public/checkouts, Max-Age 2592000. Treat it as bearer-equivalent: whoever holds it can read this checkout.","schema":{"type":"string"}}},"content":{"application/json":{"example":{"publicCheckoutReference":"public_checkout_7Js9Qm2Vx4ZaR3tB","expiresAt":"2026-12-01T09:25:00.000Z","checkoutState":"awaiting_payment","paymentState":"created","reservationState":"pending","safeNextAction":"wait"},"schema":{"$ref":"#/components/schemas/PublicCheckoutResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business (no CORS is granted), or a relay key was sent that is not active or cannot read this booking page's Property.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"The booking page or the quote is not available (BOOKING_NOT_AVAILABLE).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"409":{"description":"QUOTE_EXPIRED — create a new Quote and let the guest accept the current total. APARTMENT_NO_LONGER_AVAILABLE — the unit was taken; search again. IDEMPOTENCY_KEY_REUSED — the same key was used for a different body.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"413":{"description":"The request body exceeded 16 KiB (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"415":{"description":"The request was not application/json (INVALID_BOOKING_DETAILS).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"422":{"description":"The request is not valid (INVALID_BOOKING_DETAILS) — also when `returnUrl` is not an origin listed on one of the business's active publishable keys. Nothing was held; list the website address in Keyset and repeat the same request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"429":{"description":"The request budget for this source is exhausted (TOO_MANY_REQUESTS). The body carries retryAfter in seconds; wait at least that long before repeating.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"503":{"description":"SERVICE_UNAVAILABLE: external effects are temporarily paused (retryable), or the property cannot currently accept payments (not retryable immediately; no checkout was created). Reads keep working.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/public/checkouts/{publicCheckoutReference}":{"get":{"operationId":"readCheckoutStatus","summary":"Read the authoritative checkout status","tags":["Booking"],"description":"The only authority on whether a stay is booked. A browser redirect or a payment-provider return page never is. Requires the `keyset_checkout_<reference>` capability cookie that startCheckout issued; without it the answer is an indistinguishable 404. `checkoutState`, `paymentState` and `reservationState` are separate dimensions — never collapse them into one status. It stays the authority after the stay is booked: a cancellation by the guest or the host, a no-show and every refund show here (`bookingState`, `cancelledAt`, `cancelledBy`, `refund`, and `changedAt` for a change by the host), so a confirmation page read again later never shows a booking that no longer stands. While `safeNextAction` is `wait` the response is `202` and carries `retryAfter` in seconds: poll, and never offer a second payment while the outcome is unresolved. Asked with `include=guestPortalUrl`, a confirmed booking also carries `guestPortalUrl`, the guest's own page for it, for the confirmation page to link to: it is handed only to a reader of this checkout, because it is derived from the checkout's capability. Without the parameter no link is created. Budgeted at 60 reads per 300 seconds per checkout.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"The reference returned by startCheckout. Reading it also requires that checkout capability cookie.","example":"public_checkout_7Js9Qm2Vx4ZaR3tB"},"required":true,"description":"The reference returned by startCheckout. Reading it also requires that checkout capability cookie.","name":"publicCheckoutReference","in":"path"},{"schema":{"type":"string","enum":["guestPortalUrl"],"description":"`guestPortalUrl` asks for the guest's personal page once the booking is confirmed. Without it the response carries no `guestPortalUrl` and no link is created.","example":"guestPortalUrl"},"required":false,"description":"`guestPortalUrl` asks for the guest's personal page once the booking is confirmed. Without it the response carries no `guestPortalUrl` and no link is created.","name":"include","in":"query"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,128}$","description":"Optional, with a publishable key only. This checkout's capability, from the `keyset-checkout-capability` header of startCheckout. Bearer-equivalent: whoever holds it can read this checkout; keep it in the page's session, never in a URL or a log."},"required":false,"description":"Optional, with a publishable key only. This checkout's capability, from the `keyset-checkout-capability` header of startCheckout. Bearer-equivalent: whoever holds it can read this checkout; keep it in the page's session, never in a URL or a log.","name":"keyset-checkout-capability","in":"header"}],"responses":{"200":{"description":"A settled outcome. `reservationState: confirmed` with a `confirmationReference` is the booking; `bookingState` says whether it still stands, and `refund` what was returned.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}}},"content":{"application/json":{"example":{"publicCheckoutReference":"public_checkout_7Js9Qm2Vx4ZaR3tB","expiresAt":"2026-12-01T09:25:00.000Z","property":{"publicPropertyId":"public_property_e2e_customer_zero_01","displayName":"Customer Zero Apartments"},"unit":{"publicUnitReference":"public_unit_e2e_apartment_1_000","displayName":"Apartment 1"},"stay":{"checkIn":"2027-02-01","checkOut":"2027-02-03","nights":2},"occupancy":{"adults":2,"children":0},"total":{"minorUnits":"24500","currency":"EUR"},"lineItems":[{"kind":"nightly_accommodation","serviceDate":"2027-02-01","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2027-02-02","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"4500","currency":"EUR"}},{"kind":"percentage_fee","serviceDate":null,"label":"Servicegebühr (10 %)","amount":{"minorUnits":"1000","currency":"EUR"}}],"checkoutState":"completed","paymentState":"succeeded","reservationState":"confirmed","confirmationReference":"K7M2QX9B4TZA","reservationNumber":1042,"paymentUi":{"kind":"none"},"safeNextAction":"booking_confirmed","paymentPreparing":false,"heldUntil":null,"confirmationMail":"sent","changedAt":null,"bookingState":"confirmed","cancelledAt":null,"cancelledBy":null,"refund":null,"guestPortalUrl":"https://booking.keyset.cloud/g/q3V9xR2mT7bK4nW8yL1cF6hJ0sD5aE9gU2iO7pZ3tXw"},"schema":{"$ref":"#/components/schemas/PublicCheckoutStatusResponse"}}}},"202":{"description":"The outcome is still moving. Poll again after `retryAfter` seconds and change nothing meanwhile.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}}},"content":{"application/json":{"example":{"publicCheckoutReference":"public_checkout_7Js9Qm2Vx4ZaR3tB","expiresAt":"2026-12-01T09:25:00.000Z","property":{"publicPropertyId":"public_property_e2e_customer_zero_01","displayName":"Customer Zero Apartments"},"unit":{"publicUnitReference":"public_unit_e2e_apartment_1_000","displayName":"Apartment 1"},"stay":{"checkIn":"2027-02-01","checkOut":"2027-02-03","nights":2},"occupancy":{"adults":2,"children":0},"total":{"minorUnits":"24500","currency":"EUR"},"lineItems":[{"kind":"nightly_accommodation","serviceDate":"2027-02-01","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2027-02-02","label":"Übernachtung","amount":{"minorUnits":"9500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"4500","currency":"EUR"}},{"kind":"percentage_fee","serviceDate":null,"label":"Servicegebühr (10 %)","amount":{"minorUnits":"1000","currency":"EUR"}}],"checkoutState":"processing","paymentState":"processing","reservationState":"pending","paymentUi":{"kind":"none"},"safeNextAction":"wait","retryAfter":2,"paymentPreparing":false,"heldUntil":"2026-12-01T09:25:00.000Z","confirmationMail":null,"changedAt":null,"bookingState":null,"cancelledAt":null,"cancelledBy":null,"refund":null,"guestPortalUrl":null},"schema":{"$ref":"#/components/schemas/PublicCheckoutStatusResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business. No CORS is granted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"Unknown checkout, or the capability cookie is missing or does not match (BOOKING_NOT_AVAILABLE). The two cases answer identically on purpose.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"429":{"description":"The request budget for this source is exhausted (TOO_MANY_REQUESTS). The body carries retryAfter in seconds; wait at least that long before repeating.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/public/checkouts/{publicCheckoutReference}/payment-session":{"get":{"operationId":"readPaymentSession","summary":"Read the short-lived payment handoff","tags":["Booking"],"description":"Returns the credentials a payment surface needs, as a separate request so a secret never rides on a polled status response. `kind` names the form they belong to: `stripe_embedded_checkout` mounts Stripe's embedded Checkout page, `stripe_checkout_elements` (only for a checkout started with that `paymentUi`) initialises Stripe's Checkout Elements with the same fields. Requires the same capability cookie. Every field is a secret: never log it, never place it in a URL, never cache it, and request it only when you are about to mount the payment surface. Budgeted at 20 reads per 600 seconds per checkout.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,64}$","description":"The reference returned by startCheckout. Reading it also requires that checkout capability cookie.","example":"public_checkout_7Js9Qm2Vx4ZaR3tB"},"required":true,"description":"The reference returned by startCheckout. Reading it also requires that checkout capability cookie.","name":"publicCheckoutReference","in":"path"},{"schema":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]{24}$","description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page."},"required":false,"description":"Optional. A publishable key for a direct call from a website's browser. The key must be active, list the page's `Origin` and belong to this booking page's business; the answer then carries CORS for that origin (never credentials), and the session and capability travel in the headers below instead of cookies. Without it the call works as before, through a same-origin relay or the hosted booking page.","name":"keyset-publishable-key","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,128}$","description":"Optional, with a publishable key only. This checkout's capability, from the `keyset-checkout-capability` header of startCheckout. Bearer-equivalent: whoever holds it can read this checkout; keep it in the page's session, never in a URL or a log."},"required":false,"description":"Optional, with a publishable key only. This checkout's capability, from the `keyset-checkout-capability` header of startCheckout. Bearer-equivalent: whoever holds it can read this checkout; keep it in the page's session, never in a URL or a log.","name":"keyset-checkout-capability","in":"header"}],"responses":{"200":{"description":"The payment handoff. Treat every field as a secret.","headers":{"x-request-id":{"description":"Correlation id for this response. Quote it in a support request; it carries no guest data.","schema":{"type":"string","example":"req_7Js9Qm2Vx4ZaR3tB"}}},"content":{"application/json":{"example":{"kind":"stripe_embedded_checkout","publishableKey":"pk_test_placeholder_publishable_key","accountId":"acct_placeholder","clientSecret":"cs_test_placeholder_client_secret","expiresAt":"2026-12-01T09:25:00.000Z"},"schema":{"$ref":"#/components/schemas/PublicCheckoutPaymentSessionResponse"}}}},"403":{"description":"BOOKING_NOT_AVAILABLE: a publishable key was sent that is not active, does not list the calling origin or belongs to another business. No CORS is granted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"404":{"description":"Unknown checkout, or the capability cookie is missing or does not match (BOOKING_NOT_AVAILABLE).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"409":{"description":"This checkout can no longer be paid here (PAYMENT_SESSION_UNAVAILABLE). Read the checkout status to find the safe next action.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"429":{"description":"The request budget for this source is exhausted (TOO_MANY_REQUESTS). The body carries retryAfter in seconds; wait at least that long before repeating.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}},"500":{"description":"The request failed inside Keyset (INTERNAL_ERROR, retryable).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicBookingProblem"}}}}}}},"/media/{assetKey}/{variant}.webp":{"get":{"operationId":"readMediaVariant","summary":"Read an accommodation image","tags":["Booking"],"description":"Returns one immutable, metadata-stripped WebP variant for an image placed on accommodation content. Placed variants are public immediately; the private normalized original is never served, and the opaque URL never reveals a storage path.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{2,63}$"},"required":true,"name":"assetKey","in":"path"},{"schema":{"type":"string","enum":["thumbnail","small","medium","large"]},"required":true,"name":"variant","in":"path"}],"responses":{"200":{"description":"The immutable WebP bytes.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Public immutable cache policy"},"Content-Length":{"schema":{"type":"string"},"description":"Exact representation size in bytes"}},"content":{"image/webp":{"example":"binary WebP image","schema":{"type":"string","format":"binary"}}}},"404":{"description":"The asset, variant or physical file is unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/MediaProblem"}}}},"500":{"description":"The image could not be read.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/MediaProblem"}}}}}}},"/v1/properties/{propertyId}":{"get":{"operationId":"getDeveloperProperty","summary":"Read a Property and its units","description":"Requires property.read on this Property. A credential is bound to one Tenant and deployment environment. Foreign and ungranted resources answer the same 404. At most 120 requests per minute per source and service principal.","tags":["Developer API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Property identifier within the service principal’s explicitly selected scope."},"required":true,"description":"Property identifier within the service principal’s explicitly selected scope.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The authorized Property and its units.","content":{"application/json":{"example":{"id":"20000000-0000-4000-8000-000000000001","name":"Synthetic apartments","timezone":"Europe/Berlin","currency":"EUR","units":[]},"schema":{"$ref":"#/components/schemas/DeveloperProperty"}}}},"401":{"description":"Missing, invalid, revoked, expired or wrong-environment secret.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"The credential can read this Property but lacks the required operation permission.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"Resource not found or outside this credential scope; the response does not distinguish these cases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"Request limit reached. Wait before retrying the same intent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"The request could not be completed. A read may be retried.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations":{"post":{"operationId":"createDeveloperReservation","summary":"Create an offline Reservation","description":"Requires property.read and reservation.create_manual on this Property. Creates a canonical manual Reservation for an explicitly agreed EUR amount; payment is handled externally. PostgreSQL arbitrates exclusive inventory. Reuse the same Idempotency-Key and body after an uncertain outcome. Never retry with a new key. At most 120 requests per minute per source and service principal.","tags":["Developer API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Property identifier within the service principal’s explicitly selected scope."},"required":true,"description":"Property identifier within the service principal’s explicitly selected scope.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualReservationCreateRequest"}}}},"responses":{"200":{"description":"Original Reservation returned for the same intent.","content":{"application/json":{"example":{"id":"20000000-0000-4000-8000-000000000001","confirmationReference":"TESTBOOKING1","source":"manual","paymentHandling":"external","createdAt":"2026-09-12T00:00:00Z"},"schema":{"$ref":"#/components/schemas/DeveloperReservation"}}}},"201":{"description":"Reservation created.","content":{"application/json":{"example":{"id":"20000000-0000-4000-8000-000000000001","confirmationReference":"TESTBOOKING1","source":"manual","paymentHandling":"external","createdAt":"2026-09-12T00:00:00Z"},"schema":{"$ref":"#/components/schemas/DeveloperReservation"}}}},"401":{"description":"Missing, invalid, revoked, expired or wrong-environment secret.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"The credential can read this Property but lacks the required operation permission.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"Resource not found or outside this credential scope; the response does not distinguish these cases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"Inventory conflict or idempotency key reused for another body.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"Request limit reached. Wait before retrying the same intent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"Unknown mutation outcome: retry only with the original idempotency key and identical body.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"get":{"operationId":"listReservations","summary":"List bookings","description":"Requires property.read and reservation.read. The bookings list of the app, ordered by arrival then id, with its filters: apartment, arrival window, departure from, state, view, number and a search `q`. The guest's name is present, and matched by `q`, only for a key that also holds guest.read; PostgreSQL withholds it otherwise. Continue with `after` set to the previous page's `nextCursor`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."},"required":false,"description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one.","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"unitId","in":"query"},{"schema":{"type":"string","format":"date","description":"Bookings arriving on or after this day."},"required":false,"description":"Bookings arriving on or after this day.","name":"checkInFrom","in":"query"},{"schema":{"type":"string","format":"date","description":"Bookings arriving on or before this day."},"required":false,"description":"Bookings arriving on or before this day.","name":"checkInTo","in":"query"},{"schema":{"type":"string","format":"date","description":"Bookings leaving on or after this day."},"required":false,"description":"Bookings leaving on or after this day.","name":"checkOutFrom","in":"query"},{"schema":{"type":"string","enum":["confirmed","cancelled","no_show"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","enum":["current","arriving","in_house","departing","attention","unplaced","cancelled","all"],"description":"As the app's views: current (from today on), arriving, in_house, departing (today), attention (payment or refund open), unplaced (no apartment), cancelled, all."},"required":false,"description":"As the app's views: current (from today on), arriving, in_house, departing (today), attention (payment or refund open), unplaced (no apartment), cancelled, all.","name":"view","in":"query"},{"schema":{"type":"integer","minimum":1001,"maximum":2147483647},"required":false,"name":"number","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"A booking number, confirmation code, apartment name or the guest's name. Guest names match only for a key with guest.read."},"required":false,"description":"A booking number, confirmation code, apartment name or the guest's name. Guest names match only for a key with guest.read.","name":"q","in":"query"}],"responses":{"200":{"description":"One page of bookings.","content":{"application/json":{"example":{"data":[{"id":"20000000-0000-4000-8000-000000000001","number":1042,"confirmationReference":"K7Q2M9X4P1RT","state":"confirmed","source":"direct","bookedVia":null,"importSource":null,"inventoryResolution":"allocated","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"occupancy":{"adults":2,"children":1,"known":true},"total":{"minorUnits":"48600","currency":"EUR"},"paymentState":"succeeded","refundState":null,"receivedAmount":null,"receivedOn":null,"openAmount":null,"transferDueOn":null,"refundOwed":null,"guestName":"Ada Lovelace","confirmedAt":"2026-11-02T09:15:00.000Z","cancelledAt":null}],"hasMore":true,"nextCursor":"c1.WyIyMDI2LTEyLTA0IiwiMjAiXQ"},"schema":{"$ref":"#/components/schemas/ApiReservationPage"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}":{"get":{"operationId":"getDeveloperReservation","summary":"Read a Reservation","description":"Requires property.read and reservation.read. Returns booking identity, stay and lifecycle without contact data or internal payment details. Existing property.read credentials do not gain reservation.read. Unknown or ungranted resources have the same 404.","tags":["Developer API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Property identifier within the service principal’s explicitly selected scope."},"required":true,"description":"Property identifier within the service principal’s explicitly selected scope.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"reservationId","in":"path"}],"responses":{"200":{"description":"Authorized Reservation.","content":{"application/json":{"example":{"id":"20000000-0000-4000-8000-000000000001","confirmationReference":"TESTBOOKING1","source":"manual","state":"confirmed","unitId":"20000000-0000-4000-8000-000000000001","checkIn":"2026-10-01","checkOut":"2026-10-03"},"schema":{"$ref":"#/components/schemas/DeveloperBooking"}}}},"401":{"description":"Missing, invalid, revoked, expired or wrong-environment secret.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"The credential can read this Property but lacks the required operation permission.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"Resource not found or outside this credential scope; the response does not distinguish these cases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"Request limit reached. Wait before retrying the same intent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"The request could not be completed. A read may be retried.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/cancellation-preview":{"get":{"operationId":"previewDeveloperCancellation","summary":"Preview cancellation","description":"Requires property.read and reservation.cancel. This permission includes the minimum booking and refund context necessary to cancel, independently of general reservation.read. A preview makes no changes. Manual bookings have external payments and no Keyset refund; direct bookings use their stored policy. Imported bookings are not cancellable through this contract.","tags":["Developer API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Property identifier within the service principal’s explicitly selected scope."},"required":true,"description":"Property identifier within the service principal’s explicitly selected scope.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"reservationId","in":"path"}],"responses":{"200":{"description":"Current version, refund decision and any blocker.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","version":"1","source":"manual","paymentHandling":"external","refundMinor":null,"feeMinor":null,"refundState":null,"currency":"EUR","blocker":null},"schema":{"$ref":"#/components/schemas/DeveloperCancellationPreview"}}}},"401":{"description":"Missing, invalid, revoked, expired or wrong-environment secret.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"The credential can read this Property but lacks the required operation permission.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"Resource not found or outside this credential scope; the response does not distinguish these cases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"Request limit reached. Wait before retrying the same intent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"The request could not be completed. A read may be retried.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/cancel":{"post":{"operationId":"cancelDeveloperReservation","summary":"Cancel a Reservation","description":"Requires property.read and reservation.cancel. Submit the expectedVersion and expectedRefundMinor from a fresh cancellation preview. PostgreSQL serializes cancellation and releases only this booking allocation. This resource transition is intrinsically idempotent: an already cancelled Reservation returns its original cancellation without another refund, so no Idempotency-Key header is required. After an unknown outcome, read the preview or repeat the identical body against the same Reservation; never infer refund success from cancellation. VERSION_CONFLICT or PREVIEW_STALE require a new preview and explicit decision. Direct refunds remain asynchronous; manual payments remain external. An optional Idempotency-Key header (16–128 URL-safe characters) makes a retry replay the first answer: the same key with a different body answers IDEMPOTENCY_KEY_REUSED, a key whose request still runs IDEMPOTENCY_IN_PROGRESS (retryable), and one whose earlier outcome is unknown IDEMPOTENCY_OUTCOME_UNKNOWN (read the booking, never repeat blindly).","tags":["Developer API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Property identifier within the service principal’s explicitly selected scope."},"required":true,"description":"Property identifier within the service principal’s explicitly selected scope.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"required":false,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"string","pattern":"^[1-9][0-9]{0,18}$","description":"Positive reservation version from the cancellation preview, at most 9223372036854775807."},"expectedRefundMinor":{"type":["string","null"],"pattern":"^[0-9]{1,18}$"},"reason":{"type":"string","minLength":1,"maxLength":500},"notifyGuest":{"type":"boolean"}},"required":["expectedVersion","expectedRefundMinor","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Cancellation committed or original cancellation returned; refund state is separate.","content":{"application/json":{"example":{"id":"20000000-0000-4000-8000-000000000001","reservationVersion":"2","cancelledAt":"2026-09-12T00:00:00Z","paymentHandling":"external","refundState":null},"schema":{"$ref":"#/components/schemas/DeveloperCancellation"}}}},"401":{"description":"Missing, invalid, revoked, expired or wrong-environment secret.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"The credential can read this Property but lacks the required operation permission.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"Resource not found or outside this credential scope; the response does not distinguish these cases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT, PREVIEW_STALE, POLICY_MISSING or NOT_CANCELLABLE: read a fresh preview before deciding. With an Idempotency-Key also IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS or IDEMPOTENCY_OUTCOME_UNKNOWN.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"Request limit reached. Wait before retrying the same intent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"Unknown outcome. Read the cancellation preview or repeat the identical body for the same Reservation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/events":{"get":{"operationId":"listDeveloperEvents","summary":"List events","description":"Requires property.read and reservation.read. The events a webhook delivers, oldest first: bookings confirmed, changed or cancelled, payments received, refunds succeeded or failed, blocks created or released. Pass the id of the last event you have as `after` to continue; an event appears here a few seconds after it happened and stays thirty days. Data carries references, stay, apartment and amounts in minor units, never guest contact data. An unknown `after` is an invalid request.","tags":["Developer API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Property identifier within the service principal’s explicitly selected scope."},"required":true,"description":"Property identifier within the service principal’s explicitly selected scope.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^evt_[a-f0-9]{32}$"},"required":false,"name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["reservation.confirmed","reservation.changed","reservation.cancelled","payment.received","refund.succeeded","refund.failed","block.created","block.released"]},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"The next events after the cursor.","content":{"application/json":{"example":{"events":[{"id":"evt_0b6c0d1e2f3a4b5c6d7e8f9a0b1c2d3e","type":"reservation.confirmed","createdAt":"2026-10-11T08:00:00.000Z","data":{"reservationNumber":1042,"source":"direct","checkIn":"2026-11-06","checkOut":"2026-11-09","nights":3,"apartment":{"code":"apartment-2","name":"Apartment 2"},"guests":{"adults":2,"children":1},"total":{"minorUnits":"48600","currency":"EUR"}}}],"hasMore":false},"schema":{"$ref":"#/components/schemas/DeveloperEventList"}}}},"401":{"description":"Missing, invalid, revoked, expired or wrong-environment secret.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"The credential can read this Property but lacks the required operation permission.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"Resource not found or outside this credential scope; the response does not distinguish these cases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"Request limit reached. Wait before retrying the same intent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"The request could not be completed. A read may be retried.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/details":{"get":{"operationId":"getReservationDetails","summary":"Read a booking in full","description":"Requires property.read and reservation.read. The booking detail of the app: stay, state, price lines of the immutable quote, the card payment, recorded payments, refunds, disputes, balance, cancellation and changes, with `version` for later writes. `guest` (name, e-mail, phone) is present only for a key that also holds guest.read; PostgreSQL withholds it otherwise. No payment-provider identifier or secret is part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The booking.","content":{"application/json":{"example":{"id":"20000000-0000-4000-8000-000000000001","number":1042,"confirmationReference":"K7Q2M9X4P1RT","state":"confirmed","source":"direct","bookedVia":null,"importSource":null,"inventoryResolution":"allocated","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"occupancy":{"adults":2,"children":1,"known":true},"total":{"minorUnits":"48600","currency":"EUR"},"paymentState":"succeeded","refundState":null,"receivedAmount":null,"receivedOn":null,"openAmount":null,"transferDueOn":null,"refundOwed":null,"guestName":"Ada Lovelace","confirmedAt":"2026-11-02T09:15:00.000Z","cancelledAt":null,"version":"1","createdAt":"2026-11-02T09:14:41.000Z","guest":{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","phone":null,"version":"1"},"price":{"total":{"minorUnits":"48600","currency":"EUR"},"lines":[{"kind":"nightly_accommodation","label":"3 Nächte","serviceDate":null,"amount":{"minorUnits":"43500","currency":"EUR"}},{"kind":"cleaning_fee","label":"Endreinigung","serviceDate":null,"amount":{"minorUnits":"5100","currency":"EUR"}}],"ratePlanName":null,"discountCode":null},"payment":{"state":"succeeded","succeededAt":"2026-11-02T09:15:00.000Z"},"recordedPayments":[],"cardPayments":[],"refunds":[],"recordedRefunds":[],"disputes":[],"balance":{"paidAmount":{"minorUnits":"48600","currency":"EUR"},"refundableAmount":{"minorUnits":"48600","currency":"EUR"},"refundedAmount":{"minorUnits":"0","currency":"EUR"},"owedAmount":null,"dueOn":null,"state":null},"cancellation":null,"changes":[],"noShowMarkedAt":null,"arrivedAt":null,"departedAt":null,"stayVersion":"0"},"schema":{"$ref":"#/components/schemas/ApiReservationDetails"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar":{"get":{"operationId":"getCalendar","summary":"Read the calendar","description":"Requires property.read and reservation.read. The app's calendar board for the nights [from, to), at most 62: every apartment with its bookings, owner and maintenance blocks and checkout holds, and the bookings that hold no apartment. Guest names only with guest.read. A read of a moving calendar reserves nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"date","description":"First night shown."},"required":true,"description":"First night shown.","name":"from","in":"query"},{"schema":{"type":"string","format":"date","description":"The day after the last night shown; at most 62 nights after `from`."},"required":true,"description":"The day after the last night shown; at most 62 nights after `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"The calendar of the window.","content":{"application/json":{"example":{"from":"2026-12-01","to":"2026-12-15","units":[{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"}],"entries":[{"kind":"reservation","unitId":"30000000-0000-4000-8000-000000000001","checkIn":"2026-12-04","checkOut":"2026-12-07","reservationId":"20000000-0000-4000-8000-000000000001","number":1042,"source":"direct","guestName":"Ada Lovelace","adults":2,"children":1,"paymentState":"succeeded"},{"kind":"owner_block","unitId":"30000000-0000-4000-8000-000000000001","checkIn":"2026-12-10","checkOut":"2026-12-12","blockId":"40000000-0000-4000-8000-000000000001","version":"1","note":"Familie"}],"unplaced":[],"asOf":"2026-11-17T08:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiCalendar"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guests":{"get":{"operationId":"listGuests","summary":"List guests","description":"Requires property.read, reservation.read and guest.read. The guest list of the app: every guest the bookings name, merged by e-mail address or name, with contact, confirmed stays, last and next arrival, newest first, 50 per page; `q` searches name, e-mail and phone. PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."},"required":false,"description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one.","name":"after","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Part of a name, e-mail address or phone number."},"required":false,"description":"Part of a name, e-mail address or phone number.","name":"q","in":"query"}],"responses":{"200":{"description":"One page of guests.","content":{"application/json":{"example":{"data":[{"id":"a3f1c2d4e5b60718293a4b5c6d7e8f90","firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","phone":null,"stays":2,"lastCheckIn":"2026-08-14","nextCheckIn":"2026-12-04","bookings":3}],"hasMore":false,"nextCursor":null},"schema":{"$ref":"#/components/schemas/ApiGuestPage"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guests/{guestId}":{"get":{"operationId":"getGuest","summary":"Read a guest","description":"Requires property.read, reservation.read and guest.read. The guest profile of the app: contact, every booking of the guest and the host's note with the `version` a later note change sends back. PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"A guest of the list."},"required":true,"description":"A guest of the list.","name":"guestId","in":"path"}],"responses":{"200":{"description":"The guest.","content":{"application/json":{"example":{"id":"a3f1c2d4e5b60718293a4b5c6d7e8f90","firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","phone":null,"stays":2,"lastCheckIn":"2026-08-14","nextCheckIn":"2026-12-04","reservations":[{"id":"20000000-0000-4000-8000-000000000001","number":1042,"state":"confirmed","source":"direct","bookedVia":null,"checkIn":"2026-12-04","checkOut":"2026-12-07","unitName":"Apartment 1","total":{"minorUnits":"48600","currency":"EUR"}}],"note":{"body":"Kommt mit Hund.","version":"2","updatedAt":"2026-11-01T10:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ApiGuest"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/conversations":{"get":{"operationId":"listConversations","summary":"List guest conversations","description":"Requires property.read, reservation.read and guest.read. The app's messages list: one conversation per booking with its last message, newest first; `unanswered=true` keeps those waiting for the host. PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."},"required":false,"description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one.","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"`true` lists only conversations whose last guest message has no answer yet."},"required":false,"description":"`true` lists only conversations whose last guest message has no answer yet.","name":"unanswered","in":"query"}],"responses":{"200":{"description":"One page of conversations.","content":{"application/json":{"example":{"data":[{"reservationId":"20000000-0000-4000-8000-000000000001","reservationNumber":1042,"unitName":"Apartment 1","checkIn":"2026-12-04","checkOut":"2026-12-07","guestName":"Ada Lovelace","lastDirection":"guest","lastBody":"Können wir schon um 14 Uhr kommen?","lastAt":"2026-11-16T18:02:00.000Z","messages":3,"unanswered":true}],"hasMore":false,"nextCursor":null},"schema":{"$ref":"#/components/schemas/ApiConversationPage"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/conversation":{"get":{"operationId":"getConversation","summary":"Read a booking's conversation","description":"Requires property.read, reservation.read and guest.read. Every message between guest and host on this booking, oldest first, as the app shows it. PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The conversation.","content":{"application/json":{"example":{"canAnswer":true,"hasEmail":true,"messages":[{"id":"50000000-0000-4000-8000-000000000001","direction":"guest","body":"Können wir schon um 14 Uhr kommen?","createdAt":"2026-11-16T18:02:00.000Z"}]},"schema":{"$ref":"#/components/schemas/ApiConversation"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"answerConversation","summary":"Answer a guest","description":"Requires property.read, reservation.create_manual and guest.read: the key writes its own text to the guest, a guest-data action PostgreSQL holds as well. It mails the guest, so it takes the sensitive budget. The app's answer in a booking's conversation: the text appears on the guest page and is also e-mailed where the booking has an address (`mailed`). 1–2000 characters after trimming, without control characters. The answer does not repeat the text; read the conversation with getConversation.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiConversationAnswerRequest"}}}},"responses":{"200":{"description":"The answer is in the conversation.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","outcome":"sent","mailed":true},"schema":{"$ref":"#/components/schemas/ApiConversationAnswered"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/check-in":{"get":{"operationId":"getCheckIn","summary":"Read a booking's online check-in","description":"Requires property.read, reservation.read and guest.read. What the guest entered at online check-in: arrival time and every person with birth date, nationality, document number and address, and the day Keyset erases it. The document number is masked unless the key also holds reservation.create_manual, as in the app. PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The check-in of the booking.","content":{"application/json":{"example":{"enabled":true,"open":true,"partySize":2,"checkIn":{"arrivalTime":"15:00","submittedAt":"2026-11-20T08:00:00.000Z","updatedAt":"2026-11-20T08:00:00.000Z","eraseAfter":"2028-03-07","persons":[{"firstName":"Ada","lastName":"Lovelace","birthDate":"1990-12-10","nationality":"GB","documentNumber":null,"address":{"street":"St James Square 12","postalCode":"SW1Y 4JH","city":"London","country":"GB"}}]}},"schema":{"$ref":"#/components/schemas/ApiCheckIn"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-requests":{"get":{"operationId":"listBookingRequests","summary":"List booking requests","description":"Requires property.read and guest.read. The guests' booking requests the host answers in the app: the open ones by their answer deadline, then those ended in the last 30 days (at most 100). PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The requests.","content":{"application/json":{"example":{"canAnswer":true,"data":[{"id":"60000000-0000-4000-8000-000000000001","state":"open","version":"1","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"stay":{"checkIn":"2027-01-08","checkOut":"2027-01-11","nights":3},"occupancy":{"adults":2,"children":0},"total":{"minorUnits":"39000","currency":"EUR"},"guest":{"firstName":"Grace","lastName":"Hopper"},"language":"de","hasNote":true,"submittedAt":"2026-11-17T07:30:00.000Z","answerBy":"2026-11-19T07:30:00.000Z","endedAt":null,"erased":false,"reservation":null,"paymentWay":null}]},"schema":{"$ref":"#/components/schemas/ApiBookingRequestList"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-requests/{bookingRequestId}":{"get":{"operationId":"getBookingRequest","summary":"Read a booking request","description":"Requires property.read and guest.read. One request with the guest's contact and note, its price lines, the terms the guest accepted, what already uses its nights, and whether it can still be accepted; `version` is what an answer sends back. PostgreSQL answers it only for a key that holds guest.read: without it the operation answers 403, and the definer returns nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking request."},"required":true,"description":"The booking request.","name":"bookingRequestId","in":"path"}],"responses":{"200":{"description":"The request.","content":{"application/json":{"example":{"id":"60000000-0000-4000-8000-000000000001","state":"open","version":"1","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"stay":{"checkIn":"2027-01-08","checkOut":"2027-01-11","nights":3},"occupancy":{"adults":2,"children":0},"total":{"minorUnits":"39000","currency":"EUR"},"guest":{"firstName":"Grace","lastName":"Hopper"},"language":"de","hasNote":true,"submittedAt":"2026-11-17T07:30:00.000Z","answerBy":"2026-11-19T07:30:00.000Z","endedAt":null,"erased":false,"reservation":null,"paymentWay":null,"email":"grace@example.com","phone":null,"note":"Wir reisen mit dem Zug an.","declineMessage":null,"ratePlanName":null,"lines":[{"kind":"nightly_accommodation","label":"3 Nächte","amount":{"minorUnits":"39000","currency":"EUR"}}],"earlierBookings":0,"overlaps":[],"acceptable":true},"schema":{"$ref":"#/components/schemas/ApiBookingRequest"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tasks":{"get":{"operationId":"getTaskBoard","summary":"Read the task board","description":"Requires property.read. The task board of the app for a window of days: the tasks due in it and every open overdue one (cleaning after each departure, maintenance and free tasks, with their checklists and who they are assigned to), the apartments, who can be assigned and the helpers without an account. A helper’s link or token is never part of it. `canManage` and `canComplete` describe what this key may change.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"date","description":"First day of the window."},"required":true,"description":"First day of the window.","name":"from","in":"query"},{"schema":{"type":"string","format":"date","description":"Last day of the window, not before `from`."},"required":true,"description":"Last day of the window, not before `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"The board for the window.","content":{"application/json":{"example":{"canManage":true,"today":"2026-11-17","units":[{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"}],"assignees":[{"membershipId":"40000000-0000-4000-8000-000000000001","name":"Mara"}],"helpers":[{"id":"40000000-0000-4000-8000-000000000002","name":"Reinigung Süd","linkIssuedAt":"2026-10-20T09:00:00.000Z"}],"tasks":[{"id":"40000000-0000-4000-8000-000000000003","kind":"cleaning","title":"Endreinigung Apartment 1","note":null,"dueOn":"2026-11-18","state":"open","unitId":"30000000-0000-4000-8000-000000000001","unitName":"Apartment 1","reservationId":"40000000-0000-4000-8000-000000000004","reservationNumber":1042,"nextArrival":{"date":"2026-11-20","time":"15:00"},"assignee":null,"helper":{"id":"40000000-0000-4000-8000-000000000002","name":"Reinigung Süd"},"checks":[{"position":0,"label":"Betten beziehen","done":false}],"version":"1","doneAt":null,"canManage":true,"canComplete":true}]},"schema":{"$ref":"#/components/schemas/ApiTaskBoard"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"createTask","summary":"Create a task","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Aufgabe anlegen\": a maintenance or custom task with a title, an optional note, a due day, an optional apartment, an optional team member or helper (from the board's assignees and helpers) and a checklist of at most 50 items. A cleaning task is made by Keyset after each departure, never here. Read the board with getTaskBoard.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskCreateRequest"}}}},"responses":{"201":{"description":"The task exists.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiTaskCreated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/attention":{"get":{"operationId":"listAttentionCases","summary":"List the Eingang payment and refund cases","description":"Requires property.read. The payment, refund and dispute cases of Eingang, assessed as the app shows them: open cases first, resolved history last, with the open count and how many need the host (“Braucht dich”). Amounts and states only; no payment-provider identifier or secret, and no guest data, is part of a case. Imports waiting in Eingang are read with listImportBatches.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"Every case of the Property.","content":{"application/json":{"example":{"asOf":"2026-11-17T08:00:00.000Z","openCount":1,"needsYouCount":1,"cases":[{"caseId":"refund_40000000-0000-4000-8000-000000000005","kind":"refund","outcome":"delayed","severity":"high","impact":"refund_pending","nextAction":"reconcile_now","reconcileAvailable":true,"firstSeenAt":"2026-11-15T10:00:00.000Z","lastChangedAt":"2026-11-16T10:00:00.000Z","reservation":{"id":"40000000-0000-4000-8000-000000000004","confirmationReference":"K7Q2M9X4P1RT","number":1042,"state":"cancelled"},"unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"payment":{"id":"40000000-0000-4000-8000-000000000006","state":"succeeded","provider":"stripe","amount":{"minorUnits":"48600","currency":"EUR"},"createdAt":"2026-11-02T09:14:41.000Z","succeededAt":"2026-11-02T09:15:00.000Z","failedAt":null,"providerReferenceKnown":true},"checkout":{"id":"40000000-0000-4000-8000-000000000007","lifecycle":"completed","terminalReason":null,"terminalAt":"2026-11-02T09:15:00.000Z"},"refund":{"id":"40000000-0000-4000-8000-000000000005","state":"processing","reason":"operator_cancellation","amount":{"minorUnits":"48600","currency":"EUR"},"requestedAt":"2026-11-15T10:00:00.000Z","terminalAt":null,"providerReferenceKnown":true},"cancellation":{"id":"40000000-0000-4000-8000-000000000008","cancelledAt":"2026-11-15T09:59:00.000Z"},"dispute":null,"operation":{"destination":"payment_refund","state":"retry_wait","attemptCount":2,"reconcileAttemptCount":0,"firstAttemptAt":"2026-11-15T10:00:05.000Z","lastAttemptAt":"2026-11-16T10:00:05.000Z","unknownSince":null,"reconcileAfter":null,"deliveredAt":null,"quarantinedAt":null,"quarantineReason":null,"lastErrorCode":null},"attentionItem":{"state":"open","firstSeenAt":"2026-11-15T10:00:00.000Z","resolvedAt":null},"quarantinedInboxMessages":0,"closure":null,"closable":false}]},"schema":{"$ref":"#/components/schemas/ApiAttentionList"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/attention/{caseId}":{"get":{"operationId":"getAttentionCase","summary":"Read one Eingang case with its money flow","description":"Requires property.read. One payment, refund or dispute case as the app opens it: the booking, payment, checkout, refund, cancellation and dispute amounts and states, the delivery bookkeeping and the history of what happened in causal order. No payment-provider identifier or secret, and no guest data, is part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^(refund|payment|dispute)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it."},"required":true,"description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it.","name":"caseId","in":"path"}],"responses":{"200":{"description":"The case.","content":{"application/json":{"example":{"asOf":"2026-11-17T08:00:00.000Z","case":{"caseId":"refund_40000000-0000-4000-8000-000000000005","kind":"refund","outcome":"delayed","severity":"high","impact":"refund_pending","nextAction":"reconcile_now","reconcileAvailable":true,"firstSeenAt":"2026-11-15T10:00:00.000Z","lastChangedAt":"2026-11-16T10:00:00.000Z","reservation":{"id":"40000000-0000-4000-8000-000000000004","confirmationReference":"K7Q2M9X4P1RT","number":1042,"state":"cancelled"},"unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"payment":{"id":"40000000-0000-4000-8000-000000000006","state":"succeeded","provider":"stripe","amount":{"minorUnits":"48600","currency":"EUR"},"createdAt":"2026-11-02T09:14:41.000Z","succeededAt":"2026-11-02T09:15:00.000Z","failedAt":null,"providerReferenceKnown":true},"checkout":{"id":"40000000-0000-4000-8000-000000000007","lifecycle":"completed","terminalReason":null,"terminalAt":"2026-11-02T09:15:00.000Z"},"refund":{"id":"40000000-0000-4000-8000-000000000005","state":"processing","reason":"operator_cancellation","amount":{"minorUnits":"48600","currency":"EUR"},"requestedAt":"2026-11-15T10:00:00.000Z","terminalAt":null,"providerReferenceKnown":true},"cancellation":{"id":"40000000-0000-4000-8000-000000000008","cancelledAt":"2026-11-15T09:59:00.000Z"},"dispute":null,"operation":{"destination":"payment_refund","state":"retry_wait","attemptCount":2,"reconcileAttemptCount":0,"firstAttemptAt":"2026-11-15T10:00:05.000Z","lastAttemptAt":"2026-11-16T10:00:05.000Z","unknownSince":null,"reconcileAfter":null,"deliveredAt":null,"quarantinedAt":null,"quarantineReason":null,"lastErrorCode":null},"attentionItem":{"state":"open","firstSeenAt":"2026-11-15T10:00:00.000Z","resolvedAt":null},"quarantinedInboxMessages":0,"closure":null,"closable":false},"history":[{"at":"2026-11-15T09:59:00.000Z","event":"reservation_cancelled","kind":"cancelled","detail":null},{"at":"2026-11-15T10:00:00.000Z","event":"refund_requested","kind":"refund_requested","detail":null}]},"schema":{"$ref":"#/components/schemas/ApiAttentionCaseDetails"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/imports":{"get":{"operationId":"listImportBatches","summary":"List the imports","description":"Requires property.read and property.configure. The import list of the app, newest first: each dry run and committed import with its counts per classification, and the bookings the host left unticked that still wait in Eingang. The guest’s name is not part of it. Open one batch with getImportBatch.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The imports of the Property.","content":{"application/json":{"example":{"asOf":"2026-11-17T08:00:00.000Z","batches":[{"id":"40000000-0000-4000-8000-000000000009","createdAt":"2026-11-10T12:00:00.000Z","state":"dry_run","format":"keyset.import.v1+csv","sourceSystem":"keyset.import.v1","sourceReference":"buchungen.csv","sourceDigest":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","summary":{"recordCount":3,"ready":2,"duplicate":0,"conflict":1,"unmapped":0,"invalid":0,"review":0,"ignored":0},"reconciliation":null}],"openDecisions":[{"id":"40000000-0000-4000-8000-000000000010","batchId":"40000000-0000-4000-8000-000000000009","recordId":"40000000-0000-4000-8000-000000000011","rowNumber":3,"sourceReference":"buchungen.csv","checkIn":"2026-12-04","checkOut":"2026-12-07","unitReference":"Wohnung 1","unitName":null,"classification":"unmapped","openedAt":"2026-11-10T12:05:00.000Z"}]},"schema":{"$ref":"#/components/schemas/ApiImportBatchList"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/imports/{batchId}":{"get":{"operationId":"getImportBatch","summary":"Read one import report","description":"Requires property.read and property.configure. One import as the app opens it, record by record with the findings behind each. A record says whether the file carried an e-mail address or phone number, never the values; the guest’s name, the source note and the reconciliation detail of a row are not part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The import batch."},"required":true,"description":"The import batch.","name":"batchId","in":"path"}],"responses":{"200":{"description":"The report.","content":{"application/json":{"example":{"asOf":"2026-11-17T08:00:00.000Z","batch":{"id":"40000000-0000-4000-8000-000000000009","createdAt":"2026-11-10T12:00:00.000Z","state":"dry_run","format":"keyset.import.v1+csv","sourceSystem":"keyset.import.v1","sourceReference":"buchungen.csv","sourceDigest":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","summary":{"recordCount":3,"ready":2,"duplicate":0,"conflict":1,"unmapped":0,"invalid":0,"review":0,"ignored":0},"reconciliation":null},"records":[{"recordId":"40000000-0000-4000-8000-000000000011","row":1,"kind":"reservation","sourceId":"B-1001","unitReference":"Wohnung 1","unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"status":"confirmed","blockKind":null,"amount":{"minorUnits":"48600","currency":"EUR"},"confirmationCode":"ABC123","occupancy":{"adults":2,"children":1},"guestContactSupplied":{"email":true,"phone":false},"classification":"ready","findings":[],"commitOutcome":null,"businessObject":null,"committedAt":null,"laterState":null}]},"schema":{"$ref":"#/components/schemas/ApiImportBatchDetails"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/stay-analytics":{"get":{"operationId":"getStayAnalytics","summary":"Read the stay analytics","description":"Requires property.read and reservation.read. The Auswertung of the app for the twelve months up to `month` (default: the current one), oldest first: sold and available nights, occupancy, revenue by source, average per night, revenue per available night, direct share, saved commission against the Property’s commission rate, cancellation fees and arrivals. Amounts are integer minor units in the Property’s currency; an answer for more than 24 months ahead is 422.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"The month the twelve end with, `YYYY-MM`; the Property’s current month when absent."},"required":false,"description":"The month the twelve end with, `YYYY-MM`; the Property’s current month when absent.","name":"month","in":"query"}],"responses":{"200":{"description":"Twelve months of figures.","content":{"application/json":{"example":{"month":"2026-11","previousMonth":"2026-10","nextMonth":"2026-12","currency":"EUR","commissionBasisPoints":1500,"months":[{"month":"2025-12","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-01","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-02","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-03","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-04","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-05","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-06","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-07","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-08","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-09","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-10","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12},{"month":"2026-11","blockedNights":0,"availableNights":150,"soldNights":42,"occupancyBasisPoints":2800,"revenue":{"direct":{"minorUnits":"300000","currency":"EUR"},"manual":{"minorUnits":"0","currency":"EUR"},"import":{"minorUnits":"100000","currency":"EUR"},"total":{"minorUnits":"400000","currency":"EUR"}},"averageNightly":{"minorUnits":"9524","currency":"EUR"},"revenuePerAvailableNight":{"minorUnits":"2667","currency":"EUR"},"directShareBasisPoints":7500,"savedCommission":{"minorUnits":"45000","currency":"EUR"},"cancellationFees":{"minorUnits":"0","currency":"EUR"},"arrivals":12}]},"schema":{"$ref":"#/components/schemas/ApiStayAnalytics"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guest-messages":{"get":{"operationId":"getGuestMessageSettings","summary":"Read the automatic guest messages","description":"Requires property.read and reservation.read. The Gäste-Nachrichten settings of the app: whether the message before arrival and the thank-you after departure are on, how many days before arrival the first goes out, and the host's texts in German and English. The lines per apartment (they may hold key-box codes) and the guests a mail can be previewed as are not part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The message settings.","content":{"application/json":{"example":{"version":"3","property":{"name":"Haus am See","checkInTime":"15:00","checkOutTime":"10:30"},"preArrival":{"enabled":true,"daysBefore":3,"de":"Wir freuen uns auf euch!","en":"We look forward to your stay!"},"postDeparture":{"enabled":true,"de":"Danke für euren Besuch.","en":"Thank you for staying with us.","reviewUrl":null}},"schema":{"$ref":"#/components/schemas/ApiGuestMessageSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveGuestMessageSettings","summary":"Save the automatic guest messages","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Sends no mail. The app's „Gäste-Nachrichten“: whether the message before arrival (so many days before, at 10:00 at the Property) and the thank-you after departure go out, their German and English texts (a message switched on needs its German one; placeholders such as {Vorname} are filled per booking), the review link the thank-you carries and the line each apartment adds to the arrival message. Those lines can hold a key-box code, so no read answers them and this write sets only those sent in `units`: an apartment not listed keeps its line, a German line null removes it, and without `units` every line stays. Send `version` of getGuestMessageSettings as `expectedVersion` (\"0\" before the first save; getGuestMessageSettings asks reservation.read), or the `version` an earlier save answered; a newer one answers VERSION_CONFLICT. A message on without its German text, a text too long, a review link that is not https or an English line without a German one answer INVALID_REQUEST; an apartment not of this Property answers NOT_FOUND. Answers whether anything changed (always `saved` when `units` are sent) and the version now in force. Announces the `settings.changed` webhook event with `area` `guest-messages`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestMessageSettingsSaveRequest"}}}},"responses":{"200":{"description":"Saved, or the same was stored already.","content":{"application/json":{"example":{"outcome":"saved","version":"4"},"schema":{"$ref":"#/components/schemas/ApiGuestMessageSettingsSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the messages were saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid, a message is on without its German text, a text is too long or the review link is not https.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guest-mail-senders":{"get":{"operationId":"getGuestMailSenders","summary":"Read who writes each guest mail","description":"Requires property.read and property.configure. Per kind of guest mail (confirmation, cancellation, change, refund) whether Keyset writes it or the business's own system does, whether a webhook endpoint receives the kind's event right now, and how many mails Keyset wrote itself in the last 30 days because none of the event's deliveries arrived.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The sender per kind.","content":{"application/json":{"example":{"kinds":[{"kind":"confirmation","sender":"keyset","version":"0","receiverReady":false,"fallbacks":0},{"kind":"cancellation","sender":"own","version":"2","receiverReady":true,"fallbacks":1}]},"schema":{"$ref":"#/components/schemas/ApiGuestMailSenders"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"setGuestMailSender","summary":"Choose who writes a kind of guest mail","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Sends no mail. The app's „Absender der Mails“: per kind of guest mail (confirmation, cancellation, change, refund) whether Keyset writes it or the business's own system does, from the kind's webhook event. `own` is taken only while an active webhook endpoint of the Property receives that event (WEBHOOK_RECEIVER_MISSING otherwise); `fallbacks` of the read counts the mails Keyset wrote itself because none of an event's deliveries arrived. Send `kinds[].version` of getGuestMailSenders for the kind as `expectedVersion`; a newer one answers VERSION_CONFLICT. Answers the senders as getGuestMailSenders reads them. Announces the `settings.changed` webhook event with `area` `guest-mail-senders`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestMailSenderSaveRequest"}}}},"responses":{"200":{"description":"Saved, or the same sender was stored already, and every kind’s sender now.","content":{"application/json":{"example":{"kinds":[{"kind":"confirmation","sender":"own","version":"1","receiverReady":true,"fallbacks":0},{"kind":"cancellation","sender":"keyset","version":"0","receiverReady":false,"fallbacks":0},{"kind":"change","sender":"keyset","version":"0","receiverReady":false,"fallbacks":0},{"kind":"refund","sender":"keyset","version":"0","receiverReady":false,"fallbacks":0}]},"schema":{"$ref":"#/components/schemas/ApiGuestMailSenders"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the sender of this kind was saved by someone else since your read; WEBHOOK_RECEIVER_MISSING: `own` while no active webhook endpoint receives the kind’s event; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guest-cancellation-mail":{"get":{"operationId":"getGuestCancellationMail","summary":"Read the cancellation mail rule","description":"Requires property.read and property.configure. Whether Keyset writes the guest of a booking made from a request, or of a manual booking, when it is cancelled. Until the first save the defaults hold: requests yes, manual bookings only after Keyset sent that guest the confirmation.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The rule.","content":{"application/json":{"example":{"requestBookings":true,"manualBookings":"after_confirmation","version":"0"},"schema":{"$ref":"#/components/schemas/ApiGuestCancellationMail"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveGuestCancellationMail","summary":"Save the cancellation mail of request and manual bookings","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Sends no mail. The app's „Stornierung an den Gast“: whether Keyset writes the guest of a booking made from a request when it is cancelled, and for a manual booking always, only when Keyset sent that guest the confirmation, or never. Send `version` of getGuestCancellationMail as `expectedVersion` (\"0\" before the first save); a newer one answers VERSION_CONFLICT. Answers the rule as getGuestCancellationMail reads it. Announces the `settings.changed` webhook event with `area` `guest-cancellation-mail`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestCancellationMailSaveRequest"}}}},"responses":{"200":{"description":"Saved, or the same rule was stored already, and the rule now in force.","content":{"application/json":{"example":{"requestBookings":true,"manualBookings":"always","version":"1"},"schema":{"$ref":"#/components/schemas/ApiGuestCancellationMail"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the rule was saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/check-in-settings":{"get":{"operationId":"getCheckInSettings","summary":"Read the online check-in setting","description":"Requires property.read and property.configure. Whether guests are asked for their online check-in. The check-ins themselves hold personal data and are not part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The setting.","content":{"application/json":{"example":{"enabled":true,"version":"1"},"schema":{"$ref":"#/components/schemas/ApiCheckInSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveCheckInSettings","summary":"Switch the online check-in","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Sends no mail. The app's „Online-Check-in anbieten“: whether guests are asked online for the details of everyone staying before they arrive. Send `version` of getCheckInSettings as `expectedVersion` (\"0\" before the first save); a newer one answers VERSION_CONFLICT. Answers the switch as getCheckInSettings reads it. Announces the `settings.changed` webhook event with `area` `check-in-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCheckInSettingsSaveRequest"}}}},"responses":{"200":{"description":"Saved, or the same was stored already, and the switch now.","content":{"application/json":{"example":{"enabled":true,"version":"2"},"schema":{"$ref":"#/components/schemas/ApiCheckInSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the switch was saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/task-checklists":{"get":{"operationId":"getTaskChecklists","summary":"Read the cleaning checklists","description":"Requires property.read. The cleaning checklists of the app: the default list for the Property and, per active apartment, its own list or null when it uses the default. The text of an item is the host's own.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The checklists.","content":{"application/json":{"example":{"default":["Betten abziehen","Bad reinigen"],"units":[{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1","items":null}]},"schema":{"$ref":"#/components/schemas/ApiTaskChecklists"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveTaskChecklist","summary":"Save or remove a cleaning checklist","description":"Requires property.read and reservation.create_manual, the grant the app asks of a person who manages tasks; PostgreSQL holds it for a key as well. The app's „Checklisten“: the default cleaning list of the Property (`unitId` null) or an apartment's own list, as the points in order. An empty list removes it, so the apartment follows the default list again. An open cleaning without points takes the list; a cleaning keeps the points it already has. Answers the checklists as getTaskChecklists reads them. Announces the `settings.changed` webhook event with `area` `task-checklists`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskChecklistSaveRequest"}}}},"responses":{"200":{"description":"Saved, and the checklists now.","content":{"application/json":{"example":{"default":["Betten abziehen","Bad reinigen"],"units":[{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1","items":["Betten abziehen","Bad reinigen","Sauna auswischen"]}]},"schema":{"$ref":"#/components/schemas/ApiTaskChecklists"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid, or a point is empty or longer than 200 characters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-connections":{"get":{"operationId":"getCalendarConnections","summary":"Read the calendar connections","description":"Requires property.read and property.configure. The Kalender-Sync page of the app: each connected portal calendar with its state, last attempt and last success, the number of imported stays and those in conflict, and per apartment whether Keyset's own calendar link exists. Neither a calendar link nor a token is part of it; the portal appears only as its host name.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The connections and the export state per apartment.","content":{"application/json":{"example":{"asOf":"2026-11-17T08:00:00.000Z","property":{"id":"10000000-0000-4000-8000-000000000001","name":"Haus am See","timezone":"Europe/Berlin"},"units":[{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1","status":"active"}],"connections":[{"id":"20000000-0000-4000-8000-000000000001","name":"Portal A","provider":"ical","sourceHost":"portal.example","lifecycle":"active","health":"healthy","unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"lastAttemptAt":"2026-11-17T07:55:00.000Z","lastSuccessAt":"2026-11-17T07:55:00.000Z","lastErrorCode":null,"lastErrorAt":null,"activeEventCount":12,"conflictCount":0}],"exports":[{"unitId":"30000000-0000-4000-8000-000000000001","unitName":"Apartment 1","lifecycle":"active","createdAt":"2026-10-01T09:00:00.000Z","rotatedAt":null}]},"schema":{"$ref":"#/components/schemas/ApiCalendarConnections"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"connectCalendar","summary":"Connect a portal’s calendar to an apartment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Kalender verbinden“: keeps the portal's calendar link sealed and reads it from now on every 15 minutes; each portal stay blocks its nights, a stay on nights Keyset already holds becomes a conflict (probeCalendarConnection shows them first). Fetches nothing itself; the first read follows within minutes, or at once with refreshCalendarConnection. A key also needs reservation.create_manual and inventory.block (PERMISSION_DENIED otherwise; PostgreSQL holds them as well), as for taking over an import: every read turns the portal’s stays into bookings that hold nights and cancels them when the portal drops them. A connection keeps being read every 15 minutes whoever made it, as in the app. Keyset fetches the link exactly as the app does: https only (an http link is upgraded, webcal read as https), never an address outside the public internet (also after a redirect), at most three redirects, 2 MiB and 10 seconds; the request counts against the Property’s smaller budget for calls to the outside. A test business connects no portal calendar and fetches none (ADR-040): it answers NOT_FOUND. The link is the host’s key to the portal’s calendar: it is never returned, not in this answer, a replay, a read or a problem; reads name its host only. A link that is not one Keyset fetches answers CALENDAR_LINK_INVALID, this Property's own calendar link CALENDAR_OWN_LINK (both before anything is written) and a link connected already CALENDAR_ALREADY_CONNECTED. Announces the `settings.changed` webhook event with `area` `calendar-connections`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCalendarConnectRequest"}}}},"responses":{"201":{"description":"Connected.","content":{"application/json":{"example":{"outcome":"created","connectionId":"60000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiCalendarConnected"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"CALENDAR_ALREADY_CONNECTED: the same link is connected already; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid; CALENDAR_LINK_INVALID: not an https (or webcal) link, or one with a user name, password or fragment; CALENDAR_OWN_LINK: Keyset’s own calendar link of this Property.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/payment-settings":{"get":{"operationId":"getPaymentSettings","summary":"Read the payment account state","description":"Requires property.read and property.configure. The Zahlungen page of the app as flags and terms: the state of the payment account, whether charges and payouts are enabled, whether guests can pay online now, the currency and the cancellation terms of card payments. No payment-provider account identifier, link or secret is part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The payment settings.","content":{"application/json":{"example":{"environment":"live","status":"ready","currency":"EUR","country":"DE","chargesEnabled":true,"payoutsEnabled":true,"currencies":["EUR"],"acceptsBookings":true,"cancellationPolicy":{"version":2,"freeCancellationDays":14,"lateRefundPercent":50}},"schema":{"$ref":"#/components/schemas/ApiPaymentSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/deposit-policy":{"get":{"operationId":"getDepositPolicy","summary":"Read the deposit rule","description":"Requires property.read and property.configure. Whether guests pay a deposit now and the rest later, the deposit in percent and the days before arrival the rest is due. A change reaches only quotes made afterwards.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The rule.","content":{"application/json":{"example":{"enabled":true,"depositPercent":30,"balanceDueDays":30,"version":"1"},"schema":{"$ref":"#/components/schemas/ApiDepositPolicy"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveDepositPolicy","summary":"Save the deposit rule","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The app's „Anzahlung“: whether guests pay a deposit at booking and the rest later, the deposit in whole percent (10 to 90) and the days before arrival the rest is due (1 to 180). Send `version` of getDepositPolicy as `expectedVersion` (null before the first save); a newer one answers VERSION_CONFLICT. A change reaches only quotes made afterwards. Answers the rule as getDepositPolicy reads it. Announces the `settings.changed` webhook event with `area` `deposit-policy`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDepositPolicySaveRequest"}}}},"responses":{"200":{"description":"Saved, and the rule now in force.","content":{"application/json":{"example":{"enabled":true,"depositPercent":30,"balanceDueDays":30,"version":"2"},"schema":{"$ref":"#/components/schemas/ApiDepositPolicy"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the rule was saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/split-payment-policy":{"get":{"operationId":"getSplitPaymentPolicy","summary":"Read the split payment rule","description":"Requires property.read and property.configure. Whether guests may split the payment of a booking between them (Geteilte Zahlung). The links of a running split belong to the guests and are not part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The rule.","content":{"application/json":{"example":{"enabled":false,"version":null},"schema":{"$ref":"#/components/schemas/ApiSplitPaymentPolicy"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveSplitPaymentPolicy","summary":"Switch the split payment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The app's „Geteilte Zahlung“: whether guests may split the payment of a booking between several people. Send `version` of getSplitPaymentPolicy as `expectedVersion` (null before the first save); a newer one answers VERSION_CONFLICT. A split already running keeps its links. Answers the rule as getSplitPaymentPolicy reads it. Announces the `settings.changed` webhook event with `area` `split-payment-policy`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSplitPaymentPolicySaveRequest"}}}},"responses":{"200":{"description":"Saved, and the rule now in force.","content":{"application/json":{"example":{"enabled":true,"version":"1"},"schema":{"$ref":"#/components/schemas/ApiSplitPaymentPolicy"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the rule was saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/transfer-details":{"get":{"operationId":"getTransferDetails","summary":"Read the bank details for transfers","description":"Requires property.read. Whether the host's bank details for transfers are set, the account holder and the IBAN masked to its first and last digits, as the app shows them to every reader of the Property. The full IBAN and the BIC are never part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The bank details, masked.","content":{"application/json":{"example":{"configured":true,"holder":"Haus am See GbR","ibanMasked":"DE89…3000","version":"2","updatedAt":"2026-10-20T10:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiTransferDetails"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoice-settings":{"get":{"operationId":"getInvoiceSettings","summary":"Read the invoice issuer settings","description":"Requires property.read and either reservation.read or property.configure. The Rechnungen settings of the app: the issuer as it stands on an invoice (name, address, tax number, VAT id), the prefix and next number, the small-business rule (§ 19 UStG) and the last invoice issued. The host's contact and who issued the last invoice are not part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The issuer settings.","content":{"application/json":{"example":{"version":"1","issuerName":"Haus am See GbR","street":"Seestraße 1","postalCode":"83700","city":"Rottach-Egern","country":"DE","taxNumber":"143/123/45678","vatId":null,"prefix":"RE-2026-","nextNumber":43,"issued":42,"minimumNext":43,"numberingVersion":"42","smallBusiness":false,"taxVersion":"0","lastIssued":{"number":"RE-2026-0042","kind":"invoice","issueDate":"2026-11-10","issuedAt":"2026-11-10T09:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ApiInvoiceSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveInvoiceIssuer","summary":"Save the invoice issuer","description":"Requires property.read and property.configure. The invoice settings belong to the business, so PostgreSQL asks, as the app does of a person, for property.configure on every active Property of the business: a key issued for some of them only answers NOT_FOUND. The app's „Aussteller“ of Rechnungen: the name, address, tax number and VAT id every invoice of the business prints from the next one issued; invoices issued keep what they say. Send `version` of getInvoiceSettings as `expectedVersion`. The version is read with getInvoiceSettings (which asks reservation.read or property.configure); a stale one answers VERSION_CONFLICT. Answers whether anything changed. Announces the `settings.changed` webhook event with `area` `invoice-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInvoiceIssuerSaveRequest"}}}},"responses":{"200":{"description":"Saved (or already so).","content":{"application/json":{"example":{"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiInvoiceSettingsSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the issuer was saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/accounting-settings":{"get":{"operationId":"getAccountingSettings","summary":"Read the DATEV settings","description":"Requires property.read and either reservation.read or property.configure. The Buchhaltung settings of the app: the chart of accounts, the tax adviser's and the client number, the clearing account and the revenue account and VAT rate per kind of item. The accounts Keyset proposes are not part of it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The DATEV settings.","content":{"application/json":{"example":{"version":"1","chart":"SKR03","smallBusiness":false,"advisorNumber":12345,"clientNumber":100,"clearingAccount":1360,"items":[{"kind":"accommodation","rate":7,"account":8300},{"kind":"cleaning","rate":19,"account":8400}],"extras":[{"id":"breakfast","name":"Frühstück"}]},"schema":{"$ref":"#/components/schemas/ApiAccountingSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveAccountingSettings","summary":"Save the DATEV settings","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's Buchhaltung „Speichern“: the chart of accounts, the adviser's and the business's numbers at DATEV, the clearing account and one account per kind of item and VAT rate; `items` replaces the stored list. The DATEV batch (exportDatev) books by them from then on. Send `version` of getAccountingSettings (which asks reservation.read or property.configure) as `expectedVersion`; a newer one answers VERSION_CONFLICT. The small-business rule is shown there but switched with saveSmallBusiness. Announces the `settings.changed` webhook event with `area` `accounting-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAccountingSaveRequest"}}}},"responses":{"200":{"description":"Saved (or already so).","content":{"application/json":{"example":{"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiAccountingSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the settings were saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties":{"get":{"operationId":"listProperties","summary":"List the Properties a key reads","description":"Requires nothing beyond a valid secret key. Lists only the Properties on which the key holds property.read, at most 100, live ones first, each with the grants the key holds on it, so a client learns what it may call. A Property the key does not read is not listed and not hinted at. The business is named by its name and mode (live or test).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"responses":{"200":{"description":"The Properties this key reads.","content":{"application/json":{"example":{"data":[{"id":"20000000-0000-4000-8000-000000000001","name":"Ferienwohnungen am See","timezone":"Europe/Berlin","currency":"EUR","locale":"de-DE","checkInTime":"15:00","checkOutTime":"10:00","permissions":["property.read","reservation.read"],"business":{"name":"Familie Muster","mode":"live"}}]},"schema":{"$ref":"#/components/schemas/ApiPropertyList"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/configuration":{"get":{"operationId":"getPropertyConfiguration","summary":"Read the Property and its apartments","description":"Requires property.read and property.configure. The Property settings (name, time zone, currency, check-in and check-out times, kind of business, address) and the apartment list of the app: each apartment with its code, capacity, status, whether a guest can find it on the booking site, and what is booked ahead, plus archived apartments. The apartment texts, photos and prices are separate reads.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The Property and its apartments.","content":{"application/json":{"example":{"property":{"id":"20000000-0000-4000-8000-000000000001","name":"Ferienwohnungen am See","timezone":"Europe/Berlin","currency":"EUR","locale":"de-DE","status":"active","checkInTime":"15:00","checkOutTime":"10:00","businessProfile":"holiday_apartments","address":{"street":"Seestraße 1","postalCode":"83700","locality":"Rottach-Egern","country":"DE"}},"units":[{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1","maxOccupancy":4,"status":"active","futureAllocations":3,"bookedOccupancy":3,"onBookingSite":true,"componentUnitIds":[]}],"archivedUnits":[],"today":"2026-11-17","asOf":"2026-11-17T08:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiPropertyConfiguration"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"updatePropertyConfiguration","summary":"Change the Property’s settings","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Allgemein“: the Property's name, time zone, language, Anreise ab and Abreise bis, Art des Betriebs and address. Name, time zone and language are always sent; the times (together), the kind of business and the address keep what is stored when absent. The currency never changes here. An unknown time zone answers INVALID_REQUEST. Answers the Property as getPropertyConfiguration reads it after the change. Announces the `settings.changed` webhook event with `area` `configuration`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiPropertyConfigurationUpdateRequest"}}}},"responses":{"200":{"description":"The Property and its apartments after the change.","content":{"application/json":{"example":{"property":{"id":"20000000-0000-4000-8000-000000000001","name":"Ferienwohnungen am See","timezone":"Europe/Berlin","currency":"EUR","locale":"de-DE","status":"active","checkInTime":"15:00","checkOutTime":"10:00","businessProfile":"holiday_apartments","address":{"street":"Seestraße 1","postalCode":"83700","locality":"Rottach-Egern","country":"DE"}},"units":[{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1","maxOccupancy":4,"status":"active","futureAllocations":3,"bookedOccupancy":3,"onBookingSite":true,"componentUnitIds":[]}],"archivedUnits":[],"today":"2026-11-17","asOf":"2026-11-17T08:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiPropertyConfiguration"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, the times are not sent together, or the time zone is unknown.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-content":{"get":{"operationId":"getBookingContent","summary":"Read the booking page texts","description":"Requires property.read and property.configure. The texts the host writes for the booking page: the Property’s locality, description, location, amenity codes and questions, each apartment’s description, amenities, sleeping arrangement and floor area, and the English translations. `version` of the Property and of each apartment are for later writes.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The booking page texts.","content":{"application/json":{"example":{"version":"2","locality":"Rottach-Egern","description":"Fünf Apartments direkt am See.","location":null,"amenities":["wifi","parking"],"faq":[{"question":"Sind Hunde erlaubt?","answer":"Ja, auf Anfrage."}],"translations":{"en":null},"units":[{"unitId":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1","version":"1","description":"Helles Apartment mit Balkon.","amenities":["balcony","kitchen"],"sleepingArrangement":[{"kind":"bedroom","beds":[{"kind":"double","count":1}]}],"floorArea":54,"translations":{"en":null}}]},"schema":{"$ref":"#/components/schemas/ApiBookingContent"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveBookingContent","summary":"Save the booking page texts of the Property","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Buchungsseite › Inhalte“ for the Property: the place under the name, the description, the location, the amenities and the questions, and their English. The whole set is replaced; send `version` of getBookingContent as `expectedVersion` (VERSION_CONFLICT when someone saved meanwhile). Published booking pages show the new texts at once. Announces the `settings.changed` webhook event with `area` `booking-content`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBookingContentSaveRequest"}}}},"responses":{"200":{"description":"Saved, and the version the next save names.","content":{"application/json":{"example":{"outcome":"saved","version":"3"},"schema":{"$ref":"#/components/schemas/ApiContentSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/media":{"get":{"operationId":"getPropertyMedia","summary":"Read the Property photos","description":"Requires property.read and property.configure. The references of the Property’s gallery as the app shows it: asset key, alt text, role, order, size and the path of the medium and thumbnail variants under /media/, never image bytes. `version` is for later writes.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The Property gallery.","content":{"application/json":{"example":{"version":"3","images":[{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"}]},"schema":{"$ref":"#/components/schemas/ApiMediaGallery"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"uploadPropertyMedia","summary":"Upload a Property photo","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Bilder“ upload: `multipart/form-data` with `file`, `alt` and the gallery's `expectedVersion`. The photo is checked by its content exactly as in the app (only JPEG, PNG and WebP decoders run), stored as WebP variants outside any database transaction and placed last in the gallery; the first photo becomes the cover. A repeat with the same idempotency key answers the first upload with its `assetId` and stores nothing again. Answers the new photo's id and the gallery as the read gives it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The photo: JPEG, PNG or WebP, labelled with its own type, at most 12 MB and 40 megapixels. Keyset reads the content, not the label, and stores WebP variants."},"alt":{"type":"string","minLength":1,"maxLength":160,"description":"What the photo shows, for guests who cannot see it."},"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,14})$","description":"The gallery `version` of its read; \"0\" for a gallery without photos."}},"required":["file","alt","expectedVersion"]}}}},"responses":{"200":{"description":"This upload intent was placed before (a repeat after the idempotency window); nothing new was stored.","content":{"application/json":{"example":{"outcome":"existing","assetId":"50000000-0000-4000-8000-000000000002","gallery":{"version":"4","images":[{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"},{"assetId":"50000000-0000-4000-8000-000000000002","assetKey":"kueche-91c0","alt":"Küche mit Esstisch","role":"gallery","sortOrder":1,"width":2400,"height":1600,"url":"/media/kueche-91c0/medium.webp","thumbnailUrl":"/media/kueche-91c0/thumbnail.webp","availability":"available","resolution":"sufficient"}]}},"schema":{"$ref":"#/components/schemas/ApiMediaUploaded"}}}},"201":{"description":"The photo was stored and placed.","content":{"application/json":{"example":{"outcome":"created","assetId":"50000000-0000-4000-8000-000000000002","gallery":{"version":"4","images":[{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"},{"assetId":"50000000-0000-4000-8000-000000000002","assetKey":"kueche-91c0","alt":"Küche mit Esstisch","role":"gallery","sortOrder":1,"width":2400,"height":1600,"url":"/media/kueche-91c0/medium.webp","thumbnailUrl":"/media/kueche-91c0/thumbnail.webp","availability":"available","resolution":"sufficient"}]}},"schema":{"$ref":"#/components/schemas/ApiMediaUploaded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the gallery changed since your read; IDEMPOTENCY_KEY_REUSED also when the key placed another photo; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"413":{"description":"MEDIA_TOO_LARGE: the body is larger than the 12 MB photo and its fields; nothing was stored.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"415":{"description":"MEDIA_TYPE_UNSUPPORTED: not labelled image/jpeg, image/png or image/webp; MEDIA_UNREADABLE: the content is not a readable image of that kind. Nothing was stored.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the form, a parameter or the header is invalid; MEDIA_DIMENSIONS_TOO_LARGE: more than 40 megapixels; GALLERY_FULL: the gallery holds 20 photos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"updatePropertyMedia","summary":"Save the Property gallery","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Galerie speichern“: the whole gallery in its new order with the cover („Titelbild“) and each alt text; a photo left out is removed from the gallery. Send the gallery's `version` as `expectedVersion` (VERSION_CONFLICT when it changed). Only photos of this Property can be placed: an id of another Property's photo answers NOT_FOUND. Announces the `settings.changed` webhook event with `area` `media`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMediaGalleryUpdateRequest"}}}},"responses":{"200":{"description":"The gallery after the change.","content":{"application/json":{"example":{"version":"5","images":[{"assetId":"50000000-0000-4000-8000-000000000002","assetKey":"kueche-91c0","alt":"Küche mit Esstisch","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/kueche-91c0/medium.webp","thumbnailUrl":"/media/kueche-91c0/thumbnail.webp","availability":"available","resolution":"sufficient"},{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"gallery","sortOrder":1,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"}]},"schema":{"$ref":"#/components/schemas/ApiMediaGallery"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the gallery changed since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body is invalid, a photo is named twice, or there is not exactly one cover.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/media":{"get":{"operationId":"getUnitMedia","summary":"Read an apartment’s photos","description":"Requires property.read and property.configure. The references of one apartment’s gallery as the app shows it: asset key, alt text, role, order, size and the path of the medium and thumbnail variants under /media/, never image bytes. `version` is for later writes. An unknown apartment answers 404.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"}],"responses":{"200":{"description":"The apartment gallery.","content":{"application/json":{"example":{"version":"3","images":[{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"}]},"schema":{"$ref":"#/components/schemas/ApiMediaGallery"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"uploadUnitMedia","summary":"Upload an apartment photo","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Bilder“ upload: `multipart/form-data` with `file`, `alt` and the gallery's `expectedVersion`. The photo is checked by its content exactly as in the app (only JPEG, PNG and WebP decoders run), stored as WebP variants outside any database transaction and placed last in the gallery; the first photo becomes the cover. A repeat with the same idempotency key answers the first upload with its `assetId` and stores nothing again. Answers the new photo's id and the gallery as the read gives it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The photo: JPEG, PNG or WebP, labelled with its own type, at most 12 MB and 40 megapixels. Keyset reads the content, not the label, and stores WebP variants."},"alt":{"type":"string","minLength":1,"maxLength":160,"description":"What the photo shows, for guests who cannot see it."},"expectedVersion":{"type":"string","pattern":"^(0|[1-9]\\d{0,14})$","description":"The gallery `version` of its read; \"0\" for a gallery without photos."}},"required":["file","alt","expectedVersion"]}}}},"responses":{"200":{"description":"This upload intent was placed before (a repeat after the idempotency window); nothing new was stored.","content":{"application/json":{"example":{"outcome":"existing","assetId":"50000000-0000-4000-8000-000000000002","gallery":{"version":"4","images":[{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"},{"assetId":"50000000-0000-4000-8000-000000000002","assetKey":"kueche-91c0","alt":"Küche mit Esstisch","role":"gallery","sortOrder":1,"width":2400,"height":1600,"url":"/media/kueche-91c0/medium.webp","thumbnailUrl":"/media/kueche-91c0/thumbnail.webp","availability":"available","resolution":"sufficient"}]}},"schema":{"$ref":"#/components/schemas/ApiMediaUploaded"}}}},"201":{"description":"The photo was stored and placed.","content":{"application/json":{"example":{"outcome":"created","assetId":"50000000-0000-4000-8000-000000000002","gallery":{"version":"4","images":[{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"},{"assetId":"50000000-0000-4000-8000-000000000002","assetKey":"kueche-91c0","alt":"Küche mit Esstisch","role":"gallery","sortOrder":1,"width":2400,"height":1600,"url":"/media/kueche-91c0/medium.webp","thumbnailUrl":"/media/kueche-91c0/thumbnail.webp","availability":"available","resolution":"sufficient"}]}},"schema":{"$ref":"#/components/schemas/ApiMediaUploaded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the gallery changed since your read; IDEMPOTENCY_KEY_REUSED also when the key placed another photo; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"413":{"description":"MEDIA_TOO_LARGE: the body is larger than the 12 MB photo and its fields; nothing was stored.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"415":{"description":"MEDIA_TYPE_UNSUPPORTED: not labelled image/jpeg, image/png or image/webp; MEDIA_UNREADABLE: the content is not a readable image of that kind. Nothing was stored.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the form, a parameter or the header is invalid; MEDIA_DIMENSIONS_TOO_LARGE: more than 40 megapixels; GALLERY_FULL: the gallery holds 20 photos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"updateUnitMedia","summary":"Save an apartment’s gallery","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Galerie speichern“: the whole gallery in its new order with the cover („Titelbild“) and each alt text; a photo left out is removed from the gallery. Send the gallery's `version` as `expectedVersion` (VERSION_CONFLICT when it changed). Only photos of this Property can be placed: an id of another Property's photo answers NOT_FOUND. Announces the `unit.changed` webhook event with `change` `media`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMediaGalleryUpdateRequest"}}}},"responses":{"200":{"description":"The gallery after the change.","content":{"application/json":{"example":{"version":"5","images":[{"assetId":"50000000-0000-4000-8000-000000000002","assetKey":"kueche-91c0","alt":"Küche mit Esstisch","role":"cover","sortOrder":0,"width":2400,"height":1600,"url":"/media/kueche-91c0/medium.webp","thumbnailUrl":"/media/kueche-91c0/thumbnail.webp","availability":"available","resolution":"sufficient"},{"assetId":"50000000-0000-4000-8000-000000000001","assetKey":"seeblick-4f2a","alt":"Balkon mit Seeblick","role":"gallery","sortOrder":1,"width":2400,"height":1600,"url":"/media/seeblick-4f2a/medium.webp","thumbnailUrl":"/media/seeblick-4f2a/thumbnail.webp","availability":"available","resolution":"sufficient"}]},"schema":{"$ref":"#/components/schemas/ApiMediaGallery"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the gallery changed since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body is invalid, a photo is named twice, or there is not exactly one cover.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-site":{"get":{"operationId":"getBookingSite","summary":"Read the booking site status","description":"Requires property.read and property.configure. Whether the booking site is a draft, published or paused, its public key, and how many apartments are active, bookable and visible to guests today. A read of the status only; publishing and pausing are separate.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The booking site.","content":{"application/json":{"example":{"publicId":"Xk3p9Qw2Lm7Rt5Yv8Bn4Hc","state":"published","bookableUnits":5,"activeUnits":5,"publishedUnits":5,"pausedAt":null},"schema":{"$ref":"#/components/schemas/ApiBookingSite"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guest-info":{"get":{"operationId":"getGuestInfo","summary":"Read the host contact and legal texts","description":"Requires property.read and property.configure. Who a guest books with and the host’s legal texts as the booking page states them: contact line, Impressum, privacy notice, and the active cancellation terms (read-only). These are the host’s own details, not a guest’s. `version` is for later writes.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The host contact and legal texts.","content":{"application/json":{"example":{"version":"4","hostName":"Familie Muster","email":"urlaub@example.com","phone":"+49 8022 12345","imprintUrl":"https://example.com/impressum","imprintText":null,"privacyUrl":"https://example.com/datenschutz","privacyText":null,"cancellation":{"version":2,"origin":"operator_decision","freeCancellationDays":14,"lateRefundBasisPoints":5000}},"schema":{"$ref":"#/components/schemas/ApiGuestInfo"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveGuestInfo","summary":"Save the host contact and legal texts","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Kontakt und Rechtliches“: the host's contact line on the booking page and the Impressum and privacy notice, each as an https link or as text. These are the host's own details, shown to every guest, not guest data, so no guest.read is asked. The whole set is replaced; null or empty removes a field. Send `version` of getGuestInfo as `expectedVersion`. A refused field answers INVALID_REQUEST with `detail` naming the field and the reason. The cancellation terms are read-only here. Announces the `settings.changed` webhook event with `area` `guest-info`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestInfoSaveRequest"}}}},"responses":{"200":{"description":"Saved, and the texts as getGuestInfo reads them.","content":{"application/json":{"example":{"outcome":"saved","guestInfo":{"version":"5","hostName":"Familie Muster","email":"urlaub@example.com","phone":"+49 8022 12345","imprintUrl":"https://example.com/impressum","imprintText":null,"privacyUrl":"https://example.com/datenschutz","privacyText":null,"cancellation":{"version":2,"origin":"operator_decision","freeCancellationDays":14,"lateRefundBasisPoints":5000}}},"schema":{"$ref":"#/components/schemas/ApiGuestInfoSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body is invalid, or a field is refused (`detail`: the field and too_long, format, insecure_link or link_and_text).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-mode":{"get":{"operationId":"getBookingMode","summary":"Read how guests book","description":"Requires property.read. How guests book on the booking page: instantly, by request, or both. The mode itself is the value a later write sends back as the one it read.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The booking mode.","content":{"application/json":{"example":{"bookingMode":"both"},"schema":{"$ref":"#/components/schemas/ApiBookingMode"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"setBookingMode","summary":"Set how guests book","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Buchungsart“: guests book at once (instant), ask the host first (request) or choose (both). Send the mode getBookingMode read as `expectedBookingMode`; another one saved since answers VERSION_CONFLICT with the stored mode in `detail`. Bookings and requests already made keep their way. Announces the `settings.changed` webhook event with `area` `booking-mode`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBookingModeSaveRequest"}}}},"responses":{"200":{"description":"The mode now stored.","content":{"application/json":{"example":{"bookingMode":"request"},"schema":{"$ref":"#/components/schemas/ApiBookingMode"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: another mode was saved since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/rates":{"get":{"operationId":"getRates","summary":"Read the prices of all apartments","description":"Requires property.read and rates.publish. The prices overview of the app: per active apartment the published price a guest pays today (base, weekend and season nightly figures, minimum stay, version) and the host’s unpublished draft, and the apartments switched off with their last price. Use the `rateContextId` to read one apartment’s full rules.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The prices of the Property.","content":{"application/json":{"example":{"currency":"EUR","units":[{"unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"rateContextId":"standard","current":{"version":"3","publishedAt":"2026-10-01T09:00:00.000Z","baseNightly":{"minorUnits":"12000","currency":"EUR"},"minimumStayNights":2,"weekendNightly":{"minorUnits":"13500","currency":"EUR"},"seasonNightly":{"min":{"minorUnits":"11000","currency":"EUR"},"max":{"minorUnits":"16000","currency":"EUR"}}},"draft":{"revision":"5","updatedAt":"2026-11-10T09:00:00.000Z","baseNightly":{"minorUnits":"12500","currency":"EUR"},"valid":true,"invalidReason":null,"unpublishedChanges":true,"weekendNightly":null,"seasonNightly":null}}],"inactiveUnits":[],"evaluatorVersion":"pricing-v1","asOf":"2026-11-17T08:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiRateOverview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}":{"get":{"operationId":"getUnitRates","summary":"Read the price rules of one apartment","description":"Requires property.read and rates.publish. The rate editor of the app for one apartment: the published rules and the host’s working draft, each with the base price per night, weekend days and surcharge, price periods, cleaning fee, percentage fee, minimum and maximum stay and arrival and departure days (also per period), per-person surcharge, discounts and extras. Amounts are minor units in the Property’s currency. An unknown apartment or context answers 404.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"}],"responses":{"200":{"description":"The price rules of the apartment.","content":{"application/json":{"example":{"unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"rateContextId":"standard","evaluatorVersion":"pricing-v1","current":{"version":"3","publishedAt":"2026-10-01T09:00:00.000Z","configuration":{"baseNightlyMinorUnits":"12000","weekendDays":[5,6],"weekendAdjustmentMinorUnits":"1500","absoluteOverrides":[{"ruleId":"period-1","start":"2026-12-20","end":"2027-01-03","nightlyMinorUnits":"16000","label":"Weihnachten"}],"cleaningFee":{"ruleId":"cleaning","minorUnits":"5100"},"percentageFee":{"ruleId":"fee","label":"Servicegebühr","basisPoints":0,"bases":["nightly_accommodation"],"roundingMode":"half_up"},"minimumStayNights":2,"maximumStayNights":null,"arrivalDays":null,"departureDays":null,"minimumStayByArrivalDay":[],"stayRulePeriods":[],"guestSurcharge":null,"discounts":null,"extras":[],"quoteLifetimeSeconds":900}},"draft":null},"schema":{"$ref":"#/components/schemas/ApiRateScope"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/rate-plans":{"get":{"operationId":"listRatePlans","summary":"List the rate plans","description":"Requires property.read. The rate plans of the app: the standard rate’s cancellation terms and each further plan with its discount on the accommodation, its own cancellation terms, the apartments it is not offered for and its version. Changing a plan needs rates.publish; `canManage` says whether this key holds it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The rate plans.","content":{"application/json":{"example":{"canManage":false,"units":[{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"}],"standardTerms":{"freeCancellationDays":14,"lateRefundBasisPoints":5000},"plans":[{"id":"60000000-0000-4000-8000-000000000001","reference":"nr-7k2m","name":"Nicht erstattbar","basisPoints":1000,"version":"1","terms":{"freeCancellationDays":null,"lateRefundBasisPoints":0},"excludedUnitIds":[]}]},"schema":{"$ref":"#/components/schemas/ApiRatePlans"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"createRatePlan","summary":"Create a rate plan","description":"Requires property.read and rates.publish. The app's \"Neuer Tarif\" (and its \"Nicht erstattbar\" template): a discount on the accommodation with its own cancellation terms, offered beside the standard rate except for the excluded apartments. At most ten active plans (LIMIT_REACHED). Publishes rate_plan.changed.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRatePlanRequest"}}}},"responses":{"201":{"description":"The new plan and its version.","content":{"application/json":{"example":{"id":"90000000-0000-4000-8000-000000000001","version":"1"},"schema":{"$ref":"#/components/schemas/ApiRatePlanSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"LIMIT_REACHED: ten plans are active; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/discount-codes":{"get":{"operationId":"listDiscountCodes","summary":"List the discount codes","description":"Requires property.read. The discount codes of the app: each code with its percentage off the accommodation, the booking days it counts on and how many bookings used it. A code is what a guest types to get the discount, so treat the list as confidential. Creating and ending codes need rates.publish; `canManage` says whether this key holds it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The discount codes.","content":{"application/json":{"example":{"canManage":false,"codes":[{"id":"70000000-0000-4000-8000-000000000001","code":"STAMMGAST10","basisPoints":1000,"validFrom":null,"validUntil":"2027-03-31","bookings":4}]},"schema":{"$ref":"#/components/schemas/ApiDiscountCodes"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"createDiscountCode","summary":"Create a discount code","description":"Requires property.read and rates.publish. The app's \"Code anlegen\": a percentage off the accommodation for a guest who types the code, optionally only on booking days from validFrom to validUntil in the Property's calendar. The code is stored in capitals without spaces; it is what a guest types, so treat it as a shared secret. At most twenty active codes (LIMIT_REACHED). Publishes discount_code.changed, which never carries the code.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDiscountCodeRequest"}}}},"responses":{"201":{"description":"The new code.","content":{"application/json":{"example":{"id":"91000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiDiscountCodeCreated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"DUPLICATE_DISCOUNT_CODE (an active code has this text) or LIMIT_REACHED (twenty are active); or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tourist-tax":{"get":{"operationId":"getTouristTax","summary":"Read the tourist tax settings","description":"Requires property.read and either reservation.read or property.configure. The tourist tax of the app: whether it is part of the price or paid on site, the rates for adults and child age bands, the season, the cap on taxed nights and a planned new rate with its start day. `version` is for later writes. The monthly report is a separate download and not part of this read.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The tourist tax settings.","content":{"application/json":{"example":{"version":"3","currency":"EUR","canConfigure":true,"settings":{"collection":"in_price","childAgeLimits":[6,18],"rates":{"adult":{"minorUnits":"250","currency":"EUR"},"children":[{"minorUnits":"0","currency":"EUR"},{"minorUnits":"125","currency":"EUR"}]},"season":null,"maximumNights":null,"change":{"from":"2027-01-01","rates":{"adult":{"minorUnits":"300","currency":"EUR"},"children":[{"minorUnits":"0","currency":"EUR"},{"minorUnits":"150","currency":"EUR"}]},"season":null}},"changeDroppable":true},"schema":{"$ref":"#/components/schemas/ApiTouristTax"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveTouristTax","summary":"Save the tourist tax","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The app's „Kurtaxe“, as the municipality's statute sets it: how the guest pays it, the child bands, the rates per adult and child and night, a main season with its own rates, the nights taxed and a new rate planned from a day („Gilt ab“). Every rate is integer minor units of the Property's currency. `settings` null switches the tourist tax off. Each save is a new version that only bookings priced afterwards use. Send `version` of getTouristTax (or of the last write's answer) as `expectedVersion` (\"0\" before the first save); a newer one answers VERSION_CONFLICT. Answers the version now in force. Rates the domain refuses (an adult rate of zero, a rate per band missing, bands not ascending) answer INVALID_REQUEST. Keyset computes the tax; it makes no claim that the rates meet the statute. Announces the `settings.changed` webhook event with `area` `tourist-tax`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTouristTaxSaveRequest"}}}},"responses":{"200":{"description":"Saved, or the same rates were stored already.","content":{"application/json":{"example":{"outcome":"saved","version":"4"},"schema":{"$ref":"#/components/schemas/ApiTouristTaxSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the tourist tax was saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid, or the rates are refused.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks/{blockId}":{"get":{"operationId":"getBlock","summary":"Read a block","description":"Requires property.read and inventory.block. The app's \"Sperre ansehen\": the apartment, kind, nights, note, state and the version a change or release sends back. A released block stays readable as history.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The block."},"required":true,"description":"The block.","name":"blockId","in":"path"}],"responses":{"200":{"description":"The block.","content":{"application/json":{"example":{"id":"80000000-0000-4000-8000-000000000001","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"kind":"owner_block","checkIn":"2026-12-20","checkOut":"2026-12-27","nights":7,"state":"active","version":"1","note":"Familie","createdAt":"2026-11-17T09:00:00.000Z","releasedAt":null},"schema":{"$ref":"#/components/schemas/ApiBlock"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks":{"post":{"operationId":"createBlock","summary":"Block an apartment","description":"Requires property.read and inventory.block. The app's \"Sperre anlegen\": the apartment's nights [checkIn, checkOut) are held as an owner block (Sperre) or maintenance (Wartung), at most 400 nights, with an optional note. PostgreSQL takes the nights in the same transaction or refuses with INVENTORY_CONFLICT when a booking, a checkout in progress or another block holds one; nothing is moved or cancelled. Publishes block.created.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBlockCreateRequest"}}}},"responses":{"201":{"description":"The block holds the nights.","content":{"application/json":{"example":{"id":"80000000-0000-4000-8000-000000000001","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"kind":"owner_block","checkIn":"2026-12-20","checkOut":"2026-12-27","nights":7,"state":"active","version":"1","note":"Familie","createdAt":"2026-11-17T09:00:00.000Z","releasedAt":null},"schema":{"$ref":"#/components/schemas/ApiBlock"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"INVENTORY_CONFLICT: something holds a night (preview to see what); or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks/{blockId}/change":{"post":{"operationId":"changeBlock","summary":"Change a block","description":"Requires property.read and inventory.block. The app's \"Änderung speichern\": new nights, kind and note for an active block at the version you read. The block is replaced in one transaction by a new one over the new nights (the answer names both); the old one is released as history. INVENTORY_CONFLICT leaves the old block as it was. Moving a block to another apartment is release and create. Publishes block.released and block.created.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The block."},"required":true,"description":"The block.","name":"blockId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBlockChangeRequest"}}}},"responses":{"200":{"description":"Changed (replaced), or already as asked.","content":{"application/json":{"example":{"outcome":"changed","block":{"id":"80000000-0000-4000-8000-000000000002","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"kind":"owner_block","checkIn":"2026-12-20","checkOut":"2026-12-28","nights":8,"state":"active","version":"1","note":"Familie","createdAt":"2026-11-17T09:00:00.000Z","releasedAt":null},"replacedBlockId":"80000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiBlockChange"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"INVENTORY_CONFLICT (something holds a new night), VERSION_CONFLICT (read the block again) or BLOCK_ALREADY_RELEASED; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks/{blockId}/release":{"post":{"operationId":"releaseBlock","summary":"Release a block","description":"Requires property.read and inventory.block. The app's \"Freigeben\": the block at the version you read stops holding its nights, which are bookable again at once. Releasing a released block answers it unchanged. Publishes block.released.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The block."},"required":true,"description":"The block.","name":"blockId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBlockReleaseRequest"}}}},"responses":{"200":{"description":"The released block.","content":{"application/json":{"example":{"id":"80000000-0000-4000-8000-000000000001","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"kind":"owner_block","checkIn":"2026-12-20","checkOut":"2026-12-27","nights":7,"state":"released","version":"2","note":"Familie","createdAt":"2026-11-17T09:00:00.000Z","releasedAt":"2026-11-18T09:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiBlock"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the block changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks/period":{"post":{"operationId":"blockPeriod","summary":"Block a period in several apartments","description":"Requires property.read and inventory.block. The app's \"Mehrere Apartments sperren\": blocks the free runs the preview gave, per apartment, in one transaction. An apartment where something now holds a night of its runs stays unblocked and answers conflict with what holds it; the others are blocked. Publishes block.created per block.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBlockPeriodRequest"}}}},"responses":{"200":{"description":"The outcome per apartment.","content":{"application/json":{"example":{"units":[{"unitId":"30000000-0000-4000-8000-000000000001","outcome":"blocked","blocks":[{"id":"80000000-0000-4000-8000-000000000001","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"kind":"owner_block","checkIn":"2027-01-09","checkOut":"2027-01-14","nights":5,"state":"active","version":"1","note":null,"createdAt":"2026-11-17T09:00:00.000Z","releasedAt":null}]}]},"schema":{"$ref":"#/components/schemas/ApiBlockPeriod"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}/draft":{"post":{"operationId":"saveRateDraft","summary":"Save the apartment’s rate draft","description":"Requires property.read and rates.publish. The app's \"Als Entwurf speichern\": the host's working copy of the apartment's price rules, at exactly the revision you read (null creates it). It never changes what a guest pays; publishRateDraft does. A draft may be saved invalid (`valid` false says why) and is never published so. The configuration is the shape getUnitRates answers.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRateDraftSaveRequest"}}}},"responses":{"200":{"description":"The saved draft with its new revision.","content":{"application/json":{"example":{"revision":"4","configuration":{"baseNightlyMinorUnits":"12000","weekendDays":[5,6],"weekendAdjustmentMinorUnits":"1500","absoluteOverrides":[{"ruleId":"period-1","start":"2026-12-20","end":"2027-01-03","nightlyMinorUnits":"16000","label":"Weihnachten"}],"cleaningFee":{"ruleId":"cleaning","minorUnits":"5100"},"percentageFee":{"ruleId":"fee","label":"Servicegebühr","basisPoints":0,"bases":["nightly_accommodation"],"roundingMode":"half_up"},"minimumStayNights":2,"maximumStayNights":null,"arrivalDays":null,"departureDays":null,"minimumStayByArrivalDay":[],"stayRulePeriods":[],"guestSurcharge":null,"discounts":null,"extras":[],"quoteLifetimeSeconds":900},"valid":true,"invalidReason":null,"lastPublished":{"version":"3","revision":"3","at":"2026-10-01T09:00:00.000Z"},"createdAt":"2026-09-01T09:00:00.000Z","updatedAt":"2026-11-17T09:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiRateDraft"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the draft changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}/draft/discard":{"post":{"operationId":"discardRateDraft","summary":"Discard the apartment’s rate draft","description":"Requires property.read and rates.publish. The app's \"Eingaben verwerfen\", at exactly the revision you read: a never-published draft is gone; otherwise it holds the published rules again. Never changes what a guest pays.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRateDraftDiscardRequest"}}}},"responses":{"200":{"description":"What became of the draft.","content":{"application/json":{"example":{"outcome":"reset","draft":{"revision":"5","configuration":{"baseNightlyMinorUnits":"12000","weekendDays":[5,6],"weekendAdjustmentMinorUnits":"1500","absoluteOverrides":[{"ruleId":"period-1","start":"2026-12-20","end":"2027-01-03","nightlyMinorUnits":"16000","label":"Weihnachten"}],"cleaningFee":{"ruleId":"cleaning","minorUnits":"5100"},"percentageFee":{"ruleId":"fee","label":"Servicegebühr","basisPoints":0,"bases":["nightly_accommodation"],"roundingMode":"half_up"},"minimumStayNights":2,"maximumStayNights":null,"arrivalDays":null,"departureDays":null,"minimumStayByArrivalDay":[],"stayRulePeriods":[],"guestSurcharge":null,"discounts":null,"extras":[],"quoteLifetimeSeconds":900},"valid":true,"invalidReason":null,"lastPublished":{"version":"3","revision":"3","at":"2026-10-01T09:00:00.000Z"},"createdAt":"2026-09-01T09:00:00.000Z","updatedAt":"2026-11-17T09:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ApiRateDraftDiscard"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the draft changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}/draft/publish":{"post":{"operationId":"publishRateDraft","summary":"Publish the apartment’s rate draft","description":"Requires property.read and rates.publish. The app's \"Veröffentlichen\": exactly the draft revision you previewed becomes a new immutable published version on top of exactly expectedCurrentVersion; from then on guests are quoted it. A quote a guest already holds keeps its price. Both versions are checked again under PostgreSQL's row lock. Publishes rate.published.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRatePublishRequest"}}}},"responses":{"201":{"description":"The new published version.","content":{"application/json":{"example":{"version":"4","previousVersion":"3","publishedAt":"2026-11-17T09:00:00.000Z","draft":{"revision":"4","configuration":{"baseNightlyMinorUnits":"12000","weekendDays":[5,6],"weekendAdjustmentMinorUnits":"1500","absoluteOverrides":[{"ruleId":"period-1","start":"2026-12-20","end":"2027-01-03","nightlyMinorUnits":"16000","label":"Weihnachten"}],"cleaningFee":{"ruleId":"cleaning","minorUnits":"5100"},"percentageFee":{"ruleId":"fee","label":"Servicegebühr","basisPoints":0,"bases":["nightly_accommodation"],"roundingMode":"half_up"},"minimumStayNights":2,"maximumStayNights":null,"arrivalDays":null,"departureDays":null,"minimumStayByArrivalDay":[],"stayRulePeriods":[],"guestSurcharge":null,"discounts":null,"extras":[],"quoteLifetimeSeconds":900},"valid":true,"invalidReason":null,"lastPublished":{"version":"4","revision":"4","at":"2026-11-17T09:00:00.000Z"},"createdAt":"2026-09-01T09:00:00.000Z","updatedAt":"2026-11-17T09:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ApiRatePublication"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT (the draft or the published version changed) or RATE_REVISION_ALREADY_PUBLISHED; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST (the body is invalid) or RATE_CONFIGURATION_INVALID (the draft breaks a rule; `detail` names it).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/rate-plans/{planId}":{"put":{"operationId":"updateRatePlan","summary":"Change a rate plan","description":"Requires property.read and rates.publish. The app's \"Tarif bearbeiten\" at the version you read: name, discount, cancellation terms and excluded apartments together. Bookings made earlier keep the terms they were made with. Publishes rate_plan.changed when anything changed.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The rate plan."},"required":true,"description":"The rate plan.","name":"planId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRatePlanUpdateRequest"}}}},"responses":{"200":{"description":"The plan and its version.","content":{"application/json":{"example":{"id":"90000000-0000-4000-8000-000000000001","version":"2"},"schema":{"$ref":"#/components/schemas/ApiRatePlanSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the plan changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/rate-plans/{planId}/archive":{"post":{"operationId":"archiveRatePlan","summary":"End a rate plan","description":"Requires property.read and rates.publish. The app's \"Tarif beenden\" at the version you read: guests can no longer choose the plan; bookings made with it keep it. Publishes rate_plan.changed.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The rate plan."},"required":true,"description":"The rate plan.","name":"planId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRatePlanArchiveRequest"}}}},"responses":{"200":{"description":"The plan is ended.","content":{"application/json":{"example":{"id":"90000000-0000-4000-8000-000000000001","archived":true},"schema":{"$ref":"#/components/schemas/ApiRatePlanArchived"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the plan changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/discount-codes/{codeId}/end":{"post":{"operationId":"endDiscountCode","summary":"End a discount code","description":"Requires property.read and rates.publish. The app's \"Code beenden\": a guest can no longer use it; bookings made with it keep their discount. Ending an ended code answers NOT_FOUND. Publishes discount_code.changed.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The discount code."},"required":true,"description":"The discount code.","name":"codeId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The code is ended.","content":{"application/json":{"example":{"id":"91000000-0000-4000-8000-000000000001","ended":true},"schema":{"$ref":"#/components/schemas/ApiDiscountCodeEnded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks/preview":{"post":{"operationId":"previewBlock","summary":"Check whether an apartment is free to block","description":"Requires property.read and inventory.block. The app's \"Verfügbarkeit prüfen\" of a new block: what holds the apartment's nights [checkIn, checkOut) at asOf — bookings, checkouts in progress and other blocks. It reserves nothing; creating the block decides again in PostgreSQL. With exceptBlockId the nights of that block do not count, for previewing a change.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Optional: a preview writes nothing."},"required":false,"description":"Optional: a preview writes nothing.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBlockPreviewRequest"}}}},"responses":{"200":{"description":"What holds the nights.","content":{"application/json":{"example":{"asOf":"2026-11-17T09:00:00.000Z","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"checkIn":"2026-12-20","checkOut":"2026-12-27","nights":7,"available":false,"conflicts":[{"kind":"reservation","checkIn":"2026-12-22","checkOut":"2026-12-26","reservationId":"40000000-0000-4000-8000-000000000001","number":1042}]},"schema":{"$ref":"#/components/schemas/ApiBlockPreview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/blocks/period/preview":{"post":{"operationId":"previewBlockPeriod","summary":"Check a period over several apartments","description":"Requires property.read and inventory.block. The app's \"Zeitraum sperren — Prüfen\": per apartment what holds the period at asOf and the runs of nights that are free. Send exactly those runs to blockPeriod. A booking carries the guest's name only for a key that also holds guest.read. Advisory; it reserves nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Optional: a preview writes nothing."},"required":false,"description":"Optional: a preview writes nothing.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBlockPeriodPreviewRequest"}}}},"responses":{"200":{"description":"The period per apartment.","content":{"application/json":{"example":{"asOf":"2026-11-17T09:00:00.000Z","checkIn":"2027-01-07","checkOut":"2027-01-14","nights":7,"units":[{"unitId":"30000000-0000-4000-8000-000000000001","outcome":"found","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"occupied":[{"kind":"reservation","checkIn":"2027-01-05","checkOut":"2027-01-09","reservationId":"40000000-0000-4000-8000-000000000001","number":1042,"guestName":null}],"free":[{"checkIn":"2027-01-09","checkOut":"2027-01-14","nights":5}]}]},"schema":{"$ref":"#/components/schemas/ApiBlockPeriodPreview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}/draft/preview":{"post":{"operationId":"previewRateDraft","summary":"Price sample stays with the draft","description":"Requires property.read and rates.publish. The app's \"Durchrechnen\": what up to 20 sample stays would cost under exactly the draft revision you read, line by line. It evaluates with the same evaluator a guest is quoted by, persists nothing, creates no quote and promises no availability.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Optional: a preview writes nothing."},"required":false,"description":"Optional: a preview writes nothing.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRateDraftPreviewRequest"}}}},"responses":{"200":{"description":"The sample stays priced.","content":{"application/json":{"example":{"revision":"4","evaluatorVersion":"pricing-v1","evaluatedAt":"2026-11-17T09:00:00.000Z","valid":true,"invalidReason":null,"scenarios":[{"checkIn":"2026-12-04","checkOut":"2026-12-06","nights":2,"occupancy":{"adults":2,"children":0},"outcome":{"type":"priced","total":{"minorUnits":"32100","currency":"EUR"},"lines":[{"kind":"nightly_accommodation","serviceDate":"2026-12-04","label":"Nacht","amount":{"minorUnits":"12000","currency":"EUR"}},{"kind":"weekend_adjustment","serviceDate":"2026-12-04","label":"Wochenende","amount":{"minorUnits":"1500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2026-12-05","label":"Nacht","amount":{"minorUnits":"12000","currency":"EUR"}},{"kind":"weekend_adjustment","serviceDate":"2026-12-05","label":"Wochenende","amount":{"minorUnits":"1500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"5100","currency":"EUR"}}]}}]},"schema":{"$ref":"#/components/schemas/ApiRateDraftPreview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the draft changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}/published/preview":{"post":{"operationId":"previewPublishedRates","summary":"Price sample stays with the published rates","description":"Requires property.read and rates.publish. The list price of a stay as the app shows it while a booking is made or moved: up to 20 sample stays under exactly the published version you read. It evaluates with the same evaluator a guest is quoted by, persists nothing, creates no quote and promises no availability.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Optional: a preview writes nothing."},"required":false,"description":"Optional: a preview writes nothing.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiPublishedRatesPreviewRequest"}}}},"responses":{"200":{"description":"The sample stays priced.","content":{"application/json":{"example":{"version":"3","evaluatorVersion":"pricing-v1","evaluatedAt":"2026-11-17T09:00:00.000Z","scenarios":[{"checkIn":"2026-12-04","checkOut":"2026-12-06","nights":2,"occupancy":{"adults":2,"children":0},"outcome":{"type":"priced","total":{"minorUnits":"32100","currency":"EUR"},"lines":[{"kind":"nightly_accommodation","serviceDate":"2026-12-04","label":"Nacht","amount":{"minorUnits":"12000","currency":"EUR"}},{"kind":"weekend_adjustment","serviceDate":"2026-12-04","label":"Wochenende","amount":{"minorUnits":"1500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2026-12-05","label":"Nacht","amount":{"minorUnits":"12000","currency":"EUR"}},{"kind":"weekend_adjustment","serviceDate":"2026-12-05","label":"Wochenende","amount":{"minorUnits":"1500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"5100","currency":"EUR"}}]}}]},"schema":{"$ref":"#/components/schemas/ApiPublishedRatesPreview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the published version changed since it was read, or none exists; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/rates/{rateContextId}/proposal/preview":{"post":{"operationId":"previewRateProposal","summary":"Price a change before saving it","description":"Requires property.read and rates.publish. The app's \"Preis für einen Zeitraum — Neu berechnen\": a changed configuration (for example the published one with one more price period) evaluated on top of exactly the published version you read, for up to 20 sample stays. To make it real, save it as the draft and publish. It evaluates with the same evaluator a guest is quoted by, persists nothing, creates no quote and promises no availability.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment."},"required":true,"description":"The apartment.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$","description":"The `rateContextId` the rates overview gives for the apartment."},"required":true,"description":"The `rateContextId` the rates overview gives for the apartment.","name":"rateContextId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Optional: a preview writes nothing."},"required":false,"description":"Optional: a preview writes nothing.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRateProposalPreviewRequest"}}}},"responses":{"200":{"description":"The sample stays priced under the proposal.","content":{"application/json":{"example":{"version":"3","evaluatorVersion":"pricing-v1","evaluatedAt":"2026-11-17T09:00:00.000Z","valid":true,"invalidReason":null,"scenarios":[{"checkIn":"2026-12-04","checkOut":"2026-12-06","nights":2,"occupancy":{"adults":2,"children":0},"outcome":{"type":"priced","total":{"minorUnits":"32100","currency":"EUR"},"lines":[{"kind":"nightly_accommodation","serviceDate":"2026-12-04","label":"Nacht","amount":{"minorUnits":"12000","currency":"EUR"}},{"kind":"weekend_adjustment","serviceDate":"2026-12-04","label":"Wochenende","amount":{"minorUnits":"1500","currency":"EUR"}},{"kind":"nightly_accommodation","serviceDate":"2026-12-05","label":"Nacht","amount":{"minorUnits":"12000","currency":"EUR"}},{"kind":"weekend_adjustment","serviceDate":"2026-12-05","label":"Wochenende","amount":{"minorUnits":"1500","currency":"EUR"}},{"kind":"cleaning_fee","serviceDate":null,"label":"Endreinigung","amount":{"minorUnits":"5100","currency":"EUR"}}]}}]},"schema":{"$ref":"#/components/schemas/ApiRateProposalPreview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the published version changed since it was read, or none exists; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/guest-messages":{"get":{"operationId":"getReservationGuestMessages","summary":"Read a booking’s automatic messages","description":"Requires property.read and reservation.read. The app’s card of a booking’s automatic guest messages: whether they are switched off, when each is due, scheduled and sent, and the `version` setReservationGuestMessages needs. It shows whether the booking has an address, never the address, and no message text.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The booking’s automatic messages.","content":{"application/json":{"example":{"canEdit":true,"source":"direct","lifecycle":"confirmed","timezone":"Europe/Berlin","hasEmail":true,"off":false,"version":"1","messages":[{"kind":"pre_arrival","enabled":true,"dueAt":"2026-11-18T08:00:00.000Z","scheduledAt":null,"state":null,"sentAt":null},{"kind":"post_departure","enabled":false,"dueAt":"2026-11-24T10:00:00.000Z","scheduledAt":null,"state":null,"sentAt":null}]},"schema":{"$ref":"#/components/schemas/ApiReservationGuestMessages"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"setReservationGuestMessages","summary":"Switch a booking’s automatic messages","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for editing a booking. The app's switch of one booking's automatic guest messages, at exactly the `version` getReservationGuestMessages gave. Nothing is sent by this call.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiReservationGuestMessagesSetRequest"}}}},"responses":{"200":{"description":"The switch was saved, or already stood so.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiReservationGuestMessagesSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the messages changed since they were read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/guest-portal":{"get":{"operationId":"getGuestPortal","summary":"Read a booking’s guest page","description":"Requires property.read and reservation.read. Whether a guest page link can be issued for the booking, how many links are active and until when links are valid. Never a link or a token: a link is shown once, by issueGuestPortalLink.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The guest page of the booking.","content":{"application/json":{"example":{"canEdit":true,"available":true,"expiresOn":"2026-12-24","expired":false,"active":1,"lastIssuedAt":"2026-11-02T09:20:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiGuestPortal"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guest-requests":{"get":{"operationId":"listGuestRequests","summary":"List guest requests","description":"Requires property.read. The app’s “Zu erledigen”: a guest’s cancellation, request to cancel or message, open ones and those closed recently, in one answer without a cursor. Name and note are present only for a key that holds guest.read; PostgreSQL holds that rule and a key without it reads them as null.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The guest requests.","content":{"application/json":{"example":{"data":[{"id":"73000000-0000-4000-8000-000000000001","kind":"cancellation_request","state":"open","reservationId":"20000000-0000-4000-8000-000000000001","reservationNumber":1042,"checkIn":"2026-11-20","checkOut":"2026-11-23","unitName":"Apartment 1","guestName":"Ada Lovelace","note":"Wir müssen leider absagen.","refund":{"minorUnits":"43500","currency":"EUR"},"createdAt":"2026-11-16T18:02:00.000Z","closedAt":null,"closedReason":null}]},"schema":{"$ref":"#/components/schemas/ApiGuestRequestList"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/move-targets":{"get":{"operationId":"listMoveTargets","summary":"List the apartments a booking without a place could go to","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for placing a booking. The app's \"Platz zuweisen\": the active apartments with no booking, hold or block in any night of the stay, for a booking that has no apartment (an import or a channel booking that named none). A booking that already has one, or is cancelled, answers with no targets. Advice; placing it decides again in PostgreSQL. No guest data.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The booking and the apartments that were free for every night when read.","content":{"application/json":{"example":{"reservation":{"id":"40000000-0000-4000-8000-000000000001","number":1042,"stay":{"checkIn":"2026-12-20","checkOut":"2026-12-24","nights":4},"occupancy":{"adults":2,"children":0,"known":true},"placement":"unplaced","unit":null},"targets":[{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1","maxOccupancy":4,"requested":false}],"asOf":"2026-11-17T09:00:00.000Z"},"schema":{"$ref":"#/components/schemas/ApiMoveTargets"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/task-problems":{"get":{"operationId":"listTaskProblems","summary":"List reported task problems","description":"Requires property.read. The app's \"Gemeldete Probleme\": the open problems plus those closed in the last 30 days, each with its task, apartment, text, reporter and, when closed, the time. The free text and the reporter’s name are given only to a key with guest.read (PostgreSQL withholds them otherwise; persons in the app always hold it). `canClose` says whether this key may close one (closeTaskProblem).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The problems.","content":{"application/json":{"example":{"canClose":true,"problems":[{"id":"72000000-0000-4000-8000-000000000001","taskId":"70000000-0000-4000-8000-000000000001","taskTitle":"Endreinigung","taskKind":"cleaning","dueOn":"2026-11-18","unitName":"Apartment 1","text":"Der Staubsauger ist defekt.","reportedAt":"2026-11-18T09:30:00.000Z","reporterName":"Maria","closedAt":null}]},"schema":{"$ref":"#/components/schemas/ApiTaskProblems"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/stay":{"post":{"operationId":"recordStay","summary":"Record an arrival or departure","description":"Requires property.read and reservation.cancel, the grant PostgreSQL holds for who may cancel the booking. The app's \"Angekommen\" and \"Abgereist\": when the host saw the guest arrive or leave, at exactly the `stayVersion` getReservationDetails gave (\"0\" while nothing is recorded). `undo_arrival` and `undo_departure` take a recorded fact back. Not before the arrival day (TOO_EARLY); only a confirmed booking whose stay is not long over (STAY_NOT_RECORDABLE). A repeat of what the stay already says answers `unchanged`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStayRecordRequest"}}}},"responses":{"200":{"description":"The stay as it now stands.","content":{"application/json":{"example":{"outcome":"recorded","stay":{"arrivedAt":"2026-11-20T15:42:00.000Z","departedAt":null,"version":"1"}},"schema":{"$ref":"#/components/schemas/ApiStayRecorded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the stay changed since it was read; TOO_EARLY: not before the arrival day; STAY_NOT_RECORDABLE: not confirmed, long gone or already departed; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/no-show":{"post":{"operationId":"markNoShow","summary":"Mark a booking as not arrived","description":"Requires property.read and reservation.cancel, the grant PostgreSQL holds for who may cancel the booking. The app's \"Nicht angereist\", at exactly the booking's `version`: the booking stays but no longer holds its nights as an arrival. The note is for the host and never shown to the guest. Not before the arrival day (TOO_EARLY); only a confirmed booking with an apartment and no recorded arrival (NO_SHOW_NOT_POSSIBLE).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiNoShowMarkRequest"}}}},"responses":{"200":{"description":"The booking is marked, or already was.","content":{"application/json":{"example":{"outcome":"marked","reservationVersion":"4"},"schema":{"$ref":"#/components/schemas/ApiNoShowAnswered"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the booking changed since it was read; TOO_EARLY: not before the arrival day; NO_SHOW_NOT_POSSIBLE: not confirmed, without a place or arrival recorded; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/no-show/revert":{"post":{"operationId":"revertNoShow","summary":"Take back \"not arrived\"","description":"Requires property.read and reservation.cancel, the grant PostgreSQL holds for who may cancel the booking. The app's taking-back of \"Nicht angereist\", at exactly the booking's `version`: the booking is confirmed again and holds its nights, which fails with INVENTORY_CONFLICT when another stay holds one of them now.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiNoShowRevertRequest"}}}},"responses":{"200":{"description":"The booking is confirmed again, or already was.","content":{"application/json":{"example":{"outcome":"reverted","reservationVersion":"5"},"schema":{"$ref":"#/components/schemas/ApiNoShowAnswered"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the booking changed since it was read; INVENTORY_CONFLICT: a night of the booking is taken again; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/contact":{"put":{"operationId":"changeGuestContact","summary":"Correct a booking’s guest contact","description":"Requires property.read, reservation.create_manual and guest.read: it changes where a guest’s mail goes or opens the guest’s page, a guest-data action. The app's correction of a guest contact at exactly the `guest.version` getReservationDetails gave: name, e-mail and phone are replaced as a whole. A booking made or requested online keeps an e-mail address (GUEST_EMAIL_REQUIRED); an imported booking keeps the contact of its source (GUEST_CONTACT_NOT_EDITABLE). The answer carries the new version, never the contact.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestContactChangeRequest"}}}},"responses":{"200":{"description":"The contact was saved.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","version":"2","outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiGuestContactChanged"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the contact changed since it was read; GUEST_EMAIL_REQUIRED: a booking paid or requested online keeps an e-mail address; GUEST_CONTACT_NOT_EDITABLE: an imported booking; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or a contact field cannot be stored.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/guest-confirmation":{"post":{"operationId":"sendGuestConfirmation","summary":"Send a manual booking’s confirmation","description":"Requires property.read and reservation.create_manual, and reservation.cancel as well when `paymentLink` is true (PERMISSION_DENIED otherwise). It mails the guest, so it takes the sensitive budget. The app's \"Bestätigung senden\" for a confirmed manual booking, with a link to pay what is open by card or without. `sequence` says which confirmation this is: a repeat of a number sends nothing (`already_requested`). NOT_MANUAL_BOOKING: not a confirmed manual booking; GUEST_HAS_NO_EMAIL: nothing to send to; TEST_MODE_NO_MAIL: a test Property writes to no guest; PAYMENT_LINK_UNAVAILABLE: nothing open, below the provider's minimum or payments not ready (`detail` says which).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestConfirmationRequest"}}}},"responses":{"200":{"description":"The mail is queued, or this confirmation was already requested.","content":{"application/json":{"example":{"outcome":"requested","paymentLink":true},"schema":{"$ref":"#/components/schemas/ApiGuestConfirmationSent"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"NOT_MANUAL_BOOKING; GUEST_HAS_NO_EMAIL; TEST_MODE_NO_MAIL; PAYMENT_LINK_UNAVAILABLE (with `detail`); or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/check-in/erase":{"post":{"operationId":"eraseCheckIn","summary":"Erase a booking’s check-in data","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for editing a booking. The app's \"Daten löschen\": the guest's online check-in data of this booking is erased now instead of 15 months after departure. It cannot be undone.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The check-in data is erased.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","outcome":"erased"},"schema":{"$ref":"#/components/schemas/ApiCheckInErased"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/guest-portal/links":{"post":{"operationId":"issueGuestPortalLink","summary":"Issue a guest page link","description":"Requires property.read, reservation.create_manual and guest.read: it changes where a guest’s mail goes or opens the guest’s page, a guest-data action. The app's \"Link erstellen\": a new personal link to the guest page of a confirmed booking that is not an import, for the host to pass on. A cancelled or imported booking has no guest page (GUEST_PORTAL_UNAVAILABLE). It takes the sensitive budget. The link is shown once and never stored: a repeat with the same idempotency key answers without it (url and token null); issue a new one to get a link again.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The link, shown once.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","url":"https://booking.keyset.cloud/g/q3Zr0mVx8Jt5nKp2LcYw7HbD1eFgS4uAoIiTkNhEyRM","token":"q3Zr0mVx8Jt5nKp2LcYw7HbD1eFgS4uAoIiTkNhEyRM"},"schema":{"$ref":"#/components/schemas/ApiGuestPortalLink"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"GUEST_PORTAL_UNAVAILABLE: a cancelled or imported booking has no guest page; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/guest-portal/revoke":{"post":{"operationId":"revokeGuestPortalLinks","summary":"Revoke a booking’s guest page links","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for editing a booking. The app's \"Links widerrufen\": every link of the booking stops working at once; the answer counts them. Issue a new one with issueGuestPortalLink.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The links stopped working.","content":{"application/json":{"example":{"reservationId":"20000000-0000-4000-8000-000000000001","revoked":2},"schema":{"$ref":"#/components/schemas/ApiGuestPortalRevoked"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guests/{guestId}/note":{"put":{"operationId":"saveGuestNote","summary":"Save the note on a guest","description":"Requires property.read, reservation.cancel and guest.read: the note is the guest’s data, held by PostgreSQL as well. The app's note per guest (preferences and arrangements, never health or payment data), at exactly the note's version getGuest gave (\"0\" for a guest without a note). An empty body clears the note. The answer carries the new version, never the note.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"A guest of the list (listGuests)."},"required":true,"description":"A guest of the list (listGuests).","name":"guestId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiGuestNoteRequest"}}}},"responses":{"200":{"description":"The note was saved, or already read so.","content":{"application/json":{"example":{"guestId":"a3f1c2d4e5b60718293a4b5c6d7e8f90","version":"2","outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiGuestNoteSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the note changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/guest-requests/{requestId}/close":{"post":{"operationId":"closeGuestRequest","summary":"Close a guest request","description":"Requires property.read and reservation.cancel, the grant PostgreSQL holds for who may cancel the booking. The app's \"Erledigt\" on an entry of \"Zu erledigen\". Closing one that is already closed answers `already_closed` (the app shows that as a conflict; here it is the same end state and a repeat is harmless).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The guest request, as listGuestRequests gives it."},"required":true,"description":"The guest request, as listGuestRequests gives it.","name":"requestId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The request is closed.","content":{"application/json":{"example":{"id":"73000000-0000-4000-8000-000000000001","outcome":"closed"},"schema":{"$ref":"#/components/schemas/ApiGuestRequestClosed"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/change":{"post":{"operationId":"changeBooking","summary":"Change a booking","description":"Requires property.read and reservation.cancel, the grant PostgreSQL holds for changing a booking (its definer checks it again). The app's \"Buchung ändern\", at exactly the `version` getReservation gave: the apartment, the stay and the agreed total of a booking are replaced as a whole, in one transaction, and the nights are taken from PostgreSQL's exclusion (INVENTORY_CONFLICT when another booking holds one). The agreed total is the host's own figure as in the app, never derived; it may not be below what was already received (BELOW_RECEIVED), and a total that differs from the list price needs a priceReason (PRICE_REASON_REQUIRED). A booking that is cancelled, departed, imported, unpaid or composed of several apartments is not changeable (NOT_CHANGEABLE, `detail` says why). The request carries no refund: Keyset sends nothing back with a change made here; a refund is Keyset's rule when a booking is cancelled. notifyGuest false keeps Keyset's mail about the change from the guest. Publishes reservation.changed.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBookingChangeRequest"}}}},"responses":{"200":{"description":"The booking is changed, or was already as asked.","content":{"application/json":{"example":{"outcome":"changed","reservationVersion":"3","change":{"id":"60000000-0000-4000-8000-000000000001","sequence":1,"from":{"unitId":"30000000-0000-4000-8000-000000000001","checkIn":"2026-12-20","checkOut":"2026-12-23","total":{"minorUnits":"38400","currency":"EUR"}},"to":{"unitId":"30000000-0000-4000-8000-000000000001","checkIn":"2026-12-20","checkOut":"2026-12-24","total":{"minorUnits":"51200","currency":"EUR"}},"listPrice":{"minorUnits":"51200","currency":"EUR"},"priceReason":null,"changedAt":"2026-11-17T09:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ApiBookingChanged"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT (the booking changed since it was read), INVENTORY_CONFLICT (a night of the new stay is taken), BELOW_RECEIVED (the total is below what was received) or NOT_CHANGEABLE; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or the new stay is not possible; PRICE_REASON_REQUIRED: a total that differs from the list price needs its priceReason.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/move":{"post":{"operationId":"moveBooking","summary":"Place a booking without an apartment","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for placing a booking. The app's \"Platz zuweisen\": the booking gets the apartment for exactly its nights, taken from PostgreSQL's exclusion (INVENTORY_CONFLICT when another booking holds one). Only a booking that has no apartment is placed (NOT_MOVABLE otherwise, `detail` says cancelled or placed); to change an apartment of a booking that has one use changeBooking. A repeat of the same key answers `already_moved`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMoveRequest"}}}},"responses":{"200":{"description":"The booking holds the apartment.","content":{"application/json":{"example":{"outcome":"moved","reservationId":"40000000-0000-4000-8000-000000000001","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1"},"previousUnitId":null,"stay":{"checkIn":"2026-12-20","checkOut":"2026-12-24"}},"schema":{"$ref":"#/components/schemas/ApiMoved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"INVENTORY_CONFLICT (an apartment night is taken) or NOT_MOVABLE (the booking has an apartment, or is cancelled); or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-requests/{bookingRequestId}/accept":{"post":{"operationId":"acceptBookingRequest","summary":"Accept a booking request","description":"Requires property.read, reservation.create_manual and guest.read: a request is read only with guest.read and a decline can carry your text to the guest; PostgreSQL holds both grants. A card link (`card_link`, `card_link_and_transfer`) needs reservation.cancel as well (PERMISSION_DENIED before anything runs). The app's \"Anfrage annehmen\", at exactly the `version` getBookingRequest gave: the request becomes a confirmed booking in one transaction, its nights taken from PostgreSQL's exclusion, and the guest gets the confirmation with the way to pay (`guestMail` says what became of it). paymentWay: card_link and card_link_and_transfer need payments ready (PAYMENT_LINK_UNAVAILABLE otherwise), transfer needs the Property's bank details (TRANSFER_UNAVAILABLE), and card or transfer need an open amount (NOTHING_OPEN); outside means the host collects. A request that was answered, withdrawn or has expired answers BOOKING_REQUEST_NOT_OPEN or BOOKING_REQUEST_EXPIRED. Nothing is changed by a refusal. No guest data is part of the answer.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking request, as getBookingRequest gives it."},"required":true,"description":"The booking request, as getBookingRequest gives it.","name":"bookingRequestId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBookingRequestAcceptRequest"}}}},"responses":{"200":{"description":"The request is a confirmed booking.","content":{"application/json":{"example":{"bookingRequestId":"50000000-0000-4000-8000-000000000001","reservationId":"40000000-0000-4000-8000-000000000001","outcome":"accepted","paymentWay":"card_link","guestMail":"requested"},"schema":{"$ref":"#/components/schemas/ApiBookingRequestAccepted"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT, BOOKING_REQUEST_NOT_OPEN, BOOKING_REQUEST_EXPIRED, INVENTORY_CONFLICT (the nights are no longer free), UNIT_UNAVAILABLE (the apartment can no longer be booked), PAYMENT_LINK_UNAVAILABLE, TRANSFER_UNAVAILABLE or NOTHING_OPEN (`detail` says why where there is a reason); or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-requests/{bookingRequestId}/decline":{"post":{"operationId":"declineBookingRequest","summary":"Decline a booking request","description":"Requires property.read, reservation.create_manual and guest.read: a request is read only with guest.read and a decline can carry your text to the guest; PostgreSQL holds both grants. A card link (`card_link`, `card_link_and_transfer`) needs reservation.cancel as well (PERMISSION_DENIED before anything runs). The app's \"Anfrage ablehnen\", at exactly the `version` getBookingRequest gave: the request ends and the guest is told by mail, with the optional message of at most 1000 characters. A request that was already answered, withdrawn or has expired answers BOOKING_REQUEST_NOT_OPEN. No guest data is part of the answer.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking request, as getBookingRequest gives it."},"required":true,"description":"The booking request, as getBookingRequest gives it.","name":"bookingRequestId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBookingRequestDeclineRequest"}}}},"responses":{"200":{"description":"The request is declined.","content":{"application/json":{"example":{"bookingRequestId":"50000000-0000-4000-8000-000000000001","outcome":"declined"},"schema":{"$ref":"#/components/schemas/ApiBookingRequestDeclined"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT (the request changed since it was read) or BOOKING_REQUEST_NOT_OPEN; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tasks/{taskId}":{"put":{"operationId":"updateTask","summary":"Change a task","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Aufgabe bearbeiten\", at exactly the `version` the board gave: title, note, due day, team member and helper are replaced as a whole. The due day of a cleaning task is ignored, because it follows its booking.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The task."},"required":true,"description":"The task.","name":"taskId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskUpdateRequest"}}}},"responses":{"200":{"description":"The task was saved.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001","outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiTaskSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the task changed since the board was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"delete":{"operationId":"deleteTask","summary":"Delete a task","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Aufgabe löschen\" for a maintenance or custom task. A cleaning task follows its booking and is not deleted: TASK_NOT_DELETABLE.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The task."},"required":true,"description":"The task.","name":"taskId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The task is gone.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001","outcome":"deleted"},"schema":{"$ref":"#/components/schemas/ApiTaskDeleted"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"TASK_NOT_DELETABLE: a cleaning task follows its booking; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tasks/{taskId}/complete":{"post":{"operationId":"completeTask","summary":"Complete or reopen a task","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. A key is never a task’s assignee (its membership has the role service, which is never assigned), so completing, ticking and reporting need reservation.create_manual, which PostgreSQL holds. The app's \"Erledigt\": done true completes the task, false reopens it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The task."},"required":true,"description":"The task.","name":"taskId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskCompleteRequest"}}}},"responses":{"200":{"description":"The task is completed or open again.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001","done":true,"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiTaskCompleted"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tasks/{taskId}/checks/{position}":{"post":{"operationId":"tickTaskCheck","summary":"Tick a checklist item","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. A key is never a task’s assignee (its membership has the role service, which is never assigned), so completing, ticking and reporting need reservation.create_manual, which PostgreSQL holds. The app's tick of one checklist item (position 0–49 as the board gives it): done true ticks it, false clears it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The task."},"required":true,"description":"The task.","name":"taskId","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":49,"description":"The checklist item’s `position` on the board, 0–49."},"required":false,"description":"The checklist item’s `position` on the board, 0–49.","name":"position","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskCheckRequest"}}}},"responses":{"200":{"description":"The item is ticked or cleared.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001","position":0,"done":true,"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiTaskChecked"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tasks/{taskId}/problems":{"post":{"operationId":"reportTaskProblem","summary":"Report a problem on a task","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. A key is never a task’s assignee (its membership has the role service, which is never assigned), so completing, ticking and reporting need reservation.create_manual, which PostgreSQL holds. The app's \"Problem melden\": a text of 1–4000 characters that appears in listTaskProblems until it is closed. Nobody is mailed.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The task."},"required":true,"description":"The task.","name":"taskId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskProblemReportRequest"}}}},"responses":{"201":{"description":"The problem is reported.","content":{"application/json":{"example":{"taskId":"70000000-0000-4000-8000-000000000001","outcome":"reported"},"schema":{"$ref":"#/components/schemas/ApiTaskProblemReported"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/task-problems/{problemId}/close":{"post":{"operationId":"closeTaskProblem","summary":"Close a reported problem","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Problem schließen\". Closing a problem that is already closed answers the same success.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The reported problem, as listTaskProblems gives it."},"required":true,"description":"The reported problem, as listTaskProblems gives it.","name":"problemId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The problem is closed.","content":{"application/json":{"example":{"id":"72000000-0000-4000-8000-000000000001","outcome":"closed"},"schema":{"$ref":"#/components/schemas/ApiTaskProblemClosed"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/task-helpers":{"post":{"operationId":"addTaskHelper","summary":"Add a helper without an account","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Helfer hinzufügen\": a helper by name, who sees and finishes only their own tasks through a personal link. The answer carries the link once. The link is shown once and never stored: a repeat with the same idempotency key answers the same helper without the link (url and token null); renew it to get a new one.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTaskHelperAddRequest"}}}},"responses":{"201":{"description":"The helper exists; the link is shown once.","content":{"application/json":{"example":{"helperId":"71000000-0000-4000-8000-000000000001","url":"https://booking.example/t/q3Zr0mVx8Jt5nKp2LcYw7HbD1eFgS4uAoIiTkNhEyRM","token":"q3Zr0mVx8Jt5nKp2LcYw7HbD1eFgS4uAoIiTkNhEyRM"},"schema":{"$ref":"#/components/schemas/ApiTaskHelperLink"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/task-helpers/{helperId}/link":{"post":{"operationId":"renewTaskHelperLink","summary":"Issue a helper a new link","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Neuen Link erzeugen\": the old link stops at once. The link is shown once and never stored: a repeat with the same idempotency key answers the same helper without the link (url and token null); renew it to get a new one.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The helper."},"required":true,"description":"The helper.","name":"helperId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The new link, shown once.","content":{"application/json":{"example":{"helperId":"71000000-0000-4000-8000-000000000001","url":"https://booking.example/t/q3Zr0mVx8Jt5nKp2LcYw7HbD1eFgS4uAoIiTkNhEyRM","token":"q3Zr0mVx8Jt5nKp2LcYw7HbD1eFgS4uAoIiTkNhEyRM"},"schema":{"$ref":"#/components/schemas/ApiTaskHelperLink"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/task-helpers/{helperId}":{"delete":{"operationId":"removeTaskHelper","summary":"Remove a helper","description":"Requires property.read and reservation.create_manual, the grant PostgreSQL holds for managing tasks and helpers. The app's \"Helfer entfernen\": the link stops working and the helper's open tasks lose the helper.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The helper."},"required":true,"description":"The helper.","name":"helperId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The helper is gone.","content":{"application/json":{"example":{"helperId":"71000000-0000-4000-8000-000000000001","outcome":"removed"},"schema":{"$ref":"#/components/schemas/ApiTaskHelperRemoved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/change/preview":{"post":{"operationId":"previewBookingChange","summary":"Check a change of a booking","description":"Requires property.read and reservation.cancel, the grant PostgreSQL holds for changing a booking (its definer checks it again). The app's check before \"Buchung ändern\": whether the new apartment is free for every night of the new stay (advice; the change decides again in PostgreSQL) and the new stay priced at the published rates for the booking's party, extras and rate plan. When the agreed total of the change differs from the priced total, the change needs a priceReason. It writes nothing and carries no guest data.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"Optional: a preview writes nothing."},"required":false,"description":"Optional: a preview writes nothing.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBookingChangePreviewRequest"}}}},"responses":{"200":{"description":"Whether the stay is free and what it costs at the published rates.","content":{"application/json":{"example":{"available":true,"price":{"type":"priced","total":{"minorUnits":"51200","currency":"EUR"},"nights":4,"lines":[{"label":"Übernachtung","amount":{"minorUnits":"44000","currency":"EUR"}},{"label":"Endreinigung","amount":{"minorUnits":"7200","currency":"EUR"}}],"touristTaxOnSite":null}},"schema":{"$ref":"#/components/schemas/ApiBookingChangePreview"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/transfer-instruction":{"get":{"operationId":"getReservationTransferInstruction","summary":"Read a booking’s bank-transfer instruction","description":"Requires property.read, reservation.read and guest.read: what the guest was asked to transfer, to whom, by when and under which reference (the reference carries the guest’s last name). The current instruction, else the one the cancellation ended; `id` is what issueTransferInstruction expects. The IBAN is masked, as getTransferDetails shows it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The instruction, or null.","content":{"application/json":{"example":{"instruction":{"id":"76000000-0000-4000-8000-000000000001","reservationId":"20000000-0000-4000-8000-000000000001","state":"issued","holder":"Haus am See GbR","ibanMasked":"DE89…3000","detailsChanged":false,"reference":"KS-1042 Berger","issuedAt":"2026-11-17T09:00:00.000Z","endedAt":null,"instalments":[{"amount":{"minorUnits":"48600","currency":"EUR"},"dueOn":"2026-11-24","open":{"minorUnits":"48600","currency":"EUR"}}],"expected":{"minorUnits":"48600","currency":"EUR"},"dueOn":"2026-11-24","overdue":false,"outdated":false}},"schema":{"$ref":"#/components/schemas/ApiReservationTransferInstruction"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"issueTransferInstruction","summary":"Issue or re-issue the bank-transfer instruction","description":"Requires property.read, reservation.create_manual and guest.read: the booking’s guest-facing money, held by PostgreSQL as well. The app's \"Überweisung anfordern\" of a confirmed manual or request-born booking: what is open, to the Property's bank details, with the reference `KS-<number> <last name>`. `expectedInstructionId` is the instruction the caller saw (null for none); another one being current answers VERSION_CONFLICT. A re-issue keeps the superseded instruction's bank details: taking the Property's new details needs the owner's password in the app and is not offered here. Recording the money is recordPayment with `transfer`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTransferInstructionRequest"}}}},"responses":{"201":{"description":"The instruction now current.","content":{"application/json":{"example":{"instruction":{"id":"76000000-0000-4000-8000-000000000001","reservationId":"20000000-0000-4000-8000-000000000001","state":"issued","holder":"Haus am See GbR","ibanMasked":"DE89…3000","detailsChanged":false,"reference":"KS-1042 Berger","issuedAt":"2026-11-17T09:00:00.000Z","endedAt":null,"instalments":[{"amount":{"minorUnits":"48600","currency":"EUR"},"dueOn":"2026-11-24","open":{"minorUnits":"48600","currency":"EUR"}}],"expected":{"minorUnits":"48600","currency":"EUR"},"dueOn":"2026-11-24","overdue":false,"outdated":false}},"schema":{"$ref":"#/components/schemas/ApiTransferInstructionIssued"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: another instruction is current; NOT_RECORDABLE: not a confirmed manual or request-born booking; TRANSFER_UNAVAILABLE: the Property has no bank details (`detail` details_missing); NOTHING_OPEN: nothing is open; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or the due day is before today, more than a year ahead or set for a booking whose dates follow its quote.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/tourist-tax":{"get":{"operationId":"getReservationTouristTax","summary":"Read a booking’s tourist tax","description":"Requires property.read, reservation.read and guest.read: the app’s tourist tax card of a booking, with the party as counted (adults, children’s ages, exemptions and their reason), what is due under the Property’s rules, what was paid with the booking and what an exemption may give back. `version` is what saveReservationTouristTax expects.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The booking’s tourist tax.","content":{"application/json":{"example":{"currency":"EUR","canEdit":true,"version":"2","source":"direct","party":{"adults":2,"childAges":[7],"exempt":1,"reason":"disability","note":null,"fromHost":true},"persons":{"adultRate":1,"childRate":1,"free":0,"exempt":1},"hasRules":true,"collection":"in_price","due":{"minorUnits":"900","currency":"EUR"},"paid":{"minorUnits":"1350","currency":"EUR"},"refundSuggestion":{"minorUnits":"450","currency":"EUR"},"refunded":{"minorUnits":"0","currency":"EUR"},"refundOpen":null},"schema":{"$ref":"#/components/schemas/ApiReservationTouristTax"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"saveReservationTouristTax","summary":"Set the party a booking’s tourist tax counts","description":"Requires property.read, reservation.create_manual and guest.read: the booking’s guest-facing money, held by PostgreSQL as well. The app's tourist tax card: the adults, the children's ages and how many are exempt and why, at exactly the `version` getReservationTouristTax gave. Keyset computes what is due from it; no amount is sent. A booking that is not confirmed keeps its party (TOURIST_TAX_NOT_EDITABLE). The same party again answers `unchanged`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiReservationTouristTaxSaveRequest"}}}},"responses":{"200":{"description":"Whether the party changed.","content":{"application/json":{"example":{"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiReservationTouristTaxSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the party changed since it was read; TOURIST_TAX_NOT_EDITABLE: the booking keeps its party; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or the party does not add up (more exempt than persons, `other` without a note).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/invoices":{"get":{"operationId":"listReservationInvoices","summary":"Read a booking’s invoices","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The app's invoice card of a booking: every invoice and credit note, oldest first (a booking has a handful, so the list is not paged), whether a new one may be issued and what it still needs, and the recipient of the guest's newest earlier invoice to prefill the next.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"}],"responses":{"200":{"description":"The booking’s invoices.","content":{"application/json":{"example":{"invoices":[{"id":"76000000-0000-4000-8000-000000000005","kind":"invoice","number":"RE-2026-0042","issueDate":"2026-11-17","amount":{"minorUnits":"48600","currency":"EUR"},"cancelsInvoiceId":null,"cancelledBy":null,"mail":"sent","xrechnung":false}],"contactName":"Anna Berger","missing":[],"canIssue":false,"canMail":true,"previousRecipient":null},"schema":{"$ref":"#/components/schemas/ApiReservationInvoices"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"issueInvoice","summary":"Issue the invoice of a booking","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The app's \"Rechnung erstellen\": the invoice of a confirmed booking, to the recipient sent, with the lines, taxes and totals Keyset takes from the booking's immutable quote and the issuer settings; no amount is sent. PostgreSQL takes the next number without a gap. A booking with an invoice that is not cancelled gets no second one (INVOICE_ALREADY_ISSUED). Answers the `invoice.issued` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInvoiceIssueRequest"}}}},"responses":{"201":{"description":"The invoice and its number.","content":{"application/json":{"example":{"id":"76000000-0000-4000-8000-000000000005","number":"RE-2026-0042"},"schema":{"$ref":"#/components/schemas/ApiInvoiceIssued"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"BOOKING_NOT_CONFIRMED: only a confirmed booking gets an invoice; INVOICE_ALREADY_ISSUED: it has one; VERSION_CONFLICT: the booking’s total or the tax setting changed while the invoice was made; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid; INVOICE_INCOMPLETE: the issuer settings or a line lack something (`detail` lists it).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoices/{invoiceId}/pdf":{"get":{"operationId":"getInvoicePdf","summary":"Download an invoice as PDF","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The invoice or credit note as the PDF the guest receives, rendered from its stored document: the same bytes the app downloads for the same invoice. An invoice issued while a bank transfer was open prints the Property's full IBAN and BIC with its QR code, as the guest receives it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"An invoice or credit note, as listReservationInvoices gives it."},"required":true,"description":"An invoice or credit note, as listReservationInvoices gives it.","name":"invoiceId","in":"path"}],"responses":{"200":{"description":"The PDF, named after the invoice number (`RE-2026-0042.pdf`; a `/` becomes `-`).","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"application/pdf":{"example":"binary PDF document","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoices/{invoiceId}/xrechnung":{"get":{"operationId":"getInvoiceXRechnung","summary":"Download an invoice as XRechnung","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The invoice or credit note as an XRechnung (UBL, EN 16931) for a business guest, as the app downloads it. It states the full IBAN and BIC (PaymentMeansCode 58) when a bank transfer was open at issue. Only when its document has what the standard needs, a company recipient with both addresses and the host's phone (`xrechnung` in listReservationInvoices); else XRECHNUNG_UNAVAILABLE with what is missing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"An invoice or credit note, as listReservationInvoices gives it."},"required":true,"description":"An invoice or credit note, as listReservationInvoices gives it.","name":"invoiceId","in":"path"}],"responses":{"200":{"description":"The XML file, named after the invoice number (`RE-2026-0042.xml`; a `/` becomes `-`).","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"application/xml":{"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice …/>","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter is invalid; XRECHNUNG_UNAVAILABLE: the invoice lacks what an XRechnung needs (`detail` lists it).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/exports/reservations":{"get":{"operationId":"exportReservations","summary":"Download the bookings of a period","description":"Requires property.read, reservation.read and guest.read: the app’s booking export, every booking arriving from `from` to `to` with its guest’s contact data, stay, total, paid and refunded, as UTF-8 CSV with a byte-order mark, `;`-separated, German headings. At most 366 days and 10000 bookings (TOO_MANY_ROWS).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"date","description":"The first arrival day, inclusive."},"required":true,"description":"The first arrival day, inclusive.","name":"from","in":"query"},{"schema":{"type":"string","format":"date","description":"The last arrival day, inclusive; at most 366 days after `from`."},"required":true,"description":"The last arrival day, inclusive; at most 366 days after `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"The CSV file, as `buchungen-<from>-bis-<to>.csv` (`buchungen-<from>.csv` for one day).","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"text/csv":{"example":"Buchungsnummer;Status;Quelle;Apartment;Anreise;…","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: an invalid period; TOO_MANY_ROWS: more bookings than one file holds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/exports/datev":{"get":{"operationId":"exportDatev","summary":"Download the DATEV booking batch","description":"Requires property.read and reservation.read: the app’s DATEV export, the confirmed bookings arriving in the months from `from` to `to` (one calendar year) as a DATEV booking batch (EXTF, version 700, category 21) in Windows-1252, with the accounts of the accounting settings. It carries booking numbers and amounts, no guest’s name. Incomplete settings answer SETTINGS_INCOMPLETE with what is missing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"The first arrival month, inclusive."},"required":true,"description":"The first arrival month, inclusive.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"The last arrival month, inclusive; in the same calendar year."},"required":true,"description":"The last arrival month, inclusive; in the same calendar year.","name":"to","in":"query"}],"responses":{"200":{"description":"The batch, under the file name DATEV expects (`EXTF_Buchungsstapel_…csv`).","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"text/csv":{"example":"\"EXTF\";700;21;\"Buchungsstapel\";…","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: an invalid period; SETTINGS_INCOMPLETE: the accounting settings lack something (`detail` lists it); UNSUPPORTED_CURRENCY: DATEV takes euros only; TOO_MANY_ROWS: more bookings than one batch holds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/exports/tourist-tax":{"get":{"operationId":"exportTouristTaxReport","summary":"Download the monthly tourist tax report","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The app's Kurtaxe report of a month: every booking's nights in the month with the party, exemptions and the tax due, and the totals, as CSV (UTF-8, `;`-separated) or as the PDF the app prints, by `format`. The host checks it before handing it in.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"`YYYY-MM` in the Property’s calendar."},"required":true,"description":"`YYYY-MM` in the Property’s calendar.","name":"month","in":"query"},{"schema":{"type":"string","enum":["csv","pdf"]},"required":true,"name":"format","in":"query"}],"responses":{"200":{"description":"The report, as `Kurtaxe_<month>.csv` or `Kurtaxe_<month>.pdf`.","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"text/csv":{"example":"Buchung;Gast;Unterkunft;Anreise;…","schema":{"type":"string","format":"binary"}},"application/pdf":{"example":"binary PDF document","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: an invalid month or format; TOO_MANY_ROWS: more stays than one report holds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/exports/check-in":{"get":{"operationId":"exportCheckIns","summary":"Download the month’s check-ins","description":"Requires property.read, reservation.create_manual and guest.read: the app’s Meldeschein export, the check-ins the guests gave for the arrivals of a month (names, birth dates, nationality, document number, address), as UTF-8 CSV. It is the most personal file Keyset makes, held by PostgreSQL to the same grants. Its rows never reach a log.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"`YYYY-MM` in the Property’s calendar."},"required":true,"description":"`YYYY-MM` in the Property’s calendar.","name":"month","in":"query"}],"responses":{"200":{"description":"The CSV file, as `Check-in_<month>.csv`.","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"text/csv":{"example":"Buchung;Anreise;Abreise;Apartment;…","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: an invalid month; TOO_MANY_ROWS: more check-ins than one file holds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/exports/guests":{"get":{"operationId":"exportGuests","summary":"Download the guest list","description":"Requires property.read, reservation.read and guest.read: the app’s guest export, every guest of the Property with name, e-mail, phone, stays, bookings, last and next arrival and whether they are a regular guest, as UTF-8 CSV with a byte-order mark, `;`-separated, German headings.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The CSV file, as `gaeste.csv`.","headers":{"content-disposition":{"schema":{"type":"string","description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"required":true,"description":"`attachment; filename=\"…\"`: the name the app gives the same file."},"cache-control":{"schema":{"type":"string","enum":["no-store"]},"required":true}},"content":{"text/csv":{"example":"Vorname;Nachname;E-Mail;Telefon;…","schema":{"type":"string","format":"binary"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter is invalid; TOO_MANY_ROWS: more guests than one file holds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/payments":{"post":{"operationId":"recordPayment","summary":"Record a payment received outside Keyset","description":"Requires property.read, reservation.cancel and payment.manage: money moves, a grant PostgreSQL holds for a key as well. The app's \"Zahlung erfassen\" of a manual or request-born booking: money that reached the host in cash, by transfer or otherwise. It is the host's statement, never provider evidence. PostgreSQL decides the Property's local today, refuses a day after it and an amount above what is still open (EXCEEDS_OUTSTANDING, `detail` names the open amount), and keeps one payment per idempotency key. `transfer` also marks an open bank transfer as received.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRecordPaymentRequest"}}}},"responses":{"201":{"description":"The payment, and what the booking now has received and still has open.","content":{"application/json":{"example":{"payment":{"id":"76000000-0000-4000-8000-000000000002","amount":{"minorUnits":"20000","currency":"EUR"},"receivedOn":"2026-11-17","method":"transfer"},"receivedAmount":{"minorUnits":"20000","currency":"EUR"},"outstandingAmount":{"minorUnits":"28600","currency":"EUR"}},"schema":{"$ref":"#/components/schemas/ApiPaymentRecorded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"EXCEEDS_OUTSTANDING: more than is still open; NOT_MANUAL_BOOKING: the booking was paid through Keyset; NOT_RECORDABLE: a cancelled booking takes no payment; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or the day lies after the Property’s today.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/payments/{paymentId}/void":{"post":{"operationId":"voidPayment","summary":"Take back a recorded payment","description":"Requires property.read, reservation.cancel and payment.manage: money moves, a grant PostgreSQL holds for a key as well. The app's \"Zahlung stornieren\": a mistaken recorded payment stops counting; it stays in the history. Money already given back from it blocks this (PAYMENT_REFUNDED): take that refund back first. A payment already taken back answers `already_voided`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A recorded payment, `recordedPayments[].id` of getReservationDetails."},"required":true,"description":"A recorded payment, `recordedPayments[].id` of getReservationDetails.","name":"paymentId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"What the booking now has received and still has open.","content":{"application/json":{"example":{"outcome":"voided","receivedAmount":{"minorUnits":"0","currency":"EUR"},"outstandingAmount":{"minorUnits":"48600","currency":"EUR"}},"schema":{"$ref":"#/components/schemas/ApiPaymentVoided"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"PAYMENT_REFUNDED: money of it was given back; take that refund back first; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/recorded-refunds":{"post":{"operationId":"recordRefund","summary":"Record money given back outside Keyset","description":"Requires property.read, reservation.cancel and payment.manage: money moves, a grant PostgreSQL holds for a key as well. The app's \"Erstattung erfassen\" of a booking paid outside Keyset: money the host gave back by transfer, in cash or otherwise. PostgreSQL refuses an amount above what the guest still holds with the host (EXCEEDS_REFUNDABLE, `detail` names it) and a day after the Property's today, and keeps one refund per idempotency key. A booking paid through Keyset refunds with refundThroughProvider instead (NOT_RECORDABLE).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRecordRefundRequest"}}}},"responses":{"201":{"description":"The refund, and what may still go back and is still owed.","content":{"application/json":{"example":{"refund":{"id":"76000000-0000-4000-8000-000000000003","amount":{"minorUnits":"10000","currency":"EUR"},"refundedOn":"2026-11-17","method":"transfer"},"refundableAmount":{"minorUnits":"10000","currency":"EUR"},"owedAmount":{"minorUnits":"0","currency":"EUR"}},"schema":{"$ref":"#/components/schemas/ApiRefundRecorded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"EXCEEDS_REFUNDABLE: more than the guest still holds with the host; NOT_RECORDABLE: a booking whose money Keyset handles, or an import; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or the day lies after the Property’s today.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/recorded-refunds/{refundId}/void":{"post":{"operationId":"voidRecordedRefund","summary":"Take back a recorded refund","description":"Requires property.read, reservation.cancel and payment.manage: money moves, a grant PostgreSQL holds for a key as well. The app's \"Erstattung stornieren\": a mistaken recorded refund stops counting; it stays in the history. One already taken back answers `already_voided`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A recorded refund, `recordedRefunds[].id` of getReservationDetails."},"required":true,"description":"A recorded refund, `recordedRefunds[].id` of getReservationDetails.","name":"refundId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"What may still go back and is still owed.","content":{"application/json":{"example":{"outcome":"voided","refundableAmount":{"minorUnits":"20000","currency":"EUR"},"owedAmount":{"minorUnits":"0","currency":"EUR"}},"schema":{"$ref":"#/components/schemas/ApiRecordedRefundVoided"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/reservations/{reservationId}/refunds":{"post":{"operationId":"refundThroughProvider","summary":"Refund through the payment provider","description":"Requires property.read, reservation.cancel and payment.manage: money moves, a grant PostgreSQL holds for a key as well. The app's \"Geld zurückgeben\" (goodwill) and \"Kurtaxe erstatten\" of a booking paid through Keyset: the money goes back to the guest's card through the host's Stripe account. The amount is the host's, at most what the booking's payments may still give back (EXCEEDS_REFUNDABLE). The refund is recorded first and the provider is asked after the answer, once, under this idempotency key; follow it in getReservationDetails `refunds[]`. When the provider's answer is lost the refund stays open and becomes an Eingang case (listAttentionCases), never a second refund. A tourist tax refund is this operation with getReservationTouristTax `refundSuggestion` as the amount and `Kurtaxe-Befreiung` as the note, as the app sends it. A test key's refund reaches the sandbox twin only.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The booking."},"required":true,"description":"The booking.","name":"reservationId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProviderRefundRequest"}}}},"responses":{"201":{"description":"The refund is recorded and will be sent to the provider.","content":{"application/json":{"example":{"refund":{"id":"76000000-0000-4000-8000-000000000004","amount":{"minorUnits":"5000","currency":"EUR"},"state":"requested"},"refundableAmount":{"minorUnits":"43600","currency":"EUR"}},"schema":{"$ref":"#/components/schemas/ApiProviderRefundRequested"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"EXCEEDS_REFUNDABLE: more than the booking’s payments may still give back; NOT_REFUNDABLE: the booking was not paid through Keyset; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoices/{invoiceId}/cancellation":{"post":{"operationId":"cancelInvoice","summary":"Cancel an invoice with a credit note","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The app's \"Rechnung stornieren\": an issued invoice is never changed or deleted; a credit note with the next number cancels it in full, and the booking may then get a new invoice. Answers the `invoice.cancelled` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"An invoice or credit note, as listReservationInvoices gives it."},"required":true,"description":"An invoice or credit note, as listReservationInvoices gives it.","name":"invoiceId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"201":{"description":"The credit note and its number.","content":{"application/json":{"example":{"id":"76000000-0000-4000-8000-000000000006","number":"RE-2026-0043"},"schema":{"$ref":"#/components/schemas/ApiInvoiceIssued"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"INVOICE_ALREADY_CANCELLED: the invoice was already cancelled, or is a credit note; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoices/{invoiceId}/mail":{"post":{"operationId":"mailInvoice","summary":"Send an invoice to the guest","description":"Requires property.read, reservation.read and guest.read: the document carries the guest’s name and address, and PostgreSQL holds guest.read for a key as well. The app's \"Per E-Mail senden\": the invoice or credit note goes to the booking's guest address as a PDF, with the XRechnung for a business guest, after the answer through Keyset's outbox; its `mail` in listReservationInvoices follows it. A test key mails no guest (TEST_MODE_NO_MAIL). One document is mailed at most five times, a business at most thirty invoice mails an hour.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"An invoice or credit note, as listReservationInvoices gives it."},"required":true,"description":"An invoice or credit note, as listReservationInvoices gives it.","name":"invoiceId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"example":{"outcome":"requested"},"schema":{"$ref":"#/components/schemas/ApiInvoiceMailRequested"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"MAIL_PENDING: its last mail is still on its way; MAIL_LIMIT_REACHED: it was mailed five times; GUEST_HAS_NO_EMAIL: the booking has no guest address; TEST_MODE_NO_MAIL: a test Property writes to no guest; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget is spent, or the business sent thirty invoice mails in the last hour. Nothing was queued; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/attention/{caseId}/reconciliation":{"post":{"operationId":"reconcileAttentionCase","summary":"Ask the provider again about a lost answer","description":"Requires property.read and payment.manage. The Eingang’s \"Jetzt prüfen\": for a case whose provider answer was lost (`nextAction` reconcile_now), Keyset asks the payment provider again after the answer, never repeating the money movement itself. `not_unknown`: the case has no lost answer to look for. The case is answered as listAttentionCases shows it.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^(refund|payment|dispute)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it."},"required":true,"description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it.","name":"caseId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Whether the provider is asked again, and the case.","content":{"application/json":{"example":{"outcome":"scheduled","asOf":"2026-11-17T08:00:00.000Z","case":{"caseId":"refund_40000000-0000-4000-8000-000000000005","kind":"refund","outcome":"delayed","severity":"high","impact":"refund_pending","nextAction":"reconcile_now","reconcileAvailable":true,"firstSeenAt":"2026-11-15T10:00:00.000Z","lastChangedAt":"2026-11-16T10:00:00.000Z","reservation":{"id":"40000000-0000-4000-8000-000000000004","confirmationReference":"K7Q2M9X4P1RT","number":1042,"state":"cancelled"},"unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"payment":{"id":"40000000-0000-4000-8000-000000000006","state":"succeeded","provider":"stripe","amount":{"minorUnits":"48600","currency":"EUR"},"createdAt":"2026-11-02T09:14:41.000Z","succeededAt":"2026-11-02T09:15:00.000Z","failedAt":null,"providerReferenceKnown":true},"checkout":{"id":"40000000-0000-4000-8000-000000000007","lifecycle":"completed","terminalReason":null,"terminalAt":"2026-11-02T09:15:00.000Z"},"refund":{"id":"40000000-0000-4000-8000-000000000005","state":"processing","reason":"operator_cancellation","amount":{"minorUnits":"48600","currency":"EUR"},"requestedAt":"2026-11-15T10:00:00.000Z","terminalAt":null,"providerReferenceKnown":true},"cancellation":{"id":"40000000-0000-4000-8000-000000000008","cancelledAt":"2026-11-15T09:59:00.000Z"},"dispute":null,"operation":{"destination":"payment_refund","state":"retry_wait","attemptCount":2,"reconcileAttemptCount":0,"firstAttemptAt":"2026-11-15T10:00:05.000Z","lastAttemptAt":"2026-11-16T10:00:05.000Z","unknownSince":null,"reconcileAfter":null,"deliveredAt":null,"quarantinedAt":null,"quarantineReason":null,"lastErrorCode":null},"attentionItem":{"state":"open","firstSeenAt":"2026-11-15T10:00:00.000Z","resolvedAt":null},"quarantinedInboxMessages":0,"closure":null,"closable":false}},"schema":{"$ref":"#/components/schemas/ApiAttentionReconciled"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/attention/{caseId}/closure":{"post":{"operationId":"closeAttentionCase","summary":"Close an Eingang case by hand","description":"Requires property.read, reservation.cancel and payment.manage: money moves, a grant PostgreSQL holds for a key as well. The Eingang's \"Als erledigt markieren\": the host settled the case outside Keyset (for example in the Stripe dashboard) and says why; the reason is stored with the closure. A case that still resolves by itself cannot be closed (CASE_NOT_CLOSABLE). No money moves.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^(refund|payment|dispute)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it."},"required":true,"description":"`refund_<uuid>`, `payment_<uuid>` or `dispute_<uuid>`, as the list gives it.","name":"caseId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAttentionCloseRequest"}}}},"responses":{"200":{"description":"The case, now closed.","content":{"application/json":{"example":{"asOf":"2026-11-17T08:00:00.000Z","case":{"caseId":"refund_40000000-0000-4000-8000-000000000005","kind":"refund","outcome":"delayed","severity":"high","impact":"refund_pending","nextAction":"reconcile_now","reconcileAvailable":true,"firstSeenAt":"2026-11-15T10:00:00.000Z","lastChangedAt":"2026-11-16T10:00:00.000Z","reservation":{"id":"40000000-0000-4000-8000-000000000004","confirmationReference":"K7Q2M9X4P1RT","number":1042,"state":"cancelled"},"unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"payment":{"id":"40000000-0000-4000-8000-000000000006","state":"succeeded","provider":"stripe","amount":{"minorUnits":"48600","currency":"EUR"},"createdAt":"2026-11-02T09:14:41.000Z","succeededAt":"2026-11-02T09:15:00.000Z","failedAt":null,"providerReferenceKnown":true},"checkout":{"id":"40000000-0000-4000-8000-000000000007","lifecycle":"completed","terminalReason":null,"terminalAt":"2026-11-02T09:15:00.000Z"},"refund":{"id":"40000000-0000-4000-8000-000000000005","state":"processing","reason":"operator_cancellation","amount":{"minorUnits":"48600","currency":"EUR"},"requestedAt":"2026-11-15T10:00:00.000Z","terminalAt":null,"providerReferenceKnown":true},"cancellation":{"id":"40000000-0000-4000-8000-000000000008","cancelledAt":"2026-11-15T09:59:00.000Z"},"dispute":null,"operation":{"destination":"payment_refund","state":"retry_wait","attemptCount":2,"reconcileAttemptCount":0,"firstAttemptAt":"2026-11-15T10:00:05.000Z","lastAttemptAt":"2026-11-16T10:00:05.000Z","unknownSince":null,"reconcileAfter":null,"deliveredAt":null,"quarantinedAt":null,"quarantineReason":null,"lastErrorCode":null},"attentionItem":{"state":"open","firstSeenAt":"2026-11-15T10:00:00.000Z","resolvedAt":null},"quarantinedInboxMessages":0,"closure":null,"closable":false}},"schema":{"$ref":"#/components/schemas/ApiAttentionClosed"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"CASE_ALREADY_CLOSED: the case was already closed; CASE_NOT_CLOSABLE: it still resolves by itself; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or the reason is not 3 to 300 characters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/bookable":{"get":{"operationId":"getUnitBookable","summary":"Read what switching „Buchbar“ changes","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Buchbar“ dialog, read before switching: the bookings ahead that stay (by stay and an opaque `ref`; with their id and number only for a key that also holds reservation.read, and the guest's name only for one that also holds guest.read), holds and blocks, the apartments it is part of or made of, whether the booking page loses its last bookable apartment, and how many apartments the Keyset subscription counts now and after the switch. Amounts and every change to the subscription stay in the app with the owner (ADR-059). An archived apartment answers NOT_FOUND.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"}],"responses":{"200":{"description":"What switching the apartment changes and what stays.","content":{"application/json":{"example":{"status":"active","bookings":[{"id":"40000000-0000-4000-8000-000000000001","number":1042,"ref":"c82a1958-db8b-8dbb-b862-cb7aaa0438c1","guestName":null,"checkIn":"2026-12-20","checkOut":"2026-12-27","via":null}],"holds":0,"blocks":1,"partOf":[{"id":"30000000-0000-4000-8000-000000000009","code":"ganzes-haus","name":"Ganzes Haus"}],"partsOff":[],"published":true,"priced":true,"siteEmptied":false,"subscription":{"apartmentsNow":5,"apartmentsAfter":4}},"schema":{"$ref":"#/components/schemas/ApiUnitBookable"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"setUnitBookable","summary":"Switch „Buchbar“ on or off","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Buchbar“ switch. Off keeps every booking ahead and refuses the apartment every new one (and the apartments it is part of); on takes bookings again. Read getUnitBookable first and send the `ref` of each of its bookings as `seen` (a key without reservation.read sees the bookings by stay and ref only): switching off is refused while a booking ahead stands that was not seen (BOOKINGS_CHANGED, `detail` names its booking number, or with a key without reservation.read how many). The apartment then counts for the Keyset subscription as getUnitBookable said; the subscription itself is changed by Keyset's own billing, never by this call. Announces the `unit.changed` webhook event with `change` `bookable`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUnitBookableRequest"}}}},"responses":{"200":{"description":"Whether the switch changed.","content":{"application/json":{"example":{"outcome":"switched"},"schema":{"$ref":"#/components/schemas/ApiUnitBookableSwitched"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"BOOKINGS_CHANGED: a booking ahead was made since getUnitBookable; read it again; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/archive":{"get":{"operationId":"getUnitArchive","summary":"Read what keeps an apartment from being archived","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Archivieren“ check: whether the apartment is archived, how many holds and bookings ahead keep it, and the apartments it is part of.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"}],"responses":{"200":{"description":"What keeps the apartment.","content":{"application/json":{"example":{"archived":false,"openBookings":0,"partOf":[]},"schema":{"$ref":"#/components/schemas/ApiUnitArchive"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"archiveUnit","summary":"Archive an apartment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Archivieren“: the apartment leaves the apartment list, the calendar and the booking page and takes no booking; its past bookings stay. PostgreSQL refuses it while a hold or booking ahead holds it or it is part of another apartment (UNIT_IN_USE, `detail` says which). Archiving switches it off, so it no longer counts for the Keyset subscription. It can be brought back with restoreUnit. Announces the `unit.archived` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Whether the apartment was archived now.","content":{"application/json":{"example":{"outcome":"archived"},"schema":{"$ref":"#/components/schemas/ApiUnitArchived"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"UNIT_IN_USE: a stay ahead holds the apartment, or it is part of another; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units":{"post":{"operationId":"createUnit","summary":"Create an apartment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Apartment anlegen“: a new apartment with its name and the most guests it takes, switched on („Buchbar“). Without a code Keyset derives one from the name. Guests can book it once it has a price and is on the booking site; from then on it counts for the Keyset subscription, as in the app (getUnitBookable shows the count; the subscription itself stays in the app). The texts, photos and prices are written separately. Announces the `unit.created` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUnitCreateRequest"}}}},"responses":{"201":{"description":"The new apartment.","content":{"application/json":{"example":{"unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment 1","maxOccupancy":4,"status":"active","futureAllocations":0,"bookedOccupancy":null,"onBookingSite":false,"componentUnitIds":[]}},"schema":{"$ref":"#/components/schemas/ApiUnitCreated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"UNIT_CODE_TAKEN: another apartment of the Property has the code you named; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}":{"put":{"operationId":"updateUnit","summary":"Change an apartment’s name and capacity","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The apartment's Stammdaten: its name and the most guests it takes. PostgreSQL refuses a maximum below a booking ahead (OCCUPANCY_BELOW_BOOKINGS, `detail` names the largest booked guest count). „Buchbar“ is switched with setUnitBookable, never here. An archived apartment answers NOT_FOUND. Announces the `unit.changed` webhook event with `change` `details`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUnitUpdateRequest"}}}},"responses":{"200":{"description":"The apartment after the change.","content":{"application/json":{"example":{"outcome":"configured","unit":{"id":"30000000-0000-4000-8000-000000000001","code":"apartment-1","name":"Apartment Seeblick","maxOccupancy":4,"status":"active","futureAllocations":3,"bookedOccupancy":3,"onBookingSite":true,"componentUnitIds":[]}},"schema":{"$ref":"#/components/schemas/ApiUnitUpdated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"OCCUPANCY_BELOW_BOOKINGS: a booking ahead has more guests than the new maximum; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/components":{"put":{"operationId":"setUnitComponents","summary":"Set which apartments an apartment is made of","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Besteht aus“ (the whole house made of its apartments): from then on a booking of the house holds its parts and a booking of a part holds the house, decided by PostgreSQL. Only other active single apartments of the Property can be parts (INVALID_COMPONENTS); while a stay ahead holds the composite its composition cannot change (UNIT_IN_USE). An empty list makes it a single apartment again. Announces the `unit.changed` webhook event with `change` `components`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUnitComponentsRequest"}}}},"responses":{"200":{"description":"Whether the composition changed.","content":{"application/json":{"example":{"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiUnitComponentsSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"UNIT_IN_USE: a stay ahead holds the apartment; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid; INVALID_COMPONENTS: these apartments cannot make it up.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/restore":{"post":{"operationId":"restoreUnit","summary":"Bring back an archived apartment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Wiederherstellen“ of an archived apartment (getPropertyConfiguration `archivedUnits`): it returns to the list switched off, neither bookable nor on the booking page until setUnitBookable switches it on; only then does it count for the Keyset subscription again. Announces the `unit.restored` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Whether the apartment was brought back now.","content":{"application/json":{"example":{"outcome":"restored"},"schema":{"$ref":"#/components/schemas/ApiUnitRestored"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/units/{unitId}/content":{"put":{"operationId":"saveUnitContent","summary":"Save an apartment’s booking page texts","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Inhalte“ of one apartment: its description, amenities, rooms with their beds, floor area and English description. The whole set is replaced; send the apartment's `version` of getBookingContent as `expectedVersion` (VERSION_CONFLICT when someone saved meanwhile). Announces the `unit.changed` webhook event with `change` `content`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUnitContentSaveRequest"}}}},"responses":{"200":{"description":"Saved, and the version the next save names.","content":{"application/json":{"example":{"outcome":"saved","version":"2"},"schema":{"$ref":"#/components/schemas/ApiContentSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-site/effect":{"get":{"operationId":"getBookingSiteEffect","summary":"Read what publishing or pausing the booking site does","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's dialog before „Veröffentlichen“ and „Pausieren“: PostgreSQL runs the real change in a transaction it never commits and answers what it would refuse right now, or how many apartments the Keyset subscription counts now and after (a published apartment with a price counts). The subscription changes by Keyset’s own billing, never by this call; amounts, the plan and the subscription itself stay in the app with the owner (ADR-059).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","enum":["publish","pause"],"description":"The change to look at."},"required":true,"description":"The change to look at.","name":"action","in":"query"}],"responses":{"200":{"description":"The refusal, or the apartments counted before and after.","content":{"application/json":{"example":{"action":"publish","refusal":null,"subscription":{"apartmentsNow":0,"apartmentsAfter":5}},"schema":{"$ref":"#/components/schemas/ApiBookingSiteEffect"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/search-indexing":{"get":{"operationId":"getSearchIndexing","summary":"Read „Von Suchmaschinen finden lassen“","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Whether search engines may list the published booking page (the sitemap and the page’s noindex rule follow it). On by default.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"Whether the switch is on.","content":{"application/json":{"example":{"enabled":true},"schema":{"$ref":"#/components/schemas/ApiSearchIndexing"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"setSearchIndexing","summary":"Switch „Von Suchmaschinen finden lassen“","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Whether search engines may list the published booking page (the sitemap and the page’s noindex rule follow it). On by default. Switching to what is stored changes nothing. Announces the `settings.changed` webhook event with `area` `search-indexing`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSwitchRequest"}}}},"responses":{"200":{"description":"The switch as stored now.","content":{"application/json":{"example":{"enabled":false},"schema":{"$ref":"#/components/schemas/ApiSearchIndexing"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/agent-access":{"get":{"operationId":"getAgentAccess","summary":"Read „Von KI-Assistenten finden lassen“","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Whether AI assistants may find and read the published booking page through Keyset’s MCP server; never anything about a guest. Off until the host turns it on.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"Whether the switch is on.","content":{"application/json":{"example":{"enabled":true},"schema":{"$ref":"#/components/schemas/ApiAgentAccess"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"setAgentAccess","summary":"Switch „Von KI-Assistenten finden lassen“","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Whether AI assistants may find and read the published booking page through Keyset’s MCP server; never anything about a guest. Off until the host turns it on. Switching to what is stored changes nothing. Announces the `settings.changed` webhook event with `area` `agent-access`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSwitchRequest"}}}},"responses":{"200":{"description":"The switch as stored now.","content":{"application/json":{"example":{"enabled":false},"schema":{"$ref":"#/components/schemas/ApiAgentAccess"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-site/publish":{"post":{"operationId":"publishBookingSite","summary":"Publish the booking site, or put it back online","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Veröffentlichen“ and „Wieder online stellen“: every active apartment with a published price goes on the booking site, also one priced after it went live. PostgreSQL refuses it without a priced apartment (BOOKING_SITE_NOT_READY), without an Impressum and a privacy notice (BOOKING_SITE_LEGAL_MISSING, `detail` names which), while the subscription has lapsed (BOOKING_SITE_BILLING_REQUIRED) and when nothing is left to publish (BOOKING_SITE_ALREADY_PUBLISHED). Answers the site and the apartments the subscription counts before and after. The subscription changes by Keyset’s own billing, never by this call; amounts, the plan and the subscription itself stay in the app with the owner (ADR-059). Announces the `booking_site.published` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The booking site is online.","content":{"application/json":{"example":{"outcome":"published","site":{"publicId":"Xk3p9Qw2Lm7Rt5Yv8Bn4Hc","state":"published","bookableUnits":5,"activeUnits":5,"publishedUnits":5,"pausedAt":null},"subscription":{"apartmentsBefore":0,"apartmentsAfter":5}},"schema":{"$ref":"#/components/schemas/ApiBookingSiteChanged"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"BOOKING_SITE_NOT_READY, BOOKING_SITE_LEGAL_MISSING, BOOKING_SITE_BILLING_REQUIRED or BOOKING_SITE_ALREADY_PUBLISHED; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/booking-site/pause":{"post":{"operationId":"pauseBookingSite","summary":"Pause the booking site","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's „Pausieren“: the booking site answers guests like an unknown one until it is published again (publishBookingSite); a checkout already in flight can still pay. A paused site answers `already_paused`; a site never published answers BOOKING_SITE_NOT_PUBLISHED. Answers the site and the apartments the subscription counts before and after. The subscription changes by Keyset’s own billing, never by this call; amounts, the plan and the subscription itself stay in the app with the owner (ADR-059). Announces the `booking_site.paused` webhook event.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The booking site is paused.","content":{"application/json":{"example":{"outcome":"paused","site":{"publicId":"Xk3p9Qw2Lm7Rt5Yv8Bn4Hc","state":"paused","bookableUnits":5,"activeUnits":5,"publishedUnits":5,"pausedAt":"2026-11-17T08:00:00.000Z"},"subscription":{"apartmentsBefore":5,"apartmentsAfter":0}},"schema":{"$ref":"#/components/schemas/ApiBookingSiteChanged"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"BOOKING_SITE_NOT_PUBLISHED: the site was never published; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/payment-settings/cancellation-policy/example":{"get":{"operationId":"getCancellationPolicyExample","summary":"Work an example of cancellation terms","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The worked example the app's „Stornobedingungen“ dialog shows while the host types: what terms with `freeCancellationDays` and `lateRefundPercent` would refund of a booking of `totalMinorUnits` when the guest cancels 20 days, 10 days and on the arrival day, beside what the terms in force refund. PostgreSQL computes it with the rule a cancellation refunds by. Changes nothing.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":365},"required":false,"name":"freeCancellationDays","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100},"required":false,"name":"lateRefundPercent","in":"query"},{"schema":{"type":"string","pattern":"^[1-9]\\d{0,11}$","description":"A booking total in minor units of the Property’s currency, greater than zero, to work the example on."},"required":true,"description":"A booking total in minor units of the Property’s currency, greater than zero, to work the example on.","name":"totalMinorUnits","in":"query"}],"responses":{"200":{"description":"The example.","content":{"application/json":{"example":{"total":{"minorUnits":"80000","currency":"EUR"},"cases":[{"daysBefore":20,"refund":{"minorUnits":"80000","currency":"EUR"},"currentRefund":{"minorUnits":"80000","currency":"EUR"}},{"daysBefore":10,"refund":{"minorUnits":"40000","currency":"EUR"},"currentRefund":{"minorUnits":"40000","currency":"EUR"}},{"daysBefore":0,"refund":{"minorUnits":"40000","currency":"EUR"},"currentRefund":{"minorUnits":"40000","currency":"EUR"}}]},"schema":{"$ref":"#/components/schemas/ApiCancellationPolicyExample"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/payment-settings/cancellation-policy":{"put":{"operationId":"setCancellationPolicy","summary":"Save the cancellation terms","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The app's „Stornobedingungen“ of card payments: free cancellation up to so many days before arrival, a whole percent refunded after that. Send `cancellationPolicy.version` of getPaymentSettings as `expectedVersion` (null before the first save); a newer one answers VERSION_CONFLICT. A change reaches only bookings made afterwards; every booking keeps the terms it was made under. Saving the terms in force changes nothing. Answers the payment settings as getPaymentSettings reads them. Announces the `settings.changed` webhook event with `area` `payment-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCancellationPolicySaveRequest"}}}},"responses":{"200":{"description":"Saved, and the payment settings with the terms in force.","content":{"application/json":{"example":{"environment":"live","status":"ready","currency":"EUR","country":"DE","chargesEnabled":true,"payoutsEnabled":true,"currencies":["EUR"],"acceptsBookings":true,"cancellationPolicy":{"version":3,"freeCancellationDays":14,"lateRefundPercent":50}},"schema":{"$ref":"#/components/schemas/ApiPaymentSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the terms were saved by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/payment-settings/currency":{"put":{"operationId":"setPaymentCurrency","summary":"Set the Property’s currency","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The app's „Währung“: the currency prices, bookings and payments of the Property are in. Only a currency Keyset admits for a Property is taken (today EUR; the list is the database's), another answers INVALID_REQUEST. Send `currency` of getPaymentSettings as `expectedCurrency`; another stored answers VERSION_CONFLICT. Once the Property has prices, quotes, bookings or imports, the currency stays (CURRENCY_LOCKED). Answers the payment settings as getPaymentSettings reads them. Announces the `settings.changed` webhook event with `area` `payment-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiPaymentCurrencySaveRequest"}}}},"responses":{"200":{"description":"Saved, and the payment settings in the currency now stored.","content":{"application/json":{"example":{"environment":"live","status":"ready","currency":"EUR","country":"DE","chargesEnabled":true,"payoutsEnabled":true,"currencies":["EUR"],"acceptsBookings":true,"cancellationPolicy":{"version":3,"freeCancellationDays":14,"lateRefundPercent":50}},"schema":{"$ref":"#/components/schemas/ApiPaymentSettings"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: another currency is stored than you read; CURRENCY_LOCKED: the Property has prices, quotes, bookings or imports; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid, or the currency is not one Keyset admits for a Property.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/tourist-tax/change/discard":{"post":{"operationId":"discardTouristTaxChange","summary":"Drop the planned tourist tax rate","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. Nothing here reaches the payment provider. The app's „Geplanten Satz verwerfen“: drops the rate planned from a day still ahead in the Property's time zone (getTouristTax `changeDroppable`), as a new version without it. A plan whose day has come is the rate in force and stays (TOURIST_TAX_CHANGE_NOT_PLANNED). Send `version` of getTouristTax as `expectedVersion`; a newer one answers VERSION_CONFLICT. Answers the version now in force. Announces the `settings.changed` webhook event with `area` `tourist-tax`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTouristTaxChangeDiscardRequest"}}}},"responses":{"200":{"description":"The planned rate is dropped.","content":{"application/json":{"example":{"outcome":"discarded","version":"5"},"schema":{"$ref":"#/components/schemas/ApiTouristTaxChangeDiscarded"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the tourist tax was saved by someone else since your read; TOURIST_TAX_CHANGE_NOT_PLANNED: no rate is planned ahead; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-connections/{connectionId}/removal":{"get":{"operationId":"getCalendarRemoval","summary":"Read what removing a connected calendar would affect","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's confirmation before „Kalender entfernen“: the stays the calendar brought in that arrive after today at the Property (kept by a removal unless their nights are released) and how many current and past stays it brought in (kept either way). Each future stay carries an opaque `ref`; its booking's id and number only for a key that also holds reservation.read. Send the `futureStays[].ref` to removeCalendarConnection when releasing them.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The connection, `connections[].id` of getCalendarConnections."},"required":true,"description":"The connection, `connections[].id` of getCalendarConnections.","name":"connectionId","in":"path"}],"responses":{"200":{"description":"What a removal would keep and what it could release.","content":{"application/json":{"example":{"futureStays":[{"reservationId":"40000000-0000-4000-8000-000000000001","reservationNumber":1051,"ref":"c82a1958-db8b-8dbb-b862-cb7aaa0438c1","checkIn":"2027-02-10","checkOut":"2027-02-14"}],"otherStays":4},"schema":{"$ref":"#/components/schemas/ApiCalendarRemoval"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-connections/probe":{"post":{"operationId":"probeCalendarConnection","summary":"Check a portal’s calendar link before connecting it","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Kalender verbinden“ check: fetches the link once and answers what the first sync into the apartment would do, the stays not over by today and each stay that lands on nights Keyset already holds (a booking, by its number only for a key that also holds reservation.read and with the guest's name only for one that also holds guest.read; a stay another calendar brought in; a block; a guest paying right now). It writes nothing and keeps neither the link nor the calendar. Keyset fetches the link exactly as the app does: https only (an http link is upgraded, webcal read as https), never an address outside the public internet (also after a redirect), at most three redirects, 2 MiB and 10 seconds; the request counts against the Property’s smaller budget for calls to the outside. A test business connects no portal calendar and fetches none (ADR-040): it answers NOT_FOUND. The link is the host’s key to the portal’s calendar: it is never returned, not in this answer, a replay, a read or a problem; reads name its host only. The answer is kept for the idempotency key like any write's: to check again, send a new key. Classes of `failed`: invalid (INVALID_URL, OWN_CALENDAR, MALFORMED_CALENDAR, INVALID_EVENT, DUPLICATE_EVENT_ID; fix the link or the calendar at the portal), unreachable (FEED_UNAVAILABLE, FEED_TIMEOUT; try later with a new key); a 500 has no known outcome.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCalendarProbeRequest"}}}},"responses":{"200":{"description":"What the first sync would do, the connection that already has the link, or why nothing came.","content":{"application/json":{"example":{"outcome":"found","stays":7,"lastCheckOut":"2027-03-14","conflicts":[{"checkIn":"2026-12-27","checkOut":"2027-01-02","keyset":{"kind":"booking","reservationNumber":1042,"guestName":null}}]},"schema":{"$ref":"#/components/schemas/ApiCalendarProbeResult"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-connections/{connectionId}/refresh":{"post":{"operationId":"refreshCalendarConnection","summary":"Read a connected calendar now","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Jetzt abrufen“: reads the connection's calendar now instead of at its next turn and takes in what changed under the import's rules, the same as the automatic read. The fetch runs between two short transactions, never inside one; another read of the same calendar finishing first answers `stale`. A failed read is recorded as the connection's last error and answered as `failed` with its code; it is a definite outcome, so a repeat with the same key replays it: to read again, send a new key. A key also needs reservation.create_manual and inventory.block (PERMISSION_DENIED otherwise; PostgreSQL holds them as well), as for taking over an import: every read turns the portal’s stays into bookings that hold nights and cancels them when the portal drops them. A connection keeps being read every 15 minutes whoever made it, as in the app. Keyset fetches the link exactly as the app does: https only (an http link is upgraded, webcal read as https), never an address outside the public internet (also after a redirect), at most three redirects, 2 MiB and 10 seconds; the request counts against the Property’s smaller budget for calls to the outside. A test business connects no portal calendar and fetches none (ADR-040): it answers NOT_FOUND. A removed connection answers NOT_FOUND.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The connection, `connections[].id` of getCalendarConnections."},"required":true,"description":"The connection, `connections[].id` of getCalendarConnections.","name":"connectionId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"What the read took in, or why it took in nothing.","content":{"application/json":{"example":{"outcome":"applied","revision":12,"imported":1,"unchanged":6,"modified":0,"cancelled":0,"conflicted":0},"schema":{"$ref":"#/components/schemas/ApiCalendarRefreshResult"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-connections/{connectionId}/remove":{"post":{"operationId":"removeCalendarConnection","summary":"Remove a connected calendar","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Kalender entfernen“: Keyset stops reading the calendar. Its future stays keep their nights unless `releaseFutureStays` is true, which frees them (their bookings are cancelled as the portal's own would be) and needs reservation.cancel as well (PERMISSION_DENIED, nothing removed, otherwise; PostgreSQL holds it for a key); current and past stays stay as history. To release, send the `futureStays[].ref` getCalendarRemoval listed (a stay's `reservationId` counts as well): when the future stays are no longer exactly those, nothing happens and the answer is CALENDAR_STAYS_CHANGED, so a stay you did not see is never released. A connection removed already answers `already_removed`. Announces the `settings.changed` webhook event with `area` `calendar-connections`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The connection, `connections[].id` of getCalendarConnections."},"required":true,"description":"The connection, `connections[].id` of getCalendarConnections.","name":"connectionId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCalendarRemoveRequest"}}}},"responses":{"200":{"description":"Removed, or removed already.","content":{"application/json":{"example":{"outcome":"removed","released":1},"schema":{"$ref":"#/components/schemas/ApiCalendarRemoved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"CALENDAR_STAYS_CHANGED: releasing, the future stays are not those you named; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid, or `futureStays` is missing while releasing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-exports":{"post":{"operationId":"ensureCalendarExports","summary":"Create Keyset’s calendar link for apartments","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Keysets Link anlegen“: each listed apartment gets a link where it has none or only a withdrawn one; an active link is never replaced, so a portal already reading it keeps working. Keyset’s link of an apartment lets any portal holding it read when the apartment is taken (dates only, never a guest). The link is shown in the answer of the write that made it and never again: a replay answers the same outcome with `url` and `token` null, and getCalendarConnections shows only whether it exists. Keep it where you keep secrets. An apartment whose link was active already is not in `links`: its link is not shown again (renew it with rotateCalendarExport to get a new one). A test business makes no link: it answers NOT_FOUND (ADR-040).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCalendarLinksEnsureRequest"}}}},"responses":{"200":{"description":"The links this call made.","content":{"application/json":{"example":{"outcome":"ensured","created":1,"links":[{"unitId":"30000000-0000-4000-8000-000000000001","url":"https://app.keyset.cloud/calendar/q3Vx8mZ2pL0rT5nW9cY4bH7kD1sF6gJ3aE8uI2oP5xQ.ics","token":"q3Vx8mZ2pL0rT5nW9cY4bH7kD1sF6gJ3aE8uI2oP5xQ"}]},"schema":{"$ref":"#/components/schemas/ApiCalendarLinksEnsured"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-exports/{unitId}/rotate":{"post":{"operationId":"rotateCalendarExport","summary":"Renew Keyset’s calendar link of an apartment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Link erneuern“: a new link for the apartment; the old one stops working at once, so every portal reading it needs the new one. Makes a link where there was none. Keyset’s link of an apartment lets any portal holding it read when the apartment is taken (dates only, never a guest). The link is shown in the answer of the write that made it and never again: a replay answers the same outcome with `url` and `token` null, and getCalendarConnections shows only whether it exists. Keep it where you keep secrets.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The new link.","content":{"application/json":{"example":{"outcome":"rotated","link":{"unitId":"30000000-0000-4000-8000-000000000001","url":"https://app.keyset.cloud/calendar/q3Vx8mZ2pL0rT5nW9cY4bH7kD1sF6gJ3aE8uI2oP5xQ.ics","token":"q3Vx8mZ2pL0rT5nW9cY4bH7kD1sF6gJ3aE8uI2oP5xQ"}},"schema":{"$ref":"#/components/schemas/ApiCalendarLinkRotated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/calendar-exports/{unitId}/revoke":{"post":{"operationId":"revokeCalendarExport","summary":"Withdraw Keyset’s calendar link of an apartment","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the calendars; PostgreSQL holds it for a key as well. The app's „Link widerrufen“: the apartment's link stops working at once; portals reading it no longer see when the apartment is taken. ensureCalendarExports or rotateCalendarExport make a new one. An apartment that never had a link answers NOT_FOUND.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The apartment, `units[].id` of getPropertyConfiguration."},"required":true,"description":"The apartment, `units[].id` of getPropertyConfiguration.","name":"unitId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Withdrawn.","content":{"application/json":{"example":{"outcome":"revoked"},"schema":{"$ref":"#/components/schemas/ApiCalendarLinkRevoked"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoice-settings/small-business/example":{"get":{"operationId":"getSmallBusinessExample","summary":"Show an invoice both ways before switching","description":"Requires property.read and reservation.read: the example is a real booking’s invoice (the one of the last invoice issued, or else the last confirmed booking with a price), made both as a small business and with VAT by the very rule that issues invoices, as the app’s dialog shows it before the switch. The recipient is a placeholder; no guest data is part of it. `withTax` is null while an item of the booking has no VAT rate (`missing`, set them with saveAccountingSettings); `example` is null without such a booking.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The example, or null.","content":{"application/json":{"example":{"example":{"bookingNumber":1042,"invoiceNumber":"RE-2026-0017","smallBusiness":{"lines":[{"description":"Übernachtung Apartment 1, 3 Nächte","rate":null,"gross":{"minorUnits":"36000","currency":"EUR"},"touristTax":false},{"description":"Kurtaxe (ohne Umsatzsteuer)","rate":null,"gross":{"minorUnits":"1500","currency":"EUR"},"touristTax":true}],"taxGroups":[],"total":{"minorUnits":"37500","currency":"EUR"},"tax":{"minorUnits":"0","currency":"EUR"},"notes":["Gemäß § 19 UStG wird keine Umsatzsteuer berechnet."]},"withTax":{"lines":[{"description":"Übernachtung Apartment 1, 3 Nächte","rate":7,"gross":{"minorUnits":"36000","currency":"EUR"},"touristTax":false},{"description":"Kurtaxe (ohne Umsatzsteuer)","rate":null,"gross":{"minorUnits":"1500","currency":"EUR"},"touristTax":true}],"taxGroups":[{"rate":7,"gross":{"minorUnits":"36000","currency":"EUR"},"net":{"minorUnits":"33645","currency":"EUR"},"tax":{"minorUnits":"2355","currency":"EUR"}}],"total":{"minorUnits":"37500","currency":"EUR"},"tax":{"minorUnits":"2355","currency":"EUR"},"notes":[]},"missing":[]}},"schema":{"$ref":"#/components/schemas/ApiSmallBusinessExample"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoice-settings/numbering":{"put":{"operationId":"saveInvoiceNumbering","summary":"Set the prefix and the next invoice number","description":"Requires property.read and property.configure. The invoice settings belong to the business, so PostgreSQL asks, as the app does of a person, for property.configure on every active Property of the business: a key issued for some of them only answers NOT_FOUND. The app's „Nächste Nummer ändern“, under the same guards, because gaps and repeats in invoice numbers are a legal matter: a number already issued or below the last one issued with that prefix answers INVOICE_NUMBER_TAKEN, and a next number that skips numbers answers INVOICE_NUMBER_GAP unless `gapAcknowledged` is true (then the skipped numbers are recorded). Each refusal and VERSION_CONFLICT name the smallest next number accepted for that prefix in `detail` (`Minimum: 12.`). Send `numberingVersion` of getInvoiceSettings; every invoice issued moves it on. The version is read with getInvoiceSettings (which asks reservation.read or property.configure); a stale one answers VERSION_CONFLICT. Announces the `settings.changed` webhook event with `area` `invoice-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInvoiceNumberingSaveRequest"}}}},"responses":{"200":{"description":"Saved (or already so).","content":{"application/json":{"example":{"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiInvoiceSettingsSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the numbering moved on since your read (an invoice was issued); INVOICE_NUMBER_TAKEN; INVOICE_NUMBER_GAP; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/invoice-settings/small-business":{"put":{"operationId":"saveSmallBusiness","summary":"Switch the small-business rule","description":"Requires property.read and property.configure. The invoice settings belong to the business, so PostgreSQL asks, as the app does of a person, for property.configure on every active Property of the business: a key issued for some of them only answers NOT_FOUND. The app's „Kleinunternehmer-Regelung“ (§ 19 UStG) for the whole business: from the next invoice issued, invoices carry no VAT and print the § 19 sentence; invoices issued keep what they say, and nobody is told. Read what an invoice would say either way with getSmallBusinessExample first. Send `taxVersion` of getInvoiceSettings. The version is read with getInvoiceSettings (which asks reservation.read or property.configure); a stale one answers VERSION_CONFLICT. Announces the `settings.changed` webhook event with `area` `invoice-settings`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSmallBusinessSaveRequest"}}}},"responses":{"200":{"description":"Saved (or already so).","content":{"application/json":{"example":{"outcome":"saved"},"schema":{"$ref":"#/components/schemas/ApiInvoiceSettingsSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the rule was switched by someone else since your read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/portal-commission":{"put":{"operationId":"setPortalCommission","summary":"Set the portal commission rate","description":"Requires property.read and property.configure, the grant the app asks of a person who sets up the Property; PostgreSQL holds it for a key as well. The app's Auswertung „Provisionssatz ändern“: the commission a booking portal would have taken of a direct booking, in basis points (15 % until changed, at most 50 %). getStayAnalytics computes the saved commission with it (`commissionBasisPoints`). The rate has no version: the last save stands. Announces the `settings.changed` webhook event with `area` `portal-commission`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiPortalCommissionSaveRequest"}}}},"responses":{"200":{"description":"Set (or already so).","content":{"application/json":{"example":{"outcome":"configured"},"schema":{"$ref":"#/components/schemas/ApiPortalCommissionSaved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/imports/dry-run":{"post":{"operationId":"checkImportFile","summary":"Check an import file","description":"Requires property.read and property.configure, as the app’s Import does; PostgreSQL holds it for a key as well. The app's „Datei prüfen“: the file (Keyset's import format as JSON or CSV, its text in `content`, at most 512 KiB) is read, every booking and block in it is judged against what the Property holds now, and the report is kept as a dry run. Nothing is booked or blocked. Answers the report as getImportBatch reads it, each row with its `recordId` for takeOverImport; the guest's name, contact and note in the file are kept for the app's report but never answered here (a row says only whether an e-mail address or phone number was there). A file that cannot be read as a whole answers `rejected` with the reasons and keeps nothing. The body is JSON (`content-type: application/json`) and at most 1.0625 MiB (IMPORT_TOO_LARGE); the file is never fetched from anywhere.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiImportDryRunRequest"}}}},"responses":{"200":{"description":"The report, or the reasons the file was refused.","content":{"application/json":{"example":{"outcome":"staged","asOf":"2026-11-10T12:00:00.000Z","batch":{"id":"00000009-0000-4000-8000-000000000001","createdAt":"2026-11-10T12:00:00.000Z","state":"dry_run","format":"keyset.import.v1+csv","sourceSystem":"buchungen.csv","sourceReference":"buchungen.csv","sourceDigest":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","summary":{"recordCount":1,"ready":1,"duplicate":0,"conflict":0,"unmapped":0,"invalid":0,"review":0,"ignored":0},"reconciliation":null},"records":[{"recordId":"00000011-0000-4000-8000-000000000001","row":1,"kind":"reservation","sourceId":"B-1001","unitReference":"Wohnung 1","unit":{"id":"30000000-0000-4000-8000-000000000001","name":"Apartment 1"},"stay":{"checkIn":"2026-12-04","checkOut":"2026-12-07","nights":3},"status":"confirmed","blockKind":null,"amount":{"minorUnits":"48600","currency":"EUR"},"confirmationCode":"ABC123","occupancy":{"adults":2,"children":1},"guestContactSupplied":{"email":true,"phone":false},"classification":"ready","findings":[],"commitOutcome":null,"businessObject":null,"committedAt":null,"laterState":null}]},"schema":{"$ref":"#/components/schemas/ApiImportDryRun"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"413":{"description":"IMPORT_TOO_LARGE: the body is larger than an import file of 512 KiB as JSON; nothing was kept.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/imports/{batchId}/commit":{"post":{"operationId":"takeOverImport","summary":"Take an import over","description":"Requires property.read, property.configure, reservation.create_manual and inventory.block: taking a file over creates confirmed bookings (the file’s guest name becomes the booking’s contact) and blocks, so a key needs the grants that create them directly as well; PostgreSQL holds all of them for a key (a person keeps the app’s rule). The app’s „Übernehmen“: the rows named in `approvedRecordIds` of the report whose `sourceDigest` is `approvedDigest` are taken over, each checked again against the inventory as it stands; a booking on nights taken since, or without an apartment, is created with a conflict for the host (never dropped). A row left out is not taken over; a real booking left out that clashes or names no apartment waits in Eingang. No guest is mailed. A batch is taken over once: the same approval again answers the first counts with `replayed` true; another approval answers IMPORT_APPROVAL_MISMATCH. A test key takes over only into the test business (ADR-040).","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The import batch, `batch.id` of the check."},"required":true,"description":"The import batch, `batch.id` of the check.","name":"batchId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiImportCommitRequest"}}}},"responses":{"200":{"description":"Taken over.","content":{"application/json":{"example":{"outcome":"committed","replayed":false,"reconciliation":{"imported":3,"idempotent":0,"conflicted":1,"skippedByDecision":1,"unresolved":0}},"schema":{"$ref":"#/components/schemas/ApiImportCommitted"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IMPORT_DIGEST_MISMATCH: the report is of another file; IMPORT_APPROVAL_MISMATCH: the batch was taken over with another approval; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid, or a row named is a duplicate, invalid or ignored row or not of this batch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/imports/{batchId}/remove":{"post":{"operationId":"removeImportCheck","summary":"Remove an import check","description":"Requires property.read and property.configure, as the app’s Import does; PostgreSQL holds it for a key as well. The app's „Probelauf entfernen“: a check that was never taken over is removed from the import list together with its rows (and the guest names they held). A batch that took anything over or holds a row waiting in Eingang answers IMPORT_NOT_REMOVABLE and stays.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The import batch, `batch.id` of the check."},"required":true,"description":"The import batch, `batch.id` of the check.","name":"batchId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"example":{"outcome":"removed"},"schema":{"$ref":"#/components/schemas/ApiImportDryRunRemoved"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IMPORT_NOT_REMOVABLE: the batch took something over or holds an open row; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/import-decisions/{decisionId}/dismiss":{"post":{"operationId":"dismissImportDecision","summary":"Let an open import row go","description":"Requires property.read and property.configure, as the app’s Import does; PostgreSQL holds it for a key as well. Eingang's „Nicht übernehmen“: a real booking a host left out of an import although it clashed or named no apartment waits in Eingang (`openDecisions` of listImportBatches) until it is taken over by a later import or let go here. Letting it go creates nothing and closes the row; a later import of the same booking is judged afresh. A row closed already answers `already_resolved`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"An open row, `openDecisions[].id` of listImportBatches."},"required":true,"description":"An open row, `openDecisions[].id` of listImportBatches.","name":"decisionId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Let go (or closed before).","content":{"application/json":{"example":{"outcome":"dismissed"},"schema":{"$ref":"#/components/schemas/ApiImportDecisionDismissed"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"List the webhook endpoints","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's Webhooks list: every endpoint of the Property (at most ten) with its address (scheme and host; the path and query, which can hold a token, masked), events, state, version and the last delivery. The signing secret is never shown, only its last four characters.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The endpoints, oldest first.","content":{"application/json":{"example":{"data":[{"id":"70000000-0000-4000-8000-000000000001","url":"https://hooks.example.com/…","host":"hooks.example.com","eventTypes":["reservation.cancelled","reservation.confirmed"],"description":"Hausverwaltung","secretHint":"k3Q=","state":"active","version":"1","createdAt":"2026-11-17T09:00:00.000Z","previousSecretUntil":null,"lastDelivery":{"state":"succeeded","at":"2026-11-17T09:05:00.000Z"},"failedLastDay":0}]},"schema":{"$ref":"#/components/schemas/ApiWebhookEndpointList"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"post":{"operationId":"createWebhookEndpoint","summary":"Add a webhook endpoint","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Webhook hinzufügen\": an https address on a public host (no user name or password, no fragment, at most 2000 characters; a private, loopback or internal address is refused) receives the chosen events, signed (Standard Webhooks). A key subscribes only to events whose data it may read itself: reservation.read for the booking, payment, refund and block events; guest.read for booking requests; reservation.read and guest.read for guest messages and invoices; nothing more for the rate, plan, discount code and task events; property.configure, which managing the endpoint asks already, for the apartment, booking site and settings events. A missing grant answers PERMISSION_DENIED, and PostgreSQL holds the rule too. An endpoint a key made stops receiving (its deliveries end `failed` with `key_inactive`) once that key is revoked or expired. At most ten endpoints per Property: WEBHOOK_LIMIT_REACHED. The answer carries the endpoint’s signing secret (`whsec_…`) this once: store it before anything else. A replay of the request answers the same endpoint with `secret` null; no read shows it again. The address comes back in full in this answer only; reads and a replay show it with its path and query masked.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookEndpointCreateRequest"}}}},"responses":{"201":{"description":"Added; the secret is in this answer only.","content":{"application/json":{"example":{"endpoint":{"id":"70000000-0000-4000-8000-000000000001","url":"https://hooks.example.com/keyset","host":"hooks.example.com","eventTypes":["reservation.cancelled","reservation.confirmed"],"description":"Hausverwaltung","secretHint":"k3Q=","state":"active","version":"1","createdAt":"2026-11-17T09:00:00.000Z","previousSecretUntil":null,"lastDelivery":{"state":"succeeded","at":"2026-11-17T09:05:00.000Z"},"failedLastDay":0},"secret":"whsec_ShownOnlyOnce"},"schema":{"$ref":"#/components/schemas/ApiWebhookSecretReveal"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"WEBHOOK_LIMIT_REACHED: the Property has ten endpoints; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"WEBHOOK_URL_INVALID: the address cannot receive webhooks (detail: invalid, not_https, private_host or too_long); INVALID_REQUEST: the body or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/webhook-endpoints/{endpointId}":{"get":{"operationId":"getWebhookEndpoint","summary":"Read a webhook endpoint","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. One endpoint as listWebhookEndpoints shows it, with the version updateWebhookEndpoint needs.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A webhook endpoint of the Property."},"required":true,"description":"A webhook endpoint of the Property.","name":"endpointId","in":"path"}],"responses":{"200":{"description":"The endpoint.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001","url":"https://hooks.example.com/…","host":"hooks.example.com","eventTypes":["reservation.cancelled","reservation.confirmed"],"description":"Hausverwaltung","secretHint":"k3Q=","state":"active","version":"1","createdAt":"2026-11-17T09:00:00.000Z","previousSecretUntil":null,"lastDelivery":{"state":"succeeded","at":"2026-11-17T09:05:00.000Z"},"failedLastDay":0},"schema":{"$ref":"#/components/schemas/ApiWebhookEndpoint"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"put":{"operationId":"updateWebhookEndpoint","summary":"Change or pause a webhook endpoint","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Bearbeiten\" and \"Pausieren\": the events, the description and whether it sends (`state`). The address stays; to change it, add a new endpoint and delete this one. Send `version` as `expectedVersion`; a stale one answers VERSION_CONFLICT. A key subscribes only to events whose data it may read itself: reservation.read for the booking, payment, refund and block events; guest.read for booking requests; reservation.read and guest.read for guest messages and invoices; nothing more for the rate, plan, discount code and task events; property.configure, which managing the endpoint asks already, for the apartment, booking site and settings events. A missing grant answers PERMISSION_DENIED, and PostgreSQL holds the rule too. An endpoint a key made stops receiving (its deliveries end `failed` with `key_inactive`) once that key is revoked or expired. Pausing needs no read grant. An event type added later reaches the endpoint only once it is added here. A key changes, rotates, deletes, test-sends to and resends to only an endpoint it made itself (with any of its credentials); an endpoint the host or another key made answers NOT_FOUND. A person keeps the app’s rule.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A webhook endpoint of the Property."},"required":true,"description":"A webhook endpoint of the Property.","name":"endpointId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookEndpointUpdateRequest"}}}},"responses":{"200":{"description":"Changed.","content":{"application/json":{"example":{"id":"70000000-0000-4000-8000-000000000001","url":"https://hooks.example.com/…","host":"hooks.example.com","eventTypes":["reservation.confirmed","unit.changed","booking_site.paused","settings.changed"],"description":"Kanal-Abgleich","secretHint":"k3Q=","state":"disabled","version":"2","createdAt":"2026-11-17T09:00:00.000Z","previousSecretUntil":null,"lastDelivery":{"state":"succeeded","at":"2026-11-17T09:05:00.000Z"},"failedLastDay":0},"schema":{"$ref":"#/components/schemas/ApiWebhookEndpoint"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"VERSION_CONFLICT: the endpoint changed since it was read; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Löschen\": the endpoint and its deliveries are gone; nothing more is sent to it. A key changes, rotates, deletes, test-sends to and resends to only an endpoint it made itself (with any of its credentials); an endpoint the host or another key made answers NOT_FOUND. A person keeps the app’s rule.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A webhook endpoint of the Property."},"required":true,"description":"A webhook endpoint of the Property.","name":"endpointId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"example":{"outcome":"deleted"},"schema":{"$ref":"#/components/schemas/ApiWebhookEndpointDeleted"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/webhook-endpoints/{endpointId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List an endpoint’s deliveries","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Zustellungen\", newest first, in pages: what was sent, whether it arrived, the receiver's last status and why it did not arrive. Metadata only: never the event's data, the receiver's answer or the secret. A key sees only the deliveries of events it may receive itself (see createWebhookEndpoint); the others are left out of its pages. Read an event's data with GET /v1/properties/{propertyId}/events or the read of its booking.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A webhook endpoint of the Property."},"required":true,"description":"A webhook endpoint of the Property.","name":"endpointId","in":"path"},{"schema":{"type":"string","pattern":"^c1\\.[A-Za-z0-9_-]{4,512}$","description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one."},"required":false,"description":"The `nextCursor` of the previous page, unchanged. Opaque; never build one.","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"One page of deliveries.","content":{"application/json":{"example":{"data":[{"id":"71000000-0000-4000-8000-000000000001","eventId":"evt_7a1c0d6e2f3b4a5c8d9e0f1a2b3c4d5e","type":"reservation.confirmed","state":"succeeded","attemptCount":1,"lastStatus":200,"lastError":null,"createdAt":"2026-11-17T09:05:00.000Z","lastAttemptAt":"2026-11-17T09:05:01.000Z","deliveredAt":"2026-11-17T09:05:01.000Z","nextAttemptAt":null,"resendOf":null,"reservationNumber":1042}],"hasMore":false,"nextCursor":null},"schema":{"$ref":"#/components/schemas/ApiWebhookDeliveryPage"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/webhook-endpoints/{endpointId}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","summary":"Renew the signing secret","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Secret erneuern\": a new signing secret; the one it replaces keeps signing beside it for 24 hours (`previousSecretUntil`), so a receiver can switch without losing a message. A key rotates only an endpoint whose every event it may receive itself. A key changes, rotates, deletes, test-sends to and resends to only an endpoint it made itself (with any of its credentials); an endpoint the host or another key made answers NOT_FOUND. A person keeps the app’s rule. The answer carries the endpoint’s signing secret (`whsec_…`) this once: store it before anything else. A replay of the request answers the same endpoint with `secret` null; no read shows it again.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A webhook endpoint of the Property."},"required":true,"description":"A webhook endpoint of the Property.","name":"endpointId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Renewed; the new secret is in this answer only.","content":{"application/json":{"example":{"endpoint":{"id":"70000000-0000-4000-8000-000000000001","url":"https://hooks.example.com/…","host":"hooks.example.com","eventTypes":["reservation.cancelled","reservation.confirmed"],"description":"Hausverwaltung","secretHint":"k3Q=","state":"active","version":"2","createdAt":"2026-11-17T09:00:00.000Z","previousSecretUntil":"2026-11-18T09:00:00.000Z","lastDelivery":{"state":"succeeded","at":"2026-11-17T09:05:00.000Z"},"failedLastDay":0},"secret":"whsec_ShownOnlyOnce"},"schema":{"$ref":"#/components/schemas/ApiWebhookSecretReveal"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/webhook-endpoints/{endpointId}/test":{"post":{"operationId":"sendWebhookTest","summary":"Send a test event","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Test senden\": a `webhook.test` event to this active endpoint, signed like every delivery, with no data of the Property. It makes Keyset call the address, so it counts against the lower budget of sensitive operations. A paused endpoint answers NOT_FOUND. A key changes, rotates, deletes, test-sends to and resends to only an endpoint it made itself (with any of its credentials); an endpoint the host or another key made answers NOT_FOUND. A person keeps the app’s rule. A test key sends from its test business only.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A webhook endpoint of the Property."},"required":true,"description":"A webhook endpoint of the Property.","name":"endpointId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"202":{"description":"Queued; listWebhookDeliveries shows how it went.","content":{"application/json":{"example":{"deliveryId":"71000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiWebhookDeliveryQueued"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/webhook-deliveries/{deliveryId}/resend":{"post":{"operationId":"resendWebhookDelivery","summary":"Send a delivery again","description":"Requires property.read and property.configure, the grant the app asks of a person who manages webhooks; PostgreSQL holds it for a key as well. The app's \"Erneut senden\": a new delivery of the same event to the same active endpoint, with the same `webhook-id`, so a receiver that has it already can drop it. A key resends only an event it may receive itself (see createWebhookEndpoint), and only to an endpoint it made itself; any other, or a delivery of a paused endpoint, answers NOT_FOUND. It makes Keyset call the address, so it counts against the lower budget of sensitive operations.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A delivery of one of the Property’s endpoints."},"required":true,"description":"A delivery of one of the Property’s endpoints.","name":"deliveryId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"example":{"deliveryId":"71000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiWebhookDeliveryQueued"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/test-twin":{"get":{"operationId":"getTestTwin","summary":"Read the test twin","description":"Requires property.read, the grant the app asks to show „Testbetrieb“; PostgreSQL holds it for a key as well. Whether this Property’s business is the live one or its test twin (ADR-040), whether a twin exists, what this key may do there and, in the twin, the cases armed for its next matching operation. A key belongs to one business, so the way across to the other side is not part of it. Creating the first twin stays in the app with an owner of the live business.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The twin as this key sees it.","content":{"application/json":{"example":{"mode":"test","twinExists":true,"canArm":true,"canReset":true,"armed":[{"kind":"payment_unknown","armedAt":"2026-11-17T09:00:00.000Z"}]},"schema":{"$ref":"#/components/schemas/ApiTestTwin"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/team":{"get":{"operationId":"getTeam","summary":"Read the team","description":"Requires property.read and property.configure; PostgreSQL holds it for a key as well. The app’s Team page as a member who does not manage the team sees it: each active person’s role, display name and Properties, narrowed to the Properties this key reads. No e-mail address, invitation, invitation link or sign-in identifier. Read only: inviting, changing a role or Properties, removing someone and handing the business over stay in the app with an owner.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"}],"responses":{"200":{"description":"The team on this key’s Properties.","content":{"application/json":{"example":{"properties":[{"id":"20000000-0000-4000-8000-000000000001","name":"Ferienwohnungen am Hafen"}],"members":[{"memberId":"50000000-0000-4000-8000-000000000001","role":"owner","name":"Martina","propertyIds":["20000000-0000-4000-8000-000000000001"]},{"memberId":"50000000-0000-4000-8000-000000000002","role":"staff","name":null,"propertyIds":["20000000-0000-4000-8000-000000000001"]}]},"schema":{"$ref":"#/components/schemas/ApiTeam"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks the grant this operation needs.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: a parameter or cursor is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: the read did not complete; it may be repeated.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/test-twin/scenarios":{"post":{"operationId":"armTestScenario","summary":"Arm a test case","description":"Requires property.read and property.configure on a Property of the test twin: a test key (`sk_test_`) of the twin, the grant the app asks as the owner or manager role of the twin; PostgreSQL holds it for a key as well. A key of the live business answers LIVE_KEY and changes nothing. The app's „Scharf stellen“: the case waits for the twin's next matching operation and is consumed by it once (a payment, a refund, the next webhook event's deliveries; a resend you ask for is not one). A case already armed answers `already_armed`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTestScenarioArmRequest"}}}},"responses":{"200":{"description":"Armed, or it was armed already.","content":{"application/json":{"example":{"outcome":"armed"},"schema":{"$ref":"#/components/schemas/ApiTestScenarioOutcome"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks property.configure; or LIVE_KEY: a key of the live business. The twin’s controls act in the twin only; use a key of the test business.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/test-twin/scenarios/{kind}":{"delete":{"operationId":"withdrawTestScenario","summary":"Withdraw an armed test case","description":"Requires property.read and property.configure on a Property of the test twin: a test key (`sk_test_`) of the twin, the grant the app asks as the owner or manager role of the twin; PostgreSQL holds it for a key as well. A key of the live business answers LIVE_KEY and changes nothing. The app's „Zurücknehmen“: the armed case of this kind is withdrawn before anything consumed it; none armed answers `not_armed`.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"$ref":"#/components/schemas/ApiTestScenarioKind"},"required":true,"description":"`payment_unknown`: the next payment’s answer is lost and stays unknown until reconciliation; `refund_failed`: the next refund is refused by the provider; `webhook_failure`: the next event’s deliveries are answered 500 on their first three attempts.","name":"kind","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Withdrawn, or none was armed.","content":{"application/json":{"example":{"outcome":"withdrawn"},"schema":{"$ref":"#/components/schemas/ApiTestScenarioOutcome"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks property.configure; or LIVE_KEY: a key of the live business. The twin’s controls act in the twin only; use a key of the test business.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/test-twin/conflict":{"post":{"operationId":"createTestConflict","summary":"Make a booking from outside on the next booking","description":"Requires property.read and property.configure on a Property of the test twin: a test key (`sk_test_`) of the twin, the grant the app asks as the owner or manager role of the twin; PostgreSQL holds it for a key as well. A key of the live business answers LIVE_KEY and changes nothing. The app's „Überbuchung von außen“: a confirmed booking from an imported calendar lands on the dates of this test Property's next booking, with the conflict case and attention item a calendar import writes when its dates are taken, so the case can be worked as a real one. Without a booking ahead it answers TEST_CONFLICT_NO_BOOKING.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"201":{"description":"The booking from outside and its open conflict case were made.","content":{"application/json":{"example":{"outcome":"created","reservationId":"40000000-0000-4000-8000-000000000001"},"schema":{"$ref":"#/components/schemas/ApiTestConflictCreated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks property.configure; or LIVE_KEY: a key of the live business. The twin’s controls act in the twin only; use a key of the test business.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"TEST_CONFLICT_NO_BOOKING: this Property holds no booking ahead; or IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/test-twin/reset":{"post":{"operationId":"resetTestTwin","summary":"Reset the test twin","description":"Requires property.read and property.configure on a Property of the test twin: a test key (`sk_test_`) of the twin, the grant the app asks as the owner or manager role of the twin; PostgreSQL holds it for a key as well. A key of the live business answers LIVE_KEY and changes nothing. The app's „Testbetrieb zurücksetzen“, which the app leaves to an owner of the live business: a key may reset only while the person who created it is still an active owner of the live business (PERMISSION_DENIED otherwise). The twin is retired for good — out of every list, its booking page closed, every key of it stopped with it, this one included — and a fresh copy of the live business's configuration is made, without bookings, guests, keys or webhooks. The live business is only read. No key reaches the new twin: issue a test key there in the app. It copies a whole business, so it counts against the lower budget of sensitive operations.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Retired and copied afresh.","content":{"application/json":{"example":{"outcome":"created","propertyId":"20000000-0000-4000-8000-000000000002","reachableByThisKey":false},"schema":{"$ref":"#/components/schemas/ApiTestTwinReset"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key reads this Property but lacks property.configure; or LIVE_KEY: a key of the live business. The twin’s controls act in the twin only; use a key of the test business.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body, a parameter or the header is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}},"/v1/properties/{propertyId}/further-properties":{"post":{"operationId":"createFurtherProperty","summary":"Create a further Property in this business","description":"Requires property.read and property.configure on this Property, and the person who created the key must be allowed to create a Property in the business now (an active owner or manager, the app’s rule); PERMISSION_DENIED otherwise. PostgreSQL holds both. The app’s „Unterkunft hinzufügen“: a Property with its draft booking site in the same business, created as that person creates it in the app — they get every right on it, every owner and manager their role’s. This key gets nothing: a key never widens its own reach, so it cannot reach the new Property (`reachableByThisKey` false); issue a key for it in the app. A test key’s business is its test twin, so it creates there. The subscription is unchanged: it counts bookable apartments, and the new Property has none. Counts against the lower budget of sensitive operations.","tags":["Operator API"],"security":[{"SecretApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A Property this key was issued for."},"required":true,"description":"A Property this key was issued for.","name":"propertyId","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$","description":"16–128 URL-safe characters, one per intent; repeat it only for the same request."},"required":true,"description":"16–128 URL-safe characters, one per intent; repeat it only for the same request.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFurtherPropertyRequest"}}}},"responses":{"201":{"description":"Created; this key cannot reach it.","content":{"application/json":{"example":{"propertyId":"20000000-0000-4000-8000-000000000002","name":"Ferienhaus am See","reachableByThisKey":false,"subscriptionChanged":false},"schema":{"$ref":"#/components/schemas/ApiFurtherPropertyCreated"}}}},"401":{"description":"AUTHENTICATION_REQUIRED: missing, invalid, revoked, expired or wrong-environment secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"403":{"description":"PERMISSION_DENIED: the key lacks property.configure, or the person who created it may no longer create a Property in this business.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"404":{"description":"NOT_FOUND: unknown, or outside this key’s Properties; the answer does not tell them apart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), IDEMPOTENCY_IN_PROGRESS (retryable) or IDEMPOTENCY_OUTCOME_UNKNOWN (read before acting).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"422":{"description":"INVALID_REQUEST: the body or the header is invalid, or the time zone, currency or language is not usable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"429":{"description":"TOO_MANY_REQUESTS: a request budget of the key or the Property is spent; wait, then repeat.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}},"500":{"description":"INTERNAL_ERROR: no known outcome. Repeat the identical request with the identical idempotency key, or read first.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/DeveloperProblem"}}}}}}}},"webhooks":{}}