# 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 [#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](#sandbox).
3. **Get a free account and a token.** Sign up at [/signup](/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](/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](/pricing)). `POST /workflow/{workflow_name}` charges before it queues.

Or skip the HTTP and use the [SDK and CLI](/developers/docs/sdk): `npx @groovesheet/sdk search "easy on me"`.

## Jobs [#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 [#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](/explore/easy-on-me-adele-0fff6be3), 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`.

```bash
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 [#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 [#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 [#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](/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]

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 [#everything-else-an-agent-reads]

- [llms.txt](/llms.txt), [agents.md](/agents.md), [auth.md](/auth.md)
- [API catalog](/.well-known/api-catalog) (RFC 9727), [ARD catalog](/.well-known/ard.json), [MCP discovery](/.well-known/mcp.json)
- NLWeb: `POST https://www.groovesheet.net/ask` answers questions about GrooveSheet from these docs
- Client configuration and skill for coding agents: [github.com/groovesheet/groovesheet-mcp](https://github.com/groovesheet/groovesheet-mcp)
