Ingestions

Use the ingestions endpoints to submit catalogue or audio content, track how each submission progresses, and inspect which entities were accepted during delivery. Ingestion is usually the first step in a MusiMap workflow: you send content, MusiMap processes it asynchronously, and accepted rows become visible in your catalogue inventory.

When to use ingestions

Ingestion endpoints answer operational questions: what did we submit, what stage is it in, and which entities were delivered? Catalogue inventory endpoints answer a different question: what is visible in the Workspace catalogue?

• Ingestion status: submission lifecycle, entity counts, delivery outcomes.
• Catalogue inventory: current tracks, artists, releases, and works in your accessible catalogue.

After a successful ingestion, entities should appear through Workspace inventory (/v1/workspace/tracks, /v1/workspace/artists, /v1/workspace/releases, /v1/workspace/works, /v1/workspace/labels) when catalogue membership exists. Summary fields include entities_available (delivered entities readable in Workspace inventory) and analysis_status (none, not_started, running, completed, failed, or partial).

Entity status vs analysis status

Ingestion responses expose two independent progress axes:

• status reports entity-ingestion progress only (delivery of catalogue entities).
• analysis_status reports audio-analysis progress independently for the same ingestion.
• completed_at is the entity-ingestion completion timestamp. It does not wait for analysis.
• entities_available is true when delivered entities are readable in Workspace inventory.

Entity ingestion can finish while analysis is still running. Valid combinations include:

{
  "status": "completed",
  "entities_available": true,
  "analysis_status": "running",
  "completed_at": "2026-08-30T10:15:00+00:00"
}

and later:

{
  "status": "completed",
  "entities_available": true,
  "analysis_status": "completed",
  "completed_at": "2026-08-30T10:15:00+00:00"
}

Poll status until it is terminal (completed, completed_with_errors, or failed) to know when entities are delivered. Poll analysis_status separately when your workflow needs analysis results (completed, failed, or partial). none means no relevant linked audio; not_started / running mean analysis has not finished.

Entity ingestion can complete while analysis fails or only partially succeeds:

{
  "status": "completed",
  "entities_available": true,
  "analysis_status": "failed"
}

or:

{
  "status": "completed_with_errors",
  "entities_available": true,
  "analysis_status": "partial"
}

Supported modes

Use the mode field to select the ingestion method.

Processing is asynchronous. After you create an ingestion, poll the read endpoints below until the public status reaches a terminal entity-ingestion value such as completed, completed_with_errors, or failed. Use analysis_status separately for analysis progress.

Create an ingestion

POST /v1/ingestions creates an ingestion and queues expansion on the server. Eligible audio analysis runs automatically when included in your plan. Send only the public create fields documented below and in OpenAPI.

Every create request requires:

• mode: one of the four public modes above.
• idempotency_key: your stable key for safe retries (max 255 characters).
• catalog_id: optional when your token already carries a default catalogue context. Must refer to an organisation-owned customer catalogue.

Ingestion always targets Workspace catalogues only. MusiMap Atlas is read-only and cannot be selected as an ingestion destination. See Atlas.

OAuth scope: ingestion.write. Request this scope when exchanging client credentials.

Idempotency

• New key, accepted create. 202 Accepted.
• Same key and equivalent body. 200 OK with the existing ingestion.
• Same key but a different body. 409 Conflict.

Example: api_json

curl -X POST "https://api.musimap.com/v1/ingestions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "api_json",
    "idempotency_key": "customer-json-batch-001",
    "payload": {
      "tracks": [],
      "artists": [{"key": "A1", "outer_id": "customer-json-batch-001-artist-1", "name": "Artist One"}],
      "albums": [],
      "compositions": []
    }
  }'

outer_id values are durable client identifiers within your organisation and catalogue. Reusing the same outer_id for a distinct track, artist, or release across independent ingestions rematches the existing entity. Choose stable, unique values (for example batch-scoped keys) when each upload represents new catalogue material.

Example: s3_csv

curl -X POST "https://api.musimap.com/v1/ingestions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "s3_csv",
    "idempotency_key": "catalog-2026-06-20",
    "source": {
      "type": "s3_object",
      "uri": ""
    },
    "csv": { "auto_mapping": true }
  }'

