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.

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.

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.