{ "openapi": "3.1.1", "info": { "title": "scanlines.app Public API", "description": "Public game catalog and local barcode lookup API.", "version": "1.0.0" }, "servers": [ { "url": "https://api.scanlines.app/" } ], "paths": { "/v1/games": { "get": { "tags": [ "scanlines.app Public API v1" ], "summary": "Search the public game catalog", "operationId": "PublicApiSearchGames", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "type": "string" } }, { "name": "region", "in": "query", "schema": { "type": "string" } }, { "name": "releaseYear", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "hasPhysical", "in": "query", "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiListResponseOfPublicApiGameSummaryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/games/{gameId}": { "get": { "tags": [ "scanlines.app Public API v1" ], "summary": "Get a game by Scanlines ID", "operationId": "PublicApiGetGame", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiDataResponseOfPublicApiGameDetailResponse" } } } }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/barcodes/{barcode}": { "get": { "tags": [ "scanlines.app Public API v1" ], "summary": "Resolve a barcode from the local catalog", "operationId": "PublicApiGetByBarcode", "parameters": [ { "name": "barcode", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiDataResponseOfPublicApiBarcodeLookupResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/barcodes/resolve": { "post": { "tags": [ "scanlines.app Public API v1" ], "summary": "Resolve up to 50 barcodes from the local catalog", "operationId": "PublicApiResolveBarcodes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePublicBarcodesRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiDataResponseOfIReadOnlyListOfPublicApiBarcodeBatchItemResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/platforms": { "get": { "tags": [ "scanlines.app Public API v1" ], "summary": "List public catalog platforms", "operationId": "PublicApiGetPlatforms", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiDataResponseOfIReadOnlyListOfPublicApiPlatformResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/regions": { "get": { "tags": [ "scanlines.app Public API v1" ], "summary": "List supported game regions", "operationId": "PublicApiGetRegions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiDataResponseOfIReadOnlyListOfPublicApiRegionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/account/usage": { "get": { "tags": [ "scanlines.app Public API v1" ], "summary": "Get usage for the current API key account", "operationId": "PublicApiGetUsage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiDataResponseOfPublicApiUsageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "GameLanguage": { "enum": [ "ES", "EN", "JA", "FR", "DE", "PT", "IT", "KO", "ZH", "NL", "SV", "PL", "RU", "AR", "Other", null ] }, "GamePhysicalType": { "enum": [ "Cartridge", "Disc", "CodeInBox", "KeyCard", "LimitedPrint", "Unknown", null ] }, "GameRegion": { "enum": [ "NTSC", "NTSC_J", "NTSC_K", "PAL", "PAL_AU", "Other", null ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "PublicApiBarcodeBatchErrorResponse": { "required": [ "code", "detail" ], "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "PublicApiBarcodeBatchItemResponse": { "required": [ "submittedBarcode", "normalizedBarcode", "status", "game", "error" ], "type": "object", "properties": { "submittedBarcode": { "type": "string" }, "normalizedBarcode": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "game": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicApiGameSummaryResponse" } ] }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicApiBarcodeBatchErrorResponse" } ] } } }, "PublicApiBarcodeLookupResponse": { "required": [ "submittedBarcode", "normalizedBarcode", "game" ], "type": "object", "properties": { "submittedBarcode": { "type": "string" }, "normalizedBarcode": { "type": "string" }, "game": { "$ref": "#/components/schemas/PublicApiGameSummaryResponse" } } }, "PublicApiDataResponseOfIReadOnlyListOfPublicApiBarcodeBatchItemResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/PublicApiBarcodeBatchItemResponse" } } } }, "PublicApiDataResponseOfIReadOnlyListOfPublicApiPlatformResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/PublicApiPlatformResponse" } } } }, "PublicApiDataResponseOfIReadOnlyListOfPublicApiRegionResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/PublicApiRegionResponse" } } } }, "PublicApiDataResponseOfPublicApiBarcodeLookupResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicApiBarcodeLookupResponse" } ] } } }, "PublicApiDataResponseOfPublicApiGameDetailResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicApiGameDetailResponse" } ] } } }, "PublicApiDataResponseOfPublicApiUsageResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicApiUsageResponse" } ] } } }, "PublicApiGameDetailResponse": { "required": [ "id", "title", "platform", "edition" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "platform": { "$ref": "#/components/schemas/PublicApiPlatformResponse" }, "edition": { "$ref": "#/components/schemas/PublicApiGameEditionResponse" } } }, "PublicApiGameEditionResponse": { "required": [ "region", "country", "language", "releaseYear", "hasPhysical", "hasDigital", "physicalType", "coverUrl", "barcodes" ], "type": "object", "properties": { "region": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GameRegion" } ] }, "country": { "type": [ "null", "string" ] }, "language": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GameLanguage" } ] }, "releaseYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "hasPhysical": { "type": [ "null", "boolean" ] }, "hasDigital": { "type": [ "null", "boolean" ] }, "physicalType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GamePhysicalType" } ] }, "coverUrl": { "type": [ "null", "string" ] }, "barcodes": { "type": "array", "items": { "type": "string" } } } }, "PublicApiGameSummaryResponse": { "required": [ "id", "title", "platform", "edition" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "platform": { "$ref": "#/components/schemas/PublicApiPlatformResponse" }, "edition": { "$ref": "#/components/schemas/PublicApiGameEditionResponse" } } }, "PublicApiListResponseOfPublicApiGameSummaryResponse": { "required": [ "meta", "data" ], "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PublicApiPageMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiGameSummaryResponse" } } } }, "PublicApiPageMeta": { "required": [ "limit", "nextCursor" ], "type": "object", "properties": { "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "nextCursor": { "type": [ "null", "string" ] } } }, "PublicApiPlan": { "enum": [ "DeveloperFree", "PatreonSupporter", "Partner" ] }, "PublicApiPlatformResponse": { "required": [ "key", "name" ], "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "PublicApiRegionResponse": { "required": [ "key", "name" ], "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "PublicApiUsageResponse": { "required": [ "plan", "limit", "used", "remaining", "resetsAtUtc" ], "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/PublicApiPlan" }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "used": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "remaining": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "resetsAtUtc": { "type": "string", "format": "date-time" } } }, "ResolvePublicBarcodesRequest": { "required": [ "barcodes" ], "type": "object", "properties": { "barcodes": { "type": "array", "items": { "type": "string" } } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Developer API key issued by scanlines.app.", "name": "X-Api-Key", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "scanlines.app Public API v1" } ] }