Guidelines: ingest content into AXIS

Fetch reference data before ingesting

Before sending content, fetch the required reference data from axis-api-pm. Reference data must match the platform's stored values exactly. Incorrect values cause validation failures. Fetch and cache:

• Rating systems
• Segmentation tags
• Relation types, if creating item relations
• User groups, if ingesting offers
• Offer groups
• Offer template IDs

If a validation failure mentions an unknown ID or key, re-fetch the reference data before retrying. The platform reference data may have changed since your last cache warm.

Cache Reference Data

Reference data changes infrequently, but different data types have different recommended TTLs.

Data	Recommended Cache TTL
Rating systems	24 hours
Segmentation tags	1 hour
Offers	5 minutes
Relation types	1 hour
User groups	1 hour

Use cached reference data when building ingestion payloads so your service does not need to call axis-api-pm for every ingest request.

Validate payloads before submitting

Validate payloads locally where possible before submitting them to AXIS. Check out this:

• itemType maps to an item type supported for your project
• Ratings use valid id and systemId pairs
• Segmentation tags use known external IDs
• Relation types are enabled before use
• Offer groups reference existing offer group IDs and offer template IDs
• Child items reference a parent that already exists in Catalog
• Schedule item externalId values are unique within the schedule
• Schedule startAt and endAt values are ISO 8601 UTC timestamps
• Schedule items fall within the same calendar day

If an item type uses custom extension properties, request the JSON schema and validate the extensions object against it before submitting.

Apply item schema validation locally

Use the relevant item schema as a pre-submit contract for every catalog item payload. At minimum, validate:

Validation Area	What To Check
Required fields	Payload includes the schema-required fields, commonly externalId, itemType, title, and offerGroups.
Item type	itemType exactly matches the intended schema, such as Movie, Program, Event, Trailer, Show, Season, Episode, Channel, Team, or Persona.
Localized text	Localized arrays include cultureName and text.
Reference data	Ratings, segmentation tags, relation types, offer groups, and offers resolve to known platform values.
Images	Image URLs are externally accessible and use approved imageType values.
Availability	Availability windows include a key, start, and end where used.
Extensions	Type-specific metadata matches the expected shape for that item type.
Parent links	parentExternalId points to an existing parent item when required.
Relations	Relation payloads include both relationType and relatedItemIds.

Do not submit records that fail local schema validation. Fix the source mapping first, then submit the corrected payload.

Use item-type-specific rules

Do not treat every source record as a generic item. Map and validate each record against the item type it represents.

Item Type	Validation Guidance
Movie	Validate standalone movie metadata, ratings, images, availability windows, offers, and movie-specific extensions such as duration, release year, cast, crew, genres, advisory, and media references.
Program	Validate program metadata for documentaries, highlights, interviews, news, replays, or similar items. Use program-specific extensions such as sequence number, subtype, venue, location, broadcast date, event date, duration, genres, cast, and crew where applicable.
Event	Validate event metadata, timing, venue or location fields where used, images, availability, offers, and related media references.
Trailer	Validate trailer metadata and link it to the related destination, parent, or media reference required by the project.
Show	Validate series-level metadata and ingest it before seasons or episodes that depend on it.
Season	Validate season metadata, season number where available, and parentExternalId pointing to the show.
Episode	Validate episode metadata, episode number where available, duration or broadcast date where used, and parentExternalId pointing to the season.
Confederation, Competition, Stage, Team, Persona	Validate sports or organizational hierarchy metadata and confirm the expected parent-child model with the platform team.
Channel	Validate channel metadata and any image, offer, or destination fields required by the project.

Limit bulk ingestion concurrency

For large catalog feeds, use a queue to parallelize ingestion, but limit concurrency per tenant. The source recommendation is to start with 5-10 parallel requests and increase only if the platform team approves. For large catalogs:

1. Warm the reference data cache at startup.
2. Ingest in dependency order.
3. Track externalId to platform item ID mappings in your own store if needed.
4. Run reconciliation against reports to catch failed or partial workflows.

Avoid blind retries

Retry only after addressing the likely root cause. Examples:

• For 401, refresh the JWT before retrying.
• For 206 Partial Content, fix the failed step before retrying with forceUpdate=true.
• For unknown rating IDs, re-fetch rating systems from axis-api-pm.
• For unknown segmentation tags, re-fetch segmentation tags from axis-api-pm.
• For invalid parentExternalId, ingest the parent item first, then retry the child.
• For duplicate schedule item IDs, deduplicate the schedule items in your feed.
• For schema validation failures, fix the payload mapping before retrying.
• For invalid relation types, re-fetch relation types from axis-api-pm and rebuild the relation payload.
• For unknown related item IDs, confirm the related items exist before retrying.

Do not repeatedly retry invalid payloads without changing the data.