Beat Requests API

Create, manage, and fulfill custom beat requests on the BeatPass marketplace.

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-requests

Authentication: 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

Error	Code	Cause
Invalid duration	400	Duration must be 24, 48, or 72
Insufficient tokens	429	Not enough tokens for chosen duration
Description too short	422	Content under minimum length
Reference track required	422	Missing reference track URL

Submission

Error	Code	Cause
Request not found	404	Invalid request ID
Request expired	410	Duration window has closed
Duplicate submission	409	Same track already submitted
Submission limit reached	422	Maximum tracks per request reached
Duplicate audio detected	409	Audio fingerprint matches existing submission
Track not platform-hosted	422	Track must be uploaded to the platform
Fingerprint not completed	422	Track audio processing not finished
Not track owner	403	Must own or collaborate on the track
Self-submission blocked	403	Cannot submit to your own request

Deletion & Renewal

Error	Code	Cause
Unauthorized	403	Only the request owner can delete or renew
Request still active	409	Cannot renew a request that hasn’t expired
Renewal window expired	410	More than 30 days since expiration
No token for renewal	429	No tokens available

---

Related Resources

Rate Limits

API rate limiting and throttling.

Error Catalog

Beat request error codes.