{ "openapi": "3.1.0", "info": { "title": "ChartNet API", "version": "1.0.0-beta", "description": "Private jobs, passkey accounts and bearer API keys; shared daily quotas. Full API workflow requires a configured CPU runner." }, "servers": [ { "url": "https://chartnet.shadowhusky-london.uk/api" } ], "paths": { "/v1/generate": { "post": { "summary": "Upload audio and enqueue a chart", "operationId": "post_v1_generate", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "202": { "description": "Created / queued job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "filename", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "keys", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 4, "maximum": 7, "default": 4 } }, { "name": "difficulty", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "casual", "easy", "normal", "hard", "full" ], "default": "normal" } }, { "name": "rights", "in": "query", "required": true, "schema": { "type": "boolean", "const": true } }, { "name": "trainingConsent", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw audio; at most 25 MiB and 240 seconds. Send Content-Length." } } } } } }, "/v1/jobs": { "post": { "summary": "Reserve an audio upload", "operationId": "post_v1_jobs", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "201": { "description": "Created / queued job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInput" } } } } }, "get": { "summary": "List your jobs", "operationId": "get_v1_jobs", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/jobs/{id}": { "get": { "summary": "Read job status", "operationId": "get_v1_jobs_job", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Delete audio, chart and feedback", "operationId": "delete_v1_jobs_job", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/jobs/{id}/audio": { "put": { "summary": "Upload audio to a reservation", "operationId": "put_v1_jobs_job_audio", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw audio; at most 25 MiB and 240 seconds. Send Content-Length." } } } } }, "get": { "summary": "Read your audio", "operationId": "get_v1_jobs_job_audio", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/jobs/{id}/chart": { "get": { "summary": "Download generated ChartNet JSON", "operationId": "get_v1_jobs_job_chart", "responses": { "200": { "description": "Generated chart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chart" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/jobs/{id}/events": { "get": { "summary": "Read actual processing events", "operationId": "get_v1_jobs_job_events", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ] } }, "/v1/jobs/{id}/feedback": { "post": { "summary": "Submit structured feedback", "operationId": "post_v1_jobs_job_feedback", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } } } }, "/v1/jobs/{id}/consent": { "patch": { "summary": "Update research consent", "operationId": "patch_v1_jobs_job_consent", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trainingConsent" ], "properties": { "trainingConsent": { "type": "boolean" } } } } } } } }, "/v1/me": { "get": { "summary": "Read remaining daily quota", "operationId": "get_v1_me", "responses": { "200": { "description": "Success" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ctn_\u2026" } }, "schemas": { "JobInput": { "type": "object", "required": [ "title", "filename", "bytes", "keys", "difficulty", "rightsConfirmed" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "filename": { "type": "string", "maxLength": 180 }, "bytes": { "type": "integer", "minimum": 1, "maximum": 26214400 }, "keys": { "type": "integer", "minimum": 4, "maximum": 7 }, "difficulty": { "type": "string", "enum": [ "casual", "easy", "normal", "hard", "full" ] }, "trainingConsent": { "type": "boolean", "default": false }, "rightsConfirmed": { "type": "boolean", "const": true } } }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "uploading", "queued", "processing", "complete", "failed", "rejected", "expired", "deleted", "receiving", "deleting" ] }, "title": { "type": "string" }, "error": { "type": [ "string", "null" ] } } }, "Note": { "type": "object", "required": [ "t", "lane", "dur" ], "properties": { "t": { "type": "number", "minimum": 0, "maximum": 240, "description": "Absolute seconds from audio start" }, "lane": { "type": "integer", "minimum": 0, "maximum": 6 }, "dur": { "type": "number", "minimum": 0, "maximum": 60 } } }, "Chart": { "type": "object", "required": [ "schema", "id", "notes", "keys", "difficulty", "duration", "provenance" ], "properties": { "schema": { "type": "string", "const": "chartnet/1" }, "id": { "type": "string" }, "title": { "type": "string" }, "duration": { "type": "number" }, "bpm": { "type": "number", "description": "Summary BPM; absolute note timestamps are authoritative" }, "keys": { "type": "integer" }, "difficulty": { "type": "string", "enum": [ "casual", "easy", "normal", "hard", "full" ] }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "provenance": { "type": "object", "additionalProperties": true } } }, "Feedback": { "type": "object", "required": [ "ratings", "trainingConsent" ], "properties": { "ratings": { "type": "object", "properties": { "timing": { "type": "integer", "minimum": 1, "maximum": 5 }, "musicality": { "type": "integer", "minimum": 1, "maximum": 5 }, "playability": { "type": "integer", "minimum": 1, "maximum": 5 }, "difficulty": { "type": "integer", "minimum": 1, "maximum": 5 }, "holds": { "type": "integer", "minimum": 1, "maximum": 5 } } }, "text": { "type": "string", "maxLength": 4000 }, "skill": { "type": "string", "enum": [ "new", "casual", "experienced", "expert" ] }, "trainingConsent": { "type": "boolean" }, "offsetMs": { "type": "number", "minimum": -500, "maximum": 500 }, "segment": { "type": "object", "required": [ "start", "end", "issue" ], "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "maximum": 240 }, "issue": { "type": "string", "enum": [ "early", "late", "missing", "extra", "hold", "pattern", "difficulty", "other" ] } } }, "correction": { "type": "array", "maxItems": 8000, "items": { "$ref": "#/components/schemas/Note" } } } } } } }