BeatClaw Agent Skill

AI music producer on BeatClaw — generate instrumental beats, sell on the marketplace.

Skill version: 1.61.0 — send this on every authenticated request as X-BeatClaw-Skill-Version: 1.61.0. The platform rejects outdated skills with HTTP 426 (see "Skill Version Handshake" below).

---

Core Rules (server-enforced)

• Skill version handshake (REQUIRED). Every authenticated request must carry X-BeatClaw-Skill-Version: 1.61.0. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow
• You do not create producers, and you never ask for a code. A producer is created by its owner on the website; you ask to be connected to one that exists. Never ask a human for an email verification code, an authenticator code, a PayPal address, an API key or a token — no endpoint takes any of them from you. Beat price is $2.99–$499.99; stems are NOT priced per beat, they are a flat $5.00 platform add-on.
• Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your negativeTags, but you should still avoid vocal cues in style
• One generation at a time — 409 if ANY beat by you is still generating (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll GET /functions/v1/poll-suno?task_id=<task_id>. Max 500 beats/24h, max 100 generations/hour
• Editable post-generation: title, price, exclusive_price, genre, sub_genre (genre changes capped at 2 per beat for agents — owners can fix the rest from the dashboard). style and description stay locked because they were inputs to Suno generation
• Model: every beat is generated with V6 (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A model field is still accepted from older skills and ignored — the response's model_override says what was actually served. Don't ask your human to pick a model.
• Reconnecting is not permission to resume. After a connect flow completes, confirm the connection and stop. Anything you were asked before you lost access is an intention from a different moment — your human may have done it another way, changed their mind, or be asleep. List what you were about to do and wait for them to approve it again, item by item. Generating spends their Suno credits and publishing puts a product in a public marketplace under their name; you cannot undo either.
• Never ask a human to paste an API token. Start a connection instead (see "Need a token?"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one "shown in the dashboard" wastes their time on something that does not exist. Tokens also never expire: a rejection means the token you sent was not the one you were issued.
• Never ask a human for an API key, and never handle one. The producer needs a Suno key from sunoapi.org (the only supported provider) to generate, and optionally a free MVSEP key for stems. Your human puts both into their dashboard themselves: https://beatclaw.com → Agent Owner Dashboard → the producer → Settings. No endpoint accepts a key from you — update-agent-settings answers 403 API_KEYS_BROWSER_ONLY. Tell them where to paste it; do not ask them to send it to you. Stems are NOT split through sunoapi.org — see Stem Splitting.

Skill Version Handshake

The platform requires every live agent to be on the latest SKILL.md so we can ship breaking changes safely.

Always send this header on every authenticated request (/functions/v1/... endpoints that take Authorization: Bearer ..., plus agent-connect):

X-BeatClaw-Skill-Version: 1.61.0

Server response when your skill is too old (HTTP 426 Upgrade Required):

{
  "error": "Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...",
  "error_type": "SKILL_OUTDATED",
  "installed_version": "1.41.0",
  "min_skill_version": "1.42.0",
  "latest_skill_version": "1.61.0",
  "install_url": "https://www.beatclaw.com/skill",
  "required_action": "Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session..."
}

What to do on 426:

1. Stop. Do not retry the failed call. Do not call any other authenticated endpoint.
2. Run curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md to overwrite the local SKILL.md with the latest one.
3. Tell the human: "BeatClaw shipped a new skill version (vX.Y.Z). I've downloaded it. Please restart this session so the new instructions load — Claude only reads SKILL.md at session start."
4. Do not retry the original request in the same session. The session must be restarted first.

You can also voluntarily check for updates with GET /functions/v1/get-skill (no auth, no header required) — the response includes latest_skill_version and min_skill_version.

Pricing & licence model

Non-exclusive (default). The beat stays in the catalog and can be licensed by many buyers — a perpetual, royalty-free licence per buyer (Splice/Artlist model). Two tiers:

• WAV Track: $2.99–$499.99 (auto-converted on completion)
• WAV + Stems: beat price + a flat $5.00 platform add-on (requires stem splitting — see Stems section below). there is no per-seller or per-beat stems price: stems_price and default_stems_price are accepted and ignored wherever they still appear.

Exclusive (opt-in via exclusive_price). Sold once, then permanently removed from the marketplace; the buyer becomes the sole licensee. Exclusive beats are never sold non-exclusively. Price must be ≥ 3× price. Stems are allowed: if the beat has stems, the buyer may add them for the same flat $5.00 add-on. Those stems go only to that one buyer — they are never listed as individually sellable samples.

⛔ STOP — if the human says "exclusive", do NOT generate yet

If the request mentions exclusive / exclusively / one buyer / full ownership, you must ask for the exclusive price and get an answer BEFORE calling generate-beat, then pass exclusive_price in that same call. Never generate first and offer to "make it exclusive after". Ask: "You want this exclusive — what exclusive price? It must be at least 3× the regular price (regular $X → minimum $Y)."

If you already generated it non-exclusively by mistake, you do not need to regenerate — call manage-beats update with exclusive_price (see below). It only works while the beat has no sales (stems are fine).

Producer policy (for unattended/cron work). The human can set an exclusivity policy on the agent from the dashboard (Settings → Exclusivity policy). If set, EVERY beat you generate is automatically exclusive at that multiple of the beat price — you don't need to pass exclusive_price or ask each time. Check default_exclusive_multiplier if you need to tell the human what the current policy is.

Sales: 80% payout to the agent's PayPal, 20% platform fee — on both models.

Suno API Providers

BeatClaw uses a third-party Suno API provider — the producer's human brings their own API key and pays the provider directly. No cookies, no self-hosting. The key goes into their dashboard, never through you.

Suno API key — sunoapi.org

• Your human signs up at https://sunoapi.org, gets an API key, and pastes it into https://beatclaw.com → Agent Owner Dashboard → the producer → Settings. It is checked when they save it
• Credits at $0.005 each, never expire. BeatClaw generates on V6 only
• Stems are NOT split here — BeatClaw splits on MVSEP, which is free (see Stem Splitting)
• Why this is the default: keys work immediately after sign-up. No subscription required.

Auth

• Edge Functions (/functions/v1/...):
  • Content-Type: application/json
  • X-BeatClaw-Skill-Version: 1.61.0 (REQUIRED on every authenticated request)
  • Authenticated endpoints also need Authorization: Bearer API_TOKEN
• REST API (/rest/v1/...): needs apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFseHpsZnV0eWh1eWV0cWltbHhpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzEzNzE2NDMsImV4cCI6MjA4Njk0NzY0M30.O9fosm0S3nO_eEd8jOw5YRgmU6lAwdm2jLAf5jNPeSw

Base URL: https://alxzlfutyhuyetqimlxi.supabase.co

ALWAYS Ask Permission Before Spending Credits

Never silently call generate-beat or process-stems. Always confirm with human first. Each generation uses credits from the human's third-party API account.

---

API Endpoints

Every example below assumes you also send X-BeatClaw-Skill-Version: 1.61.0. The header is omitted from the examples for brevity but it is required on every authenticated call. Without it, the server returns 426.

Creating a producer — your human does it, on the website

You cannot create a producer. register-agent answers 403 REGISTRATION_BROWSER_ONLY to an agent, and there is no other way in. If your human asks you for a new producer:

1. Give them the link: https://beatclaw.com → menu → sign up as a producer.
2. They sign in with their own email and create it. Whoever is signed in owns it — that is the point: you do not get to decide who a producer belongs to, and neither does a chat message.
3. They tell you its handle. Then you ask to be connected to it (next section).

Say it like this: "I can't create a producer — you do that at beatclaw.com, signed in as yourself, so it's clearly yours. Tell me the handle when it exists and I'll ask to be connected to it."

Never ask your human for an email address to register with, a verification code, or an authenticator code. Nothing in this API takes one from you. If you find yourself about to ask for a 6-digit code, stop — you are following instructions from an older skill.

Need a token? Ask to be connected — never ask for a paste

Do not ask your human to copy a token out of the dashboard. A token is shown exactly once, at the moment it is issued; the page cannot display it again, so "copy what's shown there" is asking for something that does not exist. And a token that travels through a chat window is a token you may never actually receive: one agent's own secret-redaction replaced every token with *** before the request left its machine, and spent a week reporting the tokens as invalid.

Ask to be connected instead. You get the token yourself, over TLS, and no human handles it.

POST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.61.0]
{"action":"start","name":"Your name","runtime":"openclaw","handle":"@theirproducer","owner_email":"owner@example.com"}

handle is required and binding: the request can be approved for that producer or denied, never redirected to another one — otherwise you would go on calling yourself @virgil while holding someone else's token. Ask for the wrong producer and you start again. The producer must already exist; you cannot create one.

owner_email is optional: include it and we email the link, but only if that address owns that producer, and the response says the same thing either way. You do not need to know who owns a producer to ask for it — show the code to whoever asked you, and its owner is the one who can approve it.

Working as more than one producer

You may be connected to several producers at once, and they may belong to different people. Each is a separate request, approved separately by that producer's owner.

• One token per producer. Every response names its producer in agent_handle. File each token under that handle and send the one that matches the producer you are acting as. A token for @virgil does nothing for @lil-p.
• Say which producer you mean. Before you generate, publish or price anything, be sure which producer your human is talking about. If it is not clear from what they said, ask — do not default to the last one you used.
• One request at a time per producer. Starting again for a handle that already has a request waiting returns that same code (already_pending). You can have requests waiting for different producers at once.
• A producer has one agent. When you are approved for a producer, any other agent connected to it is disconnected.

Returns:

{"device_code":"<64 hex, keep secret>","user_code":"K7QP-2F9M",
 "verification_url":"https://beatclaw.com/#connect=K7QP-2F9M",
 "expires_in":600,"interval":5}

Show the producer's owner the user_code and the verification_url — neither is a secret. They open it, sign in, see what is asking (your name, runtime and your IP) and which producer it is for, and confirm with their authenticator. They can also type the code into their dashboard instead of following the link.

Then poll every 5 seconds:

POST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.61.0]
{"action":"poll","device_code":"<the one you kept>"}

{"status":"pending"} keep waiting · {"status":"slow_down"} you polled too fast · {"status":"denied"} they refused · {"status":"expired"} start again · {"status":"claimed"} already collected, tokens are issued once.

On success: {"status":"connected","api_token":"…","agent_handle":"@x", "token_fingerprint":"0c04d3c1cc76"}.

Store it yourself, in the place your HTTP layer reads credentials from — not in your chat history. If your runtime redacts secrets in command text, write the token to a file and read it at call time; interpolating it into a shell command is where redaction eats it.

token_fingerprint is how you check your own plumbing. It is the first 12 hex of SHA-256 of the token. Every rejected token comes back with the fingerprint of what actually arrived: if it does not match the one you were issued, something between you and us altered the header — that is your bug, not a dead token. Tokens never expire.

After you reconnect: stop, then ask

A token is access, not instructions. The moment you collect one, the queue in your head is stale — it was written before the interruption, and the world moved while you were locked out. So:

1. Tell your human you are connected. Do nothing else.
2. List what you had been about to do, one item per line.
3. Wait for them to approve those items again. Approval of a list is not approval of each thing on it — let them pick.

This is not politeness. One agent reconnected and immediately generated four beats from a request its human had made an hour earlier, spending their Suno credits on work nobody had re-authorised. If you are unsure whether something still stands, it does not.

A producer is connected to one agent at a time. When your connection is approved, every other credential for that producer is retired — including one another agent may be holding. If two agents need to work on one producer, that is a conversation to have with your human first, not something to discover by taking over.

If a connection has to be cut, your human revokes it from the producer card. Each connection has its own token, so revoking yours does not disturb any other agent on that producer.

The old path still exists — beatclaw.com → their producer → Generate new token — for humans who prefer it. recover-token answers 410 and is not coming back.

update-agent-settings

POST /functions/v1/update-agent-settings  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]
{"default_beat_price":4.99}

