HTTP Endpoints

REST-style endpoints available alongside JSON-RPC. User-scoped endpoints usually require Authorization: Bearer <token>. Large-file chunk uploads can also use the scoped x-mcp-upload-token returned by prepare_local_file_upload.

Provenance

Every request to /api/mcp is tagged with a provenance — an identifier for which surface initiated it. ONCE auto-detects:

• AIMD — the request Origin / Referer matches app.aimusicdistributor.com, OR the JSON-RPC arguments include "provenance": "AIMD" (used for server-to-server calls).
• MCP — every other authenticated MCP client.

Submissions tagged AIMD are billed at 2 credits per AI-detected song (the AI surcharge); all other songs remain 1 credit. The provenance is persisted on the release row (releases.mcp_provenance) and visible in the admin AI dashboard.

Authentication

OAuth metadata discovery (no auth required)

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/api/mcp
• GET /.well-known/oauth-authorization-server
• GET /.well-known/openid-configuration

OAuth authorization + token

• GET /oauth/authorize
• POST /oauth/token
• POST /oauth/register

Most MCP clients use these automatically when they receive a 401 challenge from /api/mcp.

Upload

POST /api/mcp/upload (requires auth)

Multipart form-data with fields:

Returns fileUrl for use in submission payloads.

Large local files in Claude Code / Cursor

1. Call the prepare_local_file_upload MCP tool.
2. Upload chunks to POST /api/mcp/upload/chunk with x-mcp-upload-token.
3. Finish with POST /api/mcp/upload/complete using the same scoped token.

Draft Snapshot

POST /api/mcp/draft (requires auth)

Save work-in-progress metadata before final submission.

{
  "releaseId": "optional",
  "conversationId": "optional",
  "mode": "delta",
  "release": { ... },
  "tracks": [ ... ],
  "trackPatches": [ ... ],
  "uploadRequests": [ ... ],
  "status": "collecting"
}

Submit Release

POST /api/mcp/submit (requires auth)

{
  "release": { ... },
  "tracks": [ ... ],
  "releaseId": "optional",
  "conversationId": "optional"
}

Rate limited. On 429 response, check retryAfterSeconds.

Note: MCP submissions debit credits from the authenticated ONCE account.

AI Detection

The Vobile/Pex AI Song Detector is exposed as the detect_audio_ai MCP tool — there is no dedicated REST endpoint. After uploading audio, call the tool with the returned fileUrl to read back the detection result (including the predicted-model classification). See API Reference → AI Detection.

Profile & Credits

The agent can fetch the authenticated user’s profile and credit balance directly:

• get_profile MCP tool — returns id, email, name, signed avatar URL, patron + admin flags. Mirrors GET /api/profile.
• get_credits MCP tool — returns balance, lifetime aggregates, and recent transactions. Mirrors GET /api/credits.

Both tools require authentication. See API Reference → Profile & Credits.

List Releases

GET /api/mcp/releases?limit=100 (requires auth)

Returns the most recent releases for the authenticated user.

Release Metadata

GET /api/mcp/releases/:id/metadata (requires auth)

Returns merged metadata for a release (draft snapshot or latest merged data).

Release Status

GET /api/mcp/releases/:id/status (requires auth)

Returns store and aggregate status information.

Job Status

GET /api/mcp/release-jobs/:id (requires auth)

Returns job processing status and error information.