Sign-in and keys Every request needs the header Authorization: Bearer <token>. The token is an API key (it starts with shk_) or a sign-in token that Claude.ai or ChatGPT gets when you connect them (OAuth, it starts with sha_). Make a key on the Development page, in your account menu. The key is shown once. You can revoke it at any time, and it stops at once. A key cannot change billing, delete your account, or make other keys. Without a token, or with a bad one, the answer is 401. A token without the scope a call needs gets 403 insufficient_scope. Each MCP tool, its arguments, and the same thing on the web API.
make_songShawarma’s composer writes a new song from words: style, mood, instruments, tempo, length. Saves it and returns its id, code and a note.
Web API: POST /v1/songs {description, title?, length_seconds?}
Plan: AI allowance (Pro; Free only on its 5 free replies)
change_songChanges only what you ask for (“make the drums heavier”) and saves a new version.
Web API: POST /v1/songs/:id/changes {request}
Plan: AI allowance
get_songA song’s name, code, newest versions and share link.
Web API: GET /v1/songs/:id
Plan: Free
list_songsYour songs, newest first, with their ids.
No arguments.
Web API: GET /v1/songs
Plan: Free
restore_versionMakes an earlier version the newest one again. It is saved as a new version, so nothing is lost.
Web API: GET /v1/songs/:id/versions, GET /v1/songs/:id/versions/:vid , POST /v1/songs/:id/versions/:vid/restore
Plan: Free
share_songA public link (shawarma.studio/s/…) that plays in any browser without signing in. Sharing again updates the same link.
Web API: POST /v1/songs/:id/share {nickname?}
Plan: Free
export_audioRenders the song as an MP3 or WAV file, up to 5 minutes, and returns a download link for the same key.
Web API: POST /v1/songs/:id/exports {format?, version_id?}, GET /v1/jobs/:id/audio
Plan: Pro
list_soundsThe sounds songs can use: drums and drum machines, synths, recorded instruments (darbuka, riq, oud and more), and maqam scales.
Web API: GET /v1/sounds?query=
Plan: Free
write_songSaves music code your agent wrote, as a new song or a new version. Shawarma checks it first and refuses code that does not play. No AI cost.
Web API: POST /v1/songs {title, code}, PUT /v1/songs/:id/code {code}
Plan: Free
check_codeChecks music code without saving it: whether it plays, the error if not, the sounds it uses and how long it is.
Web API: POST /v1/check {code}
Plan: Free
guideA short guide to writing Shawarma music code. Read it before write_song.
No arguments.
Web API: GET /v1/guide
Plan: Free
get_jobThe state of a long request (make_song, change_song, export_audio): queued, running, done with the result, or failed with why. Can wait for it.
Web API: GET /v1/jobs/:id?wait=
Plan: Free
An example Make a song curl https://shawarma.studio/v1/songs \
-H "Authorization: Bearer shk_…" \
-H "Content-Type: application/json" \
-d '{"description": "calm 20-second intro for a podcast"}'The answer (shortened) {
"song": { "id": "calm-20-second-intro", "name": "Calm 20-second intro", "app_url": "https://shawarma.studio/open?song=…" },
"version": { "n": 1 },
"reply": "A soft piano intro with light drums, 20 seconds.",
"job": { "id": "…", "status": "done" }
}Long work Composing and audio can take a while. A request waits up to wait_seconds (default 40, at most 55) for the result. If it is not ready, the web API answers 202 with { job }, a Location header and Retry-After. The MCP server answers with the job and says to call get_job. A release of Shawarma does not lose the work: the job finishes on the next server. You have one AI reply running at a time, shared with the app’s chat. A second one while one runs gets 409 busy with Retry-After. Limits Per key or connection: 300 requests in 10 minutes, and 30 compositions an hour. Code up to 100,000 characters. At most 20 keys per person. Over a limit, the answer is 429 with Retry-After. Connect your agent The setup for Claude Code, Codex, Cursor, Claude.ai and ChatGPT is on the Developers page.