The same service behind groovesheet.net and the MCP server, as plain HTTP. The complete, generated description of every route is the OpenAPI 3.1 document at https://api.groovesheet.net/openapi.json; this page is the part you cannot read from a schema.
Getting started
- Start without a token. The song library (
GET /library/tracks?q=,GET /library/tracks/{id},POST /library/tracks/batch),/workflowsand/statusanswer without credentials. - Build against the sandbox.
https://api.groovesheet.net/sandboxruns the whole upload, poll and download loop with nothing charged and no account. See Sandbox. - Get a free account and a token. Sign up at /signup (free; the free tier is a 30-second preview of any song plus the whole library). Tokens come from OAuth 2.1 with dynamic client registration at
https://api.groovesheet.net/oauth/register, open to anyone, or from verified-email registration for an agent that cannot open a browser. Both are written out in auth.md. There is no separate API key. - Go to production. Full songs are paid in minutes from the account's plan or top-up (pricing).
POST /workflow/{workflow_name}charges before it queues.
Or skip the HTTP and use the SDK and CLI: npx @groovesheet/sdk search "easy on me".
Jobs
POST /workflow/{workflow_name} (multipart file) answers 202 Accepted with a workflow_id and a status_url, also in the Location header. Poll GET /workflow/status/{workflow_id} every few seconds until status is completed or failed, then read outputs.files (a map of file key to storage path) and fetch each with GET /workflow/download/{workflow_id}/{file_key}, or everything as a zip from GET /workflow/download/{workflow_id}.
Send Idempotency-Key: <uuid> on the start request. The same key from the same caller within 24 hours returns the first answer (Idempotent-Replayed: true) instead of starting, and charging for, the work twice.
Sandbox
https://api.groovesheet.net/sandbox is the second entry in the OpenAPI servers list. Point a client at it instead of the production URL and:
- every GET read route answers as in production, with
X-Sandbox: trueon the response; POST /sandbox/workflow/{workflow_name}(multipartfile, or/from-keyswith JSON) accepts any file, needs noAuthorization, charges nothing and answers202with aworkflow_idstarting withSBX;- the job moves
started,processing,completedon a timer, about 15 seconds in all, andGET /sandbox/workflow/status/{id}then carriesoutputs.fileswith the real notation, MIDI and stems of one fixed demo song, Easy On Me by Adele, for that workflow's instrument, under the same file keys the production workers write; GET /sandbox/workflow/download/{id}/{file_key}streams those files.
Sandbox jobs expire after 24 hours. The upload is discarded unread, nothing is stored and no account is created, so a sandbox call can never cost anything or touch live data. Production routes that write (accounts, billing, publishing) do not exist under the prefix and answer 404.
curl -s -X POST https://api.groovesheet.net/sandbox/workflow/separate_to_drumscore_full \
-F "file=@any.mp3"
# {"workflow_id":"SBX...","status":"started","status_url":"/sandbox/workflow/status/SBX...","sandbox":true}
curl -s https://api.groovesheet.net/sandbox/workflow/status/SBX...
Batch requests
POST /library/tracks/batchwith{"ids": ["<uuid or slug>", ...]}(up to 50) returns{"tracks": [...]}in the order asked, each entry whatGET /library/tracks/{id}returns, ornullfor an id that does not exist or is not visible. No token needed.POST /workflow/status/batchwith{"workflow_ids": [...]}(up to 50, signed in) returns{"results": [...]}, one status per job, with anerrorobject in place of a job that is not the caller's.
Rate limits
Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy for the caller's overall budget, about 1200 requests a minute per client. Some routes have tighter limits of their own. A 429 carries Retry-After in seconds; wait that long and retry.
Versioning and deprecation
This is version 2 of the API (info.version in the OpenAPI document), served at the root with no version prefix. Every response carries API-Version: 2; a request may send the same header, and an unknown version is refused with 400.
Compatible changes (new routes, new optional fields or parameters, new enum values on output) ship without notice and without a version change. Clients must ignore fields they do not know.
Deprecation policy. When a route, parameter or field is going away:
- It is marked
deprecated: truein the OpenAPI document on the day it is announced, withx-deprecated-at,x-sunsetandx-successoron the operation, and listed ininfo.x-deprecationsand on the changelog. - Every response from it carries
Deprecation: @<unix time>(RFC 9745, the announcement date),Sunset: <HTTP date>(RFC 8594, the removal date) andLinkheaders withrel="deprecation"pointing at this section andrel="successor-version"pointing at the replacement when there is one. - The sunset date is at least 90 days after the announcement. Until then the route behaves exactly as before.
- After the sunset date the route answers
410 Gonewith a JSON body naming the successor.
A breaking change that cannot be made this way ships as a new version, announced at least 90 days ahead, with the old version kept alive for the same 90 days.
The policy is machine-readable as info.x-sunset-policy in the OpenAPI document.
Currently deprecated: GET /service-status (use GET /status, which the status page reads, and GET /status/history), announced 6 November 2026, sunset 6 February 2027.
Errors
Errors are JSON: {"detail": "..."}, or a list under detail for validation errors. A 401 carries WWW-Authenticate: Bearer resource_metadata="https://api.groovesheet.net/.well-known/oauth-protected-resource". An unknown path answers 404 with a JSON body pointing at the OpenAPI document, or Markdown when the request sends Accept: text/markdown.
Everything else an agent reads
- llms.txt, agents.md, auth.md
- API catalog (RFC 9727), ARD catalog, MCP discovery
- NLWeb:
POST https://www.groovesheet.net/askanswers questions about GrooveSheet from these docs - Client configuration and skill for coding agents: github.com/groovesheet/groovesheet-mcp
