{
  "openapi": "3.1.0",
  "info": {
    "title": "CNBeebay Public Agent API",
    "version": "2026-08-18",
    "description": "Read-only pharmaceutical catalog discovery and CAS-list precheck. A catalog match is not a stock, price, lead-time or compliance confirmation."
  },
  "servers": [{ "url": "https://www.cnbeebay.com" }],
  "tags": [
    { "name": "Capabilities" },
    { "name": "Catalog" },
    { "name": "CAS Lists" }
  ],
  "paths": {
    "/api/agents/capabilities": {
      "get": {
        "tags": ["Capabilities"],
        "operationId": "getAgentCapabilities",
        "summary": "Read live public capability boundaries",
        "responses": { "200": { "description": "Capability manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityManifest" } } } } }
      }
    },
    "/api/catalog/search": {
      "get": {
        "tags": ["Catalog"],
        "operationId": "searchPublishedCatalog",
        "summary": "Search the published catalog subset",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": "CAS number, catalog number, chemical name or SMILES" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }
        ],
        "responses": {
          "200": { "description": "Ranked discovery records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/catalog/products/{catalogNumber}": {
      "get": {
        "tags": ["Catalog"],
        "operationId": "getPublishedCatalogProduct",
        "summary": "Read one published catalog record",
        "parameters": [{ "name": "catalogNumber", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Published product record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } },
          "404": { "description": "Record not found in the published subset" }
        }
      }
    },
    "/api/cas-lists/precheck": {
      "post": {
        "tags": ["CAS Lists"],
        "operationId": "precheckCasList",
        "summary": "Precheck up to 100 product identifiers",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["identifiers"], "properties": { "identifiers": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 300 } } } }, "example": { "identifiers": ["251107-41-2", "ACQHYX842"] } } }
        },
        "responses": {
          "200": { "description": "Identity precheck only; no formal inquiry is created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrecheckResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "415": { "description": "Content-Type must be application/json" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Coverage": {
        "type": "object",
        "required": ["sourceRecordCount", "publishedRecordCount", "searchedScope", "interpretation"],
        "properties": {
          "sourceRecordCount": { "type": "integer", "example": 617992 },
          "publishedRecordCount": { "type": "integer", "example": 300 },
          "searchedScope": { "type": "string", "const": "published_catalog" },
          "sourceMode": { "type": "string", "const": "synthesis_on_demand" },
          "interpretation": { "type": "string" }
        }
      },
      "Product": {
        "type": "object",
        "required": ["catalogNumber", "chemicalName", "recordStatus", "supplyStatus", "commercialStatus", "requiresManualReview"],
        "properties": {
          "catalogNumber": { "type": "string" },
          "chemicalName": { "type": "string" },
          "casNumber": { "type": "string" },
          "smiles": { "type": "string" },
          "category": { "type": "string" },
          "listedPurity": { "type": "string" },
          "listedScaleOptions": { "type": "array", "items": { "type": "string" } },
          "listedLeadTime": { "type": "object", "properties": { "value": { "type": "string" }, "status": { "type": "string", "const": "catalog_typical_not_confirmed" } } },
          "tags": { "type": "array", "items": { "type": "string" } },
          "recordStatus": { "type": "string", "const": "catalog_record" },
          "supplyStatus": { "type": "string", "const": "supplier_confirmation_required" },
          "commercialStatus": { "type": "string", "const": "commercial_review_pending" },
          "requiresManualReview": { "type": "boolean", "const": true },
          "productUrl": { "type": "string", "format": "uri" },
          "inquiryUrl": { "type": "string", "format": "uri" }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": { "ok": { "type": "boolean" }, "query": { "type": "string" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "results": { "type": "array", "items": { "allOf": [{ "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "matchQuality": { "type": "string", "enum": ["exact", "potential"] } } }] } } }
      },
      "ProductResponse": {
        "type": "object",
        "properties": { "ok": { "type": "boolean" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "record": { "$ref": "#/components/schemas/Product" } }
      },
      "PrecheckResponse": {
        "type": "object",
        "properties": { "ok": { "type": "boolean" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "summary": { "type": "object", "additionalProperties": { "type": "integer" } }, "results": { "type": "array", "items": { "type": "object" } }, "formalInquiryCreated": { "type": "boolean", "const": false }, "confirmationRequired": { "type": "boolean", "const": true }, "inquiryUrl": { "type": "string", "format": "uri" } }
      },
      "CapabilityManifest": {
        "type": "object",
        "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" }, "service": { "type": "string" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "tools": { "type": "array", "items": { "type": "object" } }, "unavailableCapabilities": { "type": "array", "items": { "type": "string" } } }
      },
      "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "message": { "type": "string" } } }
    }
  }
}