Skip to main content

​
Overview

The Beat Requests API powers the custom beat request marketplace. Users spend tokens to create time-limited requests specifying their needs (genre, BPM, mood, budget). Producers browse active requests and submit tracks to fulfill them.
Base URL: https://open.beatpass.ca/api/v1/beat-requestsAuthentication: All beat request endpoints require a valid Bearer token.

​
Request Lifecycle

1

Create Request

User spends tokens to create a beat request with specifications (genre, BPM, mood, budget, reference track). Requests are active for 24, 48, or 72 hours.
2

Producers Browse

Producers view active requests and submit tracks that match the specifications.
3

Review Submissions

The requester reviews submitted tracks and connects with producers directly if interested.
4

Expire or Renew

Requests expire automatically after the chosen duration (24/48/72h). Expired requests can be renewed within 30 days by spending tokens again.

​
Token System

Beat requests use a token-based system tied to the user’s subscription plan:

Token Cost

24h = 1 token, 48h = 2 tokens, 72h = 3 tokens

Monthly Allocation

Tokens refresh monthly based on subscription plan

Refunds

Tokens are refunded when the owner deletes a request (capped at plan allowance)

​
Endpoints

​
List Active Requests

Get all active beat requests on the marketplace. 
GET /api/v1/beat-requests
Response: 
{
  "success": true,
  "data": [
    {
      "id": "req_abc123",
      "user_id": 1,
      "user_name": "BeatBuyer",
      "content": "Looking for dark trap beat, 140 BPM...",
      "genre": "Trap",
      "bpm_range": "135-145",
      "mood": "Dark",
      "budget": "\$50-100",
      "expires_at": "2025-01-16T14:30:00Z",
      "time_remaining": "23 hours from now",
      "hours_remaining": 23
    }
  ],
  "count": 5
}

​
Create Request

Create a new beat request by spending tokens. 
POST /api/v1/beat-requests
​
content
string
required
Description of the beat you’re looking for.
​
reference_track
string
required
Reference track URL or description for producers to understand the style.
​
genre
string
Preferred genre.
​
bpm_range
string
Preferred BPM range (e.g., “135-145”).
​
key
string
Preferred musical key.
​
mood
string
Desired mood or vibe.
​
budget
string
Budget range.
​
duration_hours
integer
How long the request stays active: 24, 48, or 72. Default: 24.
Response (201): 
{
  "success": true,
  "message": "Beat request created successfully! Active for 24 hours.",
  "data": {
    "id": "req_abc123",
    "content": "Looking for dark trap beat...",
    "expires_at": "2025-01-16T14:30:00Z",
    "time_remaining": "24 hours from now",
    "hours_remaining": 24
  },
  "token_info": {
    "tokens_remaining": 2,
    "tokens_spent": 1,
    "monthly_limit": 5,
    "used_this_month": 3,
    "plan_type": "pro",
    "plan_name": "Pro Plan",
    "reset_date": "2025-02-01",
    "days_until_reset": 16
  }
}
Token Errors (429): 
{
  "success": false,
  "message": "You need 2 tokens for a 48-hour request, but you only have 1 token.",
  "token_info": {
    "current_tokens": 1,
    "tokens_needed": 2,
    "monthly_limit": 5,
    "used_this_month": 4,
    "reset_date": "2025-02-01"
  }
}

​
Get Request

Get details for a specific beat request. 
GET /api/v1/beat-requests/{id}

​
Delete Request

Delete a beat request. Only the request owner can delete. 
DELETE /api/v1/beat-requests/{id}
When a request is deleted, the spent tokens are refunded to the owner (capped at plan allowance). For example, deleting a 72-hour request refunds up to 3 tokens, but never exceeds the user’s monthly token limit.

​
Submit Track

Submit a track to an active beat request. Producers use this endpoint to send their beats to a requester. Each producer can submit multiple tracks per request, up to the platform limit. 
POST /api/v1/beat-requests/{id}/fulfill
​
track_id
integer
required
The ID of the track to submit. Must be a platform-hosted track owned by (or collaborated on by) the authenticated user, with completed audio processing.
Validation Requirements:
  • Track must be uploaded to the platform (external links not accepted)
  • Track must have completed audio processing
  • Producer must own or collaborate on the track
  • Cannot submit to your own request
  • Cannot submit the same track twice to the same request

​
Get Submissions

Get the list of tracks submitted to a beat request. Only available to the request owner. 
GET /api/v1/beat-requests/{id}/submissions

​
Renew Request

Renew an expired beat request for an additional period. The renewal uses the same duration as the original request and costs the same number of tokens. Requests can only be renewed within 30 days of expiration. 
POST /api/v1/beat-requests/{id}/renew

​
Log Request View

Record that a producer has viewed a beat request. Used for analytics and engagement tracking. 
POST /api/v1/beat-requests/{id}/track-view
​
id
string
required
Beat request ID.

​
User-Specific Endpoints

​
My Requests

Get the authenticated user’s own beat requests. 
GET /api/v1/beat-requests/user/my-requests

​
My Submitted Tracks

Get tracks the authenticated user has submitted to beat requests. 
GET /api/v1/beat-requests/user/my-tracks

​
Token Status

Check the user’s current token balance and rate limit status. 
GET /api/v1/beat-requests/user/rate-limit-status

​
Reference Data

​
Statistics

Get platform-wide beat request statistics. 
GET /api/v1/beat-requests/statistics

​
Duration Tiers

Get available duration tiers and their token costs. 
GET /api/v1/beat-requests/duration-tiers
Response: 
{
  "success": true,
  "data": [
    { "hours": 24, "tokens": 1, "label": "24 Hours" },
    { "hours": 48, "tokens": 2, "label": "48 Hours" },
    { "hours": 72, "tokens": 3, "label": "72 Hours" }
  ]
}

​
Error Reference

​
Creation

ErrorCodeCause
Invalid duration400Duration must be 24, 48, or 72
Insufficient tokens429Not enough tokens for chosen duration
Description too short422Content under minimum length
Reference track required422Missing reference track URL

​
Submission

ErrorCodeCause
Request not found404Invalid request ID
Request expired410Duration window has closed
Duplicate submission409Same track already submitted
Submission limit reached422Maximum tracks per request reached
Duplicate audio detected409Audio fingerprint matches existing submission
Track not platform-hosted422Track must be uploaded to the platform
Fingerprint not completed422Track audio processing not finished
Not track owner403Must own or collaborate on the track
Self-submission blocked403Cannot submit to your own request

​
Deletion & Renewal

ErrorCodeCause
Unauthorized403Only the request owner can delete or renew
Request still active409Cannot renew a request that hasn’t expired
Renewal window expired410More than 30 days since expiration
No token for renewal429No tokens available

Rate Limits

API rate limiting and throttling.

Error Catalog

Beat request error codes.
Last modified on February 10, 2026