REST APIUploads

Uploads

There are three ways to get cover art and audio into your account. All require authentication. Cover art is stored as a square 3000×3000 PNG; audio is transcoded by the platform. Each endpoint returns a fileUrl you then reference when submitting a release.

EndpointUse when
POST /v1/filesYou have a small file in memory (≤ ~3 MB binary).
POST /v1/files/from-urlThe file is already at a public URL. Recommended for automated pipelines.
POST /v1/uploadsYou have a large local file and need a chunked session.

Small files (base64)

curl -X POST https://once.app/v1/files \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "coverArt",
    "file_name": "cover.jpg",
    "data_base64": "<base64>",
    "mime_type": "image/jpeg"
  }'

type is coverArt or audio. The base64 path is capped at ~3 MB binary (the gateway runs behind a ~4.5 MB request limit), so use it only for small assets.

Import from a URL

curl -X POST https://once.app/v1/files/from-url \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "type": "audio", "url": "https://example.com/track.wav", "file_name": "track.wav" }'

There is no size limit — the platform downloads the file server-side. This is the recommended method for automated, server-to-server pipelines.

Large files (chunked upload session)

For large local files, create a session and stream chunks directly to the platform (not through this gateway, so they are not subject to gateway request-size limits):

curl -X POST https://once.app/v1/uploads \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "type": "audio", "file_name": "track.wav", "file_size": 48000000, "file_type": "audio/wav" }'

The response includes session_id, upload_token, upload_header_name (x-mcp-upload-token), chunk_endpoint, complete_endpoint, and chunk sizing. To finish the upload:

  1. Upload raw or multipart chunks directly to chunk_endpoint, sending the upload_token in the upload_header_name header.
  2. POST { sessionId, fileName, fileType, type } to complete_endpoint with the same header.
AuthenticationAI Detection