ArohaDevelopers

API reference · v1

A versioned, scoped API.

Resource routes for the current booking domain. Every mutation passes through the same policy and transaction layer as the website.

Download OpenAPI 3.1
Source contract, not a deployment claim.

This reference lists implemented source routes. The broader 96-operation strategy includes future CMS/access facade, payment, erasure and feedback features that are not exposed here.

Authentication and errors

Send the scoped token in the Authorization header. Errors return a bounded code and request ID. 401 means missing/invalid credentials; 403 means insufficient scope or current permission; 404 also protects another user's resource. 409 indicates a business conflict, 412 a stale version, 428 a missing precondition and 429 a rate limit.

Explore operations

39 operations

GET/runtime

getRuntime

Required scope: runtime:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/availability

getAvailability

Required scope: availability:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/calendar

getCalendar

Required scope: calendar:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/reservations

listReservations

Required scope: reservations:read
Policy: live token, ownership, staff capabilities and shared domain checks.
POST/reservations

createReservation

Required scope: reservations:create
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "quoteId": {
      "type": "string",
      "maxLength": 100
    },
    "note": {
      "type": "string",
      "maxLength": 1000
    },
    "contact": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "phone"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 120
        },
        "phone": {
          "type": "string",
          "maxLength": 32
        }
      }
    }
  },
  "required": [
    "quoteId"
  ]
}
GET/reservations/{id}

getReservation

Required scope: reservations:read
Policy: live token, ownership, staff capabilities and shared domain checks.
DELETE/reservations/{id}

cancelReservation

Required scope: reservations:cancel
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "reason"
  ]
}
GET/units

list_units

Required scope: inventory:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/units/{id}

get_units

Required scope: inventory:read
Policy: live token, ownership, staff capabilities and shared domain checks.
PATCH/units/{id}

updateUnit

Required scope: inventory:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "capacity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "rate": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 10000,
      "maximum": 100000000
    },
    "active": {
      "type": "boolean"
    },
    "name": {
      "type": "string",
      "maxLength": 120
    },
    "verified": {
      "type": "boolean"
    }
  },
  "required": [
    "capacity",
    "rate",
    "active"
  ]
}
GET/content/published

getPublishedContent

Required scope: content:published:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/reservations/{id}/communications

listCommunications

Required scope: communications:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/me/profile

getMyProfile

Required scope: profiles:read
Policy: live token, ownership, staff capabilities and shared domain checks.
POST/me/profile

createMyProfile

Required scope: profiles:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "phone"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 120
    },
    "phone": {
      "type": "string",
      "maxLength": 32
    }
  }
}
PATCH/me/profile

updateMyProfile

Required scope: profiles:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "phone"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 120
    },
    "phone": {
      "type": "string",
      "maxLength": 32
    }
  }
}
GET/reservations/{id}/contact

getReservationContact

Required scope: contacts:read
Policy: live token, ownership, staff capabilities and shared domain checks.
GET/settings

getSettings

Required scope: settings:read
Policy: live token, ownership, staff capabilities and shared domain checks.
PATCH/settings

updateSettings

Required scope: settings:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "capacity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "approvalHours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 72
    },
    "cancelHours": {
      "type": "integer",
      "minimum": 0,
      "maximum": 336
    },
    "friendAt": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "familyAt": {
      "type": "integer",
      "minimum": 2,
      "maximum": 200
    },
    "friendDiscount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 50
    },
    "familyDiscount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 50
    },
    "paused": {
      "type": "boolean"
    },
    "products": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "dayAdultRate": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000
        },
        "dayChildRate": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000
        },
        "individualRate": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000
        },
        "roomRate": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000
        },
        "extraChildRate": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000
        },
        "siteAdults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "nightAdults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "dayStart": {
          "type": "string",
          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
        },
        "dayEnd": {
          "type": "string",
          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
        },
        "stayStart": {
          "type": "string",
          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
        },
        "stayEnd": {
          "type": "string",
          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
        },
        "eventDayRate": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000
        }
      }
    }
  },
  "required": [
    "capacity",
    "approvalHours",
    "cancelHours",
    "friendAt",
    "familyAt",
    "friendDiscount",
    "familyDiscount",
    "paused"
  ]
}
GET/blocks

listBlocks

Required scope: inventory:read
Policy: live token, ownership, staff capabilities and shared domain checks.
POST/blocks

createBlock

Required scope: inventory:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "arrival": {
      "type": "string",
      "format": "date"
    },
    "departure": {
      "type": "string",
      "format": "date"
    },
    "unitId": {
      "type": "string",
      "maxLength": 100
    },
    "reason": {
      "type": "string",
      "maxLength": 120
    }
  },
  "required": [
    "arrival",
    "departure",
    "unitId",
    "reason"
  ]
}
GET/promotions

listPromotions

Required scope: promotions:read
Policy: live token, ownership, staff capabilities and shared domain checks.
POST/promotions

createPromotion

Required scope: promotions:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4,24}$"
    },
    "kind": {
      "type": "string",
      "enum": [
        "percent",
        "fixed"
      ]
    },
    "value": {
      "type": "integer",
      "minimum": 1
    },
    "maxUses": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "from": {
      "type": "string",
      "format": "date"
    },
    "until": {
      "type": "string",
      "format": "date"
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": [
    "code"
  ]
}
POST/quotes

createQuote

Required scope: quotes:create
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "arrival": {
      "type": "string",
      "format": "date"
    },
    "departure": {
      "type": "string",
      "format": "date"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "units": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      },
      "minItems": 0,
      "maxItems": 9,
      "uniqueItems": true
    },
    "promo": {
      "type": "string",
      "maxLength": 32
    },
    "guestId": {
      "type": "string",
      "maxLength": 128
    },
    "kind": {
      "type": "string",
      "enum": [
        "day",
        "individual",
        "private",
        "event"
      ]
    },
    "adults": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "childrenAges": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9
      }
    }
  },
  "required": [
    "arrival",
    "departure",
    "units"
  ]
}
POST/reservations/{id}/actions/approve

approveReservation

Required scope: reservations:approve
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/actions/decline

declineReservation

Required scope: reservations:approve
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/actions/checkin

checkInReservation

Required scope: stays:operate
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/actions/complete

completeReservation

Required scope: stays:operate
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/actions/no-show

noShowReservation

Required scope: stays:operate
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/actions/assign-rooms

assignRooms

Required scope: inventory:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "units": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      },
      "minItems": 1,
      "maxItems": 9,
      "uniqueItems": true
    }
  },
  "required": []
}
POST/reservations/{id}/actions/offer-event

offerEvent

Required scope: reservations:approve
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "amount": {
      "type": "integer",
      "minimum": 10000,
      "maximum": 100000000
    },
    "holdHours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 72
    }
  },
  "required": []
}
POST/reservations/{id}/actions/accept-event

acceptEvent

Required scope: reservations:change
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/change-quotes

createChangeQuote

Required scope: reservations:change
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "arrival": {
      "type": "string",
      "format": "date"
    },
    "departure": {
      "type": "string",
      "format": "date"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "promo": {
      "type": "string",
      "maxLength": 32
    },
    "kind": {
      "type": "string",
      "enum": [
        "day",
        "individual",
        "private",
        "event"
      ]
    },
    "adults": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "childrenAges": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9
      }
    }
  },
  "required": [
    "arrival",
    "departure"
  ]
}
POST/reservations/{id}/changes

requestChange

Required scope: reservations:change
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "quoteId": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "quoteId"
  ]
}
POST/reservations/{id}/changes/actions/approve

approveChange

Required scope: reservations:approve
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/changes/actions/decline

declineChange

Required scope: reservations:approve
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}
POST/reservations/{id}/notes

addNote

Required scope: notes:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "note": {
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "note"
  ]
}
POST/units/{id}/actions/readiness

updateReadiness

Required scope: inventory:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "ready"
  ],
  "properties": {
    "ready": {
      "type": "boolean"
    }
  }
}
PATCH/promotions/{id}

updatePromotion

Required scope: promotions:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4,24}$"
    },
    "kind": {
      "type": "string",
      "enum": [
        "percent",
        "fixed"
      ]
    },
    "value": {
      "type": "integer",
      "minimum": 1
    },
    "maxUses": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "from": {
      "type": "string",
      "format": "date"
    },
    "until": {
      "type": "string",
      "format": "date"
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": [
    "code"
  ]
}
DELETE/blocks/{id}

releaseBlock

Required scope: inventory:write
Policy: live token, ownership, staff capabilities and shared domain checks.
Request schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}

CRUD follows the resource lifecycle

Cancel reservations, reverse recorded payments when that feature ships, retire inventory and revoke grants. There is no raw database-delete API for booking history, issued documents or audit. New room creation/retirement, contact/note editing, external CMS/access management and financial/feedback features remain planned shared-domain work.