{
  "openapi": "3.1.0",
  "info": {
    "title": "Collected API",
    "version": "2.0.0",
    "description": "Resolve canonical books and enrich them with editions, descriptions, author context, reader intelligence, and recommendations."
  },
  "servers": [{ "url": "https://api.collectedreads.com" }],
  "security": [{ "BearerAuth": [] }],
  "tags": [
    { "name": "Search and resolve" },
    { "name": "Works" },
    { "name": "Authors and editions" },
    { "name": "Recommendations" },
    { "name": "Feedback" }
  ],
  "paths": {
    "/v2/search": {
      "get": {
        "tags": ["Search and resolve"], "summary": "Search canonical works", "operationId": "searchWorks",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } },
          { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" } },
          { "name": "market", "in": "query", "schema": { "type": "string", "default": "US" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "429": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/taxonomy": {
      "get": {
        "tags": ["Search and resolve"], "summary": "Read the versioned taxonomy", "operationId": "getTaxonomy",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/resolve": {
      "post": {
        "tags": ["Search and resolve"], "summary": "Resolve one book record", "operationId": "resolveWork",
        "x-collected-scope": "resolve:read", "x-collected-meter": "resolved_items",
        "requestBody": { "$ref": "#/components/requestBodies/JsonObject" },
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/resolve/batch": {
      "post": {
        "tags": ["Search and resolve"], "summary": "Resolve an ordered batch", "operationId": "resolveWorkBatch",
        "x-collected-scope": "bulk:read", "x-collected-meter": "bulk_items",
        "requestBody": { "$ref": "#/components/requestBodies/JsonObject" },
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "429": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/source-aliases/resolve/batch": {
      "post": {
        "tags": ["Search and resolve"], "summary": "Resolve exact provider aliases", "operationId": "resolveSourceAliases",
        "x-collected-scope": "bulk:read", "x-collected-meter": "bulk_items",
        "requestBody": { "$ref": "#/components/requestBodies/JsonObject" },
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/works/{work_id}": {
      "get": {
        "tags": ["Works"], "summary": "Hydrate one canonical work", "operationId": "getWork",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [
          { "$ref": "#/components/parameters/WorkId" },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Market" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/works/{work_id}/reader-intelligence": {
      "get": {
        "tags": ["Works"], "summary": "Get typed reader intelligence", "operationId": "getReaderIntelligence",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [{ "$ref": "#/components/parameters/WorkId" }],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/works/{work_id}/editions": {
      "get": {
        "tags": ["Authors and editions"], "summary": "List editions for a work", "operationId": "listWorkEditions",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [
          { "$ref": "#/components/parameters/WorkId" },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Market" },
          { "$ref": "#/components/parameters/Cursor" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/works/batch": {
      "post": {
        "tags": ["Works"], "summary": "Hydrate canonical works in batch", "operationId": "getWorksBatch",
        "x-collected-scope": "bulk:read", "x-collected-meter": "bulk_items",
        "requestBody": { "$ref": "#/components/requestBodies/JsonObject" },
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/editions/{edition_id}": {
      "get": {
        "tags": ["Authors and editions"], "summary": "Get one exact edition", "operationId": "getEdition",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [
          { "name": "edition_id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Market" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/authors/{author_id}": {
      "get": {
        "tags": ["Authors and editions"], "summary": "Get an author and first bibliography page", "operationId": "getAuthor",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [
          { "$ref": "#/components/parameters/AuthorId" },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Market" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/authors/{author_id}/works": {
      "get": {
        "tags": ["Authors and editions"], "summary": "Page through an author bibliography", "operationId": "listAuthorWorks",
        "x-collected-scope": "catalog:read", "x-collected-meter": "catalog_requests",
        "parameters": [
          { "$ref": "#/components/parameters/AuthorId" },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Market" },
          { "$ref": "#/components/parameters/Cursor" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/recommendations": {
      "post": {
        "tags": ["Recommendations"], "summary": "Run a bounded recommendation", "operationId": "createRecommendation",
        "x-collected-scope": "recommendations:run", "x-collected-meter": "recommendation_requests",
        "requestBody": { "$ref": "#/components/requestBodies/JsonObject" },
        "responses": { "200": { "$ref": "#/components/responses/JsonResponse" }, "429": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    },
    "/v2/feedback": {
      "post": {
        "tags": ["Feedback"], "summary": "Submit structured metadata feedback", "operationId": "createFeedback",
        "description": "Restricted scope; not included in the default commercial plans.",
        "x-collected-scope": "feedback:write", "x-collected-meter": "feedback_writes",
        "requestBody": { "$ref": "#/components/requestBodies/JsonObject" },
        "responses": { "201": { "$ref": "#/components/responses/JsonResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Collected API key" }
    },
    "parameters": {
      "WorkId": { "name": "work_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^stw_" } },
      "AuthorId": { "name": "author_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sta_" } },
      "Language": { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" } },
      "Market": { "name": "market", "in": "query", "schema": { "type": "string", "default": "US" } },
      "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" } },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }
    },
    "requestBodies": {
      "JsonObject": {
        "required": true,
        "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
      }
    },
    "responses": {
      "JsonResponse": {
        "description": "Successful JSON response",
        "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Unique request identifier for logs and support." } },
        "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
      },
      "ErrorResponse": {
        "description": "Structured API error",
        "headers": { "X-Request-ID": { "schema": { "type": "string" } } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "error_code", "request_id"],
        "properties": {
          "error": { "type": "string" },
          "error_code": { "type": "string" },
          "request_id": { "type": "string" }
        }
      }
    }
  }
}