{"openapi":"3.1.0","info":{"title":"GrooveSheet Audio Service","description":"Audio processing service behind GrooveSheet (https://www.groovesheet.net): stem\nseparation and transcription to sheet music and MIDI, plus the song library.\nDeveloper docs: https://www.groovesheet.net/developers. MCP server: https://api.groovesheet.net/mcp (signed in) and https://api.groovesheet.net/mcp/public.\nSDK and CLI: `npm i @groovesheet/sdk` (`npx @groovesheet/sdk search \"easy on me\"`), source at https://github.com/groovesheet/groovesheet-sdk.\n\n## Getting started, with no human in the loop\n\n1. **No credential**: the song library (`GET /library/tracks?q=...`, `GET /library/tracks/{id}`,\n   `POST /library/tracks/batch`), `/workflows`, `/status` and this document answer without a token.\n2. **Sandbox**: `https://api.groovesheet.net/sandbox` is a second server (see `servers`). Every read route works there\n   unchanged, and `POST https://api.groovesheet.net/sandbox/workflow/{workflow_name}` runs the whole\n   202 -> poll -> download loop with a simulated job that completes in about 15 seconds with the\n   real outputs of a fixed demo song. No token, no account, nothing charged, nothing stored\n   beyond the job record (24 hours). Build and test against it first.\n3. **A free account and a token**: sign up at https://www.groovesheet.net/signup (free; the free tier gives a\n   30-second preview of any song and the whole library). A token comes from OAuth 2.1 with\n   dynamic client registration at `https://api.groovesheet.net/oauth/register` (open, no approval) or, for\n   an agent that cannot open a browser, verified-email registration at `/agent/identity`\n   (https://www.groovesheet.net/auth.md). There is no separate API key.\n4. **Production**: full songs are paid for in minutes of audio from the account's plan or\n   top-up (https://www.groovesheet.net/pricing). `POST /workflow/{workflow_name}` charges before queueing.\n\n## Authentication\n\nSend `Authorization: Bearer <access token>`. OAuth 2.1 with PKCE (S256):\nauthorization server metadata at `https://api.groovesheet.net/.well-known/oauth-authorization-server`\n(issuer `https://api.groovesheet.net`; endpoints `/oauth/register`, `/oauth/authorize`,\n`/oauth/token`, `/oauth/userinfo`, `/oauth/jwks`),\nprotected-resource metadata at `https://api.groovesheet.net/.well-known/oauth-protected-resource`. Every `401` carries\n`WWW-Authenticate: Bearer resource_metadata=\"https://api.groovesheet.net/.well-known/oauth-protected-resource\"`.\nScopes offered by the authorization server: `openid`, `email`, `profile`,\n`offline_access`. Access is per account; tokens carry no finer-grained scopes.\n\n## Long-running work\n\n`POST /workflow/{workflow_name}` and `POST /workflow/{workflow_name}/from-keys`\nanswer `202 Accepted`: the job is queued, not finished. The body carries the job\nid (`workflow_id`) and `status_url`; the `Location` header holds the same URL.\nPoll `GET /workflow/status/{workflow_id}` until `status` is `completed` or `failed`\n(every few seconds is plenty), then fetch outputs from `/workflow/download/...`.\n\n## Retrying safely: Idempotency-Key\n\nSend `Idempotency-Key: <uuid>` on `POST /workflow/{workflow_name}`,\n`POST /workflow/{workflow_name}/from-keys`, `POST /preview/{workflow_name}`\nand `POST /preview/{workflow_name}/from-url`. The same key from the same caller\nwithin 24 hours returns the first response (with `Idempotent-Replayed: true`)\ninstead of starting, and charging for, the work again. Same key with a different\nrequest: `422`. Same key while the first request still runs: `409` with\n`Retry-After`. Failed requests are not remembered, so a retry runs again.\n\n## Batch requests\n\n`POST /library/tracks/batch` with `{\"ids\": [\"<uuid or slug>\", ...]}` (up to 50) returns the\nsame records as `GET /library/tracks/{id}` in one round trip, in the order asked, with `null`\nfor an id that does not exist or is not visible. `POST /workflow/status/batch` with\n`{\"workflow_ids\": [...]}` (up to 50, signed in) returns the status of each of the caller's jobs,\nso a client polling several uploads makes one request per interval instead of one per job.\n\n## Rate limits\n\nEvery response carries the IETF `RateLimit-Limit`, `RateLimit-Remaining` and\n`RateLimit-Reset` (seconds until the window resets) headers, and\n`RateLimit-Policy` (`<limit>;w=<window seconds>`), for the caller's overall\nbudget (about 1200 requests per 60 s per client). Some routes\nhave tighter limits of their own. When a limit is hit the answer is `429` with\n`Retry-After` (seconds) and `RateLimit-Remaining: 0`; wait that long and retry.\n\n## Versioning and deprecation\n\nThis is version `2` of the API (`info.version`), served at the root with no\nversion prefix. Every response carries `API-Version: 2`. Clients may send\nthe optional `API-Version` request header; an unknown version is refused with\n`400` and the supported list. Compatible changes (new routes, new optional\nfields or parameters) ship without a version change. A breaking change ships as a\nnew version, announced at least 90 days ahead; until it is withdrawn the old\nbehaviour keeps working.\n\nDeprecation policy (`x-sunset-policy` in `info`, written out at https://www.groovesheet.net/developers/docs/api#versioning-and-deprecation):\n\n- A route or field that is going away is marked `deprecated: true` in this document on the\n  day it is announced, and every response from it carries `Deprecation: @<unix time>`\n  (RFC 9745, the announcement date), `Sunset: <HTTP date>` (RFC 8594, the removal date) and\n  `Link: <...>; rel=\"deprecation\"` to the policy page plus `rel=\"successor-version\"` to the\n  replacement when there is one.\n- The sunset date is at least 90 days after the deprecation date. Until then the route\n  behaves as before. After it, the route answers `410 Gone` with the successor in the body.\n- Changes are listed at https://www.groovesheet.net/changelog and in this document's `x-deprecations`.\n- Currently deprecated: `GET /service-status` (use `GET /status`), sunset 6 February 2027.\n\n## Sandbox\n\n`https://api.groovesheet.net/sandbox` (the second entry in `servers`). GET routes are the production ones with the\nprefix stripped (the response carries `X-Sandbox: true`). `POST /sandbox/workflow/{workflow_name}`\n(multipart `file`, or `/from-keys` with JSON) accepts anything, needs no `Authorization`, and\nanswers `202` with a `workflow_id` that becomes `completed` after about 15 seconds;\n`GET /sandbox/workflow/status/{id}` and `GET /sandbox/workflow/download/{id}/{file_key}`\nthen serve the demo song's real notation, MIDI and stems under the same `outputs.files` keys the\nproduction workers use. Sandbox job ids start with `SBX` and expire after 24 hours. Nothing in\nthe sandbox spends minutes or creates an account.\n\n## Errors\n\nErrors are JSON: `{\"detail\": \"...\"}` (validation errors: a list under `detail`).\nUnknown paths answer `404` with a JSON body pointing here, or Markdown when the\nrequest sends `Accept: text/markdown`.\n","version":"2.0.0","contact":{"name":"GrooveSheet developers","url":"https://www.groovesheet.net/developers","email":"support@groovesheet.net"},"license":{"name":"Terms of service","url":"https://www.groovesheet.net/terms"},"termsOfService":"https://www.groovesheet.net/terms","x-api-version":"2","x-sunset-policy":{"url":"https://www.groovesheet.net/developers/docs/api#versioning-and-deprecation","notice_days":90,"headers":["Deprecation","Sunset","Link; rel=deprecation","Link; rel=successor-version"],"summary":"A route going away is marked deprecated here and answers with Deprecation and Sunset headers for at least 90 days before it stops; then it answers 410 Gone naming the successor."},"x-sandbox":{"url":"https://api.groovesheet.net/sandbox","auth":"none","charges":"none","demo_track":"https://www.groovesheet.net/explore/easy-on-me-adele-0fff6be3","docs":"https://www.groovesheet.net/developers/docs/api#sandbox"},"x-sdk":{"npm":"@groovesheet/sdk","cli":"groovesheet","repository":"https://github.com/groovesheet/groovesheet-sdk","install":"npm i @groovesheet/sdk"},"x-onboarding":{"free_tier":"https://www.groovesheet.net/pricing","signup":"https://www.groovesheet.net/signup","self_serve_credentials":"https://api.groovesheet.net/oauth/register","agent_auth":"https://www.groovesheet.net/auth.md","sandbox":"https://api.groovesheet.net/sandbox","no_auth_routes":["/library/tracks","/library/tracks/{track_id}","/library/tracks/batch","/workflows","/status"]},"x-deprecations":[{"method":"GET","path":"/service-status","deprecated_at":"2026-11-06T00:00:00Z","sunset":"Sat, 06 Feb 2027 00:00:00 GMT","successor":"/status","note":"Replaced by GET /status (public pool status) and GET /status/history."}]},"paths":{"/sandbox/workflow/{workflow_name}":{"post":{"tags":["sandbox"],"summary":"Start a sandbox workflow","description":"Start a simulated transcription or separation job without a token or minutes.\n\nSame request shape as `POST /workflow/{workflow_name}` (multipart `file`, optional\n`metadata` JSON string). The job is not run: it completes on a timer with the demo\nsong's outputs, so the client can exercise the 202 -> poll -> download loop end to end.","operationId":"start_sandbox_workflow_sandbox_workflow__workflow_name__post","parameters":[{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"name":"metadata","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_start_sandbox_workflow_sandbox_workflow__workflow_name__post"}}}},"responses":{"202":{"description":"Accepted. The sandbox job is simulated: poll `status_url` (also in the `Location` header); it completes within about 15 seconds with the demo song's real outputs. Nothing is charged.","content":{"application/json":{"schema":{}}},"headers":{"Location":{"description":"Where to poll: /sandbox/workflow/status/{workflow_id}.","schema":{"type":"string"}}}},"404":{"description":"Unknown workflow name. `GET /sandbox/workflows` lists them."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sandbox/workflow/{workflow_name}/from-keys":{"post":{"tags":["sandbox"],"summary":"Start a sandbox workflow (JSON body)","description":"The JSON form of the sandbox start, mirroring `POST /workflow/{workflow_name}/from-keys`.","operationId":"start_sandbox_workflow_from_keys_sandbox_workflow__workflow_name__from_keys_post","parameters":[{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"202":{"description":"Accepted. The sandbox job is simulated: poll `status_url` (also in the `Location` header); it completes within about 15 seconds with the demo song's real outputs. Nothing is charged.","content":{"application/json":{"schema":{}}},"headers":{"Location":{"description":"Where to poll: /sandbox/workflow/status/{workflow_id}.","schema":{"type":"string"}}}},"404":{"description":"Unknown workflow name. `GET /sandbox/workflows` lists them."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sandbox/workflow/status/{workflow_id}":{"get":{"tags":["sandbox"],"summary":"Sandbox job status","description":"Same shape as `GET /workflow/status/{workflow_id}`. `started` for a few seconds, then\n`processing`, then `completed` with `outputs.files` ready to download.","operationId":"sandbox_workflow_status_sandbox_workflow_status__workflow_id__get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sandbox/workflow/download/{workflow_id}/{file_key}":{"get":{"tags":["sandbox"],"summary":"Download a sandbox output file","description":"Streams one output of a completed sandbox job, like `GET /workflow/download/{workflow_id}/{file_key}`.","operationId":"sandbox_workflow_download_sandbox_workflow_download__workflow_id___file_key__get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"name":"file_key","in":"path","required":true,"schema":{"type":"string","title":"File Key"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["info"],"summary":"Health","description":"Dependency-free liveness endpoint for k8s probes.\n\nDeliberately touches nothing (no Redis, no DB) — a Redis blip must not\nrestart the pod. GET / stays as the rich diagnostic check.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/":{"get":{"tags":["info"],"summary":"Root","description":"Health check endpoint.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/workflows":{"get":{"tags":["info"],"summary":"List Workflows","description":"List all available workflows.","operationId":"list_workflows_workflows_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/workflow/reload":{"post":{"tags":["workflows"],"summary":"Reload Workflows","description":"Admin-only: manually reload workflow configurations from GCS.","operationId":"reload_workflows_workflow_reload_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/workflow/config":{"get":{"tags":["workflows"],"summary":"Get Workflow Config","description":"Get current workflow configuration info.","operationId":"get_workflow_config_workflow_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/workflow/list":{"get":{"tags":["workflows"],"summary":"List User Workflows","description":"List the caller's workflows.\n\nWithout query params, returns the legacy {\"workflow_ids\": [...]} shape.\nWith ?limit/?offset, returns enriched card items (status, visibility,\ntitle, cover, progress, instrument, files) plus a total, so the Library\npage renders from one request instead of one status call per workflow.","operationId":"list_user_workflows_workflow_list_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Offset"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/{workflow_name}/from-keys":{"post":{"tags":["workflows"],"summary":"Start Workflow From Keys","description":"Start a workflow without uploading a file — for jobs that operate on\nR2 objects already present (e.g. `compress_stems` reading existing Demucs\nstem WAVs). The first worker reads its inputs from `metadata` instead of\nthe conventional `input_file`. No audio-duration credit is charged because\nno source audio is provided here.\n\n`metadata.input_file` extends this to the transcription workflows: pass an\nR2 object key (workers resolve a bare key directly) and a `*_transcribe_*`\nchain runs against a stem already in the bucket — no download-and-re-upload\nround trip, which is what the library backfill needs. Keep it operator-only:\nit reads an arbitrary key in the bucket and bills nothing.","operationId":"start_workflow_from_keys_workflow__workflow_name__from_keys_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409.","title":"Idempotency-Key"},"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409."},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_WorkflowJsonStartRequest"}}}},"responses":{"202":{"description":"Accepted: the job is queued, not finished. Poll `status_url` (also in the `Location` header) until `status` is `completed` or `failed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowResponse"}}},"headers":{"Location":{"description":"Where to poll for the result: /workflow/status/{workflow_id}.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"`true` when this is the stored answer to an earlier request with the same Idempotency-Key.","schema":{"type":"string"}}}},"409":{"description":"Another request with this Idempotency-Key is still being processed."},"422":{"description":"The Idempotency-Key was already used for a different request, or the file could not be read."}}}},"/workflow/{workflow_name}":{"post":{"tags":["workflows"],"summary":"Start Workflow","description":"Start a workflow (e.g., separate_and_transcribe).\nWorkflow will chain services automatically.\nRequires Clerk authentication via Bearer token.","operationId":"start_workflow_workflow__workflow_name__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"name":"metadata","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409.","title":"Idempotency-Key"},"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409."},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_start_workflow_workflow__workflow_name__post"}}}},"responses":{"202":{"description":"Accepted: the job is queued, not finished. Poll `status_url` (also in the `Location` header) until `status` is `completed` or `failed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowResponse"}}},"headers":{"Location":{"description":"Where to poll for the result: /workflow/status/{workflow_id}.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"`true` when this is the stored answer to an earlier request with the same Idempotency-Key.","schema":{"type":"string"}}}},"409":{"description":"Another request with this Idempotency-Key is still being processed."},"422":{"description":"The Idempotency-Key was already used for a different request, or the file could not be read."}}}},"/workflow/status/batch":{"post":{"tags":["workflows"],"summary":"Get Workflow Status Batch","description":"The status of several of the caller's jobs in one request.\n\nBody `{\"workflow_ids\": [...]}` (up to 50). Answer `{\"results\": [...]}` in the same\norder: each entry is what `GET /workflow/status/{workflow_id}` returns, or\n`{\"workflow_id\": ..., \"error\": {\"status\": 404 | 403, \"detail\": ...}}` for a job that\ndoes not exist or belongs to someone else. One poll per interval for a batch of uploads.","operationId":"get_workflow_status_batch_workflow_status_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_BatchStatusRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/workflow/status/{workflow_id}":{"get":{"tags":["workflows"],"summary":"Get Workflow Status","description":"Get workflow status and results. Users can only access their own workflows.","operationId":"get_workflow_status_workflow_status__workflow_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/score-pdf/{workflow_id}":{"get":{"tags":["workflows"],"summary":"Download Workflow Score Pdf","description":"Render the transcription's score to a paginated PDF.\n\nMusicXML is an interchange format — it needs an editor to look at. The PDF\nis the copy you can print or put on a stand, so it ships alongside the\nMusicXML on every completed transcription.","operationId":"download_workflow_score_pdf_workflow_score_pdf__workflow_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/score-gp5/{workflow_id}":{"get":{"tags":["workflows"],"summary":"Download Workflow Score Gp5","description":"The transcription's score as a Guitar Pro 5 file.\n\nDrummers, bassists and guitarists read tab in Guitar Pro, Songsterr,\nTuxGuitar or MuseScore; .gp5 opens in all of them. Converted from the same\nMusicXML the PDF is engraved from, on request (it takes well under a\nsecond, so nothing is cached).","operationId":"download_workflow_score_gp5_workflow_score_gp5__workflow_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/download/{workflow_id}/{file_key}":{"get":{"tags":["workflows"],"summary":"Download Workflow File","description":"Download a specific output file from a completed workflow.","operationId":"download_workflow_file_workflow_download__workflow_id___file_key__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"name":"file_key","in":"path","required":true,"schema":{"type":"string","title":"File Key"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/download/{workflow_id}":{"get":{"tags":["workflows"],"summary":"Download All Workflow Outputs","description":"Download all output files from a completed workflow as a ZIP.","operationId":"download_all_workflow_outputs_workflow_download__workflow_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/{workflow_id}/visibility":{"post":{"tags":["workflows"],"summary":"Set Workflow Visibility","description":"Publish (public/unlisted) or unpublish (private) a workflow's library track (§4.2).\n\nPublishing also makes the track usable publicly: sets publish dates + a\nstable slug, transcodes WAV stems to streamable formats under the track's\nsnapshot prefix, and renders a preview image for MIDI tracks. The response\ncarries `processing: true` while the transcode is in flight.","operationId":"set_workflow_visibility_workflow__workflow_id__visibility_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowVisibilityRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflow/{workflow_id}":{"patch":{"tags":["workflows"],"summary":"Update Workflow Metadata","description":"Edit a workflow's display metadata, mirroring to the library track (§4.3).","operationId":"update_workflow_metadata_workflow__workflow_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowMetadataUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["workflows"],"summary":"Delete Workflow","description":"Delete a workflow and its R2 outputs (§4.4).\n\nPublished tracks are a snapshot the public page depends on: unless the\ncaller passes delete_track=true, a public/unlisted track survives the\nworkflow deletion (it just loses its workflow link), and any R2 object\nstill referenced by a kept library asset is preserved. Private tracks are\ndeleted with the workflow as before.","operationId":"delete_workflow_workflow__workflow_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"name":"delete_track","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"For published tracks: true also removes the public track; false/omitted keeps it on Explore (default keeps it).","title":"Delete Track"},"description":"For published tracks: true also removes the public track; false/omitted keeps it on Explore (default keeps it)."},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pubsub/push":{"post":{"tags":["pubsub"],"summary":"Pubsub Push Endpoint","description":"Event push endpoint for receiving job completion events.\n\nSupports both:\n- Legacy Pub/Sub push format (base64-encoded message.data)\n- Direct JSON event posting (flat JSON body)","operationId":"pubsub_push_endpoint_pubsub_push_post","parameters":[{"name":"x-internal-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Internal-Token"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/user/ensure-account":{"post":{"tags":["users"],"summary":"Ensure Account","description":"Make sure a signed-in user has their account row. Idempotent.\n\nThe frontend calls this once per browser session after sign-in. The row\nused to appear only on the first account page view, paid run or checkout,\nso most people who signed in to browse or download from /explore never got\none (26 rows for 179 Supabase users on 2026-10-21), and credits, email\npreference links and anything else keyed on the row missed them.","operationId":"ensure_account_user_ensure_account_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EnsureAccountBody"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/subscription":{"get":{"tags":["users"],"summary":"Get User Subscription","description":"Get or create the current user's subscription details.","operationId":"get_user_subscription_user_subscription_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSubscriptionResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"post":{"tags":["users"],"summary":"Update User Subscription","description":"Update user subscription details.\nRestricted to Admin users.","operationId":"update_user_subscription_user_subscription_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSubscriptionUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSubscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/assign-plan":{"post":{"tags":["users"],"summary":"Assign User Plan","description":"Admin-only: assign a plan without payment (test tooling). Real plan changes\ngo through Stripe checkout.\nExpects {\"plan\": \"free\" | \"tier2\" | \"tier3\"}\nReturns the updated subscription.","operationId":"assign_user_plan_user_assign_plan_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignPlanRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSubscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/transactions":{"get":{"tags":["users"],"summary":"Get Credit Transactions","description":"Get the credit transaction history for the current user.","operationId":"get_credit_transactions_user_transactions_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditTransactionsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/user/profile":{"get":{"tags":["users"],"summary":"Get User Profile","operationId":"get_user_profile_user_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"put":{"tags":["users"],"summary":"Update User Profile","operationId":"update_user_profile_user_profile_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/settings":{"get":{"tags":["users"],"summary":"Get User Settings","description":"Get persisted account settings/preferences for the current user.","operationId":"get_user_settings_user_settings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferencesResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"put":{"tags":["users"],"summary":"Update User Settings","operationId":"update_user_settings_user_settings_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferencesUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferencesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/security":{"get":{"tags":["users"],"summary":"Get User Security","operationId":"get_user_security_user_security_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecuritySettingsResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/recharge-options":{"get":{"tags":["users"],"summary":"Get Recharge Options","operationId":"get_recharge_options_user_recharge_options_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RechargeOptionsResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/user/recent-usage":{"get":{"tags":["users"],"summary":"Get Recent Usage","operationId":"get_recent_usage_user_recent_usage_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/user/account":{"get":{"tags":["users"],"summary":"Get Account Summary","operationId":"get_account_summary_user_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSummaryResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"patch":{"tags":["users"],"summary":"Update Account Name","description":"Update the user's first/last name in Supabase auth metadata (§2.6).","operationId":"update_account_name_user_account_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account/summary":{"get":{"tags":["account"],"summary":"Get Account Summary","operationId":"get_account_summary_account_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPageSummaryResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account/usage-history":{"get":{"tags":["account"],"summary":"Get Usage History","operationId":"get_usage_history_account_usage_history_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/account/settings":{"get":{"tags":["account"],"summary":"Get Account Settings","operationId":"get_account_settings_account_settings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSettingsResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account/profile":{"get":{"tags":["account"],"summary":"Get Account Profile","operationId":"get_account_profile_account_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountProfileResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"put":{"tags":["account"],"summary":"Update Account Profile","operationId":"update_account_profile_account_profile_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountProfileUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account/profile/username-available":{"get":{"tags":["account"],"summary":"Username Available","operationId":"username_available_account_profile_username_available_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Username"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameAvailableResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/account/profile/avatar":{"post":{"tags":["account"],"summary":"Upload Avatar","operationId":"upload_avatar_account_profile_avatar_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_avatar_account_profile_avatar_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account/export":{"get":{"tags":["account"],"summary":"Export Account Data","description":"Machine-readable export of everything we store about the caller:\nprofile, subscription state, credit ledger, workflows, and library tracks\n(metadata only — audio is downloadable via the existing download routes).","operationId":"export_account_data_account_export_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account/email":{"post":{"tags":["account"],"summary":"Change Email","operationId":"change_email_account_email_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailChangeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailChangeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/account":{"delete":{"tags":["account"],"summary":"Delete Account","description":"Irreversible account deletion: Stripe → R2 → DB → Supabase auth (§2.8).","operationId":"delete_account_account_delete","responses":{"204":{"description":"Successful Response"}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/articles":{"get":{"tags":["articles"],"summary":"List Articles","description":"List published articles.","operationId":"list_articles_articles_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":10,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/articles/{slug}":{"get":{"tags":["articles"],"summary":"Get Article","description":"Get a published article by slug.","operationId":"get_article_articles__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/articles":{"post":{"tags":["admin-cms"],"summary":"Create Draft","description":"Create a new article draft.","operationId":"create_draft_admin_articles_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"get":{"tags":["admin-cms"],"summary":"List All Articles","description":"List all articles with optional status filter.","operationId":"list_all_articles_admin_articles_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(draft|published|archived)$"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/articles/{id}":{"get":{"tags":["admin-cms"],"summary":"Get Admin Article","description":"Get any article by ID.","operationId":"get_admin_article_admin_articles__id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","title":"Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["admin-cms"],"summary":"Update Article","description":"Update article content.","operationId":"update_article_admin_articles__id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","title":"Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["admin-cms"],"summary":"Delete Article","description":"Hard delete an article.","operationId":"delete_article_admin_articles__id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","title":"Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/articles/{id}/publish":{"post":{"tags":["admin-cms"],"summary":"Publish Article","description":"Publish an article.","operationId":"publish_article_admin_articles__id__publish_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","title":"Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/articles/{id}/unpublish":{"post":{"tags":["admin-cms"],"summary":"Unpublish Article","description":"Unpublish an article (revert to draft).","operationId":"unpublish_article_admin_articles__id__unpublish_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","title":"Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/articles/{id}/archive":{"post":{"tags":["admin-cms"],"summary":"Archive Article","description":"Soft delete/archive an article.","operationId":"archive_article_admin_articles__id__archive_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","title":"Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/media/signed-upload":{"post":{"tags":["admin-cms"],"summary":"Get Media Upload Url","description":"Get signed URL for media upload.","operationId":"get_media_upload_url_admin_media_signed_upload_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"filename","in":"query","required":true,"schema":{"type":"string","title":"Filename"}},{"name":"content_type","in":"query","required":false,"schema":{"type":"string","default":"image/jpeg","title":"Content Type"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/plans":{"get":{"tags":["billing"],"summary":"Get Billing Plans","description":"Return all available subscription plans and top-up packs.\n\nPrices are quoted in USD, or in CNY when Cloudflare geolocates the caller\nto mainland China. `?currency=` overrides that (used by the currency\ntoggle) and the chosen currency is echoed in the response so the frontend\ncan send it back at checkout.","operationId":"get_billing_plans_billing_plans_get","parameters":[{"name":"currency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPlansResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/payment-method":{"get":{"tags":["billing"],"summary":"Get Payment Method","description":"Return the default card on the user's Stripe customer (§3.1).\n\n404 when the user has no Stripe customer or no saved card — the FE hides\nthe Payment-method section until this returns 200 with data.","operationId":"get_payment_method_billing_payment_method_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/subscribe":{"post":{"tags":["billing"],"summary":"Subscribe","description":"Admin-only: set a plan without payment. Real subscriptions go through Stripe checkout.","operationId":"subscribe_billing_subscribe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/topup":{"post":{"tags":["billing"],"summary":"Topup","description":"Admin-only: grant a top-up without payment. Real top-ups go through Stripe checkout.","operationId":"topup_billing_topup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/create-checkout-session":{"post":{"tags":["billing"],"summary":"Create Checkout Session","description":"Create a Stripe Checkout Session for the signed-in user and return its URL.\n\nFlow:\n  1. Resolve the requested plan key to a Stripe price ID + checkout mode.\n  2. Look up the user's stored Stripe customer ID, creating one if missing.\n  3. Create a Checkout Session with Managed Payments enabled (per the\n     blueprint, requires API version 2026-02-25.preview).\n  4. Return the session ID + URL. The frontend redirects the browser there.\n\nChinese traffic (per Cloudflare's CF-IPCountry, so the browser must call\napi.groovesheet.net directly, not through Vercel's /api) is checked out\nin yuan on a Chinese-language Checkout page, and top-ups also offer Alipay\nand WeChat Pay. Both wallets are one-time only — Stripe doesn't support\nthem in Checkout's subscription mode — so plans stay card-only.\n\nStripe sends `checkout.session.completed` to /billing/webhook once the\ncustomer pays — that's where we actually credit the account.","operationId":"create_checkout_session_billing_create_checkout_session_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/guest-checkout-session":{"post":{"tags":["billing"],"summary":"Create Guest Checkout Session","description":"Checkout for a visitor who isn't signed in. Stripe collects the email.\n\nThe account is found or created for that email once the payment settles\n(webhook, or POST /billing/guest-claim from the success page, whichever\ncomes first). See services/guest_checkout.py for who gets signed in.","operationId":"create_guest_checkout_session_billing_guest_checkout_session_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/guest-claim":{"post":{"tags":["billing"],"summary":"Guest Claim","description":"The success page of a guest checkout: make sure the minutes are there.\n\nCredits the session if the webhook hasn't yet (both are idempotent, see\nfulfil_checkout_session), and returns a one-time sign-in token when the\naccount was created by this session and never signed into. Otherwise it\nnames the address, and the buyer signs in as usual.","operationId":"guest_claim_billing_guest_claim_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestClaimRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestClaimResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/create-portal-session":{"post":{"tags":["billing"],"summary":"Create Portal Session","description":"Create a Stripe Billing Portal session for the signed-in user.\n\nLets a subscribed user self-manage/cancel their subscription and update\ntheir card on a Stripe-hosted page. Returns the portal URL; the frontend\nredirects the browser there.\n\nRequires the user to have a stored Stripe customer ID — i.e. they must\nhave gone through checkout at least once. Free users who never checked\nout get a 409 with a clear message instead of an opaque Stripe error.\n\nNOTE: the Billing Portal must be activated once in the Stripe dashboard\n(Settings -> Billing -> Customer portal -> Save) before this works in a\ngiven mode; otherwise Stripe returns an error on the first call.","operationId":"create_portal_session_billing_create_portal_session_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePortalSessionResponse"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/cancel-subscription":{"post":{"tags":["billing"],"summary":"Cancel Subscription","description":"Cancel the signed-in user's subscription (Airwallex in-app cancel path).\n\nAirwallex has no hosted portal, so this replaces the Stripe Billing Portal's\ncancel action. Stripe users still cancel via the portal.","operationId":"cancel_subscription_billing_cancel_subscription_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/checkout-session/{session_id}":{"get":{"tags":["billing"],"summary":"Get Checkout Session","description":"What this Checkout Session actually charged, verified against Stripe.\n\nThe success page needs the real amount to report a conversion value to\nGoogle Ads. It cannot be trusted to compute one: the price shown depends on\npresentment currency and any discount, and a number carried in the redirect\nURL is attacker-controlled. So the page asks here and we read it back from\nStripe, refusing sessions that belong to somebody else.","operationId":"get_checkout_session_billing_checkout_session__session_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/revenue":{"get":{"tags":["billing"],"summary":"Get Revenue","description":"Revenue actually collected, for comparison against ad spend.\n\nEvery paid checkout writes `amount_cents`, `currency` and (when the visitor\narrived on an ad) `gclid` onto its credit transaction, so the money can be\ntotalled here rather than reconstructed from Stripe by hand. `ad_attributed`\ncounts only payments carrying a Google click id -- the subset whose\nacquisition cost is actually known -- which is what makes a\nreturn-on-ad-spend number honest instead of assumed.","operationId":"get_revenue_billing_revenue_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/webhook":{"post":{"tags":["billing"],"summary":"Stripe Webhook","description":"Payment webhook receiver (Stripe or Airwallex, by provider).\n\nVerifies the signature when STRIPE_WEBHOOK_SECRET is set (production),\nand falls back to JSON parsing in dev when it isn't.\n\nHandled events:\n    checkout.session.completed       -> credit account, store subscription_id\n    customer.subscription.deleted    -> downgrade to free\n    invoice.payment_failed           -> log (extend with email/notification later)","operationId":"stripe_webhook_billing_webhook_post","parameters":[{"name":"stripe-signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe-Signature"}},{"name":"x-timestamp","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Timestamp"}},{"name":"x-signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Signature"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/paypal-checkout":{"post":{"tags":["billing"],"summary":"Create Paypal Checkout","operationId":"create_paypal_checkout_billing_paypal_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaypalCheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/airwallex-checkout":{"post":{"tags":["billing"],"summary":"Create Method Checkout","operationId":"create_method_checkout_billing_airwallex_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodCheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaypalCheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/airwallex-guest-checkout":{"post":{"tags":["billing"],"summary":"Create Guest Method Checkout","description":"The same, for a visitor who isn't signed in: the account follows the payment.","operationId":"create_guest_method_checkout_billing_airwallex_guest_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestMethodCheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaypalCheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/paypal-confirm":{"post":{"tags":["billing"],"summary":"Confirm Paypal Checkout","description":"The return page asks: did it go through? Credits it if the webhook hasn't.","operationId":"confirm_paypal_checkout_billing_paypal_confirm_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaypalConfirmRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaypalConfirmResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/billing/airwallex-guest-claim":{"post":{"tags":["billing"],"summary":"Claim Guest Intent","description":"A guest's success page after Airwallex: like POST /billing/guest-claim.\n\nCredits the intent if the webhook hasn't, and hands a one-time sign-in\ntoken only to the account this payment created (guest_checkout.may_sign_in).","operationId":"claim_guest_intent_billing_airwallex_guest_claim_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestIntentClaimRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestClaimResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/preview/uploads":{"post":{"tags":["preview"],"summary":"Create Chunked Upload","description":"Open an upload sent in pieces (see services/chunked_uploads.py).\n\nJSON body: ``{\"size\": <bytes>, \"filename\": ..., \"content_type\": ...}``.\nAnswers ``{\"upload_id\", \"chunk_size\", \"chunks\"}``. Opening one costs no\npreview; the preview limit applies when POST /preview/{workflow} starts it.","operationId":"create_chunked_upload_preview_uploads_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/preview/uploads/{upload_id}/{index}":{"put":{"tags":["preview"],"summary":"Put Upload Chunk","description":"One chunk of an upload, as the raw request body.","operationId":"put_upload_chunk_preview_uploads__upload_id___index__put","parameters":[{"name":"upload_id","in":"path","required":true,"schema":{"type":"string","title":"Upload Id"}},{"name":"index","in":"path","required":true,"schema":{"type":"integer","title":"Index"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/preview/{workflow_name}":{"post":{"tags":["preview"],"summary":"Start Preview","operationId":"start_preview_preview__workflow_name__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409.","title":"Idempotency-Key"},"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409."},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_start_preview_preview__workflow_name__post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"409":{"description":"Another request with this Idempotency-Key is still being processed."},"422":{"description":"The Idempotency-Key was already used for a different request (or the input was unusable)."}}}},"/preview/{workflow_name}/from-url":{"post":{"tags":["preview"],"summary":"Start Preview From Url","operationId":"start_preview_from_url_preview__workflow_name__from_url_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409.","title":"Idempotency-Key"},"description":"Opaque client-chosen key (a UUID works) that makes this request safe to retry. The same key from the same caller within 24 hours returns the first response (marked `Idempotent-Replayed: true`) instead of starting the work again. Reusing a key for a different request answers 422; reusing it while the first request is still running answers 409."},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"409":{"description":"Another request with this Idempotency-Key is still being processed."},"422":{"description":"The Idempotency-Key was already used for a different request (or the input was unusable)."}}}},"/preview/{preview_id}/retry/{workflow_name}":{"post":{"tags":["preview"],"summary":"Retry Preview","description":"Preview the same song again with another workflow (another instrument).\n\nFor \"this song has no piano, try drums\": the upload is already stored, so\nthe visitor doesn't send it again. On 2026-10-12 a visitor's re-upload for\nexactly this failed three times on their connection and they left.","operationId":"retry_preview_preview__preview_id__retry__workflow_name__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}},{"name":"workflow_name","in":"path","required":true,"schema":{"type":"string","title":"Workflow Name"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/preview/status/{preview_id}":{"get":{"tags":["preview"],"summary":"Get Preview Status","description":"Status + outputs of a preview. Authorized for the originating session\n(anonymous cookie) or the owning user (after sign-up + claim).","operationId":"get_preview_status_preview_status__preview_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/preview/score-pdf/{preview_id}":{"get":{"tags":["preview"],"summary":"Download Preview Score Pdf","description":"Paginated PDF of a preview's score — the workflow endpoint's twin.\n\nPreviews are the anonymous funnel, so the teaser hands over the same\nprint-ready file a signed-in transcription does (just of the 10s excerpt).","operationId":"download_preview_score_pdf_preview_score_pdf__preview_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/preview/download/{preview_id}/{file_key}":{"get":{"tags":["preview"],"summary":"Download Preview File","description":"Stream a single output asset from a completed preview.","operationId":"download_preview_file_preview_download__preview_id___file_key__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}},{"name":"file_key","in":"path","required":true,"schema":{"type":"string","title":"File Key"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/preview/{preview_id}/claim":{"post":{"tags":["preview"],"summary":"Claim Preview","description":"Transfer an anonymous preview's ownership to the calling user.\n\nTriggered by the frontend right after a successful sign-up. Idempotent:\nrepeated calls return the same row. Also grants the one-time signup\ncredit bonus on the first claim per user (independent of preview count).\n\nBody (optional): ``{\"offer\": \"get_free\"}`` when the visitor signed up by\ntapping the Free plan's \"Get Free\" after a preview. Then a new account\n(under two hours old) that never had one gets the credits to run THIS\npreview's whole song (at most 10 minutes), once per user ever, and the\nresponse says so: ``song_credit_granted`` (bool) and ``song_credit_minutes``\n(int, minutes of audio, rounded up; 0 when not granted) are always present.\nA retried claim of a preview that already got it answers the same again.\nA failed grant never fails the claim.\n\nAuthorization rules:\n  - Caller must be authenticated (Supabase JWT).\n  - Either the inbound gs_anon cookie matches preview.anon_session_digest\n    (normal path), OR the row is unclaimed and was created within the\n    last CLAIM_GRACE_MINUTES (cookie-cleared recovery path).","operationId":"claim_preview_preview__preview_id__claim_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClaimRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/preview/{preview_id}/upgrade-to-full":{"post":{"tags":["preview"],"summary":"Upgrade To Full","description":"Run the full (non-preview) workflow against the retained upload.\n\nNo re-upload required — we re-use the original file the user dropped\nwhen they generated the preview. Requires the user to own the preview\n(post-claim) and to have enough credits for the full song's duration.\n\nOne preview buys one full run. A second request for the same preview gets\nthe run that is already going (or done) instead of a second charge: on\n2026-10-17 a buyer's tap and the after-checkout resume landed 2 ms apart\nand paid for the song twice.","operationId":"upgrade_to_full_preview__preview_id__upgrade_to_full_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/lookup":{"get":{"tags":["library"],"summary":"Lookup Parsed Music","description":"Check whether requested music already exists for this user or publicly.","operationId":"lookup_parsed_music_library_lookup_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Loose title/artist/album search","title":"Q"},"description":"Loose title/artist/album search"},{"name":"spotify_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Spotify Id"}},{"name":"isrc","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Isrc"}},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"}},{"name":"artist","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Artist"}},{"name":"filename","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"}},{"name":"workflow_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Name"}},{"name":"include_assets","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Include Assets"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/me/tracks":{"get":{"tags":["library"],"summary":"List My Tracks","description":"Authenticated user's private parsed-music catalog.","operationId":"list_my_tracks_library_me_tracks_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Loose title/artist/album search","title":"Q"},"description":"Loose title/artist/album search"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp; return rows older than this","title":"Cursor"},"description":"ISO timestamp; return rows older than this"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":60,"minimum":1,"default":24,"title":"Limit"}},{"name":"include_assets","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Assets"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks":{"get":{"tags":["library"],"summary":"List Tracks","description":"Public catalog browse + search.\n\nTwo pagination modes:\n  * default — cursor over published_at desc, for the Explore hub's endless\n    \"Load More\". Browse only: a rank-ordered search can't be resumed from a\n    published_at cursor.\n  * `page=N` — offset pagination with `total`/`pages`, for the numbered\n    results page. Rank order is stable across offsets, so this is the mode\n    that may be combined with `q` and any `sort`.","operationId":"list_tracks_library_tracks_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Full-text query against title/artist/album","title":"Q"},"description":"Full-text query against title/artist/album"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp; return rows older than this","title":"Cursor"},"description":"ISO timestamp; return rows older than this"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"description":"1-based page; switches to offset pagination with totals","title":"Page"},"description":"1-based page; switches to offset pagination with totals"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":60,"minimum":1,"default":24,"title":"Limit"}},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"relevance|popular|newest|oldest|plays|downloads|title","title":"Sort"},"description":"relevance|popular|newest|oldest|plays|downloads|title"},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated: sheet|midi|stems","title":"Format"},"description":"Comma-separated: sheet|midi|stems"},{"name":"instrument","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated stem names: piano,drums,…","title":"Instrument"},"description":"Comma-separated stem names: piano,drums,…"},{"name":"notation","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Single stem name. Keep only tracks transcribed to notation for that part (a musicxml asset with this stem_name), which is narrower than `instrument`, that only asks whether the part was separated.","title":"Notation"},"description":"Single stem name. Keep only tracks transcribed to notation for that part (a musicxml asset with this stem_name), which is narrower than `instrument`, that only asks whether the part was separated."},{"name":"length","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated: under2|2to5|over5","title":"Length"},"description":"Comma-separated: under2|2to5|over5"},{"name":"facets","in":"query","required":false,"schema":{"type":"boolean","description":"Include sidebar facet counts for this query","default":false,"title":"Facets"},"description":"Include sidebar facet counts for this query"},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}":{"get":{"tags":["library"],"summary":"Get Track","description":"Detail view for a public/unlisted track or an owned private track.\nAccepts the track UUID or its public slug.\n\nFor public and unlisted (link-shared) tracks each asset carries an inline\n`stream_url` (presigned R2 GET, 15 min) for streamable formats; lossless\nmasters (wav/flac) get `stream_url: null` and remain behind the\nauthenticated download path. Private tracks keep `stream_url: null`\neverywhere — owners go through `/library/assets/{id}/url` with auth.","operationId":"get_track_library_tracks__track_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/batch":{"post":{"tags":["library"],"summary":"Get Tracks Batch","description":"Several track details in one request.\n\nThe body is `{\"ids\": [...]}` with up to 50 UUIDs or slugs. The answer is\n`{\"tracks\": [...]}` in the same order, each entry the record\n`GET /library/tracks/{track_id}` would return, or `null` for an id that\ndoes not exist or is not visible to the caller. One request instead of\nfifty for an agent that has a list of ids from a search.","operationId":"get_tracks_batch_library_tracks_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_BatchTracksRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/library/assets/{asset_id}/url":{"get":{"tags":["library"],"summary":"Get Asset Url","description":"Return a 302 redirect to a presigned R2 URL for the asset.\n\n`format=json` returns `{\"url\": ...}` instead. The browser ZIP (gs-fe\nlib/libraryDownload.ts) needs it: following the 302 from our origin to R2\nwith an Authorization header failed on every Safari download on\n2026-10-13 (Safari either keeps the header, which R2 rejects and refuses\nto preflight, or sends `Origin: null`, which R2's CORS rule does not\nanswer). Fetching the signed URL directly is a plain CORS GET everywhere.\n\n`purpose=stream` — public, returns a short-lived URL (5 min). For public\ntracks only streamable formats (mp3/opus/mid/musicxml/json) are allowed;\nlossless masters (wav/flac) require the authenticated download path.\n\n`purpose=download` — requires sign-in. Returns a longer-lived URL (1 hour).","operationId":"get_asset_url_library_assets__asset_id__url_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}},{"name":"purpose","in":"query","required":false,"schema":{"type":"string","pattern":"^(stream|download)$","default":"stream","title":"Purpose"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(redirect|json)$","default":"redirect","title":"Format"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/assets/{asset_id}/pdf":{"get":{"tags":["library"],"summary":"Get Asset Pdf","description":"Engrave a MusicXML asset to PDF and redirect to it.\n\n/explore has always told visitors the score is \"downloadable as PDF and\nMusicXML\" while only offering the MusicXML — a file most people cannot\nopen, and cannot put on a music stand. Same visibility rules as streaming\nthe MusicXML itself, plus sign-in, like every other library download.\n`format=json` returns `{\"url\": ...}`, which the song page needs because a\ntab opened with window.open() cannot carry the Authorization header.\n\nRendering a long score is seconds of CPU, so the result is cached in R2\nbeside the source and every later request is a redirect like any other\nasset. The cache key is derived from the score's own key, so re-running a\ntranscription (which writes a new key) produces a new PDF rather than\nserving a stale one.","operationId":"get_asset_pdf_library_assets__asset_id__pdf_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(redirect|json)$","default":"redirect","title":"Format"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/assets/{asset_id}/gp5":{"get":{"tags":["library"],"summary":"Get Asset Gp5","description":"Convert a MusicXML asset to Guitar Pro 5 and redirect to it.\n\nGuitar Pro is what drummers, bassists and guitarists open (Guitar Pro,\nSongsterr, TuxGuitar and MuseScore all read .gp5); MusicXML means little\nto most of them. Same visibility and sign-in rules as the PDF, the same\n`format=json` option, and cached in R2 the same way.","operationId":"get_asset_gp5_library_assets__asset_id__gp5_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(redirect|json)$","default":"redirect","title":"Format"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}/events":{"post":{"tags":["library"],"summary":"Record Track Event","description":"Record an engagement event (currently only 'play'). Anonymous-capable;\ndeduped per (track, viewer) per hour so replays don't inflate counters,\nand rate-limited per IP so rotating identities can't flood the counters\nor mint unbounded Redis keys. Downloads are counted server-side at the\ndownload endpoints instead.","operationId":"record_track_event_library_tracks__track_id__events_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}/report":{"post":{"tags":["library"],"summary":"Report Track","description":"Report a published track (copyright / abuse). Anonymous-capable; one\nreport per viewer per track. At _REPORT_UNLIST_THRESHOLD distinct\nreporters a public track is automatically unlisted pending review — this\nis the launch DMCA path until an admin review surface ships.","operationId":"report_track_library_tracks__track_id__report_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/files/{token}":{"get":{"tags":["library"],"summary":"Get Marked File","description":"A library file with GrooveSheet's credit and the downloader's ID stamped in.\n\nThe token (services/download_marks.make_token) is minted by the download\nroutes for a signed-in user and expires after an hour, like the R2 URLs it\nreplaces. No Authorization header: the browser ZIP fetches it with\ncredentials omitted, as it did R2. Stamping is deterministic, so a resumed\ndownload's `Range` (one range, as lib/libraryDownload.ts sends) lines up.","operationId":"get_marked_file_library_files__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}/download":{"get":{"tags":["library"],"summary":"Download Track Zip","description":"Download every asset of a track as one ZIP. Sign-in required (parity\nwith the per-asset download path); visibility-gated like the detail view.","operationId":"download_track_zip_library_tracks__track_id__download_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/reserve":{"post":{"tags":["library-social"],"summary":"Reserve Track","description":"Idempotently reserve the Explore record for `spotify_id`.\n\nRepeated calls return the same UUID, the same slug, and the same canonical\nURL. Concurrent calls collapse onto one row through the `spotify_id` unique\nindex. The slug is assigned in the same transaction that creates the row, so\na record is never visible with `slug = NULL` waiting for an API restart.","operationId":"reserve_track_library_tracks_reserve_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReserveRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/library/social/lookup":{"get":{"tags":["library-social"],"summary":"Lookup Track","description":"Read-only resolver: the Explore record for a `spotify_id`, or 404.\n\nReserve is idempotent, but it still creates a row when the record does not\nexist yet. Reconciliation and backfill tooling only ever wants to ask\n\"does this song already have an Explore record?\", and answering that with\nreserve would invent production data for every unmatched ledger row. This\nendpoint never writes.\n\nDeliberately NOT under `/library/tracks/`. `routes/library.py` already\nowns `GET /library/tracks/{track_id}` and `GET /library/lookup`, and it is\nregistered first in `main.py`, so either of those paths would be swallowed\nby the public resolver and answer \"Track not found\" instead of reaching\nthis handler.","operationId":"lookup_track_library_social_lookup_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"spotify_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Spotify Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}/readiness":{"get":{"tags":["library-social"],"summary":"Track Readiness","description":"Is this record ready for a `content_kind` video to link to it?\n\nNever raises for an unready record - the pipeline needs the reason codes.","operationId":"track_readiness_library_tracks__track_id__readiness_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"name":"content_kind","in":"query","required":true,"schema":{"type":"string","description":"one of stem_video, piano_transcription, drum_transcription, bass_transcription, guitar_transcription, chord_chart","title":"Content Kind"},"description":"one of stem_video, piano_transcription, drum_transcription, bass_transcription, guitar_transcription, chord_chart"},{"name":"stem","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"for stem_video: the stem the video shows","title":"Stem"},"description":"for stem_video: the stem the video shows"},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}/chord-chart":{"put":{"tags":["library-social"],"summary":"Put Chord Chart","description":"Attach (or re-point) the chord chart of an Explore record. Idempotent.\n\nThe assets land under the \"chords\" part, which is what the `chord_chart`\nreadiness check looks for. Visibility is untouched: the pipeline publishes\nthrough the social patch endpoint as for every other kind.","operationId":"put_chord_chart_library_tracks__track_id__chord_chart_put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChordChartRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/library/tracks/{track_id}/social":{"patch":{"tags":["library-social"],"summary":"Patch Track Social","description":"Set visibility and/or platform backlinks.\n\nBacklinks use COALESCE semantics: a YouTube update can only fill a NULL\n`youtube_url`, and can never touch `bilibili_url`. A conflicting non-null\nvalue is reported rather than overwritten, so a retry against a different\nupload surfaces instead of silently rewriting history.","operationId":"patch_track_social_library_tracks__track_id__social_patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","title":"Track Id"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialPatchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/creators/{username}":{"get":{"tags":["creators"],"summary":"Get Creator Profile","description":"Public creator profile + their visibility-filtered published songs.","operationId":"get_creator_profile_creators__username__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","title":"Username"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/creators/{username}/follow":{"post":{"tags":["creators"],"summary":"Follow Creator","description":"Follow a creator. Idempotent; self-follow → 400.","operationId":"follow_creator_creators__username__follow_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","title":"Username"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["creators"],"summary":"Unfollow Creator","description":"Unfollow a creator. Idempotent.","operationId":"unfollow_creator_creators__username__follow_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","title":"Username"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/status":{"get":{"tags":["status"],"summary":"Public Status","operationId":"public_status_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/status/history":{"get":{"tags":["status"],"summary":"Status History","operationId":"status_history_status_history_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/service-status":{"get":{"tags":["status"],"summary":"Service Status","operationId":"service_status_service_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"deprecated":true,"x-sunset":"Sat, 06 Feb 2027 00:00:00 GMT","x-deprecated-at":"2026-11-06T00:00:00Z","x-successor":"/status","description":"**Deprecated** since 2026-11-06, sunset Sat, 06 Feb 2027 00:00:00 GMT. Replaced by GET /status (public pool status) and GET /status/history.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/seo/sitemap.xml":{"get":{"tags":["seo"],"summary":"Sitemap","operationId":"sitemap_seo_sitemap_xml_get","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","description":"'all' (default) is the CRA-era single sitemap: static routes, tracks, blog posts and creators. 'library' is only the tracks and creators in one file (every locale), which the frontend's per-locale plain sitemaps and the Baidu file are cut from. 'library-index' is a sitemap index of the per-locale, per-page-type children, served at /sitemaps/library.xml and in step with /sitemap.xml.","default":"all","title":"Scope"},"description":"'all' (default) is the CRA-era single sitemap: static routes, tracks, blog posts and creators. 'library' is only the tracks and creators in one file (every locale), which the frontend's per-locale plain sitemaps and the Baidu file are cut from. 'library-index' is a sitemap index of the per-locale, per-page-type children, served at /sitemaps/library.xml and in step with /sitemap.xml."},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/seo/library-sitemaps/{name}":{"get":{"tags":["seo"],"summary":"Library Child Sitemap","description":"One child of the library sitemap: /sitemaps/library-{locale}-{kind}.xml.\n\nThe frontend rewrites /sitemaps/library-*.xml here. Unknown locales and\nkinds (and light locales, which have no library pages in search) are 404s\nrather than empty files, so a typo or a retired child cannot sit in\nSearch Console looking healthy.","operationId":"library_child_sitemap_seo_library_sitemaps__name__get","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/seo/library-index":{"get":{"tags":["seo"],"summary":"Library Index","description":"Every public song with the part pages it has: what the frontend's\n/explore/all page renders, so each song and part page is one click from a\npage every footer links to. JSON, small (one row per song).","operationId":"library_index_seo_library_index_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/seo/locale-contract":{"get":{"tags":["seo"],"summary":"Locale Contract Endpoint","description":"What this service believes the site's locales and library page types are.\n\nRead by the frontend's `npm run check:locales` (and its CI step), which\ncompares it with i18n/routing.ts so the two lists cannot drift apart\nunnoticed after a deploy of only one of them.","operationId":"locale_contract_endpoint_seo_locale_contract_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/campaign/{code}":{"get":{"tags":["campaign"],"summary":"Get Campaign","description":"Everything the signup page needs to pick its state and render itself.\n\nAlways 200, including for an unknown code: the page turns a bad code into a\nsoft landing that still sells the product, and a 404 would make that harder\nto distinguish from the API being down.","operationId":"get_campaign_campaign__code__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/campaign/{code}/claim":{"post":{"tags":["campaign"],"summary":"Claim Campaign","description":"Grant this campaign's minutes to the calling account, once.\n\nCalled by the frontend immediately after sign-up (and by the \"Claim\"\nbutton when an already-signed-in visitor opens the link). Repeat calls\nreturn ``already_claimed`` rather than erroring, because the post-signup\npath can legitimately fire twice on a refresh.","operationId":"claim_campaign_campaign__code__claim_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/funnel/events":{"post":{"tags":["funnel"],"summary":"Record Events","operationId":"record_events_funnel_events_post","responses":{"204":{"description":"Successful Response"}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/mcp/upload-links":{"post":{"tags":["mcp"],"summary":"Create Upload Link","operationId":"create_upload_link_mcp_upload_links_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadLinkCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/mcp/upload-links/{code}":{"get":{"tags":["mcp"],"summary":"Get Upload Link","operationId":"get_upload_link_mcp_upload_links__code__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/email-preferences":{"get":{"tags":["email-preferences"],"summary":"Get Preferences","operationId":"get_preferences_email_preferences_get","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","title":"T"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["email-preferences"],"summary":"Update Preferences","operationId":"update_preferences_email_preferences_put","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","title":"T"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/email-preferences/unsubscribe":{"post":{"tags":["email-preferences"],"summary":"One Click Unsubscribe","operationId":"one_click_unsubscribe_email_preferences_unsubscribe_post","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","title":"T"}},{"name":"c","in":"query","required":false,"schema":{"type":"string","default":"all","title":"C"}},{"name":"k","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"K"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/email-preferences/me":{"get":{"tags":["email-preferences"],"summary":"Get My Preferences","operationId":"get_my_preferences_email_preferences_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]},"put":{"tags":["email-preferences"],"summary":"Update My Preferences","operationId":"update_my_preferences_email_preferences_me_put","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/reviews/me":{"get":{"tags":["reviews"],"summary":"My Review","operationId":"my_review_reviews_me_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"t","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"T"}},{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["reviews"],"summary":"Leave Review","operationId":"leave_review_reviews_me_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"t","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"T"}},{"$ref":"#/components/parameters/ApiVersion"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/error-apology":{"post":{"tags":["error-apology"],"summary":"Report Error","description":"Returns {\"status\": ...}; the page shows nothing either way.","operationId":"report_error_error_apology_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}},"/auth/hooks/send-sms":{"post":{"tags":["auth-hooks"],"summary":"Send Sms Hook","operationId":"send_sms_hook_auth_hooks_send_sms_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}]}}},"components":{"schemas":{"AccountPageSummaryResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"tier":{"type":"string","title":"Tier"},"tier_display_name":{"type":"string","title":"Tier Display Name"},"credits_balance":{"type":"integer","title":"Credits Balance"},"minutes_balance":{"type":"number","title":"Minutes Balance"},"balance_minutes":{"type":"number","title":"Balance Minutes"},"is_active":{"type":"boolean","title":"Is Active"},"status":{"type":"string","title":"Status"},"billing_interval":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Interval"},"plan":{"additionalProperties":true,"type":"object","title":"Plan"},"next_recharge_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Recharge At"},"last_recharge_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Recharge At"},"topup_options":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Topup Options"},"available_upgrade_plans":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Available Upgrade Plans"},"low_balance_threshold_minutes":{"type":"number","title":"Low Balance Threshold Minutes"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["user_id","tier","tier_display_name","credits_balance","minutes_balance","balance_minutes","is_active","status","plan","topup_options","available_upgrade_plans","low_balance_threshold_minutes"],"title":"AccountPageSummaryResponse","description":"Flat billing summary for the AccountBilling page (GET /account/summary)."},"AccountProfileResponse":{"properties":{"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"links":{"items":{},"type":"array","title":"Links","default":[]},"member_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Since"}},"type":"object","title":"AccountProfileResponse","description":"Signed-in user's editable creator profile (handover account-pages §2.2)."},"AccountProfileUpdate":{"properties":{"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"links":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Links"}},"type":"object","title":"AccountProfileUpdate","description":"All fields optional; only provided keys are updated (handover §2.3)."},"AccountSettingsResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"auth_provider":{"type":"string","title":"Auth Provider"},"profile_source":{"type":"string","title":"Profile Source"},"profile_edit_mode":{"type":"string","title":"Profile Edit Mode"},"security":{"additionalProperties":true,"type":"object","title":"Security"},"settings":{"additionalProperties":true,"type":"object","title":"Settings"},"support":{"additionalProperties":true,"type":"object","title":"Support"}},"type":"object","required":["user_id","auth_provider","profile_source","profile_edit_mode","security","settings","support"],"title":"AccountSettingsResponse","description":"Account settings/identity for the AccountProfile page (GET /account/settings)."},"AccountSummaryResponse":{"properties":{"profile":{"$ref":"#/components/schemas/UserProfileResponse"},"subscription":{"$ref":"#/components/schemas/UserSubscriptionResponse"},"settings":{"$ref":"#/components/schemas/UserPreferencesResponse"},"security":{"$ref":"#/components/schemas/SecuritySettingsResponse"},"recharge_options":{"$ref":"#/components/schemas/RechargeOptionsResponse"},"recent_usage":{"$ref":"#/components/schemas/RecentUsageResponse"}},"type":"object","required":["profile","subscription","settings","security","recharge_options","recent_usage"],"title":"AccountSummaryResponse"},"ArticleCreate":{"properties":{"slug":{"type":"string","title":"Slug"},"title":{"type":"string","title":"Title"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"cover_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cover Image"}},"type":"object","required":["slug","title"],"title":"ArticleCreate"},"ArticleListResponse":{"properties":{"articles":{"items":{"$ref":"#/components/schemas/ArticleResponse"},"type":"array","title":"Articles"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["articles","total"],"title":"ArticleListResponse"},"ArticleResponse":{"properties":{"slug":{"type":"string","title":"Slug"},"title":{"type":"string","title":"Title"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"cover_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cover Image"},"id":{"type":"integer","title":"Id"},"status":{"type":"string","title":"Status"},"author_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published At"}},"type":"object","required":["slug","title","id","status"],"title":"ArticleResponse"},"ArticleUpdate":{"properties":{"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"cover_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cover Image"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","title":"ArticleUpdate"},"AssignPlanRequest":{"properties":{"plan":{"type":"string","title":"Plan"}},"type":"object","required":["plan"],"title":"AssignPlanRequest","description":"Request model for assigning a plan to the authenticated user."},"AvatarUploadResponse":{"properties":{"avatar_url":{"type":"string","title":"Avatar Url"}},"type":"object","required":["avatar_url"],"title":"AvatarUploadResponse"},"BillingPlansResponse":{"properties":{"plans":{"items":{"$ref":"#/components/schemas/PlanInfo"},"type":"array","title":"Plans"},"topups":{"items":{"$ref":"#/components/schemas/TopupInfo"},"type":"array","title":"Topups"},"provider":{"type":"string","title":"Provider","default":"stripe"},"currency":{"type":"string","title":"Currency","default":"usd"},"wallets":{"items":{"type":"string"},"type":"array","title":"Wallets","default":[]},"paypal":{"type":"boolean","title":"Paypal","default":false},"airwallex_methods":{"items":{"type":"string"},"type":"array","title":"Airwallex Methods","default":[]},"checkout_primary":{"type":"string","title":"Checkout Primary","default":"stripe"},"song_unlock":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Song Unlock"},"promo":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Promo"}},"type":"object","required":["plans","topups"],"title":"BillingPlansResponse"},"Body_start_preview_preview__workflow_name__post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File"},"upload_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upload Id"},"metadata":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata"}},"type":"object","title":"Body_start_preview_preview__workflow_name__post"},"Body_start_sandbox_workflow_sandbox_workflow__workflow_name__post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File","description":"Any audio file, or none. It is discarded unread."}},"type":"object","title":"Body_start_sandbox_workflow_sandbox_workflow__workflow_name__post"},"Body_start_workflow_workflow__workflow_name__post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_start_workflow_workflow__workflow_name__post"},"Body_upload_avatar_account_profile_avatar_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_upload_avatar_account_profile_avatar_post"},"ChordChartRequest":{"properties":{"musicxml_key":{"type":"string","minLength":1,"title":"Musicxml Key"},"json_key":{"type":"string","minLength":1,"title":"Json Key"},"sync_map_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Map Key"}},"type":"object","required":["musicxml_key","json_key"],"title":"ChordChartRequest","description":"R2 keys of one chords_from_mix_full run (chords worker outputs)."},"ClaimRequest":{"properties":{"offer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer"}},"type":"object","title":"ClaimRequest","description":"Optional body of POST /preview/{id}/claim. No body keeps today's behaviour."},"CreateCheckoutSessionRequest":{"properties":{"plan":{"type":"string","title":"Plan"},"success_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Success Url"},"cancel_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Url"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"gclid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gclid"},"gbraid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gbraid"},"wbraid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wbraid"},"preview_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Id"},"ph_distinct_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ph Distinct Id"}},"type":"object","required":["plan"],"title":"CreateCheckoutSessionRequest","description":"Request model for creating a Stripe Checkout Session.\n\n`plan` matches the keys the frontend pricing section emits\n(e.g. 'tier2', 'tier3', 'topup-30'). The backend maps each\nto a configured Stripe price ID + checkout mode."},"CreateCheckoutSessionResponse":{"properties":{"provider":{"type":"string","title":"Provider","default":"stripe"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode"},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Secret"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Id"},"intent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent Id"},"consent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consent Id"}},"type":"object","title":"CreateCheckoutSessionResponse","description":"Checkout hand-off for the frontend.\n\nStripe returns a hosted URL (session_id + url) the browser redirects to.\nAirwallex has no server-returned URL on this account, so it returns the\nids + client_secret the Airwallex JS SDK needs to launch its hosted page\n(`provider=\"airwallex\"`, `mode` in {\"payment\",\"recurring\"})."},"CreatePortalSessionResponse":{"properties":{"url":{"type":"string","title":"Url"}},"type":"object","required":["url"],"title":"CreatePortalSessionResponse","description":"Response containing the hosted Stripe Billing Portal URL to redirect to."},"CreditTransactionResponse":{"properties":{"id":{"type":"integer","title":"Id"},"user_id":{"type":"string","title":"User Id"},"amount":{"type":"integer","title":"Amount"},"amount_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Minutes"},"balance_after":{"type":"integer","title":"Balance After"},"transaction_type":{"type":"string","title":"Transaction Type"},"reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Id"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","user_id","amount","balance_after","transaction_type","created_at"],"title":"CreditTransactionResponse","description":"Response model for a single credit transaction."},"CreditTransactionsResponse":{"properties":{"transactions":{"items":{"$ref":"#/components/schemas/CreditTransactionResponse"},"type":"array","title":"Transactions"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["transactions","total"],"title":"CreditTransactionsResponse","description":"Response model for credit transaction list."},"EmailChangeRequest":{"properties":{"email":{"type":"string","title":"Email"}},"type":"object","required":["email"],"title":"EmailChangeRequest"},"EmailChangeResponse":{"properties":{"status":{"type":"string","title":"Status"}},"type":"object","required":["status"],"title":"EmailChangeResponse"},"EnsureAccountBody":{"properties":{"marketing_opt_in":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Marketing Opt In"}},"type":"object","title":"EnsureAccountBody"},"GuestClaimRequest":{"properties":{"session_id":{"type":"string","maxLength":255,"minLength":10,"title":"Session Id"}},"type":"object","required":["session_id"],"title":"GuestClaimRequest","description":"The success page of a signed-out checkout, asking for the account."},"GuestClaimResponse":{"properties":{"status":{"type":"string","title":"Status"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"account":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account"},"token_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Hash"},"token_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Type"},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name"},"minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Minutes"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"}},"type":"object","required":["status"],"title":"GuestClaimResponse","description":"What a guest checkout came to.\n\nstatus: \"paid\" (minutes added), \"pending\" (Alipay/WeChat Pay still\nconfirming, ask again), or \"expired\" (too long ago to sign in from here).\naccount: \"new\" when this checkout created the account, \"existing\" when the\nemail already had one (sign in to use the minutes).\ntoken_hash/token_type: a one-time sign-in for a new account, for\nsupabase.auth.verifyOtp. Absent otherwise."},"GuestIntentClaimRequest":{"properties":{"intent_id":{"type":"string","maxLength":80,"minLength":5,"title":"Intent Id"}},"type":"object","required":["intent_id"],"title":"GuestIntentClaimRequest"},"GuestMethodCheckoutRequest":{"properties":{"plan":{"type":"string","title":"Plan"},"success_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Success Url"},"cancel_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Url"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"gclid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gclid"},"gbraid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gbraid"},"wbraid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wbraid"},"preview_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Id"},"ph_distinct_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ph Distinct Id"},"method":{"type":"string","enum":["paypal","klarna","alipayhk","airwallex"],"title":"Method","default":"paypal"},"email":{"type":"string","maxLength":254,"minLength":3,"title":"Email"}},"type":"object","required":["plan","email"],"title":"GuestMethodCheckoutRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MethodCheckoutRequest":{"properties":{"plan":{"type":"string","title":"Plan"},"success_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Success Url"},"cancel_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Url"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"gclid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gclid"},"gbraid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gbraid"},"wbraid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wbraid"},"preview_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Id"},"ph_distinct_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ph Distinct Id"},"method":{"type":"string","enum":["paypal","klarna","alipayhk","airwallex"],"title":"Method","default":"paypal"}},"type":"object","required":["plan"],"title":"MethodCheckoutRequest"},"NameUpdateRequest":{"properties":{"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"}},"type":"object","title":"NameUpdateRequest"},"PaymentMethodResponse":{"properties":{"brand":{"type":"string","title":"Brand"},"last4":{"type":"string","title":"Last4"},"exp":{"type":"string","title":"Exp"}},"type":"object","required":["brand","last4","exp"],"title":"PaymentMethodResponse"},"PaypalCheckoutResponse":{"properties":{"intent_id":{"type":"string","title":"Intent Id"},"client_secret":{"type":"string","title":"Client Secret"},"currency":{"type":"string","title":"Currency"},"amount":{"type":"number","title":"Amount"},"env":{"type":"string","title":"Env"},"method":{"type":"string","title":"Method","default":"paypal"},"methods":{"items":{"type":"string"},"type":"array","title":"Methods","default":["paypal"]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"}},"type":"object","required":["intent_id","client_secret","currency","amount","env"],"title":"PaypalCheckoutResponse"},"PaypalConfirmRequest":{"properties":{"intent_id":{"type":"string","title":"Intent Id"}},"type":"object","required":["intent_id"],"title":"PaypalConfirmRequest"},"PaypalConfirmResponse":{"properties":{"status":{"type":"string","title":"Status"},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Minutes"}},"type":"object","required":["status"],"title":"PaypalConfirmResponse"},"PlanInfo":{"properties":{"id":{"type":"string","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"credits_per_month":{"type":"integer","title":"Credits Per Month"},"minutes_per_month":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minutes Per Month"},"price_monthly_usd":{"type":"number","title":"Price Monthly Usd"},"price_annual_usd":{"type":"number","title":"Price Annual Usd"},"price_monthly":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Monthly"},"price_annual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Annual"},"max_rollover":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Rollover"},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"},"checkout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Id"}},"type":"object","required":["id","display_name","credits_per_month","price_monthly_usd","price_annual_usd","max_rollover"],"title":"PlanInfo"},"PlanOptionResponse":{"properties":{"id":{"type":"string","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"credits_per_month":{"type":"integer","title":"Credits Per Month"},"price_monthly_usd":{"type":"number","title":"Price Monthly Usd"},"price_annual_usd":{"type":"number","title":"Price Annual Usd"},"price_monthly":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Monthly"},"price_annual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Annual"},"max_rollover":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Rollover"},"is_current":{"type":"boolean","title":"Is Current"}},"type":"object","required":["id","display_name","credits_per_month","price_monthly_usd","price_annual_usd","max_rollover","is_current"],"title":"PlanOptionResponse"},"RecentUsageItemResponse":{"properties":{"transaction_id":{"type":"integer","title":"Transaction Id"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Id"},"workflow_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Name"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"amount":{"type":"integer","title":"Amount"},"credits_used":{"type":"integer","title":"Credits Used"},"created_at":{"type":"string","title":"Created At"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["transaction_id","amount","credits_used","created_at"],"title":"RecentUsageItemResponse"},"RecentUsageResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RecentUsageItemResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["items","total"],"title":"RecentUsageResponse"},"RechargeOptionsResponse":{"properties":{"current_tier":{"type":"string","title":"Current Tier"},"plans":{"items":{"$ref":"#/components/schemas/PlanOptionResponse"},"type":"array","title":"Plans"},"topups":{"items":{"$ref":"#/components/schemas/TopupOptionResponse"},"type":"array","title":"Topups"},"currency":{"type":"string","title":"Currency","default":"usd"}},"type":"object","required":["current_tier","plans","topups"],"title":"RechargeOptionsResponse"},"ReserveRequest":{"properties":{"spotify_id":{"type":"string","minLength":1,"title":"Spotify Id"},"title":{"type":"string","minLength":1,"title":"Title"},"artist":{"type":"string","minLength":1,"title":"Artist"},"album":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Album"},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"},"isrc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Isrc"},"duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Sec"},"visibility":{"type":"string","title":"Visibility","default":"private"}},"type":"object","required":["spotify_id","title","artist"],"title":"ReserveRequest","description":"Reserve (or look up) the Explore record for one source track."},"SecuritySettingsResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"password_change_supported":{"type":"boolean","title":"Password Change Supported"},"password_reset_supported":{"type":"boolean","title":"Password Reset Supported"},"password_management_mode":{"type":"string","title":"Password Management Mode"},"can_manage_email_here":{"type":"boolean","title":"Can Manage Email Here"}},"type":"object","required":["provider","password_change_supported","password_reset_supported","password_management_mode","can_manage_email_here"],"title":"SecuritySettingsResponse"},"SignedUrlResponse":{"properties":{"upload_url":{"type":"string","title":"Upload Url"},"public_url":{"type":"string","title":"Public Url"}},"type":"object","required":["upload_url","public_url"],"title":"SignedUrlResponse"},"SocialPatchRequest":{"properties":{"visibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visibility"},"youtube_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Youtube Url"},"bilibili_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bilibili Url"}},"type":"object","title":"SocialPatchRequest","description":"Update visibility and/or platform backlinks for one Explore record."},"SubscribeRequest":{"properties":{"plan_id":{"type":"string","title":"Plan Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"}},"type":"object","required":["plan_id"],"title":"SubscribeRequest"},"SubscriptionResponse":{"properties":{"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier"},"credits_balance":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Balance"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"SubscriptionResponse"},"TopupInfo":{"properties":{"id":{"type":"string","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"credits":{"type":"integer","title":"Credits"},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minutes"},"price_usd":{"type":"number","title":"Price Usd"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price"},"priority_queue":{"type":"boolean","title":"Priority Queue"},"checkout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Id"}},"type":"object","required":["id","display_name","credits","price_usd","priority_queue"],"title":"TopupInfo"},"TopupOptionResponse":{"properties":{"id":{"type":"string","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"credits":{"type":"integer","title":"Credits"},"price_usd":{"type":"number","title":"Price Usd"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price"},"priority_queue":{"type":"boolean","title":"Priority Queue"}},"type":"object","required":["id","display_name","credits","price_usd","priority_queue"],"title":"TopupOptionResponse"},"TopupRequest":{"properties":{"pack_id":{"type":"string","title":"Pack Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"}},"type":"object","required":["pack_id"],"title":"TopupRequest"},"TopupResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"pack_id":{"type":"string","title":"Pack Id"},"credits_added":{"type":"integer","title":"Credits Added"},"new_balance":{"type":"number","title":"New Balance"}},"type":"object","required":["user_id","pack_id","credits_added","new_balance"],"title":"TopupResponse"},"UploadLinkCreate":{"properties":{"task":{"type":"string","title":"Task","description":"One of: drums, piano, guitar, bass, chords, stems, drums_midi, piano_midi"},"client":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Client"}},"type":"object","required":["task"],"title":"UploadLinkCreate"},"UsageHistoryItemResponse":{"properties":{"transaction_id":{"type":"integer","title":"Transaction Id"},"transaction_type":{"type":"string","title":"Transaction Type"},"amount":{"type":"integer","title":"Amount"},"minutes_delta":{"type":"number","title":"Minutes Delta"},"balance_after":{"type":"integer","title":"Balance After"},"minutes_balance_after":{"type":"number","title":"Minutes Balance After"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Id"},"workflow_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Name"},"workflow_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Status"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["transaction_id","transaction_type","amount","minutes_delta","balance_after","minutes_balance_after","created_at"],"title":"UsageHistoryItemResponse"},"UsageHistoryResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UsageHistoryItemResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"UsageHistoryResponse"},"UserPreferencesResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email_notifications":{"type":"boolean","title":"Email Notifications"},"marketing_emails":{"type":"boolean","title":"Marketing Emails"},"default_export_format":{"type":"string","title":"Default Export Format"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["user_id","email_notifications","marketing_emails","default_export_format"],"title":"UserPreferencesResponse"},"UserPreferencesUpdate":{"properties":{"email_notifications":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Email Notifications"},"marketing_emails":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Marketing Emails"},"default_export_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Export Format"}},"type":"object","title":"UserPreferencesUpdate"},"UserProfileResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["user_id"],"title":"UserProfileResponse"},"UserProfileUpdate":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"}},"type":"object","title":"UserProfileUpdate"},"UserSubscriptionResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"tier":{"type":"string","title":"Tier"},"credits_balance":{"type":"integer","title":"Credits Balance"},"balance_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Balance Seconds"},"balance_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Balance Minutes"},"is_active":{"type":"boolean","title":"Is Active"},"last_recharge_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Recharge At"},"next_recharge_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Recharge At"},"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id"},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["user_id","tier","credits_balance","is_active"],"title":"UserSubscriptionResponse","description":"Response model for user subscription details."},"UserSubscriptionUpdate":{"properties":{"user_id":{"type":"string","title":"User Id"},"tier":{"type":"string","title":"Tier"},"is_active":{"type":"boolean","title":"Is Active"},"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id"},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Id"},"payment_method_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method Id"}},"type":"object","required":["user_id","tier","is_active"],"title":"UserSubscriptionUpdate","description":"Request model for updating user subscription."},"UsernameAvailableResponse":{"properties":{"available":{"type":"boolean","title":"Available"}},"type":"object","required":["available"],"title":"UsernameAvailableResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WorkflowMetadataUpdate":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"original_artist":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Artist"},"genre_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Genre Tags"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","title":"WorkflowMetadataUpdate"},"WorkflowResponse":{"properties":{"workflow_id":{"type":"string","title":"Workflow Id"},"workflow_name":{"type":"string","title":"Workflow Name"},"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"},"status_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Url"}},"type":"object","required":["workflow_id","workflow_name","status","message"],"title":"WorkflowResponse","description":"Response model for workflow submission."},"WorkflowVisibilityRequest":{"properties":{"visibility":{"type":"string","title":"Visibility"}},"type":"object","required":["visibility"],"title":"WorkflowVisibilityRequest"},"_BatchStatusRequest":{"properties":{"workflow_ids":{"items":{"type":"string"},"type":"array","maxItems":50,"minItems":1,"title":"Workflow Ids"}},"type":"object","required":["workflow_ids"],"title":"_BatchStatusRequest","description":"`POST /workflow/status/batch`: up to 50 workflow ids."},"_BatchTracksRequest":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":50,"minItems":1,"title":"Ids"}},"type":"object","required":["ids"],"title":"_BatchTracksRequest","description":"`POST /library/tracks/batch`: up to 50 track ids or slugs."},"_WorkflowJsonStartRequest":{"properties":{"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","default":{}}},"type":"object","title":"_WorkflowJsonStartRequest","description":"JSON body for /workflow/{name}/from-keys: file-less workflow start."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"parameters":{"ApiVersion":{"name":"API-Version","in":"header","required":false,"description":"Optional. The API version the client was written for. Only `2` exists today.","schema":{"type":"string","enum":["2"],"default":"2"}}}},"servers":[{"url":"https://api.groovesheet.net","description":"Production. Full songs use the account's minutes."},{"url":"https://api.groovesheet.net/sandbox","description":"Sandbox. No token, nothing charged: read routes mirror production and POST /workflow/{workflow_name} simulates a job that completes with a demo song's outputs."}],"externalDocs":{"description":"Developer documentation","url":"https://www.groovesheet.net/developers/docs/api"}}