ATA Travel Buildings API

openapi: 3.2.0
info:
  title: ATA Travel Public Discovery Buildings 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: Buildings
  description: Read published building and complex profiles.
paths:
  /public/stays/buildings:
    get:
      operationId: listPublicBuildings
      summary: List published buildings
      description: Returns published ATA building and complex profiles with their public property counts.
      tags:
      - Buildings
      parameters:
      - name: q
        in: query
        required: false
        description: Building, neighborhood, city, state, country, or description search.
        schema:
          type: string
      - name: city
        in: query
        required: false
        description: City search term.
        schema:
          type: string
      responses:
        '200':
          description: Published buildings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BuildingSummary'
        '429':
          description: Search rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Buildings could not be loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/stays/buildings/{slug}:
    get:
      operationId: getPublicBuilding
      summary: Get a published building
      description: Returns a published building profile and its current ATA stays.
      tags:
      - Buildings
      parameters:
      - name: slug
        in: path
        required: true
        description: Published building slug.
        schema:
          type: string
      responses:
        '200':
          description: Building profile and stays.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildingStayResponse'
        '404':
          description: Building not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Building details 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:
      - Buildings
      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'
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
    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
    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
externalDocs:
  description: ATA developer documentation
  url: https://atatravel.cloud/developers