API Reference
HTTP endpoints for ONCE MCP. All endpoints require Authorization: Bearer <token> unless noted.
Base URL: https://beta.once.app
Authentication
Login
Get an access token. No authentication required.
Request
{
"username": "user@email.com",
"password": "..."
}Response
{
"access_token": "...",
"refresh_token": "...",
"expires_in": 3600,
"token_type": "bearer",
"user": {
"id": "...",
"email": "user@email.com"
}
}Uploads
Multipart Upload
Upload cover art or audio via multipart form-data.
Form Fields
| Field | Type | Description |
|---|---|---|
file | binary | The file to upload |
type | string | coverArt or audio |
Response
{
"success": true,
"fileUrl": "/api/files/cover-art/USER_ID/file.jpg",
"fileName": "file.jpg",
"userId": "..."
}Initialize Chunked Upload
Start a chunked upload session for large files.
Request
{
"fileName": "Track.wav",
"fileSize": 2286757,
"fileType": "audio/wav",
"totalChunks": 2,
"sessionId": "uuid-v4",
"type": "audio"
}Upload Chunk
Upload a single chunk. Supports multipart, JSON base64, or raw bytes.
Multipart Fields: chunk, chunkIndex, sessionId, type
JSON Request
{
"chunkBase64": "...",
"chunkIndex": 0,
"sessionId": "uuid-v4",
"type": "audio"
}Raw Bytes Headers: x-session-id, x-chunk-index, x-upload-type
Complete Chunked Upload
Finalize a chunked upload session.
Request
{
"sessionId": "uuid-v4",
"fileName": "Track.wav",
"fileType": "audio/wav",
"type": "audio"
}Drafts
Save Draft
Persist a draft snapshot before submission.
Request
{
"releaseId": "optional",
"conversationId": "optional",
"mode": "delta",
"release": { ... },
"tracks": [ ... ],
"trackPatches": [ ... ],
"uploadRequests": [ ... ],
"status": "collecting"
}Releases
Submit Release
Submit a release for distribution. Rate limited; check retryAfterSeconds on 429.
Request
{
"release": {
"title": "My Release",
"primary_artist_name": "Artist Name",
"genre": "Pop",
"release_date": "2026-02-01",
"cover_art_file_url": "/api/files/cover-art/USER_ID/cover.jpg"
},
"tracks": [
{
"title": "My Release",
"primary_artist_name": "Artist Name",
"audio_file_url": "/api/files/audio/USER_ID/track.wav",
"explicit_flag": false,
"writers": [{ "name": "First Last" }]
}
],
"releaseId": "optional",
"conversationId": "optional"
}List Releases
Get recent releases for the authenticated user.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | number | Max results (default 100) |
Get Release Metadata
Get merged metadata for a release.
Get Release Status
Get store delivery and aggregate status.
Get Job Status
Get processing job status and errors.