{ "openapi": "3.1.1", "info": { "contact": { "name": "北京智码星图科技有限公司 / Beijing Starixs Technology Co., Ltd.", "url": "https://www.starixs.com/", "email": "contact@starixs.com" }, "title": "Toolora public Agent API", "version": "1.0.0", "description": "Find → verify → compare → monitor → cite. Anonymous read; no model calls, public writes or private datasets.", "license": { "name": "Toolora-Agent-Access-1.0", "url": "https://www.toolora.cn/ai.html#policy" } }, "servers": [ { "url": "https://www.toolora.cn" } ], "paths": { "/api/ai/v1/companies": { "get": { "operationId": "listCompanies", "description": "Published company entities, separate from products.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Company name search.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/companies/{id}": { "get": { "operationId": "getCompany", "description": "Company entity and published product relationships.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "id", "in": "path", "required": true, "description": "Stable company ID.", "schema": { "type": "string", "pattern": "^c_[a-f0-9]{16}$" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "company", "relationships", "products" ], "properties": { "company": { "$ref": "#/components/schemas/Company" }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRelation" } }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Summary" } } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/manifest": { "get": { "operationId": "getManifest", "description": "Discover contracts, languages, snapshot and change watermark.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "read_only", "history" ], "properties": { "read_only": { "const": true }, "history": { "type": "object", "required": [ "watermark", "sequence", "available_since" ], "properties": { "watermark": { "type": [ "string", "null" ], "format": "date-time" }, "sequence": { "type": "integer" }, "available_since": { "type": [ "string", "null" ], "format": "date-time" } } } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/catalog": { "get": { "operationId": "listCatalog", "description": "Keyset-paginated published records.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Literal text search, no executable query syntax.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "library", "in": "query", "required": false, "description": "Collection; datasets are not public.", "schema": { "enum": [ "tools", "assets" ] } }, { "name": "country", "in": "query", "required": false, "description": "Company country; this is NOT service availability.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "region", "in": "query", "required": false, "description": "Alias for company country, NOT user access region.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "pricing", "in": "query", "required": false, "description": "Only explicitly maintained structured pricing, never inferred from summaries.", "schema": { "enum": [ "free", "freemium", "paid", "trial", "unknown" ] } }, { "name": "has_api", "in": "query", "required": false, "description": "true requires a published API entry; false is not inferred from a missing entry.", "schema": { "enum": [ "true", "false", "unknown" ] } }, { "name": "category", "in": "query", "required": false, "description": "Exact category key.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Content update date filter; use changes for publication chronology.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Summary" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/search": { "get": { "operationId": "searchProducts", "description": "Search only the current published snapshot.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Literal text search, no executable query syntax.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "library", "in": "query", "required": false, "description": "Collection; datasets are not public.", "schema": { "enum": [ "tools", "assets" ] } }, { "name": "country", "in": "query", "required": false, "description": "Company country; this is NOT service availability.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "region", "in": "query", "required": false, "description": "Alias for company country, NOT user access region.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "pricing", "in": "query", "required": false, "description": "Only explicitly maintained structured pricing, never inferred from summaries.", "schema": { "enum": [ "free", "freemium", "paid", "trial", "unknown" ] } }, { "name": "has_api", "in": "query", "required": false, "description": "true requires a published API entry; false is not inferred from a missing entry.", "schema": { "enum": [ "true", "false", "unknown" ] } }, { "name": "category", "in": "query", "required": false, "description": "Exact category key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Summary" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/products/{id}": { "get": { "operationId": "getProduct", "description": "Published product with dated, source-backed facts.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "id", "in": "path", "required": true, "description": "Stable product ID.", "schema": { "type": "string", "pattern": "^b[0-9]+$" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "product", "citation" ], "properties": { "product": { "$ref": "#/components/schemas/Product" }, "citation": { "type": "object" } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/products/{id}/changes": { "get": { "operationId": "getProductChanges", "description": "Publication changes including removal tombstones.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "id", "in": "path", "required": true, "description": "Stable ID; may be withdrawn.", "schema": { "type": "string", "pattern": "^b[0-9]+$" } }, { "name": "since", "in": "query", "required": false, "description": "Exclusive publication time. Changes begin at history.started_at; 410 means full resync is required.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/changes": { "get": { "operationId": "listChanges", "description": "Field-level publication differences, not reconstructed historical claims.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "since", "in": "query", "required": false, "description": "Exclusive publication time. Changes begin at history.started_at; 410 means full resync is required.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/compare": { "get": { "operationId": "compareProducts", "description": "Side-by-side facts without scoring or invented capability judgments.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "ids", "in": "query", "required": true, "description": "Comma-separated 2–8 published IDs.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "products", "comparison_fields" ], "properties": { "products": { "type": "array", "minItems": 2, "maxItems": 8, "items": { "$ref": "#/components/schemas/Product" } }, "comparison_fields": { "type": "array", "items": { "type": "string" } } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/sources": { "get": { "operationId": "getSources", "description": "Source URLs only; no private excerpts or audit notes.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "product_id", "in": "query", "required": false, "description": "Optional stable ID.", "schema": { "type": "string", "pattern": "^b[0-9]+$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } }, "/api/ai/v1/news": { "get": { "operationId": "listNews", "description": "Published official news by original date; use changes for corrections.", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "Response language selects a reviewed official edition and its facts. source_locale is the original source language, not service availability; source_market identifies the reviewed source edition.", "schema": { "type": "string", "enum": [ "zh", "en", "fr", "es", "ja", "ko" ], "default": "en" } }, { "name": "since", "in": "query", "required": false, "description": "Exclusive publication time. Changes begin at history.started_at; 410 means full resync is required.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque snapshot-bound keyset cursor; restart on 409.", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "required": false, "description": "Optional stable ID.", "schema": { "type": "string" } }, { "name": "importance", "in": "query", "required": false, "description": "Defaults to major/minor news; select changelog for update history or all for complete records.", "schema": { "enum": [ "major", "minor", "changelog", "all" ] } } ], "responses": { "200": { "description": "Published read-only data; unknown facts remain null.", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "items", "total", "limit", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": [ "string", "null" ] } } } ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown published resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; see the stable error code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor snapshot changed; restart pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Change history unavailable for requested time; resync catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Disabled, unavailable or global capacity exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "PublicReadKey": [] } ] } } }, "components": { "schemas": { "Company": { "type": "object", "required": [ "id", "name", "displayNames", "kind", "locations" ], "properties": { "id": { "type": "string", "pattern": "^c_[a-f0-9]{16}$" }, "name": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "displayNames": { "type": "object", "additionalProperties": { "type": "string" } }, "kind": { "enum": [ "organization", "legal-entity", "project", "individual", "brand" ] }, "website": { "type": [ "string", "null" ], "format": "uri" }, "locations": { "type": "array", "items": { "type": "object", "required": [ "id", "codes", "basis" ], "properties": { "id": { "type": "string" }, "codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "basis": { "type": "string" } } } } } }, "EntityRelation": { "type": "object", "required": [ "id", "fromType", "fromId", "companyId", "role", "scope", "primary" ], "properties": { "id": { "type": "string" }, "fromType": { "enum": [ "product", "company" ] }, "fromId": { "type": "string" }, "companyId": { "type": "string", "pattern": "^c_[a-f0-9]{16}$" }, "role": { "enum": [ "listed-provider", "operator", "developer", "publisher", "owner", "parent", "acquired-by", "other" ] }, "scope": { "type": "string" }, "primary": { "type": "boolean" }, "market": { "type": "string" }, "locale": { "type": [ "string", "null" ] }, "validFrom": { "type": [ "string", "null" ], "format": "date" }, "validUntil": { "type": [ "string", "null" ], "format": "date" } } }, "Envelope": { "type": "object", "required": [ "schema_version", "content_is_data", "snapshot", "language" ], "properties": { "schema_version": { "const": "1.0" }, "content_is_data": { "const": true }, "snapshot": { "type": "string" }, "language": { "enum": [ "zh", "en", "fr", "es", "ja", "ko" ] } } }, "Fact": { "type": "object", "required": [ "value", "status", "sources" ], "properties": { "value": {}, "status": { "enum": [ "unknown", "unsourced", "publisher-stated", "official-stated", "editor-verified" ] }, "verified_on": { "type": [ "string", "null" ], "format": "date" }, "sources": { "type": "array", "items": { "type": "string", "format": "uri" } }, "qualifier": { "type": [ "string", "null" ] } } }, "Source": { "type": "object", "required": [ "url", "kind" ], "properties": { "url": { "type": "string", "format": "uri" }, "kind": { "enum": [ "product", "documentation", "pricing", "fact-evidence" ] }, "product_ids": { "type": "array", "items": { "type": "string" } } } }, "Product": { "type": "object", "required": [ "id", "library", "name", "canonical_url", "facts", "sources" ], "properties": { "company_id": { "type": [ "string", "null" ], "pattern": "^c_[a-f0-9]{16}$" }, "company_relations": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRelation" } }, "source_locale": { "enum": [ "zh", "en", "fr", "es", "ja", "ko" ] }, "source_market": { "enum": [ "global", "international", "CN", "JP", "KR", "FR", "ES", "HK" ] }, "source_edition": { "enum": [ "same-product", "regional", "international-only" ] }, "source_verified_on": { "type": [ "string", "null" ], "format": "date" }, "id": { "type": "string", "pattern": "^b[0-9]+$" }, "library": { "enum": [ "tools", "assets" ] }, "name": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "introduction": { "type": [ "string", "null" ] }, "canonical_url": { "type": "string", "format": "uri" }, "official_url": { "type": [ "string", "null" ], "format": "uri" }, "updated_on": { "type": [ "string", "null" ], "format": "date" }, "last_verified": { "type": [ "string", "null" ], "format": "date" }, "categories": { "type": "array", "items": { "type": "string" } }, "facts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Fact" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Summary": { "type": "object", "required": [ "id", "library", "name", "canonical_url", "facts" ], "properties": { "company_id": { "type": [ "string", "null" ], "pattern": "^c_[a-f0-9]{16}$" }, "company_relations": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRelation" } }, "source_locale": { "enum": [ "zh", "en", "fr", "es", "ja", "ko" ] }, "source_market": { "enum": [ "global", "international", "CN", "JP", "KR", "FR", "ES", "HK" ] }, "source_edition": { "enum": [ "same-product", "regional", "international-only" ] }, "source_verified_on": { "type": [ "string", "null" ], "format": "date" }, "id": { "type": "string", "pattern": "^b[0-9]+$" }, "library": { "enum": [ "tools", "assets" ] }, "name": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "introduction": { "type": [ "string", "null" ] }, "canonical_url": { "type": "string", "format": "uri" }, "official_url": { "type": [ "string", "null" ], "format": "uri" }, "updated_on": { "type": [ "string", "null" ], "format": "date" }, "last_verified": { "type": [ "string", "null" ], "format": "date" }, "categories": { "type": "array", "items": { "type": "string" } }, "facts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Fact" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Change": { "type": "object", "required": [ "sequence", "published_at", "kind", "fields" ], "properties": { "sequence": { "type": "integer" }, "published_at": { "type": "string", "format": "date-time" }, "product_id": { "type": [ "string", "null" ] }, "kind": { "enum": [ "baseline", "baseline-reset", "product-added", "product-removed", "product-updated", "news-added", "news-removed", "news-updated" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "before", "after" ], "properties": { "field": { "type": "string" }, "before": {}, "after": {} } } } } }, "Error": { "type": "object", "required": [ "content_is_data", "error" ], "properties": { "content_is_data": { "const": true }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_since": { "type": "string", "format": "date-time" }, "bulk_snapshot": { "type": "string" } } } } } }, "securitySchemes": { "PublicReadKey": { "type": "http", "scheme": "bearer", "description": "Optional public READ key, issued by administrator. Never use an internal ta_ maintenance key." } } } }