Storage

Inbound storage config, presigned uploads, listing, and delete before ingestion.

Use the storage endpoints to work with your MusiMap-managed organisation inbound area. Upload files with presigned PUT URLs, list what is already there, and delete objects you no longer need. After upload, reference the object or prefix from ingestions.

Managed buckets only

These APIs operate on MusiMap-managed organisation landing buckets and the configured inbound prefix only. If your organisation also uses an external customer-owned bucket, you manage listing, upload, and delete there yourself. MusiMap may read from that external bucket during ingestion when configured, but these storage endpoints do not manage it.

OAuth scopes

  • storage.browse — read config, list inbound objects, and look up one object.
  • storage.upload — request presigned uploads.
  • storage.delete — delete inbound objects.
  • storage.credentials.read — list storage credential metadata (no secrets).
  • storage.credentials.write — create and revoke storage credentials.
  • Request the scopes your integration needs when exchanging client credentials.

Read storage configuration

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

Returns managed storage availability, region, inbound prefix, and whether external storage is configured. No secrets, role ARNs, or credentials are returned.

List inbound objects

curl "https://api.musimap.com/v1/storage/inbound/objects?prefix=catalogue/june/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The optional prefix is relative to your inbound prefix, not an absolute S3 URI. Responses return object_key values relative to inbound, plus optional pagination through continuation_token.

Check whether an inbound object exists

curl "https://api.musimap.com/v1/storage/inbound/objects?object_key=catalogue/june/catalog.csv" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Use this after a presigned upload to confirm the object is visible, or before POST /v1/ingestions. When the object exists, the response includes safe metadata such as size and last modified time. When it does not exist, the API returns 404 Not Found.

Pass object_key relative to the inbound prefix. Do not pass s3:// URIs. object_key cannot be combined with prefix on the same request.

Request a presigned upload

curl -X POST "https://api.musimap.com/v1/storage/inbound/uploads" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object_key": "catalogue/june/catalog.csv",
    "content_type": "text/csv"
  }'

The response includes a presigned PUT URL, required headers, and expiry. Upload the file directly to that URL. Do not send file bytes to the MusiMap API gateway.

Delete an inbound object

curl -X DELETE "https://api.musimap.com/v1/storage/inbound/objects?object_key=catalogue/june/catalog.csv" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Pass object_key as a query parameter. Only single-object delete is supported in V1. Delete is idempotent when the object is already gone.

Storage credentials (optional)

Presigned uploads remain the recommended default. Storage credentials are an optional advanced workflow for bulk SDK or CLI uploads to your MusiMap-managed inbound bucket only. MusiMap does not mint credentials for customer-owned external buckets.

Secret returned once

POST /v1/storage/credentials returns the AWS secret access key only once. GET /v1/storage/credentials never returns secrets. If you lose a secret, revoke the credential and create a new one.

Generated credentials can upload and read objects under your inbound prefix, but they cannot call s3:DeleteObject. Use the public delete endpoint above instead.

List credentials

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

Returns paginated metadata: name, access key ID, status, created and revoked timestamps. No secrets.

Create credential

curl -X POST "https://api.musimap.com/v1/storage/credentials" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-upload-key", "description": "CI pipeline uploads" }'

The response includes a one-time secret.secret_access_key. Store it immediately. Requires provisioned managed storage for your organisation.

Upload with AWS CLI

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="returned-once-only"
export AWS_DEFAULT_REGION="eu-west-1"

aws s3 cp ./catalog.csv s3://YOUR_BUCKET/inbound/catalogue/june/catalog.csv

Use the bucket name and inbound prefix from GET /v1/storage/config.

Revoke credential

curl -X DELETE "https://api.musimap.com/v1/storage/credentials/0190..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Revocation deletes the AWS access key and IAM user, then marks the credential as revoked. The call is idempotent when the credential is already revoked.

Typical workflow

  1. Call GET /v1/storage/config to confirm managed inbound storage is available.
  2. Call POST /v1/storage/inbound/uploads and PUT the file to the presigned URL.
  3. Optionally call GET /v1/storage/inbound/objects?object_key=... to confirm the upload.
  4. Call POST /v1/ingestions with an S3 mode referencing the uploaded object or prefix.
  5. Track progress with the ingestions read endpoints.

You can also manage storage credentials from the developers dashboard.