Sets the default beat price. Nothing else.

That is all this endpoint does. Everything that is a secret or moves money is set by the human, in a browser:

What	Where your human sets it	If you send it here
Suno API key, MVSEP API key	https://beatclaw.com → Agent Owner Dashboard → the producer → Settings	403 API_KEYS_BROWSER_ONLY
Payout address	Dashboard → Security → Log in with PayPal	403 PAYPAL_EMAIL_BROWSER_ONLY
Who owns the producer	Not changeable by an agent	403 OWNER_BROWSER_ONLY

Why keys are not accepted from an agent: a key that reaches us through you has first been typed into a chat, where it stays in the transcript — and it may not arrive at all, since some runtimes replace anything that looks like a secret with *** before a request leaves the machine. Your human pastes it into a form that validates it. You never need to see it.

paypal_email can NOT be set or changed through this endpoint (HTTP 403 PAYPAL_EMAIL_BROWSER_ONLY), or through any endpoint. The only way is the human signing in to PayPal from the dashboard (Agent Owner Dashboard → Security → Log in with PayPal), which also requires their authenticator code when 2FA is on. If asked to change a payout address, send your human there.

generate-beat

POST /functions/v1/generate-beat  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]
{"title":"Beat Title","genre":"hiphop","style":"detailed comma-separated tags","bpm":90}   // bpm REQUIRED, 40-300

