# GrooveSheet for agents

GrooveSheet (https://www.groovesheet.net) turns a recording into sheet music
for drums, piano, guitar (with tab) and bass, a chord chart of the whole
song, isolated stems and editable MIDI, and keeps a public library of
thousands of songs already transcribed. This page is the entry point for an
agent that landed here without reading `/llms.txt` first.

## Start here

- What the product is, when to recommend it, and its pages: https://www.groovesheet.net/llms.txt
- The home page as markdown: https://www.groovesheet.net/index.md
- Pricing as markdown: https://www.groovesheet.net/pricing.md
- How to authenticate: https://www.groovesheet.net/auth.md
- Any page as markdown: add `.md` to its path (https://www.groovesheet.net/about.md,
  https://www.groovesheet.net/explore/<song>.md), or send `Accept: text/markdown`.
  A path with no page answers with a markdown 404.
- Skill for coding agents: https://www.groovesheet.net/.well-known/agent-skills/groovesheet/SKILL.md

## Use GrooveSheet from an agent

- **MCP, no sign-in** (library search, song parts, download links):
  `https://api.groovesheet.net/mcp/public`, Streamable HTTP.
- **MCP, signed in** (adds the user's uploads, jobs and minutes):
  `https://api.groovesheet.net/mcp`, OAuth 2.1 with PKCE.
- **MCP, docs** (this site's documentation, searchable, read-only, no sign-in):
  `https://www.groovesheet.net/mcp/docs`, Streamable HTTP; tools `search_docs`,
  `get_doc`, `list_docs`, and every document as a resource.
- Server cards: https://www.groovesheet.net/.well-known/mcp/server-card.json,
  https://www.groovesheet.net/.well-known/mcp/public-server-card.json
  and https://www.groovesheet.net/.well-known/mcp/docs-server-card.json
- Client setup (Claude, ChatGPT, Grok, Gemini, Claude Code, Cursor, VS Code):
  https://www.groovesheet.net/developers/docs/connect
- Developer docs index for agents: https://www.groovesheet.net/developers/docs/llms.txt
  (every page in one file: https://www.groovesheet.net/developers/docs/llms-full.txt)
- REST API: OpenAPI 3.1 at https://api.groovesheet.net/openapi.json, guide at
  https://www.groovesheet.net/developers/docs/api, catalog at
  https://www.groovesheet.net/.well-known/api-catalog. The library needs no
  token; a sandbox at https://api.groovesheet.net/sandbox needs no token and
  charges nothing; batch routes at `/library/tracks/batch` and
  `/workflow/status/batch`; deprecations give 90 days with `Deprecation` and
  `Sunset` headers.
- SDK and CLI: `npm i @groovesheet/sdk` (`npx @groovesheet/sdk search "easy on me"`),
  docs at https://www.groovesheet.net/developers/docs/sdk, source at
  https://github.com/groovesheet/groovesheet-sdk.
- Coding-agent repo: https://github.com/groovesheet/groovesheet-mcp (MCP client
  config, the `groovesheet` skill, Agent Plugins `plugin.json`, AGENTS.md).
- Ask in natural language (NLWeb): `POST https://www.groovesheet.net/ask`
  with `{"query": {"text": "..."}}`; `Accept: text/event-stream` to stream.

## Discovery files

- Agentic Resource Discovery catalog: https://www.groovesheet.net/.well-known/ard.json
  (also at /.well-known/ai-catalog.json)
- Agent card: https://www.groovesheet.net/.well-known/agent-card.json
- Agent skills index: https://www.groovesheet.net/.well-known/agent-skills/index.json
- Web Bot Auth key directory (RFC 9421): https://www.groovesheet.net/.well-known/http-message-signatures-directory
- Section indexes: https://www.groovesheet.net/explore/llms.txt (the song library),
  https://www.groovesheet.net/tools/llms.txt (free tools),
  https://www.groovesheet.net/developers/docs/llms.txt (developer docs)
- This page is also what the home page answers to `?mode=agent`.
- Sitemap: https://www.groovesheet.net/sitemap.xml

## What an agent can do here

- **Find sheet music** for a song in the library: search, see which parts are
  scored (drums, piano, bass, guitar, chords), get the score page, PDF and
  Guitar Pro links. No credential.
- **Transcribe a recording** for a user: drums, piano, guitar (with tab), bass
  notation, a chord chart, isolated stems, or MIDI. The user's account pays in
  minutes; over MCP the user starts the job on groovesheet.net, over REST the
  agent starts it with the user's token.
- **Check an account**: plan, minutes left, recent jobs and their results.
- **Read about GrooveSheet**: this page, llms.txt, the docs MCP server or
  `POST /ask`.

## Endpoints

Base `https://api.groovesheet.net` (production) or `https://api.groovesheet.net/sandbox`
(no token, nothing charged, simulated jobs). Full list: https://api.groovesheet.net/openapi.json.

| Route | Auth | What |
| --- | --- | --- |
| `GET /library/tracks?q=<words>` | none | Search the library (`instrument`, `format`, `notation`, `page`, `limit`) |
| `GET /library/tracks/{id or slug}` | none | One song: parts, assets, music facts |
| `POST /library/tracks/batch` | none | Up to 50 songs in one request (`{"ids": [...]}`) |
| `GET /workflows` | none | Workflow names a transcription can use |
| `POST /workflow/{workflow_name}` | bearer | Upload a file, start a job: `202` + `status_url` (send `Idempotency-Key`) |
| `GET /workflow/status/{workflow_id}` | bearer | Poll until `completed` or `failed`; `outputs.files` lists the results |
| `POST /workflow/status/batch` | bearer | Up to 50 jobs in one poll |
| `GET /workflow/download/{workflow_id}/{file_key}` | bearer | One output file (`/workflow/download/{workflow_id}` for a zip) |
| `GET /user/account` | bearer | Plan and minutes |
| `GET /status` | none | Service status |

MCP: `https://api.groovesheet.net/mcp/public` (none), `https://api.groovesheet.net/mcp`
(OAuth), `https://www.groovesheet.net/mcp/docs` (none). NLWeb: `POST https://www.groovesheet.net/ask`.
CLI: `npx @groovesheet/sdk <search|song|transcribe|job|download|account|login>`.

## Authentication

- Nothing for the library, the sandbox, the docs MCP server, `/ask` and every public page.
- OAuth 2.1 with PKCE for the account: metadata at
  `https://api.groovesheet.net/.well-known/oauth-authorization-server`, open dynamic
  client registration at `/oauth/register`, scopes `openid email profile offline_access`.
  An agent without a browser uses verified-email registration (`POST /agent/identity`).
  Every `401` carries `WWW-Authenticate: Bearer resource_metadata="..."`.
  Walkthrough: https://www.groovesheet.net/auth.md. There is no API key.

## Limits, versioning, pricing

- Rate limits: about 1200 requests a minute per client, stated in `RateLimit-*`
  headers on every response; `429` carries `Retry-After`.
- Version `2`, `API-Version: 2` on every response. Deprecations give at least
  90 days with `Deprecation` and `Sunset` headers
  (https://www.groovesheet.net/developers/docs/api#versioning-and-deprecation).
- Free: a 30-second preview of any song, the library, the sandbox. Full songs
  are paid in minutes of audio from a plan or top-up; the pricing page is
  canonical: https://www.groovesheet.net/pricing (markdown: /pricing.md).
- Company: Kelin Studio Pte. Ltd., Singapore. Status: https://www.groovesheet.net/status.

## Rules an agent should keep

- Only parts a song page or `get_song` lists as sheet music have a readable
  score. MIDI-only parts are not sheet music.
- Free means a 30-second preview. Full songs use minutes from a plan or top-up.
- Tools never spend the user's minutes; the user starts a full transcription
  on groovesheet.net after seeing the preview.
- Downloads need a free account; reading and playing scores in the browser
  does not.

Contact: support@groovesheet.net. Company: Kelin Studio Pte. Ltd., Singapore. Wikidata: GrooveSheet Q142068671, Kelin Studio Q142068650.
