# Atom Tickets Partner API Documentation

> Atom Tickets Partner API enables movie ticketing integrations with real-time showtime access, co-branded checkout, and venue/production search across 25,000+ screens.

## Overview

This is the official API documentation for Atom Tickets partner integrations. The API provides programmatic access to movie theaters (venues), movies (productions), showtimes, pricing, and checkout URLs.

- Base URL: `https://api-beta.atomtickets.com/partner/v1/`
- Authentication: `x-api-key` header (partner API key) + `X-Atom-Partner` header (partner name)
- Format: JSON
- Rate Limits: 25 req/sec baseline, 50 req/sec burst (testing); negotiated for production

## For AI Agents

If you are an AI agent, LLM, or automation system:
- Read this file (/llms.txt) for a quick overview
- Read /llms-full.txt for the complete API specification with all parameters and response examples
- Read /openapi.json for the OpenAPI 3.1 specification (SDK generation, API tools)
- Visit /ai-agents/ for a guided walkthrough of all machine-readable resources

## Documentation Pages

- [For AI Agents & Automation](/ai-agents/): Machine-readable resources, ingestion guide, and API overview for AI systems
- [Introduction](/getting-started/introduction/): API overview, environments, base URLs, date formats, value limits
- [Authentication](/getting-started/authentication/): API key setup, required headers, example requests
- [Rate Limits](/getting-started/rate-limits/): Testing vs production rate limits
- [Common Models](/models/common/): PageInfo, LatLonPair, ISODateBounds, LocalDateBounds
- [Venue Models](/models/venues/): Address, Properties, Venue, VenueDetail, VenueDetailsResponse
- [Production Models](/models/productions/): ImageData, TrailerData, Cast, Crew, ProductionDetail
- [Showtime Models](/models/showtimes/): Attribute, Price, Offer, ShowtimeDetail, PreOrderDetail
- [Ping API](/api/ping/): Health check endpoint
- [Venues API](/api/venues/): Search venues by location, IDs, name, or vendor ID
- [Productions API](/api/productions/): Search movies by venue, IDs, name, or vendor ID
- [Showtimes API](/api/showtimes/): Query showtimes by venue, IDs, date range, or vendor IDs
- [Venue Examples](/examples/venues/): Full cURL commands and JSON responses for venue endpoints
- [Production Examples](/examples/productions/): Full cURL commands and JSON responses for production endpoints
- [Showtime Examples](/examples/showtimes/): Full cURL commands and JSON responses for showtime endpoints
- [Ordering Models](/models/ordering/): Ordering-specific data models for checkout, seats, orders, and payments
- [Ordering API](/api/ordering/): Ticket ordering, checkout, seat selection, and order management endpoints
- [Ordering Examples](/examples/ordering/): Full cURL commands and JSON responses for ordering endpoints

## Quick Reference

### Venue Endpoints
- GET /venue/details/byLocation?lat={lat}&lon={lon}&radius={radius} — Search nearby venues
- POST /venue/details/byIds — Get venues by Atom venue IDs
- GET /venue/details/search?term={term}&lat={lat}&lon={lon}&radius={radius} — Search venues by name
- GET /venues/byVendorVenueId/{vendorVenueId} — Get venue by partner's vendor ID

### Production Endpoints
- GET /production/ids/byVenue/{venueId} — Get production IDs at a venue
- POST /production/details/byIds — Get movies by Atom production IDs
- GET /production/search/byName?name={name} — Search movies by title
- GET /productions/byVendorProductionId/{vendorProductionId} — Get production by vendor ID

### Showtime Endpoints
- GET /showtime/details/byVenue/{venueId}?isoStartDate={start}&isoEndDate={end} — Get showtimes at venue
- POST /showtime/details/byIds — Get showtimes by Atom showtime IDs
- POST /showtime/details/forVenues — Batch query showtimes for multiple venues
- GET /venues/{venueId}/showtimes/byVendorShowtimeId/{vendorShowtimeId} — By vendor showtime ID
- GET /venues/byVendorVenueId/{vendorVenueId}/showtimes/byVendorShowtimeId/{vendorShowtimeId} — By both vendor IDs

## Key Data Models

### Venue
Fields: id, name, address (line, city, state, postal, lat, lon), kmDistance, properties (supportsConcessions, supported), venueUrl, atomVenueId

### Production (Movie)
Fields: id, name, advisoryRating, genres, runtimeMinutes, synopsis, productionMedia (coverImageUrl, trailerUrls), contributors (cast, crew)

### Showtime
Fields: showtimeId, productionId, venueId, utcShowtimeStart, localShowtimeStart, attributes, offerData (offers with label/price), checkoutUrl, availableInventory

### Ordering Endpoints
- POST /ordering/v2/aggregation/checkout/refresh — Refresh checkout with aggregated pricing, fees, and available offers
- GET /ordering/v1/discovery/auditoriums — Discover auditorium layout and available seats for a showtime
- POST /ordering/v1/customer/account/guest — Create a guest customer account for checkout
- POST /ordering/v1/customer/account/authenticate — Authenticate an existing customer account
- POST /ordering/v1/inventory/lease — Lease (temporarily hold) seats for a showtime
- POST /ordering/v2/customer/orders/preview — Preview an order with full cost breakdown before placing it
- POST /ordering/v1/customer/orders — Place a ticket order with payment
- GET /ordering/v1/customer/orders/{id}/status — Get the current status of an order
- GET /ordering/v2/customer/orders/{id}/summary — Get a detailed summary of a completed order
- DELETE /v1/customer/orders/{id} — Cancel an existing order