ATA Travel Discovery API

openapi: 3.2.0
info:
  title: ATA Travel Public Discovery 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: Discovery
  description: Search ATA public inventory and discovery facets.
paths:
  /public/stays/discovery-context:
    get:
      operationId: getPublicDiscoveryContext
      summary: Get live discovery facets
      description: Returns a compact summary of destinations, stay types, capacity, amenities, views, and suitability guidance currently available on ATA.
      tags:
      - Discovery
      responses:
        '200':
          description: Current public discovery context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryContext'
        '429':
          description: Search rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The discovery context could not be generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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:
      - Discovery
      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/discover:
    get:
      operationId: discoverPublicStays
      summary: Discover map-ready ATA stays
      description: Returns property results, building-aware map markers, and result metadata for public discovery experiences.
      tags:
      - Discovery
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text property, location, or building search.
        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: Map-ready stay discovery results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryResponse'
        '429':
          description: Search rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Discovery results 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
    CountedValue:
      type: object
      required:
      - value
      - count
      properties:
        value:
          type: string
        count:
          type: integer
          minimum: 1
      additionalProperties: false
    CapacityRange:
      type: object
      required:
      - minimum
      - maximum
      properties:
        minimum:
          type: integer
          minimum: 0
        maximum:
          type: integer
          minimum: 0
      additionalProperties: false
    Image:
      oneOf:
      - type: string
        format: uri
      - type: object
        properties:
          url:
            type: string
            format: uri
          alt:
            type:
            - string
            - 'null'
        additionalProperties: true
    DiscoveryResponse:
      type: object
      required:
      - properties
      - markers
      - metadata
      properties:
        properties:
          type: array
          items:
            $ref: '#/components/schemas/PropertySummary'
        markers:
          type: array
          items:
            type: object
            additionalProperties: true
        metadata:
          type: object
          required:
          - resultCount
          - buildingGroupCount
          properties:
            resultCount:
              type: integer
              minimum: 0
            buildingGroupCount:
              type: integer
              minimum: 0
    DiscoveryDestination:
      type: object
      required:
      - label
      - propertyCount
      properties:
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        label:
          type: string
        propertyCount:
          type: integer
          minimum: 1
      additionalProperties: false
    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
    DiscoveryContext:
      type: object
      description: Live facets and guidance derived from ATA public inventory.
      required:
      - generatedAt
      - totalProperties
      - destinations
      - propertyTypes
      - buildingTypes
      - capacity
      - amenities
      - views
      - suitabilityTags
      - bestFor
      - notIdealFor
      properties:
        generatedAt:
          type: string
          format: date-time
        totalProperties:
          type: integer
          minimum: 0
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryDestination'
        propertyTypes:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
        buildingTypes:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
        capacity:
          oneOf:
          - $ref: '#/components/schemas/CapacityRange'
          - type: 'null'
        amenities:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
        views:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
        suitabilityTags:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
        bestFor:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
        notIdealFor:
          type: array
          items:
            $ref: '#/components/schemas/CountedValue'
      additionalProperties: false
    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