View as Markdownllms.txt

REST API

The GrooveSheet REST API: OpenAPI document, getting started without a human, the sandbox, batch requests, rate limits, and the versioning and deprecation policy.

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

  1. Start without a token. The song library (GET /library/tracks?q=, GET /library/tracks/{id}, POST /library/tracks/batch), /workflows and /status answer without credentials.
  2. Build against the sandbox. https://api.groovesheet.net/sandbox runs the whole upload, poll and download loop with nothing charged and no account. See Sandbox.
  3. 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.
  4. 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: true on the response;
  • POST /sandbox/workflow/{workflow_name} (multipart file, or /from-keys with JSON) accepts any file, needs no Authorization, charges nothing and answers 202 with a workflow_id starting with SBX;
  • the job moves started, processing, completed on a timer, about 15 seconds in all, and GET /sandbox/workflow/status/{id} then carries outputs.files with 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/batch with {"ids": ["<uuid or slug>", ...]} (up to 50) returns {"tracks": [...]} in the order asked, each entry what GET /library/tracks/{id} returns, or null for an id that does not exist or is not visible. No token needed.
  • POST /workflow/status/batch with {"workflow_ids": [...]} (up to 50, signed in) returns {"results": [...]}, one status per job, with an error object 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:

  1. It is marked deprecated: true in the OpenAPI document on the day it is announced, with x-deprecated-at, x-sunset and x-successor on the operation, and listed in info.x-deprecations and on the changelog.
  2. Every response from it carries Deprecation: @<unix time> (RFC 9745, the announcement date), Sunset: <HTTP date> (RFC 8594, the removal date) and Link headers with rel="deprecation" pointing at this section and rel="successor-version" pointing at the replacement when there is one.
  3. The sunset date is at least 90 days after the announcement. Until then the route behaves exactly as before.
  4. After the sunset date the route answers 410 Gone with 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

← Upload linksSDK and CLI →