{ "openapi": "3.1.0", "info": { "title": "GrooveGauge Public Music API", "version": "1.0.0", "description": "Read-only discovery data and short review previews. No key or login. Credit GrooveGauge with a link to the original review or artist page. Reviews never contain full text: excerpts are at most400 Unicode characters, and no more than60% of a short visible text (empty below40 characters). No biography, research, contact data, media binary, exports or adjustable excerpt/offset parameter. 60 requests per rolling minute per IP, additionally10 per5seconds;429 includes Retry-After. GET, HEAD and OPTIONS; public CORS without credentials. JSON UTF-8; successful data cached for at most30seconds, documentation60seconds. Unknown parameters are rejected." }, "servers": [ { "url": "https://groovegauge.com/api/v1" } ], "security": [], "paths": { "/reviews": { "get": { "summary": "List public reviews", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": "Artist name, or artist/release title for reviews and releases. Literal case-insensitive substring; not a full-text search." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{22}$" }, "description": "Only verified artist/release IDs match; unresolved IDs return no results." }, { "name": "spotify_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "artist", "album", "track" ] }, "description": "Optional disambiguation. Requires spotify_id." }, { "name": "genre_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" }, { "name": "artist_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "album", "single" ] }, "description": "Review type or release type. Reviews accept album or single only." }, { "name": "release_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" } ], "responses": { "200": { "description": "Paginated public records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/reviews/{id}": { "get": { "summary": "Get one public review", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "One compact public record. Same content limits as the index.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Review" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "404": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/artists": { "get": { "summary": "List public artists", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": "Artist name, or artist/release title for reviews and releases. Literal case-insensitive substring; not a full-text search." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{22}$" }, "description": "Only verified artist/release IDs match; unresolved IDs return no results." }, { "name": "spotify_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "artist" ] }, "description": "Optional disambiguation. Requires spotify_id." }, { "name": "genre_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" } ], "responses": { "200": { "description": "Paginated public records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/artists/{id}": { "get": { "summary": "Get one public artist", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "One compact public record. Same content limits as the index.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Artist" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "404": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/releases": { "get": { "summary": "List public releases", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": "Artist name, or artist/release title for reviews and releases. Literal case-insensitive substring; not a full-text search." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{22}$" }, "description": "Only verified artist/release IDs match; unresolved IDs return no results." }, { "name": "spotify_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "artist", "album", "track" ] }, "description": "Optional disambiguation. Requires spotify_id." }, { "name": "genre_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" }, { "name": "artist_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "album", "single", "ep", "live", "compilation" ] }, "description": "Review type or release type. Reviews accept album or single only." } ], "responses": { "200": { "description": "Paginated public records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Release" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/releases/{id}": { "get": { "summary": "Get one public release", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "One compact public record. Same content limits as the index.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Release" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "404": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/genres": { "get": { "summary": "List public genres", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "Paginated public records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Genre" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/genres/{id}": { "get": { "summary": "Get one public genre", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "One compact public record. Same content limits as the index.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Genre" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "404": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/search": { "get": { "summary": "Search public artists, releases and reviews", "description": "Provide q and/or spotify_id. Each of the three result groups has independent pagination using the same page/per_page values. Maximum per_page is20, default10. No full review text is searchable or returned.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "description": "" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": "Artist name, or artist/release title for reviews and releases. Literal case-insensitive substring; not a full-text search." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{22}$" }, "description": "Only verified artist/release IDs match; unresolved IDs return no results." }, { "name": "spotify_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "artist", "album", "track" ] }, "description": "Optional disambiguation. Requires spotify_id." } ], "responses": { "200": { "description": "data.artists, data.releases and data.reviews each contain data, meta and links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "artists": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } }, "releases": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Release" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } }, "reviews": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] } } } } } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "400": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "JSON error; responses do not contain internal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } }, "components": { "schemas": { "Artist": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "api_url", "spotify_id", "spotify_url" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "api_url": { "type": "string", "format": "uri" }, "spotify_id": { "type": [ "string", "null" ] }, "spotify_url": { "type": [ "string", "null" ] }, "reviews_url": { "type": "string", "format": "uri" }, "releases_url": { "type": "string", "format": "uri" } } }, "Release": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "type": { "enum": [ "album", "single", "ep", "live", "compilation" ] }, "release_date": { "type": [ "string", "null" ] }, "date_precision": { "enum": [ "day", "month", "year", "unknown" ] }, "url": { "type": "string", "format": "uri" }, "api_url": { "type": "string", "format": "uri" }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } }, "genres": { "type": "array", "items": { "$ref": "#/components/schemas/Genre" } }, "reviews": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/ReviewPreview" } }, "reviews_url": { "type": "string", "format": "uri" }, "spotify": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "album", "track" ] }, "id": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } }, "Review": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10 }, "excerpt": { "type": "string", "maxLength": 400 }, "url": { "type": "string", "format": "uri" }, "api_url": { "type": "string", "format": "uri" }, "type": { "enum": [ "album", "single" ] }, "score_scale": { "const": 10 }, "published_at": { "type": "string", "format": "date-time" }, "spotify": { "anyOf": [ { "type": "object", "properties": { "type": { "enum": [ "album", "track" ] }, "id": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, { "type": "null" } ] }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } }, "genres": { "type": "array", "items": { "$ref": "#/components/schemas/Genre" } }, "release": { "anyOf": [ { "$ref": "#/components/schemas/Release" }, { "type": "null" } ] } } }, "ReviewPreview": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10 }, "excerpt": { "type": "string", "maxLength": 400 }, "url": { "type": "string", "format": "uri" }, "api_url": { "type": "string", "format": "uri" } } }, "Genre": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "api_url": { "type": "string", "format": "uri" } } }, "Attribution": { "type": "object", "properties": { "name": { "const": "GrooveGauge" }, "url": { "type": "string", "format": "uri" }, "required": { "const": true }, "instructions": { "type": "string" } } } } } }