AMC Entertainment Holdings Theatres API

openapi: 3.2.0
info:
  title: AMC Theatres API
  description: 'The AMC Theatres API is a public REST API published by AMC Entertainment Holdings

    that exposes data and transactional capabilities for AMC theatres, movies, showtimes,

    locations, loyalty, concessions, orders, refunds, media, and webhooks.'
  version: v2
  contact:
    name: AMC Theatres Developer Portal
    url: https://developers.amctheatres.com
  termsOfService: https://www.amctheatres.com/legal/terms-of-use
  license:
    name: AMC Theatres API Terms of Use
    url: https://www.amctheatres.com/legal/terms-of-use
servers:
- url: https://api.amctheatres.com
  description: AMC Theatres production API
security:
- VendorKey: []
tags:
- name: Theatres
  description: AMC theatre locations, attributes, and metadata.
paths:
  /v2/theatres:
    get:
      summary: List All Active Theatres
      description: Returns a paginated list of active AMC theatres, optionally filtered by attributes, market, state/city, brand, or name.
      operationId: listTheatres
      tags:
      - Theatres
      parameters:
      - $ref: '#/components/parameters/IncludeAttributes'
      - $ref: '#/components/parameters/ExcludeAttributes'
      - $ref: '#/components/parameters/AttributeOperator'
      - name: ids
        in: query
        description: Comma-delimited list of theatre ids to filter by.
        schema:
          type: string
      - name: name
        in: query
        description: Filter theatres whose name contains the specified text.
        schema:
          type: string
      - name: market
        in: query
        description: Filter theatres in the specified market.
        schema:
          type: string
      - name: state
        in: query
        description: Filter theatres in the specified state (required when `city` is given).
        schema:
          type: string
      - name: city
        in: query
        description: Filter theatres in the specified city (requires `state`).
        schema:
          type: string
      - name: brand
        in: query
        description: Filter theatres by brand abbreviation.
        schema:
          type: string
      - name: include
        in: query
        description: Set to `closed` to include closed theatres.
        schema:
          type: string
          enum:
          - closed
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of theatres.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TheatreCollection'
  /v2/theatres/{idOrSlug}:
    get:
      summary: Get a Theatre by Id or Slug
      description: Returns a single theatre matched by numeric id or url-friendly slug.
      operationId: getTheatre
      tags:
      - Theatres
      parameters:
      - name: idOrSlug
        in: path
        required: true
        description: The theatre id (integer) or theatre slug.
        schema:
          type: string
      responses:
        '200':
          description: Theatre representation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theatre'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/theatres/views/now-playing/wwm-release-number/{wwm-release-number}:
    get:
      summary: List Theatres Now Playing a WWM Release
      description: Returns theatres now playing the specified West World Media release number.
      operationId: listTheatresByWwmRelease
      tags:
      - Theatres
      parameters:
      - name: wwm-release-number
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Theatres playing the release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TheatreCollection'
components:
  parameters:
    PageNumber:
      name: page-number
      in: query
      description: Page number to retrieve. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: page-size
      in: query
      description: Results per page (max 100). Defaults to 10.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    IncludeAttributes:
      name: include-attributes
      in: query
      description: Comma-delimited list of attributes that results must have.
      schema:
        type: string
    AttributeOperator:
      name: attribute-operator
      in: query
      description: Whether the include/exclude attribute filter is `and` (all) or `or` (any).
      schema:
        type: string
        enum:
        - and
        - or
    ExcludeAttributes:
      name: exclude-attributes
      in: query
      description: Comma-delimited list of attributes that results must not have.
      schema:
        type: string
  schemas:
    Attribute:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        name:
          type: string
        shortDescription:
          type: string
        longDescription:
          type: string
        url:
          type: string
          format: uri
        sort:
          type: integer
        appliesToMovie:
          type: boolean
        appliesToShowtime:
          type: boolean
        appliesToTheatre:
          type: boolean
        media:
          type: object
        _links:
          $ref: '#/components/schemas/HalLinks'
    HalLinks:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
          templated:
            type: boolean
    TheatreCollection:
      allOf:
      - $ref: '#/components/schemas/PagedCollection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              theatres:
                type: array
                items:
                  $ref: '#/components/schemas/Theatre'
    PagedCollection:
      type: object
      properties:
        pageSize:
          type: integer
        pageNumber:
          type: integer
        count:
          type: integer
        _links:
          $ref: '#/components/schemas/HalLinks'
    Theatre:
      type: object
      description: An AMC Theatre representation.
      properties:
        id:
          type: integer
          description: The theatre id.
        name:
          type: string
          description: The name of the theatre.
        longName:
          type: string
          description: The long name of the theatre.
        secondaryLongName:
          type: string
        showtimesPhoneNumber:
          type: string
        guestServicesPhoneNumber:
          type: string
        utcOffset:
          type: string
        timezone:
          type: string
        timezoneAbbreviation:
          type: string
        slug:
          type: string
        facebookUrl:
          type: string
          format: uri
        outageDescription:
          type: string
        websiteUrl:
          type: string
          format: uri
        directionsUrl:
          type: string
          format: uri
        loyaltyVersion:
          type: string
        isClosed:
          type: boolean
        closures:
          type: array
          items:
            type: object
        lastBusinessDate:
          type: string
          format: date
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        location:
          type: object
          properties:
            addressLine1:
              type: string
            addressLine2:
              type: string
            city:
              type: string
            postalCode:
              type: string
            state:
              type: string
            stateName:
              type: string
            country:
              type: string
            latitude:
              type: number
              format: double
            longitude:
              type: number
              format: double
            marketName:
              type: string
            marketId:
              type: integer
        media:
          type: object
          properties:
            theatreImageIcon:
              type: string
              format: uri
            theatreImageStandard:
              type: string
              format: uri
            theatreImageThumbnail:
              type: string
              format: uri
            theatreImageLarge:
              type: string
              format: uri
            heroDesktopDynamic:
              type: string
              format: uri
            heroMobileDynamic:
              type: string
              format: uri
            interiorDynamic:
              type: string
              format: uri
            exteriorDynamic:
              type: string
              format: uri
            promotionDynamic:
              type: string
              format: uri
        redemptionMethods:
          type: array
          items:
            type: string
        westWorldMediaTheatreNumber:
          type: integer
        concessionsDeliveryOptions:
          type: array
          items:
            type: string
            enum:
            - DeliveryToSeat
            - ExpressPickup
        convenienceFeeTaxPercent:
          type: number
        convenienceFeeTaxFlatAmount:
          type: number
        brand:
          type: string
          description: AMC brand abbreviation (AMC, DIT, Classic, etc.).
        productSubscriptionUsageLevel:
          type: string
        onlineConcessions:
          type: boolean
        hasMultipleKitchens:
          type: boolean
        estimatedConcessionsOrderFees:
          type: object
        _links:
          $ref: '#/components/schemas/HalLinks'
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        errorCode:
          type: string
        moreInfo:
          type: string
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    VendorKey:
      type: apiKey
      in: header
      name: X-AMC-Vendor-Key
      description: AMC vendor API key issued via the AMC Theatres developer portal.
externalDocs:
  description: AMC Theatres Developer Portal
  url: https://developers.amctheatres.com