Example: s3_ddex

curl -X POST "https://api.musimap.com/v1/ingestions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "s3_ddex",
    "idempotency_key": "ddex-batch-001",
    "source": {
      "type": "s3_prefix",
      "uri": "/"
    }
  }'

Example: s3_scan

curl -X POST "https://api.musimap.com/v1/ingestions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "s3_scan",
    "idempotency_key": "audio-scan-2026-06",
    "source": {
      "type": "s3_prefix",
      "uri": "/"
    },
    "scan": { "extensions": [".wav", ".flac", ".mp3"] }
  }'

Track progress

OAuth scope for reads: ingestion.read. Request this scope when exchanging client credentials. Tenant and catalogue access is enforced on every call.

List ingestions

curl "https://api.musimap.com/v1/ingestions?mode=api_json&status=completed" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Supported filters include:

• mode, status, delivery_id, source_ingestion_batch_id.
• submitted_after, submitted_before, created_after, created_before, updated_after, updated_before.
• page, page_size for pagination.

Get one ingestion

curl "https://api.musimap.com/v1/ingestions/$MUSIMAP_INGESTION_UUID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Detail responses include entity counts and links to related sub-resources (entities, items, stats). Poll this endpoint after create until the public status stabilises.

Items, entities, and stats

Ingestion observability uses three complementary read endpoints. They answer different questions and must not be confused:

• /items: input processing records: what was submitted, expanded, or processed as ingestion items, including failures and skips.
• /entities: delivered catalogue entities: what was published and is visible through inventory endpoints after successful delivery.
• /stats: safe aggregate counts and lifecycle summary for the whole ingestion.

The public API does not expose cancel, retry, reprocess, or delete operations on ingestions. Use /items to diagnose failed rows and /stats for a high-level progress summary.

Inspect item-level results

curl "https://api.musimap.com/v1/ingestions/$MUSIMAP_INGESTION_UUID/items?status=failed" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Each item row may include:

• id. MusiMap ingestion item UUID.
• source_record_key: safe customer record key when available (never storage paths).
• outer_id: durable client identifier when provided (catalogue-stable, not globally unique).
• status. pending, processing, completed, failed, or skipped.
• entity_type. track, artist, release, or work.
• mode: public ingestion mode for the parent batch.
• error_code and message: sanitised, customer-actionable error details when processing failed or was skipped.

Supported filters: status, entity_type, outer_id, source_record_key, error_code, plus pagination.

Read ingestion stats

curl "https://api.musimap.com/v1/ingestions/$MUSIMAP_INGESTION_UUID/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Stats responses summarise item status counts (total, pending, processing, completed, failed, skipped), delivered entity counts, has_errors, and links to self, items, and entities. Error messages on items are sanitised; raw stack traces and storage paths are never returned.

Inspect delivered entities

curl "https://api.musimap.com/v1/ingestions/$MUSIMAP_INGESTION_UUID/entities?entity_type=track" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Each row describes one delivered entity with:

• entity_type. track, artist, release, or work.
• entity_id. MusiMap canonical UUID.
• outer_id: durable client identifier when provided (catalogue-stable, not globally unique).
• source_record_key: safe customer record key when available (never storage paths).
• action: such as created, matched, updated, linked, or skipped.

Storage model

For s3_csv, s3_ddex, and s3_scan, the create request references resources that already exist in storage authorised for your organisation. MusiMap validates the location against your configured inbound area. Arbitrary storage locations are not accepted.

Place files in your authorised inbound area using storage presigned uploads or your agreed onboarding process. Manage long-lived storage credentials through the developer dashboard when your integration requires them.

Ingestion responses expose public status, entity and item summaries, and safe customer identifiers such as outer_id and source_record_key.

Errors

• 401: missing or invalid bearer token (invalid_token).
• 400: validation error, unsupported mode, or forbidden public field (validation_error).
• 404: inaccessible ingestion or missing catalogue or storage context (not_found).
• 409: idempotency key reused with a different request body (conflict).
• 422. S3 source not authorised for your organisation (validation_error).
• 503: upstream dependency unavailable (upstream_unavailable).

See References → Errors for the MusiMap error envelope and public error_code values.