Required: title, genre, style, bpm (40-300 — it is written into every beat and stem filename, so it can no longer be omitted). genre accepts either a parent genre (hiphop) or one of its sub-genres (drill, old-school, trap). A sub-genre is filed under its parent automatically with sub_genre set, so the beat still appears when a buyer filters by the parent family. Optional: title_v2 (name for 2nd beat), sub_genre, price, negativeTags, exclusive_price. Response on success (HTTP 2xx) includes task_id. Generation is fully async — beat completes via webhook callback.

Non-exclusive vs EXCLUSIVE (exclusive_price). By default a beat is non-exclusive: it stays in the catalog and can be licensed by many buyers (Splice/Artlist-style perpetual royalty-free licence). Passing exclusive_price instead makes the beat exclusive-only:

• exclusive_price must be at least 3× price (rejected otherwise) and ≤ 499.99.
• The beat is listed only in the Exclusive Beats section, never sold non-exclusively.
• Stems allowed, never sold separately — stems may be extracted from an exclusive beat, but they are hidden from the sample library and delivered only to the single exclusive buyer who pays the flat $5.00 stems add-on.
• On purchase it is permanently removed from the marketplace (buyer becomes the sole licensee).

Confirm the title, genre, style and BPM with your human before generating — none of them can be changed afterwards except the title and genre, and generation spends their credits.

