Skip to main content

deliver.media public API

A versioned REST API for integrating with deliver.media products. Every request is scoped to your organisation: you never see another tenant's data.

Base URL​

https://public-api.deliver.media

Endpoints are versioned and grouped by product under /api/v1/{product}:

  • /api/v1/musiccompanion for songs, their versions, channels and analyses.
  • /api/v1/library for media of any kind, their files, subtitles and timelines. See library..

New analysis types and optional fields are added without breaking /api/v1.

Two structural changes have shipped within /api/v1 during the beta. The first: the AnalysisJob model is no longer a flat object but a discriminated union (oneOf) keyed by the type field, with one variant per analysis type. If you use a generated client, regenerate it against the current OpenAPI document. Consumers must branch on type before reading fields whose shape depends on the analysis type, such as result.

A second one changed musiccompanion versions (EntityVersion, and PrimaryVersion on an entity):

  • playback is gone. A version's start and end are now its markers: playback.markInMs and playback.markOutMs become markers.markIn.positionMs and markers.markOut.positionMs. The fade fields have no replacement.
  • position is gone from responses and from the create and update requests. A position sent in a request is ignored. Versions are listed by kind, primary first, then in the order the product keeps them (oldest first unless reordered in the product).
  • Added: durationMs, and markers with the nine radio markers of an audio version (null for other kinds).

Media metadata written by our uploads now uses camelCase keys (durationMs, originalFilename, audioCodec); stored media was migrated to the same keys.

musiccompanion.​

  • Entities are songs and their derivative versions, carrying business metadata. You can link them to express relationships such as derived_from.
  • Versions are the media an entity exists as: one row per audio edit, artwork or video (the radio edit, the full-length mix, a station intro). Each version has a label, a type and a file, and exactly one version per kind is primary: what the product plays or shows, and what MusicMaster addresses through the entity.
  • Channels are the radio channels of your organisation with their rotation categories. A version is programmed on a channel in a category; a channel bound to a MusicMaster station synchronises the change there.
  • Assets are uploaded media files. An asset becomes a version when it is attached to an entity, or is uploaded standalone just to run analysis.
  • Analyses are asynchronous jobs that run one analysis type against one audio source and return a typed result.

Entity metadata​

An entity's metadata is deliberately customer-defined rather than a fixed music schema. Each organisation may use its own field names, and each value may be a string, number, boolean, or null. Nested objects and arrays are not part of this contract. The API preserves the field names supplied by the customer; it does not translate them to a shared catalogue vocabulary.

Entity relationships​

Relationships are directed: in POST /api/v1/musiccompanion/entities/{id}/links, the entity identified by {id} is the source, and targetEntityId is the target. relationType is the slug of a relation type configured for the organisation. The public API does not currently provide a relation-type discovery endpoint, so integrations must use a slug agreed with the organisation. The created link can be removed with DELETE /api/v1/musiccompanion/entities/{id}/links/{linkId}.

A typical flow​

  1. Create an entity for your song. Discover the valid type slugs with GET /api/v1/musiccompanion/entity-types.
  2. Upload its audio as an asset and attach it to the entity.
  3. Request an analysis for the entity (or for a standalone asset).
  4. Poll the analysis job until it succeeds, then read the result.
  5. Review your credit consumption at GET /api/v1/musiccompanion/usage.

See Authentication to get a token, then browse the API Reference.

Analyse a temporary file without creating an entity​

You do not need an entity, or even a permanent asset, just to run an analysis: upload the file with "retention": "standalone" and point the analysis at the resulting assetId. The step-by-step flow is described in the musiccompanion. analyses reference.

Errors​

Errors use standard HTTP status codes. The body carries a machine-readable code and a human-readable message:

{ "error": { "code": "asset_not_found", "message": "No asset with id ast_..." } }

The HTTP status is the authoritative signal.

Rate limiting​

Cloudflare applies two rate-limit stages to product API requests:

  • Before authentication, requests with a bearer credential are limited to 120 requests per minute per source IP address. Requests without a bearer credential are limited to 30 requests per minute per source IP address.
  • After successful authentication, ordinary requests are limited to 120 requests per minute per API key. Starting an analysis with POST /api/v1/musiccompanion/analyses is limited to 20 requests per minute per API key.

An authenticated request must pass both the source-IP limit and its API-key limit. The landing page, documentation, OpenAPI specification, and legacy compatibility endpoints are not counted by these limits.

When a limit is exceeded, the API returns 429 Too Many Requests. Use the Retry-After, RateLimit-Limit, and RateLimit-Window response headers to determine the applicable ceiling and when to retry.