{ "openapi": "3.1.0", "info": { "title": "Robskan (robskan.nl) public API", "version": "1.0.0", "description": "Anonymous read-only HTTP API for the Robskan portfolio (robskan.nl) and public Spotify listening page.", "x-official-sdk-npm": "robskan", "x-official-cli": "robskan", "x-health-endpoint": "/api/v1/health", "x-openapi": "/openapi.json", "contact": { "name": "Robskan Developers", "url": "https://robskan.nl/developers" } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" }, { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "paths": { "/api/v1": { "get": { "operationId": "getProtectedApiNamespace", "summary": "Protected API namespace (requires auth for writes)", "security": [ { "oauth2": [ "public.read" ] } ], "responses": { "200": { "description": "Namespace metadata when authorized", "content": { "application/json": { "schema": { "type": "object", "required": [ "namespace", "authentication" ], "properties": { "namespace": { "type": "string", "const": "/api/v1" }, "authentication": { "type": "string", "enum": [ "oauth2" ] }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "405": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] }, "post": { "operationId": "postProtectedApiNamespace", "summary": "Protected API namespace (requires auth for writes)", "security": [ { "oauth2": [ "public.read" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedWriteBody" } } } }, "responses": { "200": { "description": "Write accepted when authorized", "content": { "application/json": { "schema": { "type": "object", "required": [ "namespace", "authentication" ], "properties": { "namespace": { "type": "string", "const": "/api/v1" }, "authentication": { "type": "string", "enum": [ "oauth2" ] }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "405": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "API health and discovery", "description": "Machine-verifiable liveness for the public API surface.", "security": [], "responses": { "200": { "description": "Service healthy", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "version", "openapi" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "version": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "sandbox": { "type": "string", "format": "uri" }, "documentation": { "type": "string", "format": "uri" }, "pricing": { "type": "string", "format": "uri" }, "mcpProduct": { "type": "string", "format": "uri" }, "mcpDocs": { "type": "string", "format": "uri" }, "idempotency": { "type": "object", "required": [ "header", "ttlSeconds", "operations" ], "properties": { "header": { "type": "string", "const": "Idempotency-Key" }, "ttlSeconds": { "type": "integer" }, "operations": { "type": "array", "items": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "path": { "type": "string" } } } } } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" }, { "url": "https://robskan.nl/sandbox", "description": "Sandbox test mode" }, { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/time": { "get": { "operationId": "getServerTime", "summary": "Server time (epoch ms)", "description": "NTP-synced server clock for clients that need trustworthy time. Response is uncacheable (Cache-Control: no-store).", "security": [], "responses": { "200": { "description": "Current server time", "content": { "application/json": { "schema": { "type": "object", "required": [ "serverTimeMs" ], "properties": { "serverTimeMs": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/profile": { "get": { "operationId": "getProfile", "summary": "Public profile including decimal age", "description": "Returns name, links, and computed age. No authentication.", "security": [], "responses": { "200": { "description": "Profile JSON", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "ageYears", "url" ], "properties": { "name": { "type": "string" }, "alternateName": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "email": { "type": "string", "format": "email" }, "ageYears": { "type": "number" }, "ageYearsFormatted": { "type": "string" }, "birthDate": { "type": "string", "format": "date" }, "computedAt": { "type": "string", "format": "date-time" }, "sameAs": { "type": "array", "items": { "type": "string", "format": "uri" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" }, { "url": "https://robskan.nl/sandbox", "description": "Sandbox test mode" }, { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/music/now-playing": { "get": { "operationId": "getNowPlaying", "summary": "Spotify now-playing snapshot", "description": "Anonymous snapshot of the public Spotify playback state on robskan.nl.", "security": [], "responses": { "200": { "description": "Playback JSON", "content": { "application/json": { "schema": { "type": "object", "required": [ "currentlyPlaying" ], "properties": { "currentlyPlaying": { "oneOf": [ { "$ref": "#/components/schemas/SpotifyPlaybackState" }, { "type": "null" } ] }, "error": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" }, { "url": "https://robskan.nl/sandbox", "description": "Sandbox test mode" }, { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/music/listening-summary": { "get": { "operationId": "getListeningSummary", "summary": "Recent listening summary (paginated)", "security": [], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from pagination.nextCursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Summary JSON", "content": { "application/json": { "schema": { "type": "object", "required": [ "recent" ], "properties": { "recent": { "type": "array", "items": { "$ref": "#/components/schemas/ListeningHistoryEntry" } }, "topCount": { "type": "integer", "minimum": 0 }, "error": { "type": "string", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/api/v1/sandbox": { "get": { "operationId": "getSandboxInfo", "summary": "Sandbox and preview environment info", "description": "Sandbox metadata plus links to /sandbox test mode and /api/v1/sandbox fixtures.", "security": [], "responses": { "200": { "description": "Sandbox metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "testMode": { "type": "boolean" }, "verified": { "type": "boolean" }, "description": { "type": "string" }, "production": { "type": "string", "format": "uri" }, "sandboxBaseUrl": { "type": "string", "format": "uri" }, "endpoints": { "$ref": "#/components/schemas/SandboxEndpointMap" }, "musicBeta": { "type": "string", "format": "uri" }, "selfTest": { "$ref": "#/components/schemas/SandboxSelfTest" } }, "required": [ "environment", "testMode", "verified", "sandboxBaseUrl", "endpoints" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/sandbox/profile": { "get": { "operationId": "getSandboxProfile", "summary": "Sandbox fixture profile", "description": "Returns deterministic profile JSON; does not read production data.", "security": [], "responses": { "200": { "description": "Fixture profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "sandbox", "name", "ageYears" ], "properties": { "sandbox": { "type": "boolean", "const": true }, "name": { "type": "string" }, "ageYears": { "type": "number" }, "url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/sandbox/music/now-playing": { "get": { "operationId": "getSandboxNowPlaying", "summary": "Sandbox fixture now-playing", "description": "Returns deterministic Spotify snapshot JSON for integration tests.", "security": [], "responses": { "200": { "description": "Fixture playback", "content": { "application/json": { "schema": { "type": "object", "required": [ "sandbox", "currentlyPlaying" ], "properties": { "sandbox": { "type": "boolean", "const": true }, "currentlyPlaying": { "$ref": "#/components/schemas/SpotifyPlaybackState" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/v1/batch": { "post": { "operationId": "batchRead", "summary": "Batch read-only GET operations", "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "200": { "description": "Batch results", "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResultItem" } } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/api/v1/jobs/nlweb-query": { "post": { "operationId": "createNlwebQueryJob", "summary": "Start async NLWeb-style site search job", "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlwebQueryJobRequest" } } } }, "responses": { "200": { "description": "Synchronous completion (prefer 202)", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "poll" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "poll": { "type": "string", "format": "uri" } } } } } }, "202": { "description": "Job accepted", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Poll URL for job status" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "poll" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "poll": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/api/v1/jobs/{jobId}": { "get": { "operationId": "getJobStatus", "summary": "Poll async job status", "security": [], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job record", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "result": { "$ref": "#/components/schemas/NlwebResponse" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/api/get/spotify/track-listen-count": { "get": { "operationId": "getTrackListenCount", "summary": "Listen count for a track (Convex)", "security": [], "parameters": [ { "name": "trackId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "trackName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "artistNames", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listen count", "content": { "application/json": { "schema": { "type": "object", "required": [ "listenCount" ], "properties": { "listenCount": { "type": "integer", "nullable": true } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/api/get/lrclib/lyrics": { "get": { "operationId": "getTrackLyrics", "summary": "Synced or plain lyrics (LRCLIB proxy)", "security": [], "parameters": [ { "name": "trackName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "artistName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "albumName", "in": "query", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lyrics payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "syncedLyrics": { "type": "string", "nullable": true }, "plainLyrics": { "type": "string", "nullable": true }, "instrumental": { "type": "boolean" } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/api/get/spotify": { "get": { "operationId": "getNowPlayingLegacy", "summary": "Legacy now-playing endpoint", "deprecated": true, "security": [], "responses": { "200": { "description": "Playback JSON", "content": { "application/json": { "schema": { "type": "object", "required": [ "currentlyPlaying" ], "properties": { "currentlyPlaying": { "oneOf": [ { "$ref": "#/components/schemas/SpotifyPlaybackState" }, { "type": "null" } ] }, "error": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/api/get/spotify/stream": { "get": { "operationId": "streamNowPlaying", "summary": "SSE playback and history stream", "description": "Server-sent events stream of Spotify playback and listening history updates.", "security": [], "responses": { "200": { "description": "text/event-stream", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/SseStreamEnvelope" } }, "application/json": { "schema": { "type": "object", "required": [ "contentType", "description" ], "properties": { "contentType": { "type": "string", "const": "text/event-stream" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "playback", "history", "ping" ] } } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/ask": { "get": { "operationId": "askSiteGet", "summary": "NLWeb query via query string", "description": "Natural-language site search using the q query parameter.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Natural language query text" } ], "responses": { "200": { "description": "NLWeb results", "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "_meta": { "type": "object", "properties": { "response_type": { "type": "string" }, "version": { "type": "string" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "snippet": { "type": "string" } } } } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] }, "post": { "operationId": "askSite", "summary": "NLWeb natural-language site query", "description": "POST body query for NLWeb-compatible site search results.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" } } } }, "responses": { "200": { "description": "NLWeb results", "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "_meta": { "type": "object", "properties": { "response_type": { "type": "string" }, "version": { "type": "string" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "snippet": { "type": "string" } } } } } } } } }, "400": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "servers": [ { "url": "https://robskan.nl", "description": "Production public read API" } ] } }, "/": { "get": { "operationId": "getSandboxIndex", "summary": "Sandbox environment index", "description": "Sandbox base URL index with fixture links and environment metadata.", "security": [], "servers": [ { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "responses": { "200": { "description": "Sandbox index JSON", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "testMode": { "type": "boolean" }, "verified": { "type": "boolean" }, "description": { "type": "string" }, "production": { "type": "string", "format": "uri" }, "sandboxBaseUrl": { "type": "string", "format": "uri" }, "endpoints": { "$ref": "#/components/schemas/SandboxEndpointMap" }, "musicBeta": { "type": "string", "format": "uri" }, "selfTest": { "$ref": "#/components/schemas/SandboxSelfTest" } }, "required": [ "environment", "testMode", "verified", "sandboxBaseUrl", "endpoints" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/profile": { "get": { "operationId": "getSandboxProfileRelative", "summary": "Sandbox fixture profile", "servers": [ { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "security": [], "responses": { "200": { "description": "Fixture profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "sandbox", "name", "ageYears" ], "properties": { "sandbox": { "type": "boolean", "const": true }, "name": { "type": "string" }, "ageYears": { "type": "number" }, "url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/music/now-playing": { "get": { "operationId": "getSandboxNowPlayingRelative", "summary": "Sandbox fixture now playing", "servers": [ { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "security": [], "responses": { "200": { "description": "Fixture now playing", "content": { "application/json": { "schema": { "type": "object", "required": [ "sandbox", "currentlyPlaying" ], "properties": { "sandbox": { "type": "boolean", "const": true }, "currentlyPlaying": { "$ref": "#/components/schemas/SpotifyPlaybackState" } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Optional field filter (ignored when unsupported).", "schema": { "type": "string", "default": "default" } } ] } }, "/health": { "get": { "operationId": "getSandboxHealthRelative", "summary": "Sandbox health", "servers": [ { "url": "https://robskan.nl/api/v1/sandbox", "description": "Sandbox" } ], "security": [], "parameters": [ { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "default": "default" } } ], "responses": { "200": { "description": "Sandbox health JSON", "content": { "application/json": { "schema": { "type": "object", "required": [ "environment", "status" ], "properties": { "environment": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "ok" ] }, "links": { "type": "object", "properties": { "index": { "type": "string", "format": "uri" }, "profile": { "type": "string", "format": "uri" }, "nowPlaying": { "type": "string", "format": "uri" } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "HealthStatus": { "type": "object", "required": [ "status", "version", "openapi" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "version": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "sandbox": { "type": "string", "format": "uri" }, "documentation": { "type": "string", "format": "uri" }, "pricing": { "type": "string", "format": "uri" }, "mcpProduct": { "type": "string", "format": "uri" }, "mcpDocs": { "type": "string", "format": "uri" }, "idempotency": { "type": "object", "required": [ "header", "ttlSeconds", "operations" ], "properties": { "header": { "type": "string", "const": "Idempotency-Key" }, "ttlSeconds": { "type": "integer" }, "operations": { "type": "array", "items": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "path": { "type": "string" } } } } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "ServerTime": { "type": "object", "required": [ "serverTimeMs" ], "properties": { "serverTimeMs": { "type": "integer", "format": "int64" } } }, "Profile": { "type": "object", "required": [ "name", "ageYears", "url" ], "properties": { "name": { "type": "string" }, "alternateName": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "email": { "type": "string", "format": "email" }, "ageYears": { "type": "number" }, "ageYearsFormatted": { "type": "string" }, "birthDate": { "type": "string", "format": "date" }, "computedAt": { "type": "string", "format": "date-time" }, "sameAs": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, "NowPlayingResponse": { "type": "object", "required": [ "currentlyPlaying" ], "properties": { "currentlyPlaying": { "oneOf": [ { "$ref": "#/components/schemas/SpotifyPlaybackState" }, { "type": "null" } ] }, "error": { "type": "string", "nullable": true } } }, "SpotifyPlaybackState": { "type": "object", "properties": { "is_playing": { "type": "boolean" }, "progress_ms": { "type": "integer", "minimum": 0 }, "item": { "oneOf": [ { "$ref": "#/components/schemas/SpotifyTrack" }, { "type": "null" } ] } } }, "SpotifyTrack": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "uri": { "type": "string" }, "duration_ms": { "type": "integer" }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "album": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } } } } }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "ListeningSummary": { "type": "object", "required": [ "recent" ], "properties": { "recent": { "type": "array", "items": { "$ref": "#/components/schemas/ListeningHistoryEntry" } }, "topCount": { "type": "integer", "minimum": 0 }, "error": { "type": "string", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ListeningHistoryEntry": { "type": "object", "properties": { "trackId": { "type": "string" }, "trackName": { "type": "string" }, "artistNames": { "type": "string" }, "playedAt": { "type": "string", "format": "date-time" }, "listenCount": { "type": "integer", "minimum": 0 } } }, "SandboxProfile": { "type": "object", "required": [ "sandbox", "name", "ageYears" ], "properties": { "sandbox": { "type": "boolean", "const": true }, "name": { "type": "string" }, "ageYears": { "type": "number" }, "url": { "type": "string", "format": "uri" } } }, "SandboxNowPlaying": { "type": "object", "required": [ "sandbox", "currentlyPlaying" ], "properties": { "sandbox": { "type": "boolean", "const": true }, "currentlyPlaying": { "$ref": "#/components/schemas/SpotifyPlaybackState" } } }, "SandboxInfo": { "type": "object", "properties": { "environment": { "type": "string" }, "testMode": { "type": "boolean" }, "verified": { "type": "boolean" }, "description": { "type": "string" }, "production": { "type": "string", "format": "uri" }, "sandboxBaseUrl": { "type": "string", "format": "uri" }, "endpoints": { "$ref": "#/components/schemas/SandboxEndpointMap" }, "musicBeta": { "type": "string", "format": "uri" }, "selfTest": { "$ref": "#/components/schemas/SandboxSelfTest" } }, "required": [ "environment", "testMode", "verified", "sandboxBaseUrl", "endpoints" ] }, "SandboxSelfTest": { "type": "object", "required": [ "profile", "nowPlaying" ], "properties": { "profile": { "type": "string", "format": "uri" }, "nowPlaying": { "type": "string", "format": "uri" }, "expectedStatus": { "type": "integer", "enum": [ 200 ] } } }, "TrackListenCount": { "type": "object", "required": [ "listenCount" ], "properties": { "listenCount": { "type": "integer", "nullable": true } } }, "LyricsPayload": { "type": "object", "properties": { "syncedLyrics": { "type": "string", "nullable": true }, "plainLyrics": { "type": "string", "nullable": true }, "instrumental": { "type": "boolean" } } }, "BatchRequest": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "enum": [ "GET" ] }, "path": { "type": "string" } } } } } }, "BatchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResultItem" } } } }, "BatchResultItem": { "type": "object", "required": [ "path", "status" ], "properties": { "path": { "type": "string" }, "status": { "type": "integer" }, "body": { "oneOf": [ { "$ref": "#/components/schemas/Profile" }, { "$ref": "#/components/schemas/NowPlayingResponse" }, { "$ref": "#/components/schemas/ListeningSummary" }, { "$ref": "#/components/schemas/HealthStatus" }, { "type": "object", "additionalProperties": true } ] }, "error": { "$ref": "#/components/schemas/ProblemDetails" } } }, "NlwebQueryJobRequest": { "type": "object", "properties": { "query": { "type": "object", "properties": { "text": { "type": "string" } } } } }, "JobAccepted": { "type": "object", "required": [ "jobId", "status", "poll" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "poll": { "type": "string", "format": "uri" } } }, "JobRecord": { "type": "object", "required": [ "id", "status", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "result": { "$ref": "#/components/schemas/NlwebResponse" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "AskRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "prefer": { "type": "object", "properties": { "streaming": { "type": "boolean" } } } } }, "NlwebResponse": { "type": "object", "required": [ "results" ], "properties": { "_meta": { "type": "object", "properties": { "response_type": { "type": "string" }, "version": { "type": "string" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "snippet": { "type": "string" } } } } } }, "ProblemDetails": { "type": "object", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "hint": { "type": "string" }, "instance": { "type": "string" } } }, "Problem": { "$ref": "#/components/schemas/ProblemDetails" }, "ApiV1NamespaceInfo": { "type": "object", "required": [ "namespace", "authentication" ], "properties": { "namespace": { "type": "string", "const": "/api/v1" }, "authentication": { "type": "string", "enum": [ "oauth2" ] }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } }, "SseStreamEnvelope": { "type": "object", "required": [ "contentType", "description" ], "properties": { "contentType": { "type": "string", "const": "text/event-stream" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "playback", "history", "ping" ] } } } }, "SandboxEndpointMap": { "type": "object", "required": [ "meta", "profile", "nowPlaying" ], "properties": { "meta": { "type": "string", "format": "uri" }, "profile": { "type": "string", "format": "uri" }, "nowPlaying": { "type": "string", "format": "uri" }, "health": { "type": "string", "format": "uri" } } }, "ProtectedWriteBody": { "type": "object", "properties": { "action": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "SandboxHealth": { "type": "object", "required": [ "environment", "status" ], "properties": { "environment": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "ok" ] }, "links": { "type": "object", "properties": { "index": { "type": "string", "format": "uri" }, "profile": { "type": "string", "format": "uri" }, "nowPlaying": { "type": "string", "format": "uri" } } } } } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated key for safe retries of identical POST bodies. Cached responses are returned for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://robskan.nl/api/spotify/login", "tokenUrl": "https://robskan.nl/api/spotify/callback", "scopes": { "public.read": "Read public portfolio data" } } } } } } }