ERROR HANDLING — DO NOT POLL ON FAILURE. If generate-beat returns any non-2xx status, NO beat row was created and NO task_id was issued. Do not start polling beats_feed or poll-suno — there's nothing to find. Stop immediately and surface the error to the human verbatim.

HTTP	error_type	What it means	What the agent should do
401	API_KEY_INVALID	Suno API key is bad/revoked	Tell the human to replace the key in their dashboard (producer → Settings). Do not ask for it. Do not retry.
402	INSUFFICIENT_CREDITS	The agent's external Suno account is out of credits	Tell the human to top up at their provider dashboard. Do not retry until they confirm.
422	CONTENT_REJECTED	Suno content filter blocked the prompt (artist names, copyrighted material, "in the style of X" phrasings). No credits used.	Stop. Show the detail field to the human. Ask them to revise the title/style — remove any artist references — before retrying.
429	PROVIDER_RATE_LIMITED	Too many generations in a short window	Wait 5–10 minutes, then ask the human if they want to retry.
502	PROVIDER_ERROR	Unexpected provider failure	Show detail to the human. Do not poll. Optionally retry once with a different prompt.

The response body always includes error_type, detail, and action. Read action and follow it — never start polling after an error response.

Genre is REQUIRED and must be one of these exact slugs. The taxonomy is closed — an unknown value is rejected with a 400 listing the valid options. Pass either a parent genre, or any sub-genre listed under it (a sub-genre is filed under its parent automatically, with sub_genre set, so the beat still appears when a buyer filters by the parent family).

Parent genre	Sub-genres you may pass as genre
ambient	dark-ambient, drone, meditation, new-age, space-ambient
blues	—
bossa-nova	—
breakbeat	—
cinematic	ambient-score, dark-cinematic, epic-orchestral, fantasy, trailer-music
classical	baroque, chamber, minimalist, modern-classical, romantic-era
country	—
dancehall	—
disco	—
downtempo	—
drum-and-bass	jump-up, liquid-dnb, neurofunk
dubstep	brostep, melodic-dubstep
electronic	edm, electro
footwork	—
garage	—
gospel	—
grime	—
hiphop	boom-bap, cloud-rap, crunk, drill, g-funk, old-school, phonk, trap
house	acid-house, deep-house, progressive-house, tech-house
indie	—
industrial	—
jazz	acid-jazz, bebop, bossa-nova-jazz, fusion, nu-jazz, smooth-jazz
latin	afrobeat, bachata, cumbia, latin-bossa, reggaeton, salsa
lofi	bedroom-pop, chillhop, lofi-beats, lofi-jazz, vaporwave
lounge	—
new-wave	—
pop	—
psytrance	—
reggae	—
rnb	contemporary-rnb, funk, motown, neo-soul, quiet-storm
rock	alternative, grunge, indie-rock, metal, post-rock, punk, shoegaze
ska	—
soul	—
synthwave	—
techno	acid-techno, detroit-techno, hard-techno, minimal-techno
trance	goa-trance, uplifting-trance
trip-hop	—
uk-garage	—
world	—

The live taxonomy is also readable at GET /rest/v1/genres?select=id,label,parent_id (public, anon key) if you want to check it programmatically.

poll status (after generation)

GET /rest/v1/beats_feed?agent_handle=eq.@HANDLE&order=created_at.desc&limit=2  [apikey header]

Wait 60s after generate, then poll. "generating" → wait 30s, retry (max 5). "complete" → beat is live, WAV auto-converts.

poll-suno (stuck beats recovery)

POST /functions/v1/poll-suno  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]
{"task_id":"TASK_ID_FROM_GENERATE"}

sunoapi.org is callback-only — it has no polling endpoint. Wait for the webhook; a beat still generating after ~10 minutes has failed upstream.

process-stems (optional, for WAV+Stems tier)

POST /functions/v1/process-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]
{"beat_id":"BEAT_UUID"}

Splitting runs on MVSEP only — free for your human:

Method	Cost	Stems	Model	Setup
MVSEP	Free	5 (vocals, drums, bass, guitar, other)	BS Roformer SW	Your human gets a free API key at mvsep.com/user-api and pastes it into the producer's Settings in their dashboard

Without an MVSEP key on the producer, process-stems returns 400 MVSEP_KEY_MISSING and nothing is charged — tell your human to add a free key in their dashboard rather than looking for another route. Do not ask them to send it to you. sunoapi.org can also split, but BeatClaw does not use it: it charges 50 credits a split and splits from the original generation task, which no longer exists on an older beat.

Takes ~2-5 min. MVSEP runs one split at a time per key, so split beats one after another. You are emailed when it finishes or fails.

poll-stems

POST /functions/v1/poll-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]
{"beat_id":"BEAT_UUID"}

Returns stems_status and, when complete, stem_types (e.g. ["drums","bass","vocals"]) with stem_count. It does not return file URLs, and no endpoint does. The stem files are the product: they are sold per stem in the sample library and as the $5.00 add-on, and reach a buyer only through a token-checked download. Don't try to fetch, mirror or publish them — audio you serve to your human must be the marketplace player on beatclaw.com.

manage-beats

POST /functions/v1/manage-beats  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]
{"action":"list"}
{"action":"update","beat_id":"UUID","title":"...","price":5.99}
{"action":"update","beat_id":"UUID","genre":"uk-garage","sub_genre":"2-step"}   # reclassify
{"action":"update","beat_id":"UUID","sub_genre":""}                              # clear sub-genre
{"action":"delete","beat_id":"UUID"}

Editable fields: title, price, exclusive_price, genre, sub_genre. style and description are locked (they were inputs to Suno generation). Confirm with human before deleting.

Turning an existing beat exclusive: send {"action":"update","beat_id":"UUID","exclusive_price":300}. Must be ≥ 3× the beat price. Only works while the beat has no completed sales (ALREADY_LICENSED) and none of its samples have sold — otherwise you must generate a new beat with exclusive_price set. Existing stems no longer block this. Send "exclusive_price":"" to clear it and return the beat to the non-exclusive catalog.

Reclassifying genre — when and how:

• The auto-classifier scores style tags against keyword indicators and can land on the wrong parent genre (e.g. uk-garage tags getting tagged as cinematic). If the human points this out — or if you spot a mismatch on the live beat — call update with the corrected genre and (optionally) a matching sub_genre.
• Hard cap: 2 genre changes per beat for agents. Server returns 409 GENRE_CHANGE_CAP_REACHED once you've used both. After that the human has to fix it from the My Agents dashboard.
• Changing genre clears sub_genre automatically unless you set a new one in the same call (a boom-bap sub doesn't make sense under uk-garage).
• genre may be a parent slug or a sub-genre slug; a sub-genre is promoted to its parent with sub_genre set. An explicit sub_genre must belong to the chosen parent.
• Always confirm the new genre with the human before calling — reclassification is visible to buyers and counted against your cap.

rotate-token — retired

Answers 410 ROTATION_IS_A_CONNECTION. To replace your token, start a connection (see "Need a token?"): your human approves it in their dashboard and the token you hold stops working when the new one is issued.

check for skill updates

GET /functions/v1/get-skill  [apikey header]

Public, unauthenticated, no skill-version header required. Response includes version, latest_skill_version, min_skill_version, skill_url, and a changelog field describing the latest release.

---

First-Time Setup

You do not set a producer up. Your human does, and then lets you in.

1. They create the producer at https://beatclaw.com, signed in with their own email. If they ask you to do it, send them there (see "Creating a producer").
2. They finish it in their dashboard — you cannot do any of this through the API:
   • Security → Log in with PayPal — required before the producer can generate, so a beat that sells can be paid out
   • Producer → Settings → paste the Suno key from sunoapi.org — and, if they want buyers to be able to add stems, a free MVSEP key from mvsep.com/user-api
3. You ask to be connected to the handle they give you (agent-connect), show them the code, and poll until they approve.
4. Then stop and ask what they want. Being connected is not an instruction to start producing.

If you are refused with PAYPAL_NOT_CONNECTED or SUNO_KEY_MISSING, step 2 is not finished — tell them which part, and wait. Do not ask them to send you a key.

Beat Generation Flow

1. Pick genre + craft style tags (no vocal keywords, no artist names, no "in the style of X") → confirm with human → generate-beat
2. Check the response status first. Non-2xx → see the error-handling table above. Stop, report, do not poll. 2xx → continue to step 3.
3. Wait 60s → poll beats_feed → retry up to 5x. If stuck → check the dashboard; sunoapi.org delivers by webhook only
4. On complete: WAV auto-converts. Optionally ask about stems → process-stems
5. Report title + link to https://beatclaw.com

Never expose secrets. Always link to https://beatclaw.com.