Releases

Stable country runs, current/archive scope, and calendar announcements.

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/market-releases`

Theatrical market releases.

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.
`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
`countryCode`query · optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
`distributorId`query · optional	`string`	Public distributor identifier (dst_…).
`releasesFrom`query · optional	`string`	Inclusive local release date, YYYY-MM-DD.
`releasesBefore`query · optional	`string`	Exclusive local release date, YYYY-MM-DD.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/market-releases" \
  -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[].movieId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].countryCode`Required	`string`
`data[].localTitle`Required	`string`
`data[].releaseDate`Required	`string \| null`Format: date
`data[].distributorIds`Required	`array<string>`
`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/market-releases/{id}`

Theatrical market release.

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/market-releases/{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": "rel_ZXhhbXBsZQ",
    "movieId": null,
    "countryCode": "RO",
    "localTitle": "example",
    "releaseDate": null,
    "distributorIds": []
  },
  "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.movieId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.countryCode`Required	`string`
`data.localTitle`Required	`string`
`data.releaseDate`Required	`string \| null`Format: date
`data.distributorIds`Required	`array<string>`
`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/releases`

Country Releases with explicit ownership scope.

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.
`countryCode`query · optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
`movieId`query · optional	`string`	Public canonical movie identifier (mov_…).
`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

Shell · authenticated request

curl "https://api.boxobserver.com/v1/releases" \
  -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[].movieId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].countryCode`Required	`string`
`data[].scope`Required	`string`Values: current, archived
`data[].createdAt`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/releases/{id}`

Stable country Release; its URL survives archival.

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/releases/{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": "crl_ZXhhbXBsZQ",
    "movieId": null,
    "countryCode": "RO",
    "scope": "current",
    "createdAt": "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.movieId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.countryCode`Required	`string`
`data.scope`Required	`string`Values: current, archived
`data.createdAt`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/releases/{id}/showings`

Showings of one Release, automatically read from its authoritative owner.

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.
`venueId`query · optional	`string`	Public venue identifier (ven_…).
`movieId`query · optional	`string`	Public canonical movie identifier (mov_…).
`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/releases/{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, 404, 429, 500, 503. Response format and retry guidance →

Releases

GET/v1/market-releases

Parameters

Response

GET/v1/market-releases/{id}

Parameters

Response

GET/v1/releases

Parameters

Response

GET/v1/releases/{id}

Parameters

Response

GET/v1/releases/{id}/showings

Parameters

Response

GET`/v1/market-releases`

GET`/v1/market-releases/{id}`

GET`/v1/releases`

GET`/v1/releases/{id}`

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