Version: 10.0

Getting started: ingest content into AXIS

Overview

AXIS ingestion lets external data partners and internal project teams push catalog content and linear TV schedules into the AXIS platform.

The ingestion service, axis-api-ingestion, is the entry point for pushing external content into AXIS. It translates your data into the platform's internal data model, creates or updates records, link images, and publishes content automatically.

Use ingestion for:

Catalog items such as movies, shows, seasons, episodes, programs, events, and custom assets
Item image references that AXIS downloads, stores, and links during item ingestion
Offer group associations
Linear TV schedules and EPG data

The ingestion flow depends on two platform services:

Service	Purpose
`axis-api-pm`	Looks up reference data required by ingestion payloads
`axis-api-ingestion`	Submits catalog items, schedules, and related content.

Before sending content, you must look up reference data from axis-api-pm. Reference data provides the exact IDs and values AXIS expects, such as rating UUIDs or segmentation tag external IDs. Incorrect values cause validation failures.

Before you start

Confirm the following with the AXIS platform team:

JWT credentials issued, including client ID, client secret, and token endpoint (available in a future version).
Your tenant ID
Base URLs for axis-api-pm and axis-api-ingestion in your target environment
Which item types your content maps to
Which image types are expected, such as Thumbnail, Poster, Wallpaper, or Tile
Whether any item type uses custom extension properties
The JSON schema for any required custom extension properties

Also request the item schemas that apply to your feed. The current item schema reference includes schemas for:

Movie
Program
Event
Trailer
Show
Season
Episode
Confederation
Competition
Stage
Team
Persona
Channel
Create item relations
Delete item relations

Use these schemas when deciding which source records become AXIS items, which fields are required, and which fields should be validated before submission.

Basic flow

A typical ingestion integration follows this sequence:

Authenticate with the configured OAuth2 authority.
Fetch required reference data from axis-api-pm.

Best practice: Fetch and cache records with a 5-minute TTL.
Build ingestion payloads using platform-approved IDs and keys (based on reference data from axis-api-pm).
Validate payloads against the relevant item schema.
Submit content to axis-api-ingestion.
Verify ingestion results with the Reports API.
Repair partial workflows, and retry failed workflows only after correcting the documented root cause.

Authentication

Both axis-api-pm and axis-api-ingestion require a JWT Bearer token.

Obtain a token from the configured OAuth2 authority. Ask the platform team for the token endpoint and your client credentials.

POST {token-endpoint}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your-client-id}
&client_secret={your-client-secret}
&scope={api-scope}

Include the token on every subsequent request:

Authorization: Bearer {access_token}

Tokens are time-limited. Refresh them before expiry and do not cache them indefinitely.

First item ingest

Items are ingested one at a time. The service uses your externalId to determine whether to create or update an item.

POST /v1/{tenantId}/items
Content-Type: application/json
Authorization: Bearer {token}

Example movie payload:

{
  "externalId": "movie-123",
  "itemType": "Movie",
  "title": [
    { "cultureName": "en-GB", "text": "The Dark Knight" }
  ],
  "description": [
    { "cultureName": "en-GB", "text": "Batman faces the Joker in Gotham City." }
  ],
  "ratings": [
    {
      "id": "29a6b458-9789-495a-aae3-e885774b11f4",
      "systemId": "60200e98-c5f3-404e-add1-a76e1d6d2a27"
    }
  ],
  "segmentationTags": ["active"],
  "categories": ["action", "thriller"],
  "keywords": ["batman", "joker", "gotham"],
  "availabilityWindows": [
    {
      "key": "svod",
      "start": "2024-01-01T00:00:00Z",
      "end": "2025-01-01T00:00:00Z"
    }
  ],
  "images": [
    {
      "url": "https://assets.example.com/dark-knight-poster.jpg",
      "imageType": "Poster",
      "cultureName": "en-GB"
    },
    {
      "url": "https://assets.example.com/dark-knight-thumb.jpg",
      "imageType": "Thumbnail",
      "cultureName": "en-GB"
    }
  ],
  "offerGroups": [
    {
      "id": "716a45f5-a54c-4526-b8f7-710ec3bdaa5f",
      "offers": [
        {
          "id": "3b88c3af-c48d-4445-99c8-a556eb48ccda"
        }
      ]
    }
  ]
}

The ratings, segmentationTags, and offerGroups values must be built from platform reference data. Confirm required fields for your item type with the platform team or the relevant item schema.

Schema-backed item payload guidance

The item schemas define the contract your payload should satisfy before you submit it to axis-api-ingestion.

Most item schemas share the same core payload structure:

{
  "externalId": "source-system-id",
  "itemType": "Movie",
  "title": [
    { "cultureName": "en-GB", "text": "Display title" }
  ],
  "offerGroups": [
    {
      "id": "offer-group-id",
      "offers": [
        { "id": "offer-id" }
      ]
    }
  ]
}

The common required fields in the item schemas are:

Field	Purpose
`externalId`	Stable source identifier used to create or update the same item across repeated ingests. `externalIds` are correlation ids to track assets across systems.
`itemType`	AXIS item type, such as `Movie`, `Show`, `Season`, `Episode`, `Program`, `Event`, `Trailer`, or `Channel`
`title`	Localized display title array
`offerGroups`	Offer group associations resolved from platform reference data

Add optional fields when your item type and source data support them:

Field	Use When
`description`, `shortDescription`, `tagLine`, `contextualTitle`	You have localized editorial text
`ratings`	The item needs content ratings from platform rating systems
`segmentationTags`	The item should be grouped or segmented using platform-defined external IDs
`categories`, `keywords`	The item needs categorization or search metadata
`availabilityWindows`	The item has one or more availability periods
`images`	AXIS should download, store, and link images during ingestion
`extensions`	The item type has custom or type-specific metadata
`parentExternalId`	The item belongs under another item, such as a season under a show or an episode under a season
`customValues`	The item needs key/value integration metadata
`customDestination`	The item links to an external URL or AXIS page destination

Choose itemType based on the source record:

Source Record	Recommended AXIS Item Type
Standalone film	`Movie`
TV show or series container	`Show`
Season within a show	`Season`
Episode within a season	`Episode`
Documentary, highlight, interview, replay, or non-movie editorial item	`Program`
Sports match, concert, or conference session	`Event`
Short promotional media item	`Trailer`
Linear or live channel	`Channel`
Sports organization hierarchy	`Confederation`, `Competition`, `Stage`, `Team`, or `Persona`, as appropriate

For hierarchical content, include parentExternalId and ingest parents before children:

{
  "externalId": "episode-s01e03",
  "itemType": "Episode",
  "parentExternalId": "season-s01",
  "title": [
    { "cultureName": "en-GB", "text": "The Pilot" }
  ],
  "offerGroups": [
    {
      "id": "offer-group-id",
      "offers": [
        { "id": "offer-id" }
      ]
    }
  ]
}

For images, the schema expects image objects with fields such as url, imageType, and cultureName:

{
  "url": "https://assets.example.com/poster.jpg",
  "imageType": "Poster",
  "cultureName": "en-GB"
}

For item relations, use the relation schema with the enabled relationType and the related item IDs:

{
  "relationType": "related",
  "relatedItemIds": [
    "item-id-1",
    "item-id-2"
  ]
}

Fetch enabled relation types from axis-api-pm before creating or deleting item relations.

Verify the Result

Every ingest call can be verified using the Reports API. This is especially useful when integrating asynchronously or debugging partial successes.

List the recent reports:

GET /v1/{tenantId}/reports
Authorization: Bearer {token}

Get a specific report:

GET /v1/{tenantId}/reports/{workflowId}
Authorization: Bearer {token}

A report shows the state of each workflow step, including error messages for failed steps.

Example workflow steps may include:

Validating the request
Resolving or creating the item in Catalog
Downloading and uploading images to Media Service
Linking images to the item
Creating and linking offer groups
Publishing the item

Common Response Outcomes

Status	Meaning	Action
`200 OK`	All workflow steps succeeded. The item is live.	Log success and store the mapping from your `externalId` to the platform item ID if needed.
`206 Partial Content`	Some steps failed, such as image upload. The item may be created or updated but is incomplete.	Read the response messages or report steps, fix the failed step, then retry with `forceUpdate=true`.
`400 Bad Request`	The workflow failed entirely before meaningful work was done, usually because of validation failure or invalid payload data.	Check the error message, fix the payload, and retry.
`401 Unauthorized`	The token is missing or expired.	Refresh the JWT and retry.
`503 Service Unavailable`	The feature flag is disabled.	Contact the platform team.

Recover from partial success

A 206 Partial Content response means the item exists in Catalog but something went wrong in a later step. The most common case is image upload failure. The item may be published but lacks images.

To recover:

Read the messages array in the response, or inspect the report, to identify which step failed.
Fix the root cause, such as making the image URL publicly accessible.
Resubmit the same payload with forceUpdate=true.

Do not treat 206 Partial Content as a permanent failure. It is recoverable after the failed step is repaired.

POST /v1/{tenantId}/items?forceUpdate=true
Authorization: Bearer {token}