VerseOne API Docs

Introduction

VerseOne API is a RESTful API that allows you to interact with the VerseOne platform. It provides endpoints for managing users, services, and other resources within the VerseOne ecosystem. The API is designed to be easy to use and integrate with your applications, providing a seamless experience for developers and users alike.

Base URL:https://app.verseone.net

This documentation aims to provide all the information you need to work with our API.

As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile). You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).

API Workflow Guide

Authentication
- To ensure the security of user data and system resources, all protected API endpoints require a valid access token. This token-based authentication mechanism verifies your identity and grants you permission to perform sensitive operations on behalf of a user account. The token is short lived for safety and must be included in each request to maintain continuous access.
Get Access Token
- Before interacting with any secured endpoint, your application must first obtain an access token by providing valid user credentials. This endpoint issues a Bearer token that you will use for subsequent requests.
Endpoint: POST /api/v1/login

Using the Token
- Once obtained, include the token in the Authorization header for all protected API calls.
  Example: Authorization: Bearer <token>
- Tokens expire after the configured lifetime. If you receive a 401 Unauthorized response, reauthenticate to obtain a new token.
Get All Releases

Endpoint: GET /api/v1/release

Requires authentication: Yes

Headers:
```
                                
                                    Authorization: Bearer {YOUR_AUTH_KEY}
                                    Content-Type: application/json
                                    Accept: application/json
                                
                            
```
What it does

This endpoint lets you retrieve release information that already exists in your system. It is typically used after a release has been created and formatted as a DDEX 3.8.2 Release Data Set. You can use it to confirm release metadata, status, and identifiers.

How to call it

Send a GET request to /api/v1/release with your authentication token in the header. Make sure your request format is JSON.

In simple steps
- Get your API access token from your dashboard
- Add the token to your request header as Authorization: Bearer {YOUR_AUTH_KEY}
- Send a GET request to /api/v1/release
- The server returns release information in structured format (aligned with DDEX metadata fields)
What you get back

You receive:
- The release record stored in the system
- Release metadata such as:
  - Title
  - Main artist name(s)
  - Release date
  - Identifiers (ISRC, UPC) if available
  - Track listing
  - Current delivery or ingestion status
- Data formatted to support DDEX 3.8.2 delivery workflows and downstream reporting
This response helps confirm that your release is correctly set up before distributing to DSPs.
Show Release Detail

Endpoint: GET /api/v1/release/{id}

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
URL Parameter:
id – The release ID you want to view. (Example: 1)
What it does

This call lets you view the full details of one specific release. If you already created a release in the system, this is how you check its status, metadata, and track listings. You might use this to confirm that everything is correct before generating and sending DDEX ERN messages to DSPs.

How to call it

Send a GET request to /api/v1/release/{id}, replace {id} with the actual release ID number. Include your API token in the Authorization header.

In simple steps
1. Identify the release you want to review (get its ID from your dashboard or previous API response).
2. Put your access token in the Authorization header:
```
                                
                                    Authorization: Bearer YOUR_AUTH_KEY
                                
                            
```
3. Send the GET request to: /api/v1/release/1 (Change 1 to your release ID.)
4. Check the response for:
  - Title
  - Artist(s)
  - Track list
  - ISRCs
  - UPC
  - Release date
  - Territory and delivery settings
This helps ensure your release is ready to move forward in the DDEX packaging stage.

What you get back

You receive a structured release record, for example:
- Release title and version name.
- Primary artist and contributor roles.
- UPC (release identifier).
- Track list with ISRC codes and durations.
- Artwork reference (if uploaded).
- Status indicators showing whether the release is draft, ready, or delivered.
- Any DDEX-related metadata fields needed for ERN 3.8.2 packaging.
This response gives you a complete snapshot of the release, so you can verify that everything is correct before delivery to DSPs.
Create Release and Tracks

Endpoint: OST /api/v1/release

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: multipart/form-data
                                Accept: application/json
                            
                        
```
Body:

file — required, max 50,000 KB. Upload a DDEX ERN 3.8.2 XML file or a ZIP containing the ERN XML plus referenced assets as your process requires.

What it does

Creates a new release and its tracks in one step by ingesting your DDEX 3.8.2 package. Parses the ERN, builds the Release, adds SoundRecordings, links contributors, and prepares the record for delivery workflows.

How to call it

Send a POST request with multipart/form-data. Include your API token in the Authorization header. Attach your DDEX ERN 3.8.2 XML or ZIP as the file field.

In simple steps
1. Prepare your DDEX ERN 3.8.2 package
  - Include Release-level identifiers (UPC/EAN).
  - Include ISRC per track.
  - Provide DisplayArtist/Contributor roles, titles, durations.
  - Add Deals: territory sets, start dates, use types.
  - Ensure UTF-8 encoding and valid XML.
2. Open your HTTP client
  - Set Content-Type: multipart/form-data.
  - Set Authorization: Bearer {YOUR_AUTH_KEY}.
  - Add file=@/path/to/your/ern_or_zip
3. Send the request to /api/v1/release.
4. Review the response
  - Confirm release_id.
  - Note created track_ids.
  - Read any validation warnings or errors.
5. Remediate if needed
  - Fix any missing identifiers, roles, or dates flagged in the response.
  - Re-upload with corrected DDEX.
6. Proceed with the workflow
  - Optional artwork or audio uploads if your flow separates assets.
  - Use GET /api/v1/release/{id} to verify stored metadata.
  - Deliver via your delivery endpoint when ready.
What you get back

A JSON payload confirming the ingest result, typically including:
- release_id and release status.
- An array of track_ids tied to the release.
- Key fields parsed from the ERN: title, label, UPC, track list with ISRCs, durations, primary artists, explicit flag.
- Deal and territory summaries that map to your DDEX DealList.
- Validation info:
  - Warnings for non-blocking issues (naming, optional fields).
  - Errors for blocking issues (missing UPC/ISRC, bad dates, invalid territories).
- Next actions:
  - Whether the release is ready for delivery or needs fixes.
  - Links or IDs for follow-up calls (e.g., GET /api/v1/release/{id}).
Practical tips
- Validate your ERN against the 3.8.2 schema before upload.
- Keep file names stable between the ERN references and the ZIP contents.
- Use consistent territory codes (ISO 3166-1 alpha-2).
- Ensure durations are in a standard format (e.g., ISO 8601 or total milliseconds per your spec).
- Keep contributor roles aligned with DDEX dictionaries (e.g., MainArtist, FeaturedArtist, Writer, Producer).
This endpoint is your fastest path to stand up a complete release record that aligns with DDEX 3.8.2.
Upload Artwork Image

Endpoint: POST /api/v1/release/image

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: multipart/form-data
                                Accept: application/json
                            
                        
```
Body Parameters:
- release_id — the ID of the release you want to attach the artwork to.
- artwork — the image file. It must be an actual image and not larger than 50MB.
What it does

This endpoint attaches an artwork image to an existing release. It updates the release so that the cover art is included when preparing DDEX 3.8.2 messages for DSP delivery. In simple terms: this is how you upload the cover image that will appear on streaming platforms.

How to call it

Send a POST request using multipart/form-data. Include your API key in the Authorization header. Add the release ID in the form data and attach the artwork image as a file.

In simple steps
1. Make sure the release already exists in the system and you know the release ID.
2. Prepare your artwork file. Use a clear, square image (for example 3000×3000px).
3. Set the request headers:
  - Authorization: Bearer YOUR_AUTH_KEY
  - Content-Type: multipart/form-data
4. Send a POST request to /api/v1/release/image.
5. Include the release ID as a text field.
6. Attach the image file as the artwork field.
7. Submit the request.
What you get back

You will receive a confirmation message showing that the artwork was successfully uploaded and linked to the release. The response will also include a reference or path to the stored image. If anything is wrong (for example, the file is not an image or is too large), the response will explain what needs to be fixed.
Upload Track File

Endpoint: POST /api/v1/file/upload

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: multipart/form-data
                                Accept: application/json
                            
                        
```
Body Parameters:
- is_last — tells the system if this is the final file in the upload sequence.
- file — the audio file. Must not exceed 10MB.
- release_id — the release this track belongs to.
- upload_id — a unique ID you choose to group this upload session.
- track_id — optional. Use only when updating an existing track.
- replaces — optional. Use if you are replacing a specific previous audio file.
What it does

This endpoint uploads the audio track file that will be used for distribution. It links the uploaded file to the release and prepares it for DDEX 3.8.2 delivery. If the track already exists, you can update it by providing the track_id or replaces parameter.

How to call it

Send a POST request with multipart/form-data. Include your Authorization token in the header. Attach the audio file and include the release ID and upload ID in the form data.

In simple steps
1. Confirm the release is already created in the system and you know its release_id.
2. Prepare your audio file. Use a clean WAV or high-quality MP3 as required.
3. Generate or choose a unique upload_id to identify this upload group.
4. Set your request headers:
  - Authorization: Bearer YOUR_AUTH_KEY
  - Content-Type: multipart/form-data
5. Send a POST request to /api/v1/file/upload.
6. Include:
  - release_id
  - upload_id
  - file (the audio file itself)
  - is_last
  - Optional: track_id or replaces if updating a track.
7. Submit the request.
What you get back

You will receive a confirmation message showing the upload result. The response will include the track reference that was created or updated, along with status information. If something needs attention (for example, file too large or missing required fields), the response will explain what to correct.
Get Genres

Endpoint: GET /api/v1/genres

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
What it does

This endpoint returns the list of available music genres supported by the system. These genres are used when building or updating a release so the metadata matches the DDEX 3.8.2 standard and DSP requirements. In short, this is where you get the approved genre names to use when tagging your music.

How to call it

Send a GET request to /api/v1/genres. Include your API key in the Authorization header.

In simple steps
1. Make sure you have your API access token.
2. Set your Authorization header: Authorization: Bearer YOUR_AUTH_KEY
3. Send a GET request to: /api/v1/genres
4. Wait for the response to load the list of genres.
What you get back

You receive a list of genre names and their IDs. You can use these IDs when creating or editing a release so that the release metadata is recognized properly across DSPs. If your release includes sub-genres, you may see additional options depending on your platform’s catalog.
Get Subgenres for a Genre

Endpoint: GET /api/v1/subgenres

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
URL Parameter:

genre — the ID of the main genre you want to view subgenres for.

What it does

This endpoint returns all the subgenres linked to a specific main genre. It helps you choose a more precise genre label when tagging your release, which improves how platforms classify the music.

How to call it

Send a GET request to /api/v1/subgenres and include the genre ID in the URL parameters. Make sure your Authorization header contains a valid token. Example: /api/v1/subgenres?genre=7

In simple steps
1. First, get the main genre ID (for example, from /api/v1/genres).
2. Set your Authorization header: Authorization: Bearer YOUR_AUTH_KEY
3. Send a GET request to: /api/v1/subgenres?genre=GENRE_ID
4. Wait for the server to return the list of subgenres.
What you get back

You receive a list of subgenres that belong to the selected genre. Each item includes a subgenre ID and name. You can use these when creating or editing your release so the genre tagging aligns with DDEX 3.8.2 and DSP classification rules.
Get Moods

Endpoint: GET /api/v1/moods

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
What it does

This endpoint returns the list of available mood tags. Mood tags are optional descriptive labels you can apply to a release or track. They help DSPs and recommendation systems understand the feeling or vibe of the music.

How to call it

Send a GET request to /api/v1/moods. Include your API key in the Authorization header to confirm your identity.

In simple steps
1. Get your API access token from your dashboard.
2. Add your Authorization header: Authorization: Bearer YOUR_AUTH_KEY
3. Send a GET request to: /api/v1/moods
4. Wait for the response containing the mood list.
What you get back

You will receive a list of mood names and IDs. You can use these when creating or editing a release, so the metadata is more detailed and better aligned with DDEX 3.8.2 recommendations. This helps improve music categorization and search results on streaming platforms.
Get Languages

Endpoint: GET /api/v1/languages

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
What it does

This endpoint provides a list of supported languages you can assign to a release or track. These language codes help ensure your metadata matches DDEX 3.8.2 standards and is recognized correctly by streaming platforms.

How to call it

Send a GET request to /api/v1/languages. Make sure your Authorization header contains your valid API token.

In simple steps
1. Retrieve your API access token from your dashboard.
2. Add the Authorization header: Authorization: Bearer YOUR_AUTH_KEY
3. Send a GET request to: /api/v1/languages
4. Wait for the response to load the list.
What you get back

You receive a list of language names and their associated codes. You can use these codes when creating or updating a release so the language metadata is correct and consistent across DSPs.
Get Bundle Prices

Endpoint: GET /api/v1/prices

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
What it does

This endpoint returns the available bundle pricing options used when setting the commercial terms for a release. These prices help define how the release will be positioned in stores according to DDEX Deal terms, such as pricing tiers.

How to call it

Send a GET request to /api/v1/prices. Include your Authorization token so the system knows who is requesting the data

In simple steps
1. Get your API access token.
2. Add your Authorization header: Authorization: Bearer YOUR_AUTH_KEY
3. Send a GET request to: /api/v1/prices
4. Wait for the response.
What you get back

You receive a list of bundle price options. Each item typically includes a price tier or code that can be applied to a release when defining its commercial terms in DDEX. You will use these values later when setting or updating your release’s deal and territory settings.
Update Release or Tracks Data

Endpoint: PUT /api/v1/release/{id}

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: multipart/form-data
                                Accept: application/json
                            
                        
```
URL Parameter:

id — the release you want to update.

Body Parameter:

file — the upload file that contains updated release or track data. This must be a valid file and must not be larger than 50MB.

What it does

This endpoint updates the data for an existing release. It takes in a file that may contain corrected metadata, updated track information, or new DDEX details. This is useful if you need to fix titles, contributor roles, ISRCs, track order, or other metadata before delivery.

How to call it

Send a PUT request to the release’s URL, include the release ID, and attach the updated data file. Use multipart/form-data and include your authorization token in the header.

In simple steps
1. Make sure the release already exists and you know its ID
2. Prepare your update file. This may come from your DDEX ERN editor or metadata preparation tool.
3. Set your request headers:
```
                                    
                                        Authorization: Bearer YOUR_AUTH_KEY
                                        Content-Type: multipart/form-data
                                    
                                
```
4. Send a PUT request to: /api/v1/release/{id} replacing {id} with the actual release ID
5. Attach the updated file as the file field in the request.
6. Submit the request.
What you get back

You receive a confirmation that the release and its tracks were updated. The response will show the release ID and reflect any changes made. If something in the file is incorrect or incomplete, the response will explain what needs to be fixed before retrying.
Delete Release or Track

Endpoint: DELETE /api/v1/release/delete

Requires authentication: Yes

Headers:
```
                            
                                Authorization: Bearer {YOUR_AUTH_KEY}
                                Content-Type: application/json
                                Accept: application/json
                            
                        
```
Body Parameters:
- release_id — the ID of the release.
- track_id — the ID of the track, if you are deleting only a track.
What it does

This endpoint deletes a release or a specific track linked to a release. Use this if you need to remove content before final delivery, correct mistakes, or clean up unused uploads. If you provide only a release ID, the entire release is removed. If you include a track ID, only that track will be removed.

How to call it

Send a DELETE request with a JSON body containing either the release ID alone or both the release ID and track ID. Include your Authorization token so the system knows you have permission to delete.

In simple steps
1. Identify the release or track you want to remove.
2. Prepare your Authorization header:
```
                                    Authorization: Bearer YOUR_AUTH_KEY
                                
```
3. Send a DELETE request to: /api/v1/release/delete
4. Include: release_id if deleting the entire release. release_id and track_id if deleting only one track.
5. Submit the request.
What you get back

You receive a message confirming the deletion. If the release or track did not exist, or could not be removed, the response will explain why. Once deleted, the release or track will no longer be available for editing or delivery.

Royalties API Walkthrough

Royalties — Payouts List

Endpoint: GET /api/v1/payouts

This endpoint gives you a paginated list of all royalty payouts. It’s useful for showing users their payout history or for building finance and audit dashboards.

What it does
- Returns a list of payout records (like payments to bank accounts, PayPal, or mobile money).
- You can filter results by user, payout status, or time period (for example, “show all payouts in March”).
- Includes pagination info, so you can load results page by page without missing any records.
Example use: An admin dashboard showing all past payouts made to artists with the option to filter by date or payment method.
Royalties — Set Payout Threshold

Endpoint: POST /api/v1/setThreshold

This sets the minimum balance an account must reach before a payout can be requested or triggered automatically.

What it does
- Saves the payout threshold for the logged-in account.
- Used by:
  - Manual payouts: Prevents a withdrawal if the balance is below the threshold.
  - Automatic payouts: The system only triggers payments once the balance meets or exceeds the set amount.
  - Notifications: Can be used to notify users once their balance passes the payout limit.
- It doesn’t actually move money, it only sets a rule.
Example use: If you set the threshold to $500, an artist can’t withdraw or be auto-paid until their balance hits $500.
Royalties — Set Monthly Payout Type

Endpoint: POST /api/v1/payouts/set-monthly-type

This defines how monthly payouts work for a user, either automatically or manually.

What it does
- Manual payouts: The user must click “Withdraw” when they’re ready.
- Automatic monthly payouts: The system sends payments automatically, either:
  - On a specific date each month (for example, the 15th), or
  - At the end of each month.
- It follows other payout conditions; like KYC status, payout thresholds, or account holds.
- It doesn’t process payments right away. It just sets the payout rule for future cycles.
Example use: A label can choose to receive payouts automatically every month instead of manually requesting them.
Royalties — Create Payout Request

Endpoint: POST /api/v1/payouts

This is used when a user requests to withdraw their royalties (for example, by clicking “Withdraw” in your dashboard).

What it does
- Checks that the request is valid; confirms the user, verifies the available balance, and enforces minimum payout limits.
- Locks the requested amount so it can’t be withdrawn twice.
- Creates a payout record with a pending status (like pending_review or processing).
- Starts your payout workflow; things like KYC/AML checks, risk review, or sending the actual payment.
Example use: When an artist requests a $200 withdrawal, this endpoint logs it as “pending,” ensuring the same funds aren’t requested again.
Billing — Get Invoice

Endpoint:GET /api/v1/invoice

This retrieves a specific invoice for the logged-in account — useful for billing history, audits, or PDF downloads.

What it does
- Returns one invoice using its ID or number.
- Includes all billing details: header info, line items, taxes, discounts, subtotals, and totals.
- If the request header includes Accept: application/pdf, it can return a downloadable PDF version.
- Ensures users only access their own invoices (no cross-account access).
Example use: A user clicks “View Invoice” in their billing history, and the system fetches it via this endpoint.
Royalties — Income List

Endpoint: GET /api/v1/incomes

This lists all detailed royalty earnings, such as income from streaming, downloads, user-generated content, or Content ID.

What it does
- Shows every earning line linked to releases, tracks, and DSPs.
- You can filter by time period, artist, DSP, ISRC, UPC, or territory.
- Supports pagination for large data sets.
- Optionally returns total summaries for easy reporting.
Example use: An artist dashboard showing how much was earned from Spotify streams in Nigeria for September.
Royalties — Get Pending Payouts (Current User)

Endpoint: GET /api/v1/payouts/pending

This endpoint lists all pending payout requests for the authenticated user. Use it to show “Pending Withdrawals” or review payout queues.

What it does
- Only returns payouts belonging to the logged-in user.
- Shows payout requests that are still being processed (e.g., pending, pending_review, processing).
- Excludes completed, failed, or canceled payouts.
- Includes pagination data if the list is long.
Example use: A dashboard section where a user can track payouts that are not yet paid out.

VerseOne API Docs

Introduction

API Workflow Guide

Authentication

Get All Releases

Show Release Detail

Create Release and Tracks

Upload Track File

Get Genres

Get Subgenres for a Genre

Get Moods

Get Languages

Get Bundle Prices

Update Release or Tracks Data

Delete Release or Track

Royalties API Walkthrough

Royalties — Payouts List

Royalties — Set Payout Threshold

Royalties — Set Monthly Payout Type

Royalties — Create Payout Request

Billing — Get Invoice

Royalties — Income List

Royalties — Get Pending Payouts (Current User)

CONTENT