surfingdog-ai Stays API

openapi: 3.2.0
info:
  title: Surfing Dog Inbox Stays API
  description: Typed inbox for people and AI agents. Public routes need no auth; /v1/owner needs an owner API key.
  version: 0.2.0
tags:
- name: stays
paths:
  /v1/property:
    get:
      operationId: getV1Property
      tags:
      - stays
      summary: The place to stay
      responses: {}
  /v1/stays/availability:
    get:
      operationId: getV1StaysAvailability
      tags:
      - stays
      summary: What is free for dates and guests
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
      parameters:
      - in: query
        name: property_id
        schema:
          type: string
          minLength: 1
          maxLength: 64
      - in: query
        name: check_in
        schema:
          type: string
          format: date
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
        required: true
        description: Arrival date, the property's own, YYYY-MM-DD.
      - in: query
        name: check_out
        schema:
          type: string
          format: date
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
        required: true
        description: Departure date, after check_in.
      - in: query
        name: adults
        schema:
          default: 2
          type: integer
          minimum: 1
          maximum: 20
      - in: query
        name: children_ages
        schema:
          default: []
          maxItems: 10
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 17
      - in: query
        name: rooms
        schema:
          default: 1
          type: integer
          minimum: 1
          maximum: 9
        description: How many rooms, the guests shared between them.
      - in: query
        name: room_type_id
        schema:
          type: string
          minLength: 1
          maxLength: 64
  /v1/stays/quotes:
    post:
      operationId: postV1StaysQuotes
      tags:
      - stays
      summary: 'Price a stay: an offer when it confirms at once, else the estimate'
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                property_id:
                  type: string
                  minLength: 1
                  maxLength: 64
                check_in:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Arrival date, the property's own, YYYY-MM-DD.
                check_out:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Departure date, after check_in.
                rooms:
                  minItems: 1
                  maxItems: 9
                  type: array
                  items:
                    type: object
                    properties:
                      room_type_id:
                        description: A room type from get_property; any room for these guests when left out.
                        type: string
                        minLength: 1
                        maxLength: 64
                      rate_plan_id:
                        type: string
                        minLength: 1
                        maxLength: 64
                      adults:
                        type: integer
                        minimum: 1
                        maximum: 20
                      children_ages:
                        default: []
                        description: Each child's age on arrival.
                        maxItems: 10
                        type: array
                        items:
                          type: integer
                          minimum: 0
                          maximum: 17
                      extras:
                        default: []
                        maxItems: 10
                        type: array
                        items:
                          type: object
                          properties:
                            extra_id:
                              type: string
                              minLength: 1
                              maxLength: 64
                            quantity:
                              type: integer
                              minimum: 1
                              maximum: 20
                          required:
                          - extra_id
                          - quantity
                    required:
                    - adults
                offer_id:
                  description: 'An offer you were given before: the answer says if its totals changed.'
                  type: string
                  maxLength: 120
              required:
              - check_in
              - check_out
              - rooms
  /v1/stays:
    post:
      operationId: postV1Stays
      tags:
      - stays
      summary: Request a stay
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                property_id:
                  type: string
                  minLength: 1
                  maxLength: 64
                check_in:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Arrival date, the property's own, YYYY-MM-DD.
                check_out:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Departure date, after check_in.
                rooms:
                  minItems: 1
                  maxItems: 9
                  type: array
                  items:
                    type: object
                    properties:
                      room_type_id:
                        description: A room type from get_property; any room for these guests when left out.
                        type: string
                        minLength: 1
                        maxLength: 64
                      rate_plan_id:
                        type: string
                        minLength: 1
                        maxLength: 64
                      adults:
                        type: integer
                        minimum: 1
                        maximum: 20
                      children_ages:
                        default: []
                        description: Each child's age on arrival.
                        maxItems: 10
                        type: array
                        items:
                          type: integer
                          minimum: 0
                          maximum: 17
                      extras:
                        default: []
                        maxItems: 10
                        type: array
                        items:
                          type: object
                          properties:
                            extra_id:
                              type: string
                              minLength: 1
                              maxLength: 64
                            quantity:
                              type: integer
                              minimum: 1
                              maximum: 20
                          required:
                          - extra_id
                          - quantity
                    required:
                    - adults
                guests:
                  type: object
                  properties:
                    lead:
                      type: object
                      properties:
                        name:
                          type: string
                          minLength: 1
                          maxLength: 200
                      required:
                      - name
                    others:
                      default: []
                      maxItems: 40
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            maxLength: 200
                        required:
                        - name
                  required:
                  - lead
                arrival:
                  description: When the guests expect to arrive.
                  type: object
                  properties:
                    from:
                      type: string
                      pattern: ^([01]\d|2[0-3]):[0-5]\d$
                    to:
                      type: string
                      pattern: ^([01]\d|2[0-3]):[0-5]\d$
                  required:
                  - from
                  - to
                requests:
                  description: Special requests, in the guest's words.
                  type: string
                  maxLength: 2000
                contact:
                  type: object
                  properties:
                    name:
                      type: string
                      maxLength: 200
                    email:
                      type: string
                      format: email
                      pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                    phone:
                      type: string
                      maxLength: 40
                    locale:
                      type: string
                      maxLength: 12
                  description: How the property reaches the guest.
                consent:
                  type: boolean
                  const: true
                  description: The guest agreed that their request, with these details, goes to the property.
                message:
                  type: string
                  maxLength: 20000
                idempotency_key:
                  description: Same key + same request = same answer.
                  type: string
                  minLength: 1
                  maxLength: 200
                pass:
                  type: string
                  maxLength: 1608
                key:
                  type: string
                  maxLength: 200
              required:
              - check_in
              - check_out
              - rooms
              - contact
              - consent
  /v1/stays/holds:
    post:
      operationId: postV1StaysHolds
      tags:
      - stays
      summary: Hold an instant room
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                property_id:
                  type: string
                  minLength: 1
                  maxLength: 64
                check_in:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Arrival date, the property's own, YYYY-MM-DD.
                check_out:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Departure date, after check_in.
                rooms:
                  minItems: 1
                  maxItems: 9
                  type: array
                  items:
                    type: object
                    properties:
                      room_type_id:
                        description: A room type from get_property; any room for these guests when left out.
                        type: string
                        minLength: 1
                        maxLength: 64
                      rate_plan_id:
                        type: string
                        minLength: 1
                        maxLength: 64
                      adults:
                        type: integer
                        minimum: 1
                        maximum: 20
                      children_ages:
                        default: []
                        description: Each child's age on arrival.
                        maxItems: 10
                        type: array
                        items:
                          type: integer
                          minimum: 0
                          maximum: 17
                      extras:
                        default: []
                        maxItems: 10
                        type: array
                        items:
                          type: object
                          properties:
                            extra_id:
                              type: string
                              minLength: 1
                              maxLength: 64
                            quantity:
                              type: integer
                              minimum: 1
                              maximum: 20
                          required:
                          - extra_id
                          - quantity
                    required:
                    - adults
                guests:
                  type: object
                  properties:
                    lead:
                      type: object
                      properties:
                        name:
                          type: string
                          minLength: 1
                          maxLength: 200
                      required:
                      - name
                    others:
                      default: []
                      maxItems: 40
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            maxLength: 200
                        required:
                        - name
                  required:
                  - lead
                arrival:
                  description: When the guests expect to arrive.
                  type: object
                  properties:
                    from:
                      type: string
                      pattern: ^([01]\d|2[0-3]):[0-5]\d$
                    to:
                      type: string
                      pattern: ^([01]\d|2[0-3]):[0-5]\d$
                  required:
                  - from
                  - to
                requests:
                  description: Special requests, in the guest's words.
                  type: string
                  maxLength: 2000
                contact:
                  type: object
                  properties:
                    name:
                      type: string
                      maxLength: 200
                    email:
                      type: string
                      format: email
                      pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                    phone:
                      type: string
                      maxLength: 40
                    locale:
                      type: string
                      maxLength: 12
                  description: How the property reaches the guest.
                consent:
                  type: boolean
                  const: true
                  description: The guest agreed that their request, with these details, goes to the property.
                message:
                  type: string
                  maxLength: 20000
                idempotency_key:
                  description: Same key + same request = same answer.
                  type: string
                  minLength: 1
                  maxLength: 200
                pass:
                  type: string
                  maxLength: 1608
                key:
                  type: string
                  maxLength: 200
                offer_id:
                  description: The offer from check_stay_availability or quote_stay.
                  type: string
                  maxLength: 120
              required:
              - check_in
              - check_out
              - rooms
              - contact
              - consent
  /v1/stays/book:
    post:
      operationId: postV1StaysBook
      tags:
      - stays
      summary: Book a held stay on the terms your person confirmed
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                item_id:
                  type: string
                  minLength: 1
                  description: The held stay, from hold_stay.
                terms_sha:
                  description: The fingerprint of the terms your person said yes to; without it, the answer gives the terms.
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43}$
                access_token:
                  type: string
                  minLength: 16
                  maxLength: 200
                idempotency_key:
                  description: Same key + same request = same answer.
                  type: string
                  minLength: 1
                  maxLength: 200
                pass:
                  type: string
                  maxLength: 1608
                key:
                  type: string
                  maxLength: 200
              required:
              - item_id
  /v1/stays/{id}/change:
    post:
      operationId: postV1StaysByIdChange
      tags:
      - stays
      summary: Ask to change a confirmed stay
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                check_in:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Arrival date, the property's own, YYYY-MM-DD.
                check_out:
                  type: string
                  format: date
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                  description: Departure date, after check_in.
                rooms:
                  minItems: 1
                  maxItems: 9
                  type: array
                  items:
                    type: object
                    properties:
                      room_type_id:
                        description: A room type from get_property; any room for these guests when left out.
                        type: string
                        minLength: 1
                        maxLength: 64
                      rate_plan_id:
                        type: string
                        minLength: 1
                        maxLength: 64
                      adults:
                        type: integer
                        minimum: 1
                        maximum: 20
                      children_ages:
                        default: []
                        description: Each child's age on arrival.
                        maxItems: 10
                        type: array
                        items:
                          type: integer
                          minimum: 0
                          maximum: 17
                      extras:
                        default: []
                        maxItems: 10
                        type: array
                        items:
                          type: object
                          properties:
                            extra_id:
                              type: string
                              minLength: 1
                              maxLength: 64
                            quantity:
                              type: integer
                              minimum: 1
                              maximum: 20
                          required:
                          - extra_id
                          - quantity
                    required:
                    - adults
                terms_sha:
                  description: The fingerprint of the new terms your person saw; without it, the answer gives them first.
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43}$
                note:
                  type: string
                  maxLength: 2000
                access_token:
                  type: string
                  minLength: 16
                  maxLength: 200
                idempotency_key:
                  description: Same key + same request = same answer.
                  type: string
                  minLength: 1
                  maxLength: 200
                pass:
                  type: string
                  maxLength: 1608
                key:
                  type: string
                  maxLength: 200
              required:
              - check_in
              - check_out
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
components:
  securitySchemes:
    ownerKey:
      type: http
      scheme: bearer
      description: An owner or integration key (sdi_own_…), an OAuth access token from /oauth, or the owner app's session.