ATA Travel Properties API

openapi: 3.2.0
info:
  title: ATA Travel Public Discovery Properties API
  version: 1.0.0
  description: Read-only public endpoints for discovering ATA stays, buildings, property details, availability, and published pricing context. For agent-native workflows, quotes, traveler approval, and booking actions, use the MCP endpoint documented at https://atatravel.cloud/developers.
  contact:
    name: ATA developer support
    email: support@atatravel.cloud
    url: https://atatravel.cloud/contact
  license:
    name: Proprietary
servers:
- url: https://api.atatravel.cloud
  description: ATA Travel production API
tags:
- name: Properties
  description: Read published property details and indicative availability.
paths:
  /public/stays/properties:
    get:
      operationId: listPublicProperties
      summary: List public ATA properties
      description: Returns ATA-enabled properties, optionally filtered by text, city, building, token, or stay dates.
      tags:
      - Properties
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text search across traveler-facing property fields.
        schema:
          type: string
      - name: city
        in: query
        required: false
        description: City search term.
        schema:
          type: string
      - name: building
        in: query
        required: false
        description: Published building slug.
        schema:
          type: string
      - name: propertyToken
        in: query
        required: false
        description: Exact public property token.
        schema:
          type: string
      - name: checkIn
        in: query
        required: false
        description: Optional check-in date. Use together with checkOut.
        schema:
          type: string
          format: date
      - name: checkOut
        in: query
        required: false
        description: Optional check-out date. Use together with checkIn.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Matching public properties.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PropertySummary'
        '429':
          description: Search rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Properties could not be loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/stays/buildings/{slug}/stays:
    get:
      operationId: listPublicBuildingStays
      summary: List stays in a published building
      description: Returns the building summary and its ATA stays, optionally filtered by availability dates.
      tags:
      - Properties
      parameters:
      - name: slug
        in: path
        required: true
        description: Published building slug.
        schema:
          type: string
      - name: checkIn
        in: query
        required: false
        description: Optional check-in date. Use together with checkOut.
        schema:
          type: string
          format: date
      - name: checkOut
        in: query
        required: false
        description: Optional check-out date. Use together with checkIn.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Building summary and matching stays.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildingStayResponse'
        '404':
          description: Building not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Search rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Building stays could not be loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/stays/properties/{publicToken}:
    get:
      operationId: getPublicProperty
      summary: Get public property details
      description: Returns published property, room, rate-plan, amenity, policy, media, and direct-booking details.
      tags:
      - Properties
      parameters:
      - name: publicToken
        in: path
        required: true
        description: ATA public property token.
        schema:
          type: string
      responses:
        '200':
          description: Published property details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyDetail'
        '404':
          description: Property not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Property details could not be loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/stays/properties/{publicToken}/calendar:
    get:
      operationId: getPublicPropertyCalendar
      summary: Get indicative property availability
      description: Returns an indicative availability and from-rate calendar. A roomId optionally narrows the response to one room.
      tags:
      - Properties
      parameters:
      - name: publicToken
        in: path
        required: true
        description: ATA public property token.
        schema:
          type: string
      - name: start
        in: query
        required: false
        description: First calendar date. Defaults to the property-local current date.
        schema:
          type: string
          format: date
      - name: days
        in: query
        required: false
        description: Number of calendar days.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 42
      - name: adults
        in: query
        required: false
        description: Number of adult guests.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 2
      - name: children
        in: query
        required: false
        description: Number of child guests.
        schema:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
      - name: roomId
        in: query
        required: false
        description: Optional room identifier.
        schema:
          type: string
      - name: ratePlanId
        in: query
        required: false
        description: Optional rate-plan identifier.
        schema:
          type: string
      responses:
        '200':
          description: Indicative availability calendar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityCalendar'
        '400':
          description: Invalid date or query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Property or room not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Search rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Availability could not be loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Traveler- or developer-readable error message.
        code:
          type: string
          description: Stable error code when available.
      additionalProperties: true
    BuildingStayResponse:
      type: object
      required:
      - building
      - stays
      properties:
        building:
          $ref: '#/components/schemas/BuildingSummary'
        stays:
          type: array
          items:
            $ref: '#/components/schemas/PropertySummary'
    Image:
      oneOf:
      - type: string
        format: uri
      - type: object
        properties:
          url:
            type: string
            format: uri
          alt:
            type:
            - string
            - 'null'
        additionalProperties: true
    AvailabilityCalendar:
      type: object
      required:
      - publicToken
      - scope
      - start
      - days
      - adults
      - children
      - dates
      properties:
        publicToken:
          type: string
        scope:
          type: string
          enum:
          - property
          - room
        roomId:
          type:
          - string
          - 'null'
        start:
          type: string
          format: date
        days:
          type: integer
          minimum: 1
          maximum: 100
        adults:
          type: integer
          minimum: 1
        children:
          type: integer
          minimum: 0
        dates:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityDay'
    PropertySummary:
      type: object
      required:
      - id
      - publicToken
      - name
      - currency
      - images
      - roomsAvailable
      properties:
        id:
          type: string
          format: uuid
        publicToken:
          type: string
        publicSlug:
          type:
          - string
          - 'null'
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        currency:
          type: string
          minLength: 3
          maxLength: 3
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        minNightlyPrice:
          type:
          - number
          - 'null'
          minimum: 0
        roomsAvailable:
          type: integer
          minimum: 0
        maxGuests:
          type: integer
          minimum: 0
        publicUrl:
          type: string
          format: uri
        building:
          oneOf:
          - $ref: '#/components/schemas/BuildingSummary'
          - type: 'null'
      additionalProperties: true
    PropertyDetail:
      type: object
      required:
      - id
      - publicToken
      - name
      - currency
      - images
      - verified
      - rooms
      properties:
        id:
          type: string
          format: uuid
        publicToken:
          type: string
        publicSlug:
          type:
          - string
          - 'null'
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        address:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        zipCode:
          type:
          - string
          - 'null'
        currency:
          type: string
          minLength: 3
          maxLength: 3
        timezone:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        building:
          oneOf:
          - $ref: '#/components/schemas/BuildingSummary'
          - type: 'null'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        amenities:
          type: array
          items:
            type: string
        importantInformation:
          type:
          - string
          - 'null'
        verified:
          type: boolean
        rooms:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    BuildingSummary:
      type: object
      required:
      - id
      - slug
      - name
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        shortDescription:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        neighborhood:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        propertyCount:
          type: integer
          minimum: 0
      additionalProperties: true
    AvailabilityDay:
      type: object
      required:
      - date
      - available
      - availableUnits
      - currency
      properties:
        date:
          type: string
          format: date
        available:
          type: boolean
        availableUnits:
          type: integer
          minimum: 0
        totalUnits:
          type: integer
          minimum: 0
        roomId:
          type:
          - string
          - 'null'
        ratePlanId:
          type:
          - string
          - 'null'
        price:
          type:
          - number
          - 'null'
          minimum: 0
        currency:
          type: string
          minLength: 3
          maxLength: 3
        minStay:
          type:
          - integer
          - 'null'
          minimum: 1
        maxStay:
          type:
          - integer
          - 'null'
          minimum: 1
        closedToArrival:
          type: boolean
        closedToDeparture:
          type: boolean
        stopSell:
          type: boolean
externalDocs:
  description: ATA developer documentation
  url: https://atatravel.cloud/developers