AMC Entertainment Holdings Theatres API

openapi: 3.0.3
info:
  title: AMC Barcodes 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. It is intended

    for partner integrations such as movie discovery, ticket sales, dine-in / express pickup

    concession ordering, AMC Stubs loyalty integrations, and entertainment listings on

    third-party sites and apps.


    Authentication is performed by sending a vendor API key in the `X-AMC-Vendor-Key`

    request header. Responses follow a HAL-style envelope (`pageSize`, `pageNumber`,

    `count`, `_embedded`, `_links`) for collections.


    This OpenAPI definition was reconstructed from the public AMC Developer Portal

    documentation (developers.amctheatres.com) and known integrations. The dev portal

    blocks automated retrieval, so this spec was assembled from third-party mirrors

    of the AMC documentation and verified against open-source AMC API clients.'
  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:
    PageSize:
      name: page-size
      in: query
      description: Results per page (max 100). Defaults to 10.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    ExcludeAttributes:
      name: exclude-attributes
      in: query
      description: Comma-delimited list of attributes that results must not have.
      schema:
        type: string
    PageNumber:
      name: page-number
      in: query
      description: Page number to retrieve. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    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
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    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
    TheatreCollection:
      allOf:
      - $ref: '#/components/schemas/PagedCollection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              theatres:
                type: array
                items:
                  $ref: '#/components/schemas/Theatre'
    HalLinks:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
          templated:
            type: boolean
    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'
    PagedCollection:
      type: object
      properties:
        pageSize:
          type: integer
        pageNumber:
          type: integer
        count:
          type: integer
        _links:
          $ref: '#/components/schemas/HalLinks'
  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