{
  "openapi": "3.1.0",
  "info": {
    "title": "XCOPYBook public research API",
    "version": "1.1.0",
    "description": "Read-only public endpoints for the verified cross-platform XCOPY registry, member data, catalogue enrichment, and provenance research."
  },
  "servers": [{ "url": "https://xcopybook.com" }],
  "paths": {
    "/api/registry/v1/catalogue": {
      "get": {
        "summary": "Read the canonical XCOPY registry catalogue",
        "operationId": "getRegistryCatalogue",
        "parameters": [
          { "name": "work", "in": "query", "required": false, "description": "Work number, slug, or stable registry id", "schema": { "type": "string" } },
          { "name": "corpus", "in": "query", "required": false, "description": "Corpus slug or stable registry id; may disambiguate a repeated work slug", "schema": { "type": "string" } },
          { "name": "include", "in": "query", "required": false, "description": "Comma-separated related records: tokens,sources", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Versioned registry catalogue", "headers": { "x-xcopy-schema": { "schema": { "type": "string", "const": "art-registry/catalogue@1" } } }, "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "description": "Unsupported include value" },
          "404": { "description": "Unknown work or corpus" },
          "409": { "description": "Ambiguous work slug; use a stable work id or corpus filter" }
        }
      }
    },
    "/api/registry/v1/token": {
      "get": {
        "summary": "Read one token and its conceptual work",
        "operationId": "getRegistryToken",
        "parameters": [
          { "name": "chain", "in": "query", "required": true, "schema": { "type": "string", "example": "eip155:1" } },
          { "name": "contract", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "tokenId", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Token, work and source record", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "description": "Missing token identity" },
          "404": { "description": "Unknown token" }
        }
      }
    },
    "/api/members": {
      "get": {
        "summary": "List public XCOPYBook member profiles",
        "operationId": "listMembers",
        "responses": { "200": { "description": "Public member profiles", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/raster/token": {
      "get": {
        "summary": "Enrich a known catalogue token with Raster data",
        "operationId": "getRasterToken",
        "parameters": [{ "name": "tokenId", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Token enrichment or an availability reason", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid token identifier" } }
      }
    },
    "/api/raster/address": {
      "get": {
        "summary": "Look up a Raster profile by Ethereum address",
        "operationId": "getRasterAddress",
        "parameters": [{ "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }],
        "responses": { "200": { "description": "Address enrichment or an availability reason", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid address" } }
      }
    },
    "/api/raster/collectors": {
      "get": {
        "summary": "List Raster collector enrichment when configured",
        "operationId": "listRasterCollectors",
        "responses": { "200": { "description": "Collector enrichment or an availability reason", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/provenance/history": {
      "get": {
        "summary": "Return sale history for a known catalogue token",
        "operationId": "getProvenanceHistory",
        "parameters": [{ "name": "tokenId", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Provenance history", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid token identifier" } }
      }
    }
  }
}