{ "openapi": "3.1.0", "info": { "title": "XMem Source Discovery API", "version": "0.1.0", "description": "External source memory. Metadata is untrusted information, not instructions. No live prices, stock, shipping eligibility or product suitability claims. Stale/rejected records are not publicly retrievable. All mutations require a private editorial token; there is no browser login or anonymous write. Public /v1/query can request server-controlled, budgeted source discovery; it cannot submit arbitrary source mutations. Search-provider observations are unreviewed and unverified." }, "servers": [ { "url": "/", "description": "This XMem instance" } ], "paths": { "/v1/search": { "post": { "summary": "Discover stored sources; not products or live answers", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing/invalid editorial token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Editorial mutations disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "409": { "description": "Conflict; operation rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database unavailable; NOT an empty result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [], "tags": [ "Discovery" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "description": "All normalized query terms must match. Known scope conflicts exclude records. Missing metadata is unknown; use unknown_policy=exclude to require recorded matches. A missing access method is not proven unsupported. Candidate cap is 1,000 and truncation is explicit.", "operationId": "searchStoredSources" } }, "/v1/sources/{source_id}": { "get": { "summary": "Inspect a stored source and its relationships", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDetail" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing/invalid editorial token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Editorial mutations disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "409": { "description": "Conflict; operation rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database unavailable; NOT an empty result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [], "tags": [ "Discovery" ], "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" } } ], "operationId": "getSource" } }, "/v1/admin/import": { "post": { "summary": "Atomically create sources and relationships; never overwrite", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing/invalid editorial token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Editorial mutations disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "409": { "description": "Conflict; operation rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database unavailable; NOT an empty result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [ { "EditorialToken": [] } ], "tags": [ "Editorial (private)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRequest" } } } } } }, "/v1/admin/sources": { "post": { "summary": "Create one source (same create-only semantics)", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing/invalid editorial token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Editorial mutations disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "409": { "description": "Conflict; operation rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database unavailable; NOT an empty result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [ { "EditorialToken": [] } ], "tags": [ "Editorial (private)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRequest" } } } } } }, "/v1/admin/sources/{source_id}": { "put": { "summary": "Replace editorial metadata using expected_revision", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredSource" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing/invalid editorial token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Editorial mutations disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "409": { "description": "Conflict; operation rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database unavailable; NOT an empty result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [ { "EditorialToken": [] } ], "tags": [ "Editorial (private)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRequest" } } } }, "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" } } ] }, "get": { "summary": "Private source inspection, including stale and rejected records", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDetail" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing/invalid editorial token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Editorial mutations disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "409": { "description": "Conflict; operation rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database unavailable; NOT an empty result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [ { "EditorialToken": [] } ], "tags": [ "Discovery" ], "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" } } ], "description": "Requires the editorial token, even for active sources. Use this endpoint to retrieve the current full document and revision before re-reviewing an inactive record. Public detail continues to exclude inactive records. Disabled when the token is unset." } }, "/health/live": { "get": { "summary": "HTTP process liveness; does not imply DB readiness", "responses": { "200": { "description": "Process running" } } } }, "/health/ready": { "get": { "summary": "Authenticated database access and initial migration present", "responses": { "200": { "description": "Ready" }, "503": { "description": "Database/schema not ready" } } } }, "/v1/query": { "post": { "operationId": "querySourceMemory", "summary": "Query public source memory; optionally start bounded background discovery on a miss", "security": [], "tags": [ "Discovery" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "description": "Only zero eligible non-demo results starts discovery. Include unknowns for partial memory hits; exclude unknowns for hard requirements. Discovery defaults disabled until privately configured. Prior-discovery relevance is labeled and current filters always apply. No price, stock or product availability claims.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "202": { "description": "Persistent discovery pending/running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Recommended polling delay, currently 2 seconds." } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "413": { "description": "Body exceeds 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "415": { "description": "Send application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Invalid query contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Ingress request rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database/protocol failure, NOT an empty search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/v1/discoveries/{job_id}": { "get": { "operationId": "getDiscoveryJob", "summary": "Inspect discovery state without exposing private queued input", "security": [], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DiscoveryJobId" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryJob" } } } }, "404": { "description": "Unknown discovery handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "410": { "description": "Expired public discovery handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Invalid discovery UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Database/protocol failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "description": "Contains active public candidate source IDs, not a promise they satisfy requirements. Resubmit the original query after completion to reapply current filters and editorial changes. Handle valid for 24 hours." } } }, "components": { "schemas": { "APIError": { "additionalProperties": false, "properties": { "error": { "title": "Error", "type": "string" }, "message": { "title": "Message", "type": "string" }, "details": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Details" } }, "required": [ "error", "message" ], "title": "APIError", "type": "object" }, "AccessMetadata": { "additionalProperties": false, "properties": { "public_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether public information is cataloged; not a permission to bypass controls.", "title": "Public Access" }, "authentication": { "default": "unknown", "enum": [ "none", "required", "mixed", "unknown" ], "title": "Authentication", "type": "string" }, "methods": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AccessMethod" }, "maxItems": 30, "type": "array" }, { "type": "null" } ], "default": null, "title": "Methods" }, "limitations": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Limitations" } }, "title": "AccessMetadata", "type": "object" }, "AccessMethod": { "additionalProperties": false, "properties": { "kind": { "enum": [ "website", "documented_api", "rss", "search_page", "downloadable_data", "other" ], "title": "Kind", "type": "string" }, "url": { "$ref": "#/components/schemas/PublicHttpsUrl" }, "notes": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Notes" }, "verified_at": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verified At" } }, "required": [ "kind", "url" ], "title": "AccessMethod", "type": "object" }, "EntryPoint": { "additionalProperties": false, "properties": { "url": { "$ref": "#/components/schemas/PublicHttpsUrl" }, "purpose": { "maxLength": 500, "minLength": 1, "title": "Purpose", "type": "string" }, "verified_at": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verified At" } }, "required": [ "url", "purpose" ], "title": "EntryPoint", "type": "object" }, "Evidence": { "additionalProperties": false, "properties": { "supporting_url": { "$ref": "#/components/schemas/PublicHttpsUrl" }, "fields": { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 40, "minItems": 1, "title": "Fields", "type": "array" }, "verified_at": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verified At" }, "notes": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Notes" } }, "required": [ "supporting_url", "fields" ], "title": "Evidence", "type": "object" }, "SourceInput": { "additionalProperties": false, "properties": { "source_id": { "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$", "title": "Source Id", "type": "string" }, "canonical_domain": { "maxLength": 253, "minLength": 3, "title": "Canonical Domain", "type": "string" }, "name": { "maxLength": 160, "minLength": 1, "title": "Name", "type": "string" }, "description": { "maxLength": 2000, "minLength": 1, "title": "Description", "type": "string" }, "topics": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Topics" }, "categories": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Categories" }, "aliases": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Aliases" }, "supported_tasks": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Supported Tasks" }, "source_type": { "anyOf": [ { "enum": [ "manufacturer", "retailer", "documentation", "research", "publication", "public_authority", "directory", "other" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Type" }, "languages": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Languages" }, "geographic_coverage": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "Cataloged source orientation, e.g. US. Never shipping eligibility.", "title": "Geographic Coverage" }, "use_contexts": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "Catalog topics such as indoor, not verified suitability of any product.", "title": "Use Contexts" }, "entry_points": { "items": { "$ref": "#/components/schemas/EntryPoint" }, "maxItems": 30, "title": "Entry Points", "type": "array" }, "access": { "$ref": "#/components/schemas/AccessMetadata" }, "provenance": { "items": { "$ref": "#/components/schemas/Evidence" }, "maxItems": 40, "title": "Provenance", "type": "array" }, "last_verified_at": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "review_status": { "default": "unreviewed", "enum": [ "unreviewed", "reviewed", "stale", "rejected" ], "title": "Review Status", "type": "string" }, "is_demo": { "default": false, "title": "Is Demo", "type": "boolean" }, "editorial_notes": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Editorial Notes" } }, "required": [ "source_id", "canonical_domain", "name", "description" ], "title": "SourceInput", "type": "object" }, "CreateRequest": { "additionalProperties": false, "properties": { "source": { "$ref": "#/components/schemas/SourceInput" }, "editor": { "maxLength": 100, "minLength": 1, "title": "Editor", "type": "string" } }, "required": [ "source", "editor" ], "title": "CreateRequest", "type": "object" }, "SourceRelationship": { "additionalProperties": false, "properties": { "from_source_id": { "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$", "title": "From Source Id", "type": "string" }, "to_source_id": { "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$", "title": "To Source Id", "type": "string" }, "kind": { "enum": [ "related", "alternative", "same_organization" ], "title": "Kind", "type": "string" }, "supporting_url": { "anyOf": [ { "$ref": "#/components/schemas/PublicHttpsUrl" }, { "type": "null" } ], "default": null }, "notes": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Notes" } }, "required": [ "from_source_id", "to_source_id", "kind" ], "title": "SourceRelationship", "type": "object" }, "ImportRequest": { "additionalProperties": false, "properties": { "sources": { "items": { "$ref": "#/components/schemas/SourceInput" }, "maxItems": 100, "minItems": 1, "title": "Sources", "type": "array" }, "relationships": { "items": { "$ref": "#/components/schemas/SourceRelationship" }, "maxItems": 100, "title": "Relationships", "type": "array" }, "editor": { "maxLength": 100, "minLength": 1, "title": "Editor", "type": "string" } }, "required": [ "sources", "editor" ], "title": "ImportRequest", "type": "object" }, "MutationResponse": { "additionalProperties": false, "properties": { "source_ids": { "items": { "type": "string" }, "title": "Source Ids", "type": "array" }, "imported": { "title": "Imported", "type": "integer" } }, "required": [ "source_ids", "imported" ], "title": "MutationResponse", "type": "object" }, "Requirements": { "additionalProperties": false, "properties": { "task": { "anyOf": [ { "maxLength": 100, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Task" }, "country": { "anyOf": [ { "pattern": "^[A-Za-z]{2}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Country" }, "language": { "anyOf": [ { "maxLength": 35, "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Language" }, "use_context": { "anyOf": [ { "maxLength": 100, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Use Context" }, "source_types": { "anyOf": [ { "items": { "enum": [ "manufacturer", "retailer", "documentation", "research", "publication", "public_authority", "directory", "other" ], "type": "string" }, "maxItems": 8, "minItems": 1, "type": "array" }, { "type": "null" } ], "default": null, "title": "Source Types" }, "public_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Public Access" }, "access_method": { "anyOf": [ { "enum": [ "website", "documented_api", "rss", "search_page", "downloadable_data", "other" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Access Method" } }, "title": "Requirements", "type": "object" }, "SearchRequest": { "additionalProperties": false, "properties": { "query": { "maxLength": 500, "minLength": 1, "title": "Query", "type": "string" }, "requirements": { "$ref": "#/components/schemas/Requirements" }, "unknown_policy": { "default": "include", "enum": [ "include", "exclude" ], "title": "Unknown Policy", "type": "string" }, "limit": { "default": 10, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, "required": [ "query" ], "title": "SearchRequest", "type": "object" }, "RequirementCheck": { "additionalProperties": false, "properties": { "requirement": { "title": "Requirement", "type": "string" }, "requested": { "title": "Requested" }, "recorded": { "title": "Recorded" }, "status": { "enum": [ "matched", "unknown" ], "title": "Status", "type": "string" }, "explanation": { "title": "Explanation", "type": "string" } }, "required": [ "requirement", "requested", "recorded", "status", "explanation" ], "title": "RequirementCheck", "type": "object" }, "SearchResult": { "additionalProperties": false, "properties": { "source": { "$ref": "#/components/schemas/StoredSource" }, "matched_terms": { "items": { "type": "string" }, "title": "Matched Terms", "type": "array" }, "requirement_checks": { "items": { "$ref": "#/components/schemas/RequirementCheck" }, "title": "Requirement Checks", "type": "array" }, "unknown_fields": { "items": { "type": "string" }, "title": "Unknown Fields", "type": "array" }, "relevance": { "title": "Relevance", "type": "string" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "source", "matched_terms", "requirement_checks", "unknown_fields", "relevance", "warnings" ], "title": "SearchResult", "type": "object" }, "StoredSource": { "additionalProperties": false, "properties": { "source_id": { "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$", "title": "Source Id", "type": "string" }, "canonical_domain": { "maxLength": 253, "minLength": 3, "title": "Canonical Domain", "type": "string" }, "name": { "maxLength": 160, "minLength": 1, "title": "Name", "type": "string" }, "description": { "maxLength": 2000, "minLength": 1, "title": "Description", "type": "string" }, "topics": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Topics" }, "categories": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Categories" }, "aliases": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Aliases" }, "supported_tasks": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Supported Tasks" }, "source_type": { "anyOf": [ { "enum": [ "manufacturer", "retailer", "documentation", "research", "publication", "public_authority", "directory", "other" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Type" }, "languages": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "title": "Languages" }, "geographic_coverage": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "Cataloged source orientation, e.g. US. Never shipping eligibility.", "title": "Geographic Coverage" }, "use_contexts": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "Catalog topics such as indoor, not verified suitability of any product.", "title": "Use Contexts" }, "entry_points": { "items": { "$ref": "#/components/schemas/EntryPoint" }, "maxItems": 30, "title": "Entry Points", "type": "array" }, "access": { "$ref": "#/components/schemas/AccessMetadata" }, "provenance": { "items": { "$ref": "#/components/schemas/Evidence" }, "maxItems": 40, "title": "Provenance", "type": "array" }, "last_verified_at": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "review_status": { "default": "unreviewed", "enum": [ "unreviewed", "reviewed", "stale", "rejected" ], "title": "Review Status", "type": "string" }, "is_demo": { "default": false, "title": "Is Demo", "type": "boolean" }, "editorial_notes": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Editorial Notes" }, "revision": { "minimum": 1, "title": "Revision", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "source_id", "canonical_domain", "name", "description", "revision", "created_at", "updated_at" ], "title": "StoredSource", "type": "object" }, "SearchResponse": { "additionalProperties": false, "properties": { "query": { "title": "Query", "type": "string" }, "normalized_terms": { "items": { "type": "string" }, "title": "Normalized Terms", "type": "array" }, "requirements": { "$ref": "#/components/schemas/Requirements" }, "unknown_policy": { "enum": [ "include", "exclude" ], "title": "Unknown Policy", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "title": "Results", "type": "array" }, "count": { "title": "Count", "type": "integer" }, "has_more": { "title": "Has More", "type": "boolean" }, "candidate_truncated": { "title": "Candidate Truncated", "type": "boolean" }, "ranking": { "default": "All query terms, then number of known requirement matches, then stable source ID.", "title": "Ranking", "type": "string" }, "notices": { "items": { "type": "string" }, "title": "Notices", "type": "array" } }, "required": [ "query", "normalized_terms", "requirements", "unknown_policy", "results", "count", "has_more", "candidate_truncated", "notices" ], "title": "SearchResponse", "type": "object" }, "SourceDetail": { "additionalProperties": false, "properties": { "source": { "$ref": "#/components/schemas/StoredSource" }, "relationships": { "items": { "$ref": "#/components/schemas/SourceRelationship" }, "title": "Relationships", "type": "array" }, "discovery_observations": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveryObservation" }, "maxItems": 10 } }, "required": [ "source", "relationships" ], "title": "SourceDetail", "type": "object" }, "UpdateRequest": { "additionalProperties": false, "properties": { "source": { "$ref": "#/components/schemas/SourceInput" }, "editor": { "maxLength": 100, "minLength": 1, "title": "Editor", "type": "string" }, "expected_revision": { "minimum": 1, "title": "Expected Revision", "type": "integer", "maximum": 9223372036854775806, "description": "Positive current revision, strictly less than the signed 64-bit database maximum. A stale revision returns 409." } }, "required": [ "source", "editor", "expected_revision" ], "title": "UpdateRequest", "type": "object" }, "PublicHttpsUrl": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "pattern": "^https://", "description": "Public DNS HTTPS URL on port 443, without credentials, whitespace, controls or backslashes. IP addresses, localhost and .local/.internal/.localhost hosts are rejected. Host validation is syntactic, not proof of DNS resolution, reachability, safety of the linked page or access permission; the server never fetches the URL. These semantic restrictions are validated by the server in addition to this schema." }, "QueryRequest": { "additionalProperties": false, "properties": { "query": { "maxLength": 500, "minLength": 1, "title": "Query", "type": "string" }, "requirements": { "$ref": "#/components/schemas/Requirements" }, "unknown_policy": { "default": "include", "enum": [ "include", "exclude" ], "title": "Unknown Policy", "type": "string" }, "limit": { "default": 10, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" }, "discovery": { "type": "string", "enum": [ "on_miss", "off" ], "default": "on_miss" } }, "required": [ "query" ], "title": "QueryRequest", "type": "object" }, "MemoryMatch": { "additionalProperties": false, "properties": { "source": { "$ref": "#/components/schemas/StoredSource" }, "matched_terms": { "items": { "type": "string" }, "title": "Matched Terms", "type": "array" }, "requirement_checks": { "items": { "$ref": "#/components/schemas/RequirementCheck" }, "title": "Requirement Checks", "type": "array" }, "unknown_fields": { "items": { "type": "string" }, "title": "Unknown Fields", "type": "array" }, "relevance": { "title": "Relevance", "type": "string" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "match_basis": { "type": "string", "enum": [ "literal", "prior_discovery" ] } }, "required": [ "source", "matched_terms", "requirement_checks", "unknown_fields", "relevance", "warnings", "match_basis" ], "title": "SearchResult", "type": "object" }, "DiscoveryJobId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "DiscoveryState": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "not_needed", "off", "disabled", "blocked", "pending", "running", "complete", "failed" ] }, "job_id": { "anyOf": [ { "$ref": "#/components/schemas/DiscoveryJobId" }, { "type": "null" } ] }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Includes incomplete_memory_scan when capped retrieval cannot establish a genuine miss." }, "retry_after_secs": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 300 }, { "type": "null" } ] } }, "required": [ "status", "job_id", "status_url", "reason", "retry_after_secs" ] }, "QueryResponse": { "type": "object", "additionalProperties": false, "properties": { "query": { "title": "Query", "type": "string" }, "requirements": { "$ref": "#/components/schemas/Requirements" }, "unknown_policy": { "enum": [ "include", "exclude" ], "title": "Unknown Policy", "type": "string" }, "count": { "title": "Count", "type": "integer" }, "has_more": { "title": "Has More", "type": "boolean" }, "candidate_truncated": { "title": "Candidate Truncated", "type": "boolean", "description": "Either the 1000-record literal scan or ten-record association scan overflowed. Empty truncated scans do not admit discovery." }, "notices": { "items": { "type": "string" }, "title": "Notices", "type": "array" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryMatch" }, "maxItems": 50 }, "coverage": { "type": "string", "enum": [ "missing", "partial", "sufficient", "unknown" ], "description": "Recorded requirement coverage; unknown means no eligible results in an incomplete bounded memory scan, not a confirmed miss." }, "discovery": { "$ref": "#/components/schemas/DiscoveryState" } }, "required": [ "query", "requirements", "unknown_policy", "count", "has_more", "candidate_truncated", "notices", "results", "coverage", "discovery" ] }, "DiscoveryJob": { "type": "object", "additionalProperties": false, "properties": { "job_id": { "$ref": "#/components/schemas/DiscoveryJobId" }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "failed" ] }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "sources_discovered", "provider_empty", "filtered_out", "no_acceptable_sources" ] }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_ids": { "type": "array", "items": { "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$", "title": "Source Id", "type": "string" }, "maxItems": 10 }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "retry_after_secs": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 300 }, { "type": "null" } ] } }, "required": [ "job_id", "status", "outcome", "error_code", "source_ids", "created_at", "finished_at", "retry_after_secs" ] }, "DiscoveryObservation": { "type": "object", "additionalProperties": false, "properties": { "job_id": { "$ref": "#/components/schemas/DiscoveryJobId" }, "source_id": { "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$", "title": "Source Id", "type": "string" }, "provider": { "type": "string", "enum": [ "brave_web_v1" ] }, "url": { "$ref": "#/components/schemas/PublicHttpsUrl" }, "title": { "type": "string", "maxLength": 250 }, "snippet": { "type": "string", "maxLength": 1500 }, "rank": { "type": "integer", "minimum": 1, "maximum": 10 }, "observed_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "verified_at": { "type": "null" } }, "required": [ "job_id", "source_id", "provider", "url", "title", "snippet", "rank", "observed_at", "expires_at", "verified_at" ] } }, "securitySchemes": { "EditorialToken": { "type": "http", "scheme": "bearer", "description": "Private XMEM_ADMIN_TOKEN. Never embed in browsers or agent prompts. Unset token disables all editorial mutations." } } } }