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}. The currently available endpoints belong to musiccompanion. and use /api/v1/musiccompanion. New analysis types and optional fields are added without breaking /api/v1.

One structural change has shipped within /api/v1: 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.

musiccompanion.​

  • Entities are songs and their derivative versions, carrying business metadata. You can link them to express relationships such as derived_from.
  • Assets are uploaded audio files. An asset can be attached to an entity or 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.