Concepts: build an AXIS frontend

Items

An item is any piece of content in the AXIS catalog.

Examples include:

• Movie
• Show
• Season
• Episode
• Program
• Trailer
• Channel
• Custom asset
• Event
• Competition
• Stage
• Persona
• Team

Items have a type field that tells you what kind of content they are. The item type helps the frontend decide how to render metadata, navigation, and hierarchy.

Item Lists

An item list is a curated or rules-based collection of items. In a frontend, item lists commonly appear as carousel rows, rails, featured sections, editorial collections, or dynamic recommendations.

Lists have their own ID and slug, and they support pagination.

A response list may include:

• Item summaries
• List title
• List size
• Images
• Themes
• Paging metadata

Continue watching can also appear in frontend list-style experiences, but user-specific continue watching data is scoped to the signed-in user and requires a JWT when loaded through user-data endpoints.

Slugs and IDs

Most resources can be fetched either by ID or by slug.

Use slugs for URL routing in your app:

/movies/the-dark-knight

Use IDs when they come from another API response or when linking related API calls.

Offers

Each item carries an offers array listing how the content can be accessed.

Offers may represent:

• Subscription
• Rental
• Purchase
• Free access

Use the sub parameter, containing the user's active subscription codes, to filter the offers array to what the current user can access.

Use the device parameter to request offers suitable for the target device.

Images

Items and lists return image URLs in an images dictionary.

Common keys include:

• poster
• hero
• thumbnail
• banner

Image URLs point to axis-svc-shain, the AXIS image rendering service.

You can use returned URLs directly in <img> tags, or modify transformation options to request different sizes and formats.

Pages and navigation

axis-api-display provides CMS-managed pages, resolved layout entries, and platform navigation config.

Use it for:

• CMS-configured pages
• Page layouts
• Navigation menus
• Configured content blocks or rails

Pages can be fetched by path to get the full layout with item list references resolved.

Global navigation config can be fetched once at app startup and cached in your application state.

Search

Search uses a POST request.

It returns catalog items filtered by search criteria.

The documented search example includes:

• term
• userContext.maxRating
• userContext.subscriptions
• userContext.device
• filterContext.includeTypes
• page
• pageSize
• languageCode

For instant or typeahead search, debounce user input before sending requests. The source example uses a 300 ms debounce and ignores input shorter than two characters.

Live and scheduled TV

axis-api-linear provides live and scheduled TV data.

The source guide documents:

• Currently live items across channels
• Channel grids for a time window
• Schedule lookup by ID
• Auto-refreshing live data

Live data changes every program slot, so live views should refresh more often than static catalog metadata.

User data

axis-api-uxmeta provides user-scoped data.

Examples include:

• Bookmarks
• Continue watching
• Follows
• Watched events
• Ratings

User data endpoints require a JWT Bearer token from your authentication provider. They are not public and are scoped to the signed-in user.

Load user data only after authentication.

Pagination

List and search responses include a paging object.

The paging object includes:

• page
• size
• total
• next
• previous

Always use paging.next directly to load the next page. Do not construct pagination URLs manually.

When paging.next is null, there are no more pages.

Error Shape

AXIS error responses share this shape:

{
  "code": "ITEM_NOT_FOUND",
  "message": "The item with id 'abc123' was not found.",
  "details": {}
}

The front-end should map errors to appropriate UI states.

Examples from the source guide include:

• Not found screen for 404
• Request fix or safe handling for invalid query parameters
• Retrieval error state for server errors
• Offline or network error state when no response is available

Eventual Consistency

Content may not be immediately available after CMS publication.

If your app receives a link to newly published content and the API returns 404, retry once or twice with a short delay before showing a not-found screen.