Movies

Canonical film identities and their published showings.

Production · organization access required

Requests require an active organization grant and an API key or Clerk session. Results respect your granted scopes and markets. Access details →

GET`/v1/movies`

Canonical movies.

Parameters

Name	Type	Details
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`query`query · optional	`string`	Case-insensitive substring of the title or original title.
`releaseYear`query · optional	`integer`	Filter by the original release year.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/movies" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object>`
`data[].id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].title`Required	`string`
`data[].originalTitle`Required	`string \| null`
`data[].releaseYear`Required	`integer \| null`
`data[].runtimeMinutes`Required	`integer \| null`Minimum: 0
`data[].externalIds`Required	`object`
`data[].updatedAt`Required	`string`Format: date-time
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

GET`/v1/movies/{id}`

Canonical movie.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/movies/{id}" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": {
    "id": "mov_ZXhhbXBsZQ",
    "title": "example",
    "originalTitle": null,
    "releaseYear": null,
    "runtimeMinutes": null,
    "externalIds": {},
    "updatedAt": "2026-09-04T12:00:00.000Z"
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`object`
`data.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.title`Required	`string`
`data.originalTitle`Required	`string \| null`
`data.releaseYear`Required	`integer \| null`
`data.runtimeMinutes`Required	`integer \| null`Minimum: 0
`data.externalIds`Required	`object`
`data.updatedAt`Required	`string`Format: date-time
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 404, 429, 500, 503. Response format and retry guidance →

GET`/v1/movies/{id}/showings`

Movie showings.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`scope`query · optional	`string`	Defaults to current (D1-owned). Archived selects published history; all explicitly combines both. Ownership is independent of Showing or premiere dates. Archived/all requires history:read.Values: current, archived, all
`releaseId`query · optional	`string`	Public country Release identifier (crl_…).
`venueId`query · optional	`string`	Public venue identifier (ven_…).
`operatorId`query · optional	`string`	Public operator identifier (opr_…).
`marketId`query · optional	`string`	Public market identifier (mkt_…).
`countryCode`query · optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
`localDate`query · optional	`string`	Cinema-local calendar date, YYYY-MM-DD. Cannot be combined with timestamp bounds.
`startsFrom`query · optional	`string`	Inclusive start timestamp. ISO 8601; offsets are normalized to UTC.
`startsBefore`query · optional	`string`	Exclusive end timestamp. The schedule window is limited to 31 days.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/movies/{id}/showings" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object>`
`data[].id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].releaseId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].status`Required	`string`Values: scheduled, unlisted, cancelled
`data[].startsAt`Required	`string`Format: date-time
`data[].localDate`Required	`string`Format: date
`data[].timeZone`Required	`string`
`data[].venue`Required	`object`
`data[].venue.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venue.name`Required	`string`
`data[].venue.programmingType`Required	`string`Values: mainstream, mixed, specialist
`data[].venue.market`Required	`object`
`data[].venue.market.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venue.market.name`Required	`string`
`data[].venue.market.countryCode`Required	`string`
`data[].venue.market.timeZone`Required	`string`
`data[].auditorium`Required	`object \| null`
`data[].auditorium.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].auditorium.name`Required	`string`
`data[].auditorium.capacity`Required	`integer \| null`Minimum: 0
`data[].auditorium.experiences`Required	`array<string> \| null`
`data[].movie`Required	`object`
`data[].movie.canonicalMovie`Required	`object \| null`
`data[].movie.canonicalMovie.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].movie.canonicalMovie.title`Required	`string`
`data[].movie.canonicalMovie.originalTitle`Required	`string \| null`
`data[].movie.canonicalMovie.releaseYear`Required	`integer \| null`
`data[].movie.canonicalMovie.runtimeMinutes`Required	`integer \| null`Minimum: 0
`data[].movie.sourceTitle`Required	`string`
`data[].movie.sourceOriginalTitle`Required	`string \| null`
`data[].movie.identityStatus`Required	`string`Values: canonical, source
`data[].format`Required	`string`Values: 2d, 3d
`data[].experiences`Required	`array<string>`
`data[].experienceSource`Required	`string \| null`Values: showing, auditorium,
`data[].language`Required	`string \| null`
`data[].capacity`Required	`integer \| null`Minimum: 0
`data[].capacitySource`Required	`string \| null`Values: showing, observation, auditorium,
`data[].price`Required	`object`
`data[].price.status`Required	`string`Values: exact, derived, unavailable
`data[].price.amountMinor`Required	`integer \| null`Minimum: 0
`data[].price.currency`Required	`string \| null`
`data[].price.source`Required	`string \| null`Values: providerSchedule, providerBooking, officialTariff, legacyUnknown,
`data[].price.observedAt`Required	`string \| null`Format: date-time
`data[].price.lastConfirmedAt`Required	`string \| null`Format: date-time
`data[].price.options`Optional	`array<object>`Default: []
`data[].price.options[].offerKey`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].price.options[].label`Required	`string`
`data[].price.options[].amountMinor`Required	`integer`Minimum: 0
`data[].price.options[].currency`Required	`string`
`data[].price.options[].admissionsIncluded`Required	`integer`Minimum: 0
`data[].seatAvailability`Required	`object \| null`
`data[].seatAvailability.status`Required	`string`Values: exact, derived, unavailable
`data[].seatAvailability.observedAt`Required	`string`Format: date-time
`data[].seatAvailability.checkpoint`Required	`string`
`data[].seatAvailability.capacity`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.availableSeats`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.occupiedEstimate`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.occupancyRatio`Required	`number \| null`Minimum: 0 · Maximum: 1
`data[].updatedAt`Required	`string`Format: date-time
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

Movies

GET/v1/movies

Parameters

Response

GET/v1/movies/{id}

Parameters

Response

GET/v1/movies/{id}/showings

Parameters

Response

GET`/v1/movies`

GET`/v1/movies/{id}`

GET`/v1/movies/{id}/showings`