{ "openapi": "3.1.0", "info": { "title": "ShinyForge API", "version": "1.1.0", "description": "Scoped, per-user imports for kept catches, hunts and dex checkmarks. Tokens are created in Settings. Start with GET /api (no authentication). See /llms.txt and /examples/shiny_tracker_client.py." }, "servers": [ { "url": "/api/v1", "description": "This ShinyForge installation" } ], "paths": { "/me": { "get": { "summary": "GET me", "description": "See /api-docs.html for the complete field and permission contract. profile:read Required permission: profile:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" } }, "required": [] }, "scopes": { "type": "array", "items": { "type": "string" } }, "apiVersion": { "const": 1 } }, "required": [ "user", "scopes", "apiVersion" ] } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getMe", "x-required-scopes": [ "profile:read" ] } }, "/trainers": { "get": { "summary": "GET trainers", "description": "See /api-docs.html for the complete field and permission contract. profile:read Required permission: profile:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getTrainers", "x-required-scopes": [ "profile:read" ] } }, "/catches": { "get": { "summary": "GET catches", "description": "See /api-docs.html for the complete field and permission contract. catches Required permission: catches:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCatches", "x-required-scopes": [ "catches:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "description": "nextCursor from the previous page; stop when catches is empty.", "schema": { "type": "string" } } ] }, "post": { "summary": "POST catches", "description": "See /api-docs.html for the complete field and permission contract. catches Required permission: catches:write.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShinyCatch" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "catchId": { "type": "string" }, "pokemonId": { "type": "integer" }, "duplicate": { "type": "boolean" }, "addedToLivingDex": { "type": "boolean" }, "addedToShinyDex": { "type": "boolean" } }, "required": [] } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postCatches", "x-required-scopes": [ "catches:write" ] } }, "/hunts": { "get": { "summary": "GET hunts", "description": "See /api-docs.html for the complete field and permission contract. hunts Required permission: hunts:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getHunts", "x-required-scopes": [ "hunts:read" ] }, "post": { "summary": "POST hunts", "description": "See /api-docs.html for the complete field and permission contract. hunts Required permission: hunts:write.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuntSnapshot" } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postHunts", "x-required-scopes": [ "hunts:write" ] } }, "/events": { "post": { "summary": "POST events", "description": "See /api-docs.html for the complete field and permission contract. events:write Required permission: events:write. Also requires catches:write for shiny-caught or hunts:write for hunt-progress.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppEvent" } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postEvents", "x-required-scopes": [ "events:write" ] } }, "/living-dex": { "get": { "summary": "GET living-dex", "description": "See /api-docs.html for the complete field and permission contract. living:write Required permission: dex:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dex": { "type": "string" }, "schemaVersion": { "type": "integer" }, "games": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } } } }, "required": [ "dex", "games" ] } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getLivingDex", "x-required-scopes": [ "dex:read" ] }, "post": { "summary": "POST living-dex", "description": "See /api-docs.html for the complete field and permission contract. living:write Required permission: living:write.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DexUpdate" }, "example": { "entries": [ "Bulbasaur", { "name": "Eevee", "caught": true } ] } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postLivingDex", "x-required-scopes": [ "living:write" ] } }, "/shiny-dex": { "get": { "summary": "GET shiny-dex", "description": "See /api-docs.html for the complete field and permission contract. shiny:write Required permission: dex:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dex": { "type": "string" }, "schemaVersion": { "type": "integer" }, "games": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } } } }, "required": [ "dex", "games" ] } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getShinyDex", "x-required-scopes": [ "dex:read" ] }, "post": { "summary": "POST shiny-dex", "description": "See /api-docs.html for the complete field and permission contract. shiny:write Required permission: shiny:write.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DexUpdate" }, "example": { "entries": [ { "name": "Eevee", "caught": true } ] } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postShinyDex", "x-required-scopes": [ "shiny:write" ] } }, "/images/scan": { "post": { "summary": "Scan highlighted-row Pokémon text", "description": "Requires images:scan; six scans/minute. Returns suggestions only and never changes a dex. Required permission: images:scan.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "description": "PNG/JPEG/WebP base64 data URL; decoded image up to 5 MB" } } } } } }, "responses": { "200": { "description": "OCR candidates and requiresConfirmation true" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postImagesScan", "x-required-scopes": [ "images:scan" ] } }, "/catalog": { "get": { "summary": "Read species and forms", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pokemon": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "genders": { "type": "array", "items": { "type": "string" } }, "forms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" } } }, "required": [] } } }, "required": [] } } }, "required": [ "pokemon" ] } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCatalog", "x-required-scopes": [ "dex:read" ], "description": " Required permission: dex:read." } }, "/box-imports": { "get": { "summary": "Read own box snapshots", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Requires dex:read" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getBoxImports", "x-required-scopes": [ "dex:read" ], "description": " Required permission: dex:read." }, "post": { "summary": "Import a confirmed capture-card box", "description": "Requires living:write plus shiny:write if any entry is shiny. See API docs for idempotency and slot semantics. Required permission: living:write. Also requires shiny:write when any entry is shiny. Does not create catch history.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientId", "externalId", "saveId", "box", "confirmed", "entries" ], "properties": { "clientId": { "type": "string" }, "externalId": { "type": "string" }, "saveId": { "type": "string" }, "box": { "type": "integer", "minimum": 1, "maximum": 1000 }, "game": { "type": "string" }, "trainerId": { "type": "string" }, "confirmed": { "const": true }, "entries": { "type": "array", "minItems": 1, "maxItems": 120, "items": { "type": "object", "required": [ "slot", "shiny" ], "properties": { "slot": { "type": "integer", "minimum": 1, "maximum": 120 }, "name": { "type": "string" }, "pokemonId": { "type": "integer" }, "shiny": { "type": "boolean" }, "formKey": { "type": "string" }, "nickname": { "type": "string" }, "gender": { "type": "string" }, "ball": { "type": "string" } } } } } }, "example": { "clientId": "switch-box-reader", "externalId": "review-001", "saveId": "shield-save", "box": 1, "game": "Shield", "confirmed": true, "entries": [ { "slot": 1, "name": "Pikachu", "shiny": false }, { "slot": 2, "name": "Eevee", "shiny": true } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "box": { "type": "integer" }, "saveId": { "type": "string" }, "game": { "type": "string" }, "trainerId": { "type": [ "string", "null" ] }, "updated": { "type": "integer" }, "shiny": { "type": "integer" }, "createdCatchRecords": { "const": 0 }, "duplicate": { "type": "boolean" }, "message": { "type": "string" } }, "required": [] } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting ID or stale snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Expected application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postBoxImports", "x-required-scopes": [ "living:write" ] } }, "/options": { "get": { "operationId": "getOptions", "summary": "List valid individual games, methods, balls and genders", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dex:read" ], "responses": { "200": { "description": "games: [{name, generation, catchMethods, huntMethods}], balls: [name], genders: [name]" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "phub_ token" } }, "schemas": { "ShinyCatch": { "type": "object", "required": [ "clientId", "externalId", "shiny", "kept" ], "anyOf": [ { "required": [ "pokemonId" ] }, { "required": [ "name" ] } ], "properties": { "clientId": { "type": "string", "pattern": "^[-A-Za-z0-9_.:]{1,120}$" }, "externalId": { "type": "string", "pattern": "^[-A-Za-z0-9_.:]{1,120}$" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 1025 }, "name": { "type": "string" }, "game": { "type": "string" }, "method": { "type": "string" }, "encounters": { "type": "integer", "minimum": 0 }, "durationMs": { "type": "integer", "minimum": 0 }, "trainerId": { "type": "string" }, "formKey": { "type": "string" }, "shiny": { "const": true }, "kept": { "const": true }, "caughtAt": { "type": "string", "format": "date-time" }, "nickname": { "type": "string" }, "gender": { "type": "string" }, "ball": { "type": "string" }, "notes": { "type": "string" }, "huntExternalId": { "type": "string" } } }, "HuntSnapshot": { "type": "object", "required": [ "clientId", "externalId", "encounters" ], "anyOf": [ { "required": [ "pokemonId" ] }, { "required": [ "name" ] } ], "properties": { "clientId": { "type": "string", "pattern": "^[-A-Za-z0-9_.:]{1,120}$" }, "externalId": { "type": "string", "pattern": "^[-A-Za-z0-9_.:]{1,120}$" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 1025 }, "name": { "type": "string" }, "game": { "type": "string" }, "method": { "type": "string" }, "encounters": { "type": "integer", "minimum": 0 }, "durationMs": { "type": "integer", "minimum": 0 }, "trainerId": { "type": "string" }, "formKey": { "type": "string" }, "shiny": { "const": true }, "kept": { "const": true }, "caughtAt": { "type": "string", "format": "date-time" }, "nickname": { "type": "string" }, "gender": { "type": "string" }, "ball": { "type": "string" }, "notes": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "status": { "enum": [ "active", "paused" ] }, "charm": { "type": "boolean" }, "customOdds": { "type": "number", "minimum": 1 }, "base": { "enum": [ 4096, 8192 ] }, "location": { "type": "string" } } }, "AppEvent": { "type": "object", "required": [ "clientId", "externalId", "eventType" ], "properties": { "clientId": { "type": "string", "pattern": "^[-A-Za-z0-9_.:]{1,120}$" }, "externalId": { "type": "string", "pattern": "^[-A-Za-z0-9_.:]{1,120}$" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 1025 }, "name": { "type": "string" }, "game": { "type": "string" }, "method": { "type": "string" }, "encounters": { "type": "integer", "minimum": 0 }, "durationMs": { "type": "integer", "minimum": 0 }, "trainerId": { "type": "string" }, "formKey": { "type": "string" }, "shiny": { "const": true }, "kept": { "const": true }, "caughtAt": { "type": "string", "format": "date-time" }, "nickname": { "type": "string" }, "gender": { "type": "string" }, "ball": { "type": "string" }, "notes": { "type": "string" }, "eventType": { "enum": [ "hunt-progress", "shiny-caught" ] }, "huntExternalId": { "type": "string" }, "catchExternalId": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "status": { "enum": [ "active", "paused" ] } } }, "DexEntry": { "oneOf": [ { "type": "string" }, { "type": "integer", "minimum": 1, "maximum": 1025 }, { "type": "object", "anyOf": [ { "required": [ "name" ] }, { "required": [ "pokemonId" ] } ], "properties": { "name": { "type": "string" }, "pokemonId": { "type": "integer" }, "caught": { "type": "boolean" }, "checked": { "type": "boolean" }, "formKey": { "type": "string" } } } ] }, "DexUpdate": { "type": "object", "properties": { "dexGame": { "type": "string" }, "entries": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/DexEntry" } }, "name": { "type": "string" }, "pokemonId": { "type": "integer" }, "caught": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } }, "x-permission-scopes": { "profile:read": "Read own public profile and trainer profiles", "catches:read": "Read own catch history", "catches:write": "Import a kept shiny catch", "hunts:read": "Read own hunts", "hunts:write": "Import absolute hunt snapshots", "events:write": "Send Automation reader events", "dex:read": "Read own dex maps", "living:write": "Update Living Dex entries", "shiny:write": "Update Shiny Dex entries", "images:scan": "Read highlighted-row Pokémon names from an uploaded screenshot" } }