{ "openapi": "3.1.0", "info": { "title": "GENBN Publisher API", "version": "1.0.0", "description": "Publisher integration API. Registration is open. See /integration.md for confirmation flows, retry rules, and identifier policy. Admin API is intentionally excluded." }, "servers": [ { "url": "https://genbn.org/api/v1" } ], "externalDocs": { "url": "https://genbn.org/integration.md" }, "components": { "securitySchemes": { "publisherKey": { "type": "http", "scheme": "bearer", "description": "Publisher API key issued after email confirmation." } } }, "paths": { "/categories": { "get": { "operationId": "listCategories", "summary": "Canonical category/subcategory catalog", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } } }, "required": [ "code", "name", "subcategories" ] } } }, "required": [ "categories" ] } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/services": { "post": { "operationId": "registerService", "summary": "Register; human email confirmation required", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9]{1,15}$" }, "domain": { "type": [ "string", "null" ] }, "url_template": { "type": [ "string", "null" ], "maxLength": 500, "description": "HTTPS template containing {id} or {genbn}." } }, "required": [ "name", "email" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9]{1,15}$" }, "domain": { "type": [ "string", "null" ] }, "url_template": { "type": [ "string", "null" ], "maxLength": 500, "description": "HTTPS template containing {id} or {genbn}." }, "status": { "const": "pending" }, "claim_mode": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/services/resend-verification": { "post": { "operationId": "resendVerification", "summary": "Request email link; recovery confirmation rotates the key", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/services/recover-key": { "post": { "operationId": "requestKeyRecovery", "summary": "Request email link; recovery confirmation rotates the key", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/verify-email": { "post": { "operationId": "verifyEmail", "summary": "Consume a one-time email token and activate a service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "status": { "const": "active" }, "api_key": { "type": "string" }, "emailed": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/services/{code}": { "get": { "operationId": "getService", "summary": "Public publisher information", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "status": { "enum": [ "pending", "active" ] }, "claim_mode": { "type": "string" }, "url_template": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateService", "summary": "Update your service; code and email are immutable", "security": [ { "publisherKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "domain": { "type": [ "string", "null" ] }, "url_template": { "type": [ "string", "null" ], "maxLength": 500, "description": "HTTPS template containing {id} or {genbn}." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/books": { "post": { "operationId": "mintBook", "summary": "Mint a publication identifier; use Idempotency-Key for safe retries", "security": [ { "publisherKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Stable per-publication key, scoped to service, retained indefinitely. Same normalized payload replays original 201; changed payload returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "example": "FIC" }, "subcategory": { "type": "string", "example": "SCFI" }, "url": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "category", "subcategory" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "genbn": { "type": "string" }, "id": { "type": "string" }, "service_code": { "type": "string" }, "year": { "type": "integer" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "serial": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "redirect": { "type": [ "string", "null" ] } }, "required": [ "genbn", "id" ] } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/books/{id}": { "get": { "operationId": "getBook", "summary": "Public metadata and current destination", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "genbn": { "type": "string" }, "id": { "type": "string" }, "service_code": { "type": "string" }, "year": { "type": "integer" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "serial": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "redirect": { "type": [ "string", "null" ] } }, "required": [ "genbn", "id" ] } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateBookUrl", "summary": "Update destination; null clears explicit URL and uses service template", "security": [ { "publisherKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "genbn": { "type": "string" }, "id": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "redirect": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "401": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "403": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "409": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "413": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "415": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } }, "502": { "description": "Request failed; see integration.md for retry rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" }, "retry_after_sec": { "type": "integer" } }, "required": [ "error" ] } } } } } } } } }