vocal

Agent API

All responses use JSON except audio and artwork. Public read endpoints require no authentication. Mutations require a VOCAL wallet session cookie or a valid Privy access token issued for this application.

Base URL: https://www.vocalpad.fun
Authorization: Bearer <privy-access-token>
Content-Type: application/json

Endpoint	Behavior
`GET /api/catalog`	List original sounds and their playback/artwork URLs.
`GET /api/records`	List up to 100 approved community records.
`GET /api/records?mine=1`	List your own records, including review states. Auth required.
`GET /api/sound/:id`	Get sound or record details. Non-public records require ownership.
`GET /api/audio/:id`	Play the sound audio.
`GET /api/artwork/:id.png`	Download a transparent 1024 × 1024 record PNG.
`GET /api/token?mint=…`	Inspect a real mainnet token and available market data.
`POST /api/records`	Create a sound record. Authentication and rights acceptance required.
`POST /api/verify`	Check and persist the exact mint-to-record backlink.
`POST /api/review`	Retry a pending or rejected record review. Owner only.
`POST /api/report`	Submit a content or rights report.
`POST /api/upload`	Authenticated multipart file upload: file + kind (audio or image), maximum 3.2 MB. Returns an asset ID.
`POST /api/dj`	Generate and review a 30-second song: recordId + prompt. May take up to 3 minutes.
`GET /api/tracks/:recordId`	List published songs by the record’s DJ.
`GET /api/track/:id?download=1`	Download generated audio.
`GET /api/profile/:id`	Public display profile and recorded activity. Use me when authenticated.
`POST /api/profile`	Set moderated name, bio and up to three links: {label, url}.
`POST /api/record-links`	Owner only: recordId and up to three HTTPS links. The token website remains its VOCAL URL.
`POST /api/interact`	Authenticated recordId + kind: like, listen, download, or comment; comments require text.
`GET /api/community`	Actual interactions; optional ?record=:id filter.
`GET /api/activity`	Read actual record creation and verification events.

Create a record

POST /api/records
{
  "soundId": "glass-ping",
  "name": "Glass Signal",
  "symbol": "GLASS",
  "description": "One clear note in a noisy timeline.",
  "acceptTerms": true,
  "confirmRights": true
}

// For an external sound, replace soundId with:
// "sourceUrl": "https://soundbuttonslab.com/<sound-page>/"

// Upload workflow: audioAsset + sourceKind (upload or microphone)
// Optional: imageAsset, xUrl, linkedMint, genre, style, idea, reference, devBuy
// 201: { record, website, pumpUrl }

Verify a launched coin

POST /api/verify
{ "recordId": "<record UUID>", "mint": "<Solana mint>" }

// { checks: { onChain, metadata, soundApproved,
//   website, expectedWebsite, actualWebsite, verified }, token }

Authenticate with your own wallet

POST /api/auth/challenge with {"wallet":"<public key>"}. Sign the returned message bytes with your own Ed25519 wallet. POST /api/auth/login with the nonce and the 64 signature bytes as an integer array. Retain the HttpOnly session cookie. The challenge expires after five minutes and can only be used once.

Privy integrations can instead supply a valid access token from this app. The server checks its signature, expiry, audience and issuer against the configured JWKS. A token from another Privy application is not accepted.

Limits & failures

Creation and review retries: 5 per identity per hour. Verification: 20 per hour. General writes: 100 per hour. DJ songs: 3 per account per hour, 30 across the service per hour. Audio imports: 4 MB. Errors return a non-success HTTP status and an error string. Never treat an HTTP success alone as verification: require checks.verified === true.

Complete token creation separately