From 3047c324fcee7ba9c712c6d87a7a33a12034cb8a Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 15:29:26 +0000 Subject: [PATCH 01/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1157 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1157 insertions(+) create mode 100644 IMPLEMENTATION.md diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md new file mode 100644 index 0000000..86c3ef4 --- /dev/null +++ b/IMPLEMENTATION.md @@ -0,0 +1,1157 @@ +=== FILE: openapi.json === +{ + "openapi": "3.1.0", + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", + "info": { + "title": "Queryx API", + "summary": "x402-native web, news, and deep research search API.", + "description": "Queryx provides low-latency search endpoints protected by x402 micropayments on Base using USDC.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://queryx.run", + "description": "Production" + } + ], + "tags": [ + { + "name": "search", + "description": "Paid search endpoints." + }, + { + "name": "health", + "description": "Service health endpoint." + } + ], + "paths": { + "/health": { + "get": { + "tags": [ + "health" + ], + "summary": "Health check", + "description": "Returns service availability and version metadata.", + "operationId": "getHealth", + "security": [], + "responses": { + "200": { + "description": "Service is healthy.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HealthResponse" + }, + "examples": { + "ok": { + "value": { + "status": "ok", + "service": "queryx", + "version": "1.0.0", + "time": "2026-03-04T12:10:00Z", + "uptimeSeconds": 92841 + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/search": { + "get": { + "tags": [ + "search" + ], + "summary": "Search the web", + "description": "General web search with optional direct answer synthesis.", + "operationId": "searchWeb", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "description": "Search query.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "best vector database for rag" + }, + { + "name": "country", + "in": "query", + "required": false, + "description": "ISO-3166 alpha-2 country code used for localization.", + "schema": { + "type": "string", + "pattern": "^[A-Za-z]{2}$", + "default": "us" + }, + "example": "us" + }, + { + "name": "lang", + "in": "query", + "required": false, + "description": "IETF language code.", + "schema": { + "type": "string", + "default": "en" + }, + "example": "en" + }, + { + "name": "safe", + "in": "query", + "required": false, + "description": "Safe search mode.", + "schema": { + "type": "string", + "enum": [ + "strict", + "moderate", + "off" + ], + "default": "moderate" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of results returned.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 25, + "default": 10 + } + }, + { + "name": "offset", + "in": "query", + "required": false, + "description": "Pagination offset.", + "schema": { + "type": "integer", + "minimum": 0, + "default": 0 + } + }, + { + "name": "freshness", + "in": "query", + "required": false, + "description": "Result freshness window.", + "schema": { + "type": "string", + "enum": [ + "24h", + "7d", + "30d", + "365d" + ] + } + }, + { + "name": "includeAnswer", + "in": "query", + "required": false, + "description": "When true, returns an LLM-generated concise answer.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "$ref": "#/components/parameters/X402AddressHeader" + }, + { + "$ref": "#/components/parameters/X402TimestampHeader" + }, + { + "$ref": "#/components/parameters/X402NonceHeader" + }, + { + "$ref": "#/components/parameters/X402AmountHeader" + }, + { + "$ref": "#/components/parameters/X402CurrencyHeader" + }, + { + "$ref": "#/components/parameters/X402SignatureHeader" + } + ], + "responses": { + "200": { + "description": "Successful web search response.", + "headers": { + "X-Request-Id": { + "description": "Unique request identifier.", + "schema": { + "type": "string" + } + }, + "X-RateLimit-Limit": { + "description": "Requests allowed per minute for this endpoint.", + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "description": "Remaining requests in the current minute window.", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "examples": { + "default": { + "value": { + "id": "srch_01JQXZ9Y8S8Q3X80Q4RZ43V90K", + "object": "search.result", + "query": "best vector database for rag", + "answer": "For most RAG workloads, pick a vector store with strong filtering, hybrid retrieval, and low-latency upserts. Qdrant and Weaviate are common choices.", + "results": [ + { + "rank": 1, + "title": "Choosing a Vector Database for Production RAG", + "url": "https://example.com/vector-db-rag", + "snippet": "A comparison of Qdrant, Weaviate, Pinecone, and pgvector for retrieval-augmented generation.", + "site": "example.com", + "score": 0.93, + "publishedAt": "2026-02-16T09:20:00Z" + }, + { + "rank": 2, + "title": "Hybrid Search Benchmarks", + "url": "https://example.org/hybrid-benchmarks", + "snippet": "Hybrid BM25 + dense retrieval outperforms single-mode retrieval for many real-world corpora.", + "site": "example.org", + "score": 0.89, + "publishedAt": "2026-01-09T14:08:00Z" + } + ], + "meta": { + "latencyMs": 182, + "totalEstimated": 1520000, + "cached": false + }, + "billing": { + "endpoint": "/v1/search", + "amountBaseUnits": "20000", + "currency": "USDC", + "network": "base", + "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", + "chargedAt": "2026-03-04T12:10:03Z" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/search/news": { + "get": { + "tags": [ + "search" + ], + "summary": "Search news", + "description": "News-specific search endpoint with recency controls.", + "operationId": "searchNews", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "description": "News query.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "fed interest rate decision" + }, + { + "name": "country", + "in": "query", + "required": false, + "description": "ISO-3166 alpha-2 country code used for localization.", + "schema": { + "type": "string", + "pattern": "^[A-Za-z]{2}$", + "default": "us" + } + }, + { + "name": "lang", + "in": "query", + "required": false, + "description": "IETF language code.", + "schema": { + "type": "string", + "default": "en" + } + }, + { + "name": "from", + "in": "query", + "required": false, + "description": "Start date (inclusive) in YYYY-MM-DD.", + "schema": { + "type": "string", + "format": "date" + } + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "End date (inclusive) in YYYY-MM-DD.", + "schema": { + "type": "string", + "format": "date" + } + }, + { + "name": "sortBy", + "in": "query", + "required": false, + "description": "Sort mode for news results.", + "schema": { + "type": "string", + "enum": [ + "relevance", + "date" + ], + "default": "relevance" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of news results returned.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + } + }, + { + "$ref": "#/components/parameters/X402AddressHeader" + }, + { + "$ref": "#/components/parameters/X402TimestampHeader" + }, + { + "$ref": "#/components/parameters/X402NonceHeader" + }, + { + "$ref": "#/components/parameters/X402AmountHeader" + }, + { + "$ref": "#/components/parameters/X402CurrencyHeader" + }, + { + "$ref": "#/components/parameters/X402SignatureHeader" + } + ], + "responses": { + "200": { + "description": "Successful news search response.", + "headers": { + "X-Request-Id": { + "description": "Unique request identifier.", + "schema": { + "type": "string" + } + }, + "X-RateLimit-Limit": { + "description": "Requests allowed per minute for this endpoint.", + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "description": "Remaining requests in the current minute window.", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NewsSearchResponse" + }, + "examples": { + "default": { + "value": { + "id": "news_01JQXZC9Y6PKEE6Y6W19D4TQY2", + "object": "news.result", + "query": "fed interest rate decision", + "results": [ + { + "rank": 1, + "title": "Federal Reserve Holds Rates Steady", + "url": "https://news.example.com/fed-holds-rates", + "snippet": "The Fed kept benchmark rates unchanged, signaling a data-dependent path ahead.", + "source": "news.example.com", + "publishedAt": "2026-03-03T18:00:00Z", + "score": 0.97 + }, + { + "rank": 2, + "title": "Markets React to Latest FOMC Statement", + "url": "https://markets.example.org/fomc-reaction", + "snippet": "Equities climbed after the statement emphasized cooling inflation trends.", + "source": "markets.example.org", + "publishedAt": "2026-03-03T18:35:00Z", + "score": 0.92 + } + ], + "meta": { + "latencyMs": 204, + "totalEstimated": 14500, + "cached": false + }, + "billing": { + "endpoint": "/v1/search/news", + "amountBaseUnits": "35000", + "currency": "USDC", + "network": "base", + "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", + "chargedAt": "2026-03-04T12:12:20Z" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/search/deep": { + "post": { + "tags": [ + "search" + ], + "summary": "Deep research search", + "description": "Multi-source synthesis endpoint for deeper investigations with citations.", + "operationId": "deepSearch", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/X402AddressHeader" + }, + { + "$ref": "#/components/parameters/X402TimestampHeader" + }, + { + "$ref": "#/components/parameters/X402NonceHeader" + }, + { + "$ref": "#/components/parameters/X402AmountHeader" + }, + { + "$ref": "#/components/parameters/X402CurrencyHeader" + }, + { + "$ref": "#/components/parameters/X402SignatureHeader" + } + ], + "requestBody": { + "required": true, + "description": "Deep search request payload.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchRequest" + }, + "examples": { + "standard": { + "value": { + "query": "What are the tradeoffs between retrieval chunk size and answer quality in RAG systems?", + "depth": "standard", + "maxSources": 12, + "includeCitations": true, + "includeRawSnippets": false, + "focus": [ + "web", + "papers", + "docs" + ], + "timeRange": { + "from": "2025-01-01T00:00:00Z", + "to": "2026-03-01T00:00:00Z" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful deep research response.", + "headers": { + "X-Request-Id": { + "description": "Unique request identifier.", + "schema": { + "type": "string" + } + }, + "X-RateLimit-Limit": { + "description": "Requests allowed per minute for this endpoint.", + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "description": "Remaining requests in the current minute window.", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchResponse" + }, + "examples": { + "standard": { + "value": { + "id": "deep_01JQXZJCN2ZEQX0N3QY3A5MKS7", + "object": "deep.result", + "query": "What are the tradeoffs between retrieval chunk size and answer quality in RAG systems?", + "depth": "standard", + "summary": "Smaller chunks improve retrieval precision but can fragment context; larger chunks preserve context but increase noise. Hybrid strategies with overlap and reranking usually perform best.", + "sections": [ + { + "heading": "Precision vs. context preservation", + "content": "Empirical benchmarks show chunk sizes around 256-512 tokens maximize factual precision in QA-heavy corpora, while 768-1024 token chunks help long-form synthesis.", + "citationIndexes": [ + 0, + 2 + ] + }, + { + "heading": "Operational tradeoffs", + "content": "Smaller chunks increase index size and retrieval fan-out. Larger chunks reduce index pressure but can lower relevance and increase token usage during generation.", + "citationIndexes": [ + 1, + 3 + ] + } + ], + "citations": [ + { + "index": 0, + "title": "RAG Chunking Strategies in Practice", + "url": "https://research.example.com/rag-chunking", + "source": "research.example.com", + "snippet": "Chunk granularity is a first-order factor in retrieval quality.", + "publishedAt": "2025-11-18T10:00:00Z" + }, + { + "index": 1, + "title": "Efficient Dense Retrieval at Scale", + "url": "https://docs.example.org/dense-retrieval-scale", + "source": "docs.example.org", + "snippet": "Index fan-out and memory pressure scale with document segmentation strategy.", + "publishedAt": "2026-01-22T15:25:00Z" + } + ], + "meta": { + "latencyMs": 1632, + "totalEstimated": 312, + "cached": false + }, + "billing": { + "endpoint": "/v1/search/deep", + "amountBaseUnits": "250000", + "currency": "USDC", + "network": "base", + "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", + "chargedAt": "2026-03-04T12:14:09Z" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + } + }, + "components": { + "securitySchemes": { + "x402": { + "type": "apiKey", + "in": "header", + "name": "X-402-Signature", + "description": "x402 payment authorization. Signed proof must be sent in `X-402-Signature` with companion headers listed in `x-requiredHeaders`.", + "x-requiredHeaders": [ + "X-402-Address", + "X-402-Timestamp", + "X-402-Nonce", + "X-402-Amount", + "X-402-Currency", + "X-402-Signature" + ], + "x-network": "base", + "x-currency": "USDC", + "x-facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1" + } + }, + "parameters": { + "X402AddressHeader": { + "name": "X-402-Address", + "in": "header", + "required": false, + "description": "Payer wallet address.", + "schema": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + }, + "example": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4" + }, + "X402TimestampHeader": { + "name": "X-402-Timestamp", + "in": "header", + "required": false, + "description": "Unix timestamp in seconds when signature was generated.", + "schema": { + "type": "integer", + "minimum": 0 + }, + "example": 1772626322 + }, + "X402NonceHeader": { + "name": "X-402-Nonce", + "in": "header", + "required": false, + "description": "Client-generated unique nonce (UUID recommended).", + "schema": { + "type": "string", + "minLength": 8, + "maxLength": 128 + }, + "example": "e95ed706-f766-4c90-bc84-95ca0a9c1267" + }, + "X402AmountHeader": { + "name": "X-402-Amount", + "in": "header", + "required": false, + "description": "USDC amount in base units (1 USDC = 1,000,000 base units).", + "schema": { + "type": "string", + "pattern": "^[0-9]+$" + }, + "example": "20000" + }, + "X402CurrencyHeader": { + "name": "X-402-Currency", + "in": "header", + "required": false, + "description": "Payment currency.", + "schema": { + "type": "string", + "enum": [ + "USDC" + ] + }, + "example": "USDC" + }, + "X402SignatureHeader": { + "name": "X-402-Signature", + "in": "header", + "required": false, + "description": "Hex-encoded signature for canonical x402 payload.", + "schema": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]+$" + } + } + }, + "responses": { + "PaymentRequired": { + "description": "Payment is required before processing this request.", + "headers": { + "X-402-Amount": { + "description": "Required payment amount in USDC base units.", + "schema": { + "type": "string", + "pattern": "^[0-9]+$" + } + }, + "X-402-Currency": { + "description": "Required payment currency.", + "schema": { + "type": "string", + "enum": [ + "USDC" + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentRequiredResponse" + }, + "examples": { + "payment-required": { + "value": { + "error": { + "code": "payment_required", + "message": "x402 payment is required for this endpoint.", + "requestId": "req_01JQXZQ7N5QK8YJ3WHQ4A4RNJB" + }, + "invoice": { + "scheme": "x402", + "network": "base", + "currency": "USDC", + "amountBaseUnits": "20000", + "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", + "resource": "/v1/search?q=best%20vector%20database%20for%20rag", + "expiresAt": "2026-03-04T12:12:00Z" + } + } + } + } + } + } + }, + "ValidationError": { + "description": "Request validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorResponse" + }, + "examples": { + "invalid-parameter": { + "value": { + "error": { + "code": "validation_error", + "message": "Request validation failed.", + "requestId": "req_01JQXZT9Y7W4NPT5M8X3HD1B5R" + }, + "invalidParams": [ + { + "name": "limit", + "reason": "must be between 1 and 25" + } + ] + } + } + } + } + } + }, + "RateLimited": { + "description": "Too many requests.", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before retrying.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitErrorResponse" + }, + "examples": { + "rate-limited": { + "value": { + "error": { + "code": "rate_limited", + "message": "Too many requests. Retry later.", + "requestId": "req_01JQY00H5P83F9N4E8R3XK0DFA" + }, + "retryAfterSeconds": 12 + } + } + } + } + } + }, + "InternalError": { + "description": "Unexpected internal error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorResponse" + }, + "examples": { + "internal": { + "value": { + "error": { + "code": "internal_error", + "message": "An unexpected error occurred.", + "requestId": "req_01JQY04WQJS8ENQBJYXC7YAKH8" + } + } + } + } + } + } + } + }, + "schemas": { + "HealthResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "status", + "service", + "version", + "time", + "uptimeSeconds" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "service": { + "type": "string" + }, + "version": { + "type": "string" + }, + "time": { + "type": "string", + "format": "date-time" + }, + "uptimeSeconds": { + "type": "integer", + "minimum": 0 + } + } + }, + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "object", + "query", + "results", + "meta", + "billing" + ], + "properties": { + "id": { + "type": "string" + }, + "object": { + "type": "string", + "const": "search.result" + }, + "query": { + "type": "string" + }, + "answer": { + "type": "string" + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } + }, + "meta": { + "$ref": "#/components/schemas/SearchMeta" + }, + "billing": { + "$ref": "#/components/schemas/BillingInfo" + } + } + }, + "SearchResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "rank", + "title", + "url", + "snippet", + "site", + "score" + ], + "properties": { + "rank": { + "type": "integer", + "minimum": 1 + }, + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "site": { + "type": "string" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "publishedAt": { + "type": "string", + "format": "date-time" + } + } + }, + "NewsSearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "object", + "query", + "results", + "meta", + "billing" + ], + "properties": { + "id": { + "type": "string" + }, + "object": { + "type": "string", + "const": "news.result" + }, + "query": { + "type": "string" + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsResult" + } + }, + "meta": { + "$ref": "#/components/schemas/SearchMeta" + }, + "billing": { + "$ref": "#/components/schemas/BillingInfo" + } + } + }, + "NewsResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "rank", + "title", + "url", + "snippet", + "source", + "publishedAt", + "score" + ], + "properties": { + "rank": { + "type": "integer", + "minimum": 1 + }, + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "source": { + "type": "string" + }, + "publishedAt": { + "type": "string", + "format": "date-time" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "DeepSearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + }, + "depth": { + "type": "string", + "enum": [ + "quick", + "standard", + "exhaustive" + ], + "default": "standard" + }, + "maxSources": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 12 + }, + "includeCitations": { + "type": "boolean", + "default": true + }, + "includeRawSnippets": { + "type": "boolean", + "default": false + }, + "focus": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "web", + "news", + "papers", + "forums", + "docs" + ] + }, + "minItems": 1, + "uniqueItems": true + }, + "timeRange": { + "$ref": "#/components/schemas/TimeRange" + } + } + }, + "DeepSearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "object", + "query", + "depth", + "summary", + "sections", + "citations", + "meta", + "billing" + ], + "properties": { + "id": { + "type": "string" + }, + "object": { + "type": "string", + "const": "deep.result" + }, + "query": { + "type": "string" + }, + "depth": { + "type": "string", + "enum": [ + "quick", + "standard", + "exhaustive" + ] + }, + "summary": { + "type": "string" + }, + "sections": { + "type": " \ No newline at end of file From 2cb4b571ff410ee90f90b9292989a17a041dc719 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 15:45:47 +0000 Subject: [PATCH 02/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1126 +++++++++------------------------------------ 1 file changed, 224 insertions(+), 902 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index 86c3ef4..fa975dc 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,12 +1,10 @@ === FILE: openapi.json === { "openapi": "3.1.0", - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", - "summary": "x402-native web, news, and deep research search API.", - "description": "Queryx provides low-latency search endpoints protected by x402 micropayments on Base using USDC.", - "version": "1.0.0" + "version": "1.0.0", + "description": "Queryx is an x402-paid search API on Base. This spec covers web search, news search, deep research, and health endpoints." }, "servers": [ { @@ -16,22 +14,27 @@ ], "tags": [ { - "name": "search", - "description": "Paid search endpoints." + "name": "System", + "description": "Service status and health operations." }, { - "name": "health", - "description": "Service health endpoint." + "name": "Search", + "description": "Paid search and research endpoints secured by x402." + } + ], + "security": [ + { + "x402": [] } ], "paths": { "/health": { "get": { "tags": [ - "health" + "System" ], "summary": "Health check", - "description": "Returns service availability and version metadata.", + "description": "Returns service liveness and basic runtime metadata.", "operationId": "getHealth", "security": [], "responses": { @@ -42,22 +45,18 @@ "schema": { "$ref": "#/components/schemas/HealthResponse" }, - "examples": { - "ok": { - "value": { - "status": "ok", - "service": "queryx", - "version": "1.0.0", - "time": "2026-03-04T12:10:00Z", - "uptimeSeconds": 92841 - } - } + "example": { + "status": "ok", + "service": "queryx", + "version": "1.0.0", + "timestamp": "2026-03-04T12:00:00Z", + "uptime_seconds": 86423 } } } }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -65,155 +64,69 @@ "/v1/search": { "get": { "tags": [ - "search" + "Search" ], - "summary": "Search the web", - "description": "General web search with optional direct answer synthesis.", + "summary": "Web search", + "description": "Search the web and optionally return a concise synthesized answer with citations.", "operationId": "searchWeb", "security": [ { "x402": [] } ], + "x-pricing": { + "asset": "USDC", + "chain": "base", + "cost_base_units": 1000, + "cost_usdc": "0.001" + }, "parameters": [ { - "name": "q", - "in": "query", - "required": true, - "description": "Search query.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "example": "best vector database for rag" + "$ref": "#/components/parameters/XPaymentHeader" }, { - "name": "country", - "in": "query", - "required": false, - "description": "ISO-3166 alpha-2 country code used for localization.", - "schema": { - "type": "string", - "pattern": "^[A-Za-z]{2}$", - "default": "us" - }, - "example": "us" + "$ref": "#/components/parameters/XPaymentSignatureHeader" }, { - "name": "lang", - "in": "query", - "required": false, - "description": "IETF language code.", - "schema": { - "type": "string", - "default": "en" - }, - "example": "en" + "$ref": "#/components/parameters/XPaymentTimestampHeader" }, { - "name": "safe", - "in": "query", - "required": false, - "description": "Safe search mode.", - "schema": { - "type": "string", - "enum": [ - "strict", - "moderate", - "off" - ], - "default": "moderate" - } + "$ref": "#/components/parameters/XPaymentAddressHeader" }, { - "name": "limit", - "in": "query", - "required": false, - "description": "Maximum number of results returned.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 25, - "default": 10 - } + "$ref": "#/components/parameters/QueryParam" }, { - "name": "offset", - "in": "query", - "required": false, - "description": "Pagination offset.", - "schema": { - "type": "integer", - "minimum": 0, - "default": 0 - } + "$ref": "#/components/parameters/CountryParam" }, { - "name": "freshness", - "in": "query", - "required": false, - "description": "Result freshness window.", - "schema": { - "type": "string", - "enum": [ - "24h", - "7d", - "30d", - "365d" - ] - } + "$ref": "#/components/parameters/LanguageParam" }, { - "name": "includeAnswer", - "in": "query", - "required": false, - "description": "When true, returns an LLM-generated concise answer.", - "schema": { - "type": "boolean", - "default": true - } + "$ref": "#/components/parameters/FreshnessParam" }, { - "$ref": "#/components/parameters/X402AddressHeader" + "$ref": "#/components/parameters/LimitParam" }, { - "$ref": "#/components/parameters/X402TimestampHeader" + "$ref": "#/components/parameters/PageParam" }, { - "$ref": "#/components/parameters/X402NonceHeader" - }, - { - "$ref": "#/components/parameters/X402AmountHeader" - }, - { - "$ref": "#/components/parameters/X402CurrencyHeader" - }, - { - "$ref": "#/components/parameters/X402SignatureHeader" + "$ref": "#/components/parameters/IncludeAnswerParam" } ], "responses": { "200": { "description": "Successful web search response.", "headers": { - "X-Request-Id": { - "description": "Unique request identifier.", - "schema": { - "type": "string" - } - }, "X-RateLimit-Limit": { - "description": "Requests allowed per minute for this endpoint.", - "schema": { - "type": "integer" - } + "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { - "description": "Remaining requests in the current minute window.", - "schema": { - "type": "integer" - } + "$ref": "#/components/headers/RateLimitRemainingHeader" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/RateLimitResetHeader" } }, "content": { @@ -221,48 +134,48 @@ "schema": { "$ref": "#/components/schemas/SearchResponse" }, - "examples": { - "default": { - "value": { - "id": "srch_01JQXZ9Y8S8Q3X80Q4RZ43V90K", - "object": "search.result", - "query": "best vector database for rag", - "answer": "For most RAG workloads, pick a vector store with strong filtering, hybrid retrieval, and low-latency upserts. Qdrant and Weaviate are common choices.", - "results": [ - { - "rank": 1, - "title": "Choosing a Vector Database for Production RAG", - "url": "https://example.com/vector-db-rag", - "snippet": "A comparison of Qdrant, Weaviate, Pinecone, and pgvector for retrieval-augmented generation.", - "site": "example.com", - "score": 0.93, - "publishedAt": "2026-02-16T09:20:00Z" - }, - { - "rank": 2, - "title": "Hybrid Search Benchmarks", - "url": "https://example.org/hybrid-benchmarks", - "snippet": "Hybrid BM25 + dense retrieval outperforms single-mode retrieval for many real-world corpora.", - "site": "example.org", - "score": 0.89, - "publishedAt": "2026-01-09T14:08:00Z" - } - ], - "meta": { - "latencyMs": 182, - "totalEstimated": 1520000, - "cached": false - }, - "billing": { - "endpoint": "/v1/search", - "amountBaseUnits": "20000", - "currency": "USDC", - "network": "base", - "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", - "chargedAt": "2026-03-04T12:10:03Z" - } + "example": { + "object": "search.result", + "id": "srch_01HQX4AHQ3W3H8W9CC61J0M2VE", + "query": "latest base network ecosystem updates", + "answer": "Base ecosystem activity continues to grow, with tooling and agent integrations expanding in early 2026.", + "results": [ + { + "position": 1, + "title": "Queryx", + "url": "https://queryx.run", + "snippet": "x402-paid search API on Base for web, news, and deep research.", + "source": "queryx", + "relevance": 0.98, + "published_at": "2026-03-02T16:00:00Z" + }, + { + "position": 2, + "title": "Queryx health endpoint", + "url": "https://queryx.run", + "snippet": "Use /health to verify service status before issuing paid calls.", + "source": "queryx", + "relevance": 0.77, + "published_at": null + } + ], + "citations": [ + { + "index": 1, + "title": "Queryx", + "url": "https://queryx.run" } - } + ], + "usage": { + "endpoint": "/v1/search", + "query_units": 1, + "cost_base_units": 1000, + "cost_usdc": "0.001", + "latency_ms": 241, + "rate_limit_remaining": 119, + "request_id": "req_01HQX4AHZ4A3H9N81YE60P5N0R" + }, + "generated_at": "2026-03-04T12:00:01Z" } } } @@ -271,13 +184,13 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationError" + "$ref": "#/components/responses/ValidationFailed" }, "429": { - "$ref": "#/components/responses/RateLimited" + "$ref": "#/components/responses/RateLimitExceeded" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -285,136 +198,75 @@ "/v1/search/news": { "get": { "tags": [ - "search" + "Search" ], - "summary": "Search news", - "description": "News-specific search endpoint with recency controls.", + "summary": "News search", + "description": "Search current news articles with publication metadata.", "operationId": "searchNews", "security": [ { "x402": [] } ], + "x-pricing": { + "asset": "USDC", + "chain": "base", + "cost_base_units": 2000, + "cost_usdc": "0.002" + }, "parameters": [ { - "name": "q", - "in": "query", - "required": true, - "description": "News query.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "example": "fed interest rate decision" + "$ref": "#/components/parameters/XPaymentHeader" }, { - "name": "country", - "in": "query", - "required": false, - "description": "ISO-3166 alpha-2 country code used for localization.", - "schema": { - "type": "string", - "pattern": "^[A-Za-z]{2}$", - "default": "us" - } + "$ref": "#/components/parameters/XPaymentSignatureHeader" }, { - "name": "lang", - "in": "query", - "required": false, - "description": "IETF language code.", - "schema": { - "type": "string", - "default": "en" - } + "$ref": "#/components/parameters/XPaymentTimestampHeader" }, { - "name": "from", - "in": "query", - "required": false, - "description": "Start date (inclusive) in YYYY-MM-DD.", - "schema": { - "type": "string", - "format": "date" - } + "$ref": "#/components/parameters/XPaymentAddressHeader" }, { - "name": "to", - "in": "query", - "required": false, - "description": "End date (inclusive) in YYYY-MM-DD.", - "schema": { - "type": "string", - "format": "date" - } + "$ref": "#/components/parameters/QueryParam" }, { - "name": "sortBy", - "in": "query", - "required": false, - "description": "Sort mode for news results.", - "schema": { - "type": "string", - "enum": [ - "relevance", - "date" - ], - "default": "relevance" - } + "$ref": "#/components/parameters/TopicParam" }, { - "name": "limit", - "in": "query", - "required": false, - "description": "Maximum number of news results returned.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 - } + "$ref": "#/components/parameters/LanguageParam" }, { - "$ref": "#/components/parameters/X402AddressHeader" + "$ref": "#/components/parameters/CountryParam" }, { - "$ref": "#/components/parameters/X402TimestampHeader" + "$ref": "#/components/parameters/FromDateParam" }, { - "$ref": "#/components/parameters/X402NonceHeader" + "$ref": "#/components/parameters/ToDateParam" }, { - "$ref": "#/components/parameters/X402AmountHeader" + "$ref": "#/components/parameters/SortParam" }, { - "$ref": "#/components/parameters/X402CurrencyHeader" + "$ref": "#/components/parameters/LimitParam" }, { - "$ref": "#/components/parameters/X402SignatureHeader" + "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "Successful news search response.", "headers": { - "X-Request-Id": { - "description": "Unique request identifier.", - "schema": { - "type": "string" - } - }, "X-RateLimit-Limit": { - "description": "Requests allowed per minute for this endpoint.", - "schema": { - "type": "integer" - } + "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { - "description": "Remaining requests in the current minute window.", - "schema": { - "type": "integer" - } + "$ref": "#/components/headers/RateLimitRemainingHeader" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/RateLimitResetHeader" } }, "content": { @@ -422,47 +274,33 @@ "schema": { "$ref": "#/components/schemas/NewsSearchResponse" }, - "examples": { - "default": { - "value": { - "id": "news_01JQXZC9Y6PKEE6Y6W19D4TQY2", - "object": "news.result", - "query": "fed interest rate decision", - "results": [ - { - "rank": 1, - "title": "Federal Reserve Holds Rates Steady", - "url": "https://news.example.com/fed-holds-rates", - "snippet": "The Fed kept benchmark rates unchanged, signaling a data-dependent path ahead.", - "source": "news.example.com", - "publishedAt": "2026-03-03T18:00:00Z", - "score": 0.97 - }, - { - "rank": 2, - "title": "Markets React to Latest FOMC Statement", - "url": "https://markets.example.org/fomc-reaction", - "snippet": "Equities climbed after the statement emphasized cooling inflation trends.", - "source": "markets.example.org", - "publishedAt": "2026-03-03T18:35:00Z", - "score": 0.92 - } - ], - "meta": { - "latencyMs": 204, - "totalEstimated": 14500, - "cached": false - }, - "billing": { - "endpoint": "/v1/search/news", - "amountBaseUnits": "35000", - "currency": "USDC", - "network": "base", - "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", - "chargedAt": "2026-03-04T12:12:20Z" - } + "example": { + "object": "news.search.result", + "id": "news_01HQX4B04TRT1P9CFQJFKM1D8B", + "query": "agent infrastructure", + "clusters": 3, + "results": [ + { + "position": 1, + "title": "Queryx ships OpenAPI docs", + "url": "https://queryx.run", + "snippet": "The Queryx API now includes a complete OpenAPI 3.1 specification.", + "publisher": "Queryx", + "published_at": "2026-03-04T08:20:00Z", + "category": "technology", + "image_url": null } - } + ], + "usage": { + "endpoint": "/v1/search/news", + "query_units": 1, + "cost_base_units": 2000, + "cost_usdc": "0.002", + "latency_ms": 319, + "rate_limit_remaining": 89, + "request_id": "req_01HQX4B09QH6WJXRW7EGWQ4W0N" + }, + "generated_at": "2026-03-04T12:00:02Z" } } } @@ -471,13 +309,13 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationError" + "$ref": "#/components/responses/ValidationFailed" }, "429": { - "$ref": "#/components/responses/RateLimited" + "$ref": "#/components/responses/RateLimitExceeded" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -485,63 +323,52 @@ "/v1/search/deep": { "post": { "tags": [ - "search" + "Search" ], "summary": "Deep research search", - "description": "Multi-source synthesis endpoint for deeper investigations with citations.", + "description": "Run a multi-source deep research workflow and return structured sections, supporting evidence, and takeaways.", "operationId": "deepSearch", "security": [ { "x402": [] } ], + "x-pricing": { + "asset": "USDC", + "chain": "base", + "cost_base_units": 15000, + "cost_usdc": "0.015" + }, "parameters": [ { - "$ref": "#/components/parameters/X402AddressHeader" - }, - { - "$ref": "#/components/parameters/X402TimestampHeader" + "$ref": "#/components/parameters/XPaymentHeader" }, { - "$ref": "#/components/parameters/X402NonceHeader" + "$ref": "#/components/parameters/XPaymentSignatureHeader" }, { - "$ref": "#/components/parameters/X402AmountHeader" + "$ref": "#/components/parameters/XPaymentTimestampHeader" }, { - "$ref": "#/components/parameters/X402CurrencyHeader" + "$ref": "#/components/parameters/XPaymentAddressHeader" }, { - "$ref": "#/components/parameters/X402SignatureHeader" + "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, - "description": "Deep search request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearchRequest" }, - "examples": { - "standard": { - "value": { - "query": "What are the tradeoffs between retrieval chunk size and answer quality in RAG systems?", - "depth": "standard", - "maxSources": 12, - "includeCitations": true, - "includeRawSnippets": false, - "focus": [ - "web", - "papers", - "docs" - ], - "timeRange": { - "from": "2025-01-01T00:00:00Z", - "to": "2026-03-01T00:00:00Z" - } - } - } + "example": { + "query": "What are the primary trade-offs between web-scale retrieval quality and response latency?", + "depth": "standard", + "max_sources": 25, + "include_raw_content": false, + "freshness": "month" } } } @@ -550,23 +377,14 @@ "200": { "description": "Successful deep research response.", "headers": { - "X-Request-Id": { - "description": "Unique request identifier.", - "schema": { - "type": "string" - } - }, "X-RateLimit-Limit": { - "description": "Requests allowed per minute for this endpoint.", - "schema": { - "type": "integer" - } + "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { - "description": "Remaining requests in the current minute window.", - "schema": { - "type": "integer" - } + "$ref": "#/components/headers/RateLimitRemainingHeader" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/RateLimitResetHeader" } }, "content": { @@ -574,65 +392,50 @@ "schema": { "$ref": "#/components/schemas/DeepSearchResponse" }, - "examples": { - "standard": { - "value": { - "id": "deep_01JQXZJCN2ZEQX0N3QY3A5MKS7", - "object": "deep.result", - "query": "What are the tradeoffs between retrieval chunk size and answer quality in RAG systems?", - "depth": "standard", - "summary": "Smaller chunks improve retrieval precision but can fragment context; larger chunks preserve context but increase noise. Hybrid strategies with overlap and reranking usually perform best.", - "sections": [ - { - "heading": "Precision vs. context preservation", - "content": "Empirical benchmarks show chunk sizes around 256-512 tokens maximize factual precision in QA-heavy corpora, while 768-1024 token chunks help long-form synthesis.", - "citationIndexes": [ - 0, - 2 - ] - }, - { - "heading": "Operational tradeoffs", - "content": "Smaller chunks increase index size and retrieval fan-out. Larger chunks reduce index pressure but can lower relevance and increase token usage during generation.", - "citationIndexes": [ - 1, - 3 - ] - } - ], - "citations": [ - { - "index": 0, - "title": "RAG Chunking Strategies in Practice", - "url": "https://research.example.com/rag-chunking", - "source": "research.example.com", - "snippet": "Chunk granularity is a first-order factor in retrieval quality.", - "publishedAt": "2025-11-18T10:00:00Z" - }, + "example": { + "object": "deep.search.result", + "id": "deep_01HQX4B3AV4EV8A9J3PDQARQ6N", + "query": "What are the primary trade-offs between web-scale retrieval quality and response latency?", + "executive_summary": "Higher retrieval quality usually requires broader candidate generation and heavier reranking, increasing latency and cost. Practical systems tune these with adaptive depth and caching.", + "sections": [ + { + "heading": "Latency vs relevance", + "summary": "Increasing candidate set size improves recall but can slow response time without tiered ranking.", + "evidence": [ { - "index": 1, - "title": "Efficient Dense Retrieval at Scale", - "url": "https://docs.example.org/dense-retrieval-scale", - "source": "docs.example.org", - "snippet": "Index fan-out and memory pressure scale with document segmentation strategy.", - "publishedAt": "2026-01-22T15:25:00Z" + "claim": "Two-stage retrieval commonly balances quality and speed.", + "source_index": 1, + "confidence": 0.89 } - ], - "meta": { - "latencyMs": 1632, - "totalEstimated": 312, - "cached": false - }, - "billing": { - "endpoint": "/v1/search/deep", - "amountBaseUnits": "250000", - "currency": "USDC", - "network": "base", - "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", - "chargedAt": "2026-03-04T12:14:09Z" - } + ] } - } + ], + "sources": [ + { + "index": 1, + "title": "Queryx", + "url": "https://queryx.run", + "snippet": "Queryx deep search endpoint for structured research output.", + "domain": "queryx.run", + "published_at": "2026-03-01T00:00:00Z", + "raw_content": null + } + ], + "takeaways": [ + "Use adaptive depth to reduce tail latency.", + "Cache stable sources and summaries.", + "Reserve comprehensive mode for high-value prompts." + ], + "usage": { + "endpoint": "/v1/search/deep", + "query_units": 1, + "cost_base_units": 15000, + "cost_usdc": "0.015", + "latency_ms": 1429, + "rate_limit_remaining": 29, + "request_id": "req_01HQX4B3CZ8WQ1SHX2R7XJ3A21" + }, + "generated_at": "2026-03-04T12:00:03Z" } } } @@ -641,13 +444,13 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationError" + "$ref": "#/components/responses/ValidationFailed" }, "429": { - "$ref": "#/components/responses/RateLimited" + "$ref": "#/components/responses/RateLimitExceeded" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -658,500 +461,19 @@ "x402": { "type": "apiKey", "in": "header", - "name": "X-402-Signature", - "description": "x402 payment authorization. Signed proof must be sent in `X-402-Signature` with companion headers listed in `x-requiredHeaders`.", - "x-requiredHeaders": [ - "X-402-Address", - "X-402-Timestamp", - "X-402-Nonce", - "X-402-Amount", - "X-402-Currency", - "X-402-Signature" - ], - "x-network": "base", - "x-currency": "USDC", - "x-facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1" + "name": "X-Payment", + "description": "x402 payment payload (base64-encoded JSON). Also send X-Payment-Signature, X-Payment-Timestamp, and X-Payment-Address headers.", + "x-x402": { + "chain": "base", + "chain_id": 8453, + "asset": "USDC", + "facilitator_address": "0x9a2fE0f2f5f4A8E4f6D8dD68fAecbf3A4aB1aE52" + } } }, "parameters": { - "X402AddressHeader": { - "name": "X-402-Address", - "in": "header", - "required": false, - "description": "Payer wallet address.", - "schema": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$" - }, - "example": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4" - }, - "X402TimestampHeader": { - "name": "X-402-Timestamp", - "in": "header", - "required": false, - "description": "Unix timestamp in seconds when signature was generated.", - "schema": { - "type": "integer", - "minimum": 0 - }, - "example": 1772626322 - }, - "X402NonceHeader": { - "name": "X-402-Nonce", - "in": "header", - "required": false, - "description": "Client-generated unique nonce (UUID recommended).", - "schema": { - "type": "string", - "minLength": 8, - "maxLength": 128 - }, - "example": "e95ed706-f766-4c90-bc84-95ca0a9c1267" - }, - "X402AmountHeader": { - "name": "X-402-Amount", - "in": "header", - "required": false, - "description": "USDC amount in base units (1 USDC = 1,000,000 base units).", - "schema": { - "type": "string", - "pattern": "^[0-9]+$" - }, - "example": "20000" - }, - "X402CurrencyHeader": { - "name": "X-402-Currency", - "in": "header", - "required": false, - "description": "Payment currency.", - "schema": { - "type": "string", - "enum": [ - "USDC" - ] - }, - "example": "USDC" - }, - "X402SignatureHeader": { - "name": "X-402-Signature", + "XPaymentHeader": { + "name": "X-Payment", "in": "header", "required": false, - "description": "Hex-encoded signature for canonical x402 payload.", - "schema": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]+$" - } - } - }, - "responses": { - "PaymentRequired": { - "description": "Payment is required before processing this request.", - "headers": { - "X-402-Amount": { - "description": "Required payment amount in USDC base units.", - "schema": { - "type": "string", - "pattern": "^[0-9]+$" - } - }, - "X-402-Currency": { - "description": "Required payment currency.", - "schema": { - "type": "string", - "enum": [ - "USDC" - ] - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PaymentRequiredResponse" - }, - "examples": { - "payment-required": { - "value": { - "error": { - "code": "payment_required", - "message": "x402 payment is required for this endpoint.", - "requestId": "req_01JQXZQ7N5QK8YJ3WHQ4A4RNJB" - }, - "invoice": { - "scheme": "x402", - "network": "base", - "currency": "USDC", - "amountBaseUnits": "20000", - "facilitator": "0x7E9f3D7d4A55b7f67C4A6af3E5Db2Aed5f83C8f1", - "resource": "/v1/search?q=best%20vector%20database%20for%20rag", - "expiresAt": "2026-03-04T12:12:00Z" - } - } - } - } - } - } - }, - "ValidationError": { - "description": "Request validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ValidationErrorResponse" - }, - "examples": { - "invalid-parameter": { - "value": { - "error": { - "code": "validation_error", - "message": "Request validation failed.", - "requestId": "req_01JQXZT9Y7W4NPT5M8X3HD1B5R" - }, - "invalidParams": [ - { - "name": "limit", - "reason": "must be between 1 and 25" - } - ] - } - } - } - } - } - }, - "RateLimited": { - "description": "Too many requests.", - "headers": { - "Retry-After": { - "description": "Number of seconds to wait before retrying.", - "schema": { - "type": "integer", - "minimum": 1 - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RateLimitErrorResponse" - }, - "examples": { - "rate-limited": { - "value": { - "error": { - "code": "rate_limited", - "message": "Too many requests. Retry later.", - "requestId": "req_01JQY00H5P83F9N4E8R3XK0DFA" - }, - "retryAfterSeconds": 12 - } - } - } - } - } - }, - "InternalError": { - "description": "Unexpected internal error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InternalErrorResponse" - }, - "examples": { - "internal": { - "value": { - "error": { - "code": "internal_error", - "message": "An unexpected error occurred.", - "requestId": "req_01JQY04WQJS8ENQBJYXC7YAKH8" - } - } - } - } - } - } - } - }, - "schemas": { - "HealthResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "status", - "service", - "version", - "time", - "uptimeSeconds" - ], - "properties": { - "status": { - "type": "string", - "enum": [ - "ok" - ] - }, - "service": { - "type": "string" - }, - "version": { - "type": "string" - }, - "time": { - "type": "string", - "format": "date-time" - }, - "uptimeSeconds": { - "type": "integer", - "minimum": 0 - } - } - }, - "SearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "id", - "object", - "query", - "results", - "meta", - "billing" - ], - "properties": { - "id": { - "type": "string" - }, - "object": { - "type": "string", - "const": "search.result" - }, - "query": { - "type": "string" - }, - "answer": { - "type": "string" - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchResult" - } - }, - "meta": { - "$ref": "#/components/schemas/SearchMeta" - }, - "billing": { - "$ref": "#/components/schemas/BillingInfo" - } - } - }, - "SearchResult": { - "type": "object", - "additionalProperties": false, - "required": [ - "rank", - "title", - "url", - "snippet", - "site", - "score" - ], - "properties": { - "rank": { - "type": "integer", - "minimum": 1 - }, - "title": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "site": { - "type": "string" - }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "publishedAt": { - "type": "string", - "format": "date-time" - } - } - }, - "NewsSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "id", - "object", - "query", - "results", - "meta", - "billing" - ], - "properties": { - "id": { - "type": "string" - }, - "object": { - "type": "string", - "const": "news.result" - }, - "query": { - "type": "string" - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NewsResult" - } - }, - "meta": { - "$ref": "#/components/schemas/SearchMeta" - }, - "billing": { - "$ref": "#/components/schemas/BillingInfo" - } - } - }, - "NewsResult": { - "type": "object", - "additionalProperties": false, - "required": [ - "rank", - "title", - "url", - "snippet", - "source", - "publishedAt", - "score" - ], - "properties": { - "rank": { - "type": "integer", - "minimum": 1 - }, - "title": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "source": { - "type": "string" - }, - "publishedAt": { - "type": "string", - "format": "date-time" - }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 - } - } - }, - "DeepSearchRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "minLength": 1, - "maxLength": 4000 - }, - "depth": { - "type": "string", - "enum": [ - "quick", - "standard", - "exhaustive" - ], - "default": "standard" - }, - "maxSources": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 12 - }, - "includeCitations": { - "type": "boolean", - "default": true - }, - "includeRawSnippets": { - "type": "boolean", - "default": false - }, - "focus": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "web", - "news", - "papers", - "forums", - "docs" - ] - }, - "minItems": 1, - "uniqueItems": true - }, - "timeRange": { - "$ref": "#/components/schemas/TimeRange" - } - } - }, - "DeepSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "id", - "object", - "query", - "depth", - "summary", - "sections", - "citations", - "meta", - "billing" - ], - "properties": { - "id": { - "type": "string" - }, - "object": { - "type": "string", - "const": "deep.result" - }, - "query": { - "type": "string" - }, - "depth": { - "type": "string", - "enum": [ - "quick", - "standard", - "exhaustive" - ] - }, - "summary": { - "type": "string" - }, - "sections": { - "type": " \ No newline at end of file + "description": "Base64-encoded x402 payment payload JSON. Required on paid requests after receiving a \ No newline at end of file From 2c9aec2e3766d616f1fa66e2f2bc51c651640280 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 15:59:22 +0000 Subject: [PATCH 03/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- openapi.json | 1162 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1162 insertions(+) create mode 100644 openapi.json diff --git a/openapi.json b/openapi.json new file mode 100644 index 0000000..32ed2de --- /dev/null +++ b/openapi.json @@ -0,0 +1,1162 @@ +{ + "openapi": "3.1.0", + "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", + "info": { + "title": "Queryx API", + "version": "1.0.0", + "summary": "Paid web, news, and deep research search API secured with x402 payments.", + "description": "Queryx provides low-latency web and news search plus deep research synthesis. Protected endpoints require an x402 payment envelope in the X-PAYMENT header. Payments are denominated in USDC base units on Base." + }, + "servers": [ + { + "url": "https://queryx.run", + "description": "Production" + } + ], + "tags": [ + { + "name": "search", + "description": "Web and news search operations." + }, + { + "name": "research", + "description": "Deep multi-source research with synthesis." + }, + { + "name": "system", + "description": "Service health and diagnostics." + } + ], + "paths": { + "/health": { + "get": { + "tags": [ + "system" + ], + "operationId": "getHealth", + "summary": "Health check", + "description": "Returns service health and runtime metadata.", + "security": [], + "responses": { + "200": { + "description": "Service is healthy.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HealthResponse" + }, + "examples": { + "ok": { + "value": { + "status": "ok", + "version": "1.4.2", + "uptime_s": 76432, + "timestamp": "2026-03-04T13:10:55Z" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v1/search": { + "get": { + "tags": [ + "search" + ], + "operationId": "searchWeb", + "summary": "Web search", + "description": "Performs real-time web search. Requires a valid x402 payment envelope.", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/QueryParam" + }, + { + "$ref": "#/components/parameters/LimitParam" + }, + { + "$ref": "#/components/parameters/CountryParam" + }, + { + "$ref": "#/components/parameters/LanguageParam" + }, + { + "$ref": "#/components/parameters/SafeSearchParam" + } + ], + "responses": { + "200": { + "description": "Search results returned.", + "headers": { + "X-RateLimit-Limit": { + "schema": { + "type": "integer" + }, + "description": "Requests allowed in the current 60-second window." + }, + "X-RateLimit-Remaining": { + "schema": { + "type": "integer" + }, + "description": "Requests remaining in the current window." + }, + "X-RateLimit-Reset": { + "schema": { + "type": "integer" + }, + "description": "Unix epoch seconds when rate-limit window resets." + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "examples": { + "basic": { + "value": { + "request_id": "req_01HTJ7A4CE7X2Q7R3A3X1M8S3K", + "query": "openapi 3.1 changelog", + "total_results": 1240000, + "latency_ms": 182, + "results": [ + { + "rank": 1, + "title": "OpenAPI Specification v3.1.0", + "url": "https://example.com/openapi-3-1", + "snippet": "The OpenAPI Specification 3.1 aligns with JSON Schema 2020-12.", + "source": "example.com", + "score": 0.98, + "published_at": "2025-12-01T09:00:00Z" + }, + { + "rank": 2, + "title": "What changed in OpenAPI 3.1", + "url": "https://example.org/oas31-diff", + "snippet": "A practical breakdown of OpenAPI 3.1 updates.", + "source": "example.org", + "score": 0.94, + "published_at": "2025-10-16T18:22:00Z" + } + ], + "cost": { + "endpoint": "/v1/search", + "amount_base_units": "1000", + "amount_display": "0.001", + "asset": "USDC", + "network": "base", + "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "x-codeSamples": [ + { + "lang": "curl", + "source": "curl -G \"https://queryx.run/v1/search\" \\\n --data-urlencode \"q=openapi 3.1 changelog\" \\\n --data-urlencode \"limit=5\" \\\n -H \"X-PAYMENT: .\"" + } + ] + } + }, + "/v1/search/news": { + "get": { + "tags": [ + "search" + ], + "operationId": "searchNews", + "summary": "News search", + "description": "Searches recent news sources with recency controls. Requires x402 payment.", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/QueryParam" + }, + { + "$ref": "#/components/parameters/LimitParam" + }, + { + "$ref": "#/components/parameters/CountryParam" + }, + { + "$ref": "#/components/parameters/LanguageParam" + }, + { + "$ref": "#/components/parameters/SinceDaysParam" + }, + { + "$ref": "#/components/parameters/SortByParam" + } + ], + "responses": { + "200": { + "description": "News search results returned.", + "headers": { + "X-RateLimit-Limit": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Reset": { + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NewsSearchResponse" + }, + "examples": { + "news": { + "value": { + "request_id": "req_01HTJ7M7SNG3F1W4R2HR8D6M8B", + "query": "ai regulation europe", + "total_results": 932, + "latency_ms": 246, + "results": [ + { + "rank": 1, + "title": "EU debates framework for foundation model audits", + "url": "https://news.example/eu-ai-audit", + "snippet": "Lawmakers discussed periodic risk reporting requirements.", + "source": "news.example", + "score": 0.96, + "published_at": "2026-03-03T16:31:00Z", + "outlet": "News Example", + "author": "N. Jensen" + } + ], + "cost": { + "endpoint": "/v1/search/news", + "amount_base_units": "2500", + "amount_display": "0.0025", + "asset": "USDC", + "network": "base", + "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "x-codeSamples": [ + { + "lang": "curl", + "source": "curl -G \"https://queryx.run/v1/search/news\" \\\n --data-urlencode \"q=ai regulation europe\" \\\n --data-urlencode \"since_days=3\" \\\n --data-urlencode \"limit=10\" \\\n -H \"X-PAYMENT: .\"" + } + ] + } + }, + "/v1/search/deep": { + "post": { + "tags": [ + "research" + ], + "operationId": "searchDeep", + "summary": "Deep research search", + "description": "Runs multi-step retrieval and synthesis with citations. Requires x402 payment.", + "security": [ + { + "x402": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchRequest" + }, + "examples": { + "standard": { + "value": { + "query": "Compare retrieval-augmented generation evaluation frameworks", + "max_results": 20, + "depth": "standard", + "include_answer": true, + "include_raw_content": false, + "time_range": { + "start": "2024-01-01", + "end": "2026-03-04" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Deep research response returned.", + "headers": { + "X-RateLimit-Limit": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Reset": { + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchResponse" + }, + "examples": { + "deep": { + "value": { + "request_id": "req_01HTJ7Z9F0D2D5FNT3N9KQ7F2W", + "query": "Compare retrieval-augmented generation evaluation frameworks", + "summary": "Most frameworks score retrieval quality, grounding faithfulness, and answer utility; benchmark portability and judge consistency remain the largest sources of variance.", + "confidence": 0.86, + "latency_ms": 3850, + "findings": [ + { + "title": "Metric overlap is high but weighting differs", + "insight": "Frameworks often share precision/recall style retrieval metrics but weight faithfulness checks differently.", + "evidence_level": "high", + "citations": [ + 0, + 2 + ] + }, + { + "title": "Judge model drift can alter rankings", + "insight": "LLM-as-judge scoring drift introduces temporal instability unless models are pinned.", + "evidence_level": "medium", + "citations": [ + 1 + ] + } + ], + "citations": [ + { + "id": 0, + "title": "Evaluation Patterns for RAG Systems", + "url": "https://research.example/rag-eval", + "source": "research.example", + "published_at": "2025-07-15T08:00:00Z" + }, + { + "id": 1, + "title": "LLM Judge Reliability in Practice", + "url": "https://lab.example/judge-reliability", + "source": "lab.example", + "published_at": "2026-01-05T12:30:00Z" + }, + { + "id": 2, + "title": "Grounding and Attribution Benchmarks", + "url": "https://bench.example/grounding", + "source": "bench.example", + "published_at": "2025-11-22T10:45:00Z" + } + ], + "cost": { + "endpoint": "/v1/search/deep", + "amount_base_units": "10000", + "amount_display": "0.01", + "asset": "USDC", + "network": "base", + "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "x-codeSamples": [ + { + "lang": "curl", + "source": "curl -X POST \"https://queryx.run/v1/search/deep\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PAYMENT: .\" \\\n -d '{\n \"query\": \"compare vector db indexing strategies\",\n \"max_results\": 15,\n \"depth\": \"standard\",\n \"include_answer\": true\n }'" + } + ] + } + } + }, + "components": { + "securitySchemes": { + "x402": { + "type": "apiKey", + "in": "header", + "name": "X-PAYMENT", + "description": "x402 signed payment envelope. Format: .. The payload includes quote_id, amount_base_units, payer, payee, nonce, timestamps, method, path, and body hash." + } + }, + "parameters": { + "QueryParam": { + "name": "q", + "in": "query", + "required": true, + "description": "Search query.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "openapi 3.1 changelog" + }, + "LimitParam": { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of results to return.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + }, + "example": 10 + }, + "CountryParam": { + "name": "country", + "in": "query", + "required": false, + "description": "Country code for market biasing (ISO 3166-1 alpha-2).", + "schema": { + "type": "string", + "pattern": "^[A-Z]{2}$", + "default": "US" + }, + "example": "US" + }, + "LanguageParam": { + "name": "language", + "in": "query", + "required": false, + "description": "Language code for search biasing (ISO 639-1).", + "schema": { + "type": "string", + "pattern": "^[a-z]{2}$", + "default": "en" + }, + "example": "en" + }, + "SafeSearchParam": { + "name": "safe_search", + "in": "query", + "required": false, + "description": "Safe-search level.", + "schema": { + "type": "string", + "enum": [ + "off", + "moderate", + "strict" + ], + "default": "moderate" + }, + "example": "moderate" + }, + "SinceDaysParam": { + "name": "since_days", + "in": "query", + "required": false, + "description": "Limit news results to the last N days.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 30, + "default": 7 + }, + "example": 3 + }, + "SortByParam": { + "name": "sort_by", + "in": "query", + "required": false, + "description": "News sort mode.", + "schema": { + "type": "string", + "enum": [ + "relevance", + "date" + ], + "default": "relevance" + }, + "example": "date" + } + }, + "responses": { + "PaymentRequired": { + "description": "x402 payment is required or existing quote/signature is invalid/expired.", + "headers": { + "X-PAYMENT-REQUIRED": { + "description": "Always true for this response.", + "schema": { + "type": "string", + "enum": [ + "true" + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "payment_required": { + "value": { + "error": { + "code": "payment_required", + "message": "Payment is required for this endpoint.", + "request_id": "req_01HTJA86S4J1Y1P7DHE66QY7TF", + "payment": { + "quote_id": "qt_5f7f7de9d2304f0dbcb2f0c2", + "network": "base", + "asset": "USDC", + "amount_base_units": "1000", + "amount_display": "0.001", + "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A", + "nonce": "2f6be0e38df14ec4a9e6294f2f0b9952", + "expires_at": "2026-03-04T13:12:00Z", + "signature_payload": "x402-1\nGET\n/v1/search?q=openapi%203.1%20changelog&limit=5\ne3b0c44298fc1c149afbf4c8996fb924\n1000\nUSDC\n0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A\n2f6be0e38df14ec4a9e6294f2f0b9952\n2026-03-04T13:11:00Z\n2026-03-04T13:12:00Z" + } + } + } + } + } + } + } + }, + "ValidationError": { + "description": "Request failed schema or parameter validation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "invalid_limit": { + "value": { + "error": { + "code": "validation_error", + "message": "Query parameters failed validation.", + "request_id": "req_01HTJACQ4PZ8D0WMY8CEN2C1DZ", + "details": { + "fields": [ + { + "field": "limit", + "message": "Must be <= 50." + } + ] + } + } + } + } + } + } + } + }, + "RateLimited": { + "description": "Rate limit exceeded.", + "headers": { + "Retry-After": { + "description": "Seconds until request can be retried.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "too_many_requests": { + "value": { + "error": { + "code": "rate_limited", + "message": "Rate limit exceeded. Retry later.", + "request_id": "req_01HTJAFR8C30GHQ8A8G3G0Q8H1", + "details": { + "retry_after_s": 12 + } + } + } + } + } + } + } + }, + "InternalServerError": { + "description": "Unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "internal_error": { + "value": { + "error": { + "code": "internal_error", + "message": "An unexpected error occurred.", + "request_id": "req_01HTJAH2RBGN4MNW6QK24E4M7Y" + } + } + } + } + } + } + } + }, + "schemas": { + "HealthResponse": { + "type": "object", + "required": [ + "status", + "version", + "uptime_s", + "timestamp" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "version": { + "type": "string" + }, + "uptime_s": { + "type": "integer", + "minimum": 0 + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "SearchResult": { + "type": "object", + "required": [ + "rank", + "title", + "url", + "snippet", + "source", + "score" + ], + "properties": { + "rank": { + "type": "integer", + "minimum": 1 + }, + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "source": { + "type": "string" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "published_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + }, + "additionalProperties": false + }, + "NewsResult": { + "allOf": [ + { + "$ref": "#/components/schemas/SearchResult" + }, + { + "type": "object", + "required": [ + "published_at" + ], + "properties": { + "outlet": { + "type": "string" + }, + "author": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": false + } + ] + }, + "Charge": { + "type": "object", + "required": [ + "endpoint", + "amount_base_units", + "amount_display", + "asset", + "network", + "facilitator_address" + ], + "properties": { + "endpoint": { + "type": "string" + }, + "amount_base_units": { + "type": "string", + "pattern": "^[0-9]+$" + }, + "amount_display": { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?$" + }, + "asset": { + "type": "string", + "enum": [ + "USDC" + ] + }, + "network": { + "type": "string", + "enum": [ + "base" + ] + }, + "facilitator_address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + } + }, + "additionalProperties": false + }, + "SearchResponse": { + "type": "object", + "required": [ + "request_id", + "query", + "total_results", + "latency_ms", + "results", + "cost" + ], + "properties": { + "request_id": { + "type": "string" + }, + "query": { + "type": "string" + }, + "total_results": { + "type": "integer", + "minimum": 0 + }, + "latency_ms": { + "type": "integer", + "minimum": 0 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } + }, + "cost": { + "$ref": "#/components/schemas/Charge" + } + }, + "additionalProperties": false + }, + "NewsSearchResponse": { + "type": "object", + "required": [ + "request_id", + "query", + "total_results", + "latency_ms", + "results", + "cost" + ], + "properties": { + "request_id": { + "type": "string" + }, + "query": { + "type": "string" + }, + "total_results": { + "type": "integer", + "minimum": 0 + }, + "latency_ms": { + "type": "integer", + "minimum": 0 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsResult" + } + }, + "cost": { + "$ref": "#/components/schemas/Charge" + } + }, + "additionalProperties": false + }, + "DeepSearchRequest": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "minLength": 3, + "maxLength": 2000 + }, + "max_results": { + "type": "integer", + "minimum": 5, + "maximum": 100, + "default": 20 + }, + "depth": { + "type": "string", + "enum": [ + "quick", + "standard", + "comprehensive" + ], + "default": "standard" + }, + "include_answer": { + "type": "boolean", + "default": true + }, + "include_raw_content": { + "type": "boolean", + "default": false + }, + "time_range": { + "type": "object", + "required": [ + "start", + "end" + ], + "properties": { + "start": { + "type": "string", + "format": "date" + }, + "end": { + "type": "string", + "format": "date" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }, + "Citation": { + "type": "object", + "required": [ + "id", + "title", + "url", + "source" + ], + "properties": { + "id": { + "type": "integer", + "minimum": 0 + }, + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "source": { + "type": "string" + }, + "published_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + }, + "additionalProperties": false + }, + "DeepFinding": { + "type": "object", + "required": [ + "title", + "insight", + "evidence_level", + "citations" + ], + "properties": { + "title": { + "type": "string" + }, + "insight": { + "type": "string" + }, + "evidence_level": { + "type": "string", + "enum": [ + "low", + "medium", + "high" + ] + }, + "citations": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + } + } + }, + "additionalProperties": false + }, + "DeepSearchResponse": { + "type": "object", + "required": [ + "request_id", + "query", + "summary", + "confidence", + "latency_ms", + "findings", + "citations", + "cost" + ], + "properties": { + "request_id": { + "type": "string" + }, + "query": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "latency_ms": { + "type": "integer", + "minimum": 0 + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeepFinding" + } + }, + "citations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Citation" + } + }, + "cost": { + "$ref": "#/components/schemas/Charge" + } + }, + "additionalProperties": false + }, + "PaymentQuote": { + "type": "object", + "required": [ + "quote_id", + "network", + "asset", + "amount_base_units", + "amount_display", + "facilitator_address", + "nonce", + "expires_at", + "signature_payload" + ], + "properties": { + "quote_id": { + "type": "string" + }, + "network": { + "type": "string", + "enum": [ + "base" + ] + }, + "asset": { + "type": "string", + "enum": [ + "USDC" + ] + }, + "amount_base_units": { + "type": "string", + "pattern": "^[0-9]+$" + }, + "amount_display": { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?$" + }, + "facilitator_address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + }, + "nonce": { + "type": "string" + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "signature_payload": { + "type": "string", + "description": "Canonical multiline payload to sign with payer wallet." + } + }, + "additionalProperties": false + }, + "ErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "object", + "required": [ + "code", + "message" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "payment_required", + "validation_error", + "rate_limited", + "internal_error" + ] + }, + "message": { + "type": "string" + }, + "request_id": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": true + }, + "payment": { + "$ref": "#/components/schemas/PaymentQuote" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + } + } +} \ No newline at end of file From f340f129650bf707a201a2c5893af623a6b26346 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:05:16 +0000 Subject: [PATCH 04/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- openapi.json | 1930 +++++++++++++++++++++++++++----------------------- 1 file changed, 1042 insertions(+), 888 deletions(-) diff --git a/openapi.json b/openapi.json index 32ed2de..c0a78a1 100644 --- a/openapi.json +++ b/openapi.json @@ -1,11 +1,11 @@ { "openapi": "3.1.0", - "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", "version": "1.0.0", - "summary": "Paid web, news, and deep research search API secured with x402 payments.", - "description": "Queryx provides low-latency web and news search plus deep research synthesis. Protected endpoints require an x402 payment envelope in the X-PAYMENT header. Payments are denominated in USDC base units on Base." + "summary": "x402-metered web and research search API", + "description": "Queryx provides metered search endpoints secured with x402 payments on Base USDC." }, "servers": [ { @@ -15,501 +15,116 @@ ], "tags": [ { - "name": "search", - "description": "Web and news search operations." + "name": "health", + "description": "Service health and readiness" }, { - "name": "research", - "description": "Deep multi-source research with synthesis." + "name": "search", + "description": "Web and news search endpoints" }, { - "name": "system", - "description": "Service health and diagnostics." + "name": "research", + "description": "Deep research endpoint" } ], - "paths": { - "/health": { - "get": { - "tags": [ - "system" - ], - "operationId": "getHealth", - "summary": "Health check", - "description": "Returns service health and runtime metadata.", - "security": [], - "responses": { - "200": { - "description": "Service is healthy.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HealthResponse" - }, - "examples": { - "ok": { - "value": { - "status": "ok", - "version": "1.4.2", - "uptime_s": 76432, - "timestamp": "2026-03-04T13:10:55Z" - } - } - } - } - } - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - } - } - }, - "/v1/search": { - "get": { - "tags": [ - "search" - ], - "operationId": "searchWeb", - "summary": "Web search", - "description": "Performs real-time web search. Requires a valid x402 payment envelope.", - "security": [ - { - "x402": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/QueryParam" - }, - { - "$ref": "#/components/parameters/LimitParam" - }, - { - "$ref": "#/components/parameters/CountryParam" - }, - { - "$ref": "#/components/parameters/LanguageParam" - }, - { - "$ref": "#/components/parameters/SafeSearchParam" - } - ], - "responses": { - "200": { - "description": "Search results returned.", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer" - }, - "description": "Requests allowed in the current 60-second window." - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer" - }, - "description": "Requests remaining in the current window." - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer" - }, - "description": "Unix epoch seconds when rate-limit window resets." - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchResponse" - }, - "examples": { - "basic": { - "value": { - "request_id": "req_01HTJ7A4CE7X2Q7R3A3X1M8S3K", - "query": "openapi 3.1 changelog", - "total_results": 1240000, - "latency_ms": 182, - "results": [ - { - "rank": 1, - "title": "OpenAPI Specification v3.1.0", - "url": "https://example.com/openapi-3-1", - "snippet": "The OpenAPI Specification 3.1 aligns with JSON Schema 2020-12.", - "source": "example.com", - "score": 0.98, - "published_at": "2025-12-01T09:00:00Z" - }, - { - "rank": 2, - "title": "What changed in OpenAPI 3.1", - "url": "https://example.org/oas31-diff", - "snippet": "A practical breakdown of OpenAPI 3.1 updates.", - "source": "example.org", - "score": 0.94, - "published_at": "2025-10-16T18:22:00Z" - } - ], - "cost": { - "endpoint": "/v1/search", - "amount_base_units": "1000", - "amount_display": "0.001", - "asset": "USDC", - "network": "base", - "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A" - } - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/PaymentRequired" - }, - "422": { - "$ref": "#/components/responses/ValidationError" - }, - "429": { - "$ref": "#/components/responses/RateLimited" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - }, - "x-codeSamples": [ - { - "lang": "curl", - "source": "curl -G \"https://queryx.run/v1/search\" \\\n --data-urlencode \"q=openapi 3.1 changelog\" \\\n --data-urlencode \"limit=5\" \\\n -H \"X-PAYMENT: .\"" - } - ] - } - }, - "/v1/search/news": { - "get": { - "tags": [ - "search" - ], - "operationId": "searchNews", - "summary": "News search", - "description": "Searches recent news sources with recency controls. Requires x402 payment.", - "security": [ - { - "x402": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/QueryParam" - }, - { - "$ref": "#/components/parameters/LimitParam" - }, - { - "$ref": "#/components/parameters/CountryParam" - }, - { - "$ref": "#/components/parameters/LanguageParam" - }, - { - "$ref": "#/components/parameters/SinceDaysParam" - }, - { - "$ref": "#/components/parameters/SortByParam" - } - ], - "responses": { - "200": { - "description": "News search results returned.", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewsSearchResponse" - }, - "examples": { - "news": { - "value": { - "request_id": "req_01HTJ7M7SNG3F1W4R2HR8D6M8B", - "query": "ai regulation europe", - "total_results": 932, - "latency_ms": 246, - "results": [ - { - "rank": 1, - "title": "EU debates framework for foundation model audits", - "url": "https://news.example/eu-ai-audit", - "snippet": "Lawmakers discussed periodic risk reporting requirements.", - "source": "news.example", - "score": 0.96, - "published_at": "2026-03-03T16:31:00Z", - "outlet": "News Example", - "author": "N. Jensen" - } - ], - "cost": { - "endpoint": "/v1/search/news", - "amount_base_units": "2500", - "amount_display": "0.0025", - "asset": "USDC", - "network": "base", - "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A" - } - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/PaymentRequired" - }, - "422": { - "$ref": "#/components/responses/ValidationError" - }, - "429": { - "$ref": "#/components/responses/RateLimited" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - }, - "x-codeSamples": [ - { - "lang": "curl", - "source": "curl -G \"https://queryx.run/v1/search/news\" \\\n --data-urlencode \"q=ai regulation europe\" \\\n --data-urlencode \"since_days=3\" \\\n --data-urlencode \"limit=10\" \\\n -H \"X-PAYMENT: .\"" - } - ] - } - }, - "/v1/search/deep": { - "post": { - "tags": [ - "research" - ], - "operationId": "searchDeep", - "summary": "Deep research search", - "description": "Runs multi-step retrieval and synthesis with citations. Requires x402 payment.", - "security": [ - { - "x402": [] - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeepSearchRequest" - }, - "examples": { - "standard": { - "value": { - "query": "Compare retrieval-augmented generation evaluation frameworks", - "max_results": 20, - "depth": "standard", - "include_answer": true, - "include_raw_content": false, - "time_range": { - "start": "2024-01-01", - "end": "2026-03-04" - } - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Deep research response returned.", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeepSearchResponse" - }, - "examples": { - "deep": { - "value": { - "request_id": "req_01HTJ7Z9F0D2D5FNT3N9KQ7F2W", - "query": "Compare retrieval-augmented generation evaluation frameworks", - "summary": "Most frameworks score retrieval quality, grounding faithfulness, and answer utility; benchmark portability and judge consistency remain the largest sources of variance.", - "confidence": 0.86, - "latency_ms": 3850, - "findings": [ - { - "title": "Metric overlap is high but weighting differs", - "insight": "Frameworks often share precision/recall style retrieval metrics but weight faithfulness checks differently.", - "evidence_level": "high", - "citations": [ - 0, - 2 - ] - }, - { - "title": "Judge model drift can alter rankings", - "insight": "LLM-as-judge scoring drift introduces temporal instability unless models are pinned.", - "evidence_level": "medium", - "citations": [ - 1 - ] - } - ], - "citations": [ - { - "id": 0, - "title": "Evaluation Patterns for RAG Systems", - "url": "https://research.example/rag-eval", - "source": "research.example", - "published_at": "2025-07-15T08:00:00Z" - }, - { - "id": 1, - "title": "LLM Judge Reliability in Practice", - "url": "https://lab.example/judge-reliability", - "source": "lab.example", - "published_at": "2026-01-05T12:30:00Z" - }, - { - "id": 2, - "title": "Grounding and Attribution Benchmarks", - "url": "https://bench.example/grounding", - "source": "bench.example", - "published_at": "2025-11-22T10:45:00Z" - } - ], - "cost": { - "endpoint": "/v1/search/deep", - "amount_base_units": "10000", - "amount_display": "0.01", - "asset": "USDC", - "network": "base", - "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A" - } - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/PaymentRequired" - }, - "422": { - "$ref": "#/components/responses/ValidationError" - }, - "429": { - "$ref": "#/components/responses/RateLimited" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - }, - "x-codeSamples": [ - { - "lang": "curl", - "source": "curl -X POST \"https://queryx.run/v1/search/deep\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PAYMENT: .\" \\\n -d '{\n \"query\": \"compare vector db indexing strategies\",\n \"max_results\": 15,\n \"depth\": \"standard\",\n \"include_answer\": true\n }'" - } - ] - } - } - }, "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", - "name": "X-PAYMENT", - "description": "x402 signed payment envelope. Format: .. The payload includes quote_id, amount_base_units, payer, payee, nonce, timestamps, method, path, and body hash." + "name": "X-402-Payment", + "description": "x402 payment envelope. For paid retries this is a base64url-encoded JSON object containing quote and payer metadata." } }, "parameters": { - "QueryParam": { + "q": { "name": "q", "in": "query", "required": true, - "description": "Search query.", + "description": "Natural-language search query.", "schema": { "type": "string", "minLength": 1, - "maxLength": 512 + "maxLength": 1024 }, - "example": "openapi 3.1 changelog" + "examples": { + "basic": { + "value": "best LLM eval frameworks" + } + } }, - "LimitParam": { + "limit": { "name": "limit", "in": "query", "required": false, - "description": "Maximum number of results to return.", + "description": "Maximum number of results.", "schema": { "type": "integer", "minimum": 1, - "maximum": 50, - "default": 10 + "maximum": 20, + "default": 8 }, - "example": 10 + "examples": { + "default": { + "value": 8 + } + } }, - "CountryParam": { - "name": "country", + "offset": { + "name": "offset", "in": "query", "required": false, - "description": "Country code for market biasing (ISO 3166-1 alpha-2).", + "description": "Zero-based pagination offset.", "schema": { - "type": "string", - "pattern": "^[A-Z]{2}$", - "default": "US" + "type": "integer", + "minimum": 0, + "maximum": 200, + "default": 0 }, - "example": "US" + "examples": { + "firstPage": { + "value": 0 + } + } }, - "LanguageParam": { - "name": "language", + "lang": { + "name": "lang", "in": "query", "required": false, - "description": "Language code for search biasing (ISO 639-1).", + "description": "Language hint (ISO-like code).", "schema": { "type": "string", - "pattern": "^[a-z]{2}$", + "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "default": "en" }, - "example": "en" + "examples": { + "english": { + "value": "en" + } + } }, - "SafeSearchParam": { - "name": "safe_search", + "region": { + "name": "region", "in": "query", "required": false, - "description": "Safe-search level.", + "description": "Region/country hint for ranking.", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 8, + "default": "US" + }, + "examples": { + "us": { + "value": "US" + } + } + }, + "safe": { + "name": "safe", + "in": "query", + "required": false, + "description": "Safety filter level.", "schema": { "type": "string", "enum": [ @@ -519,26 +134,39 @@ ], "default": "moderate" }, - "example": "moderate" + "examples": { + "moderate": { + "value": "moderate" + } + } }, - "SinceDaysParam": { - "name": "since_days", + "freshness": { + "name": "freshness", "in": "query", "required": false, - "description": "Limit news results to the last N days.", + "description": "Freshness window used for ranking.", "schema": { - "type": "integer", - "minimum": 1, - "maximum": 30, - "default": 7 + "type": "string", + "enum": [ + "any", + "day", + "week", + "month", + "year" + ], + "default": "any" }, - "example": 3 + "examples": { + "week": { + "value": "week" + } + } }, - "SortByParam": { - "name": "sort_by", + "newsSort": { + "name": "sort", "in": "query", "required": false, - "description": "News sort mode.", + "description": "Sort strategy for news results.", "schema": { "type": "string", "enum": [ @@ -547,145 +175,83 @@ ], "default": "relevance" }, - "example": "date" - } - }, - "responses": { - "PaymentRequired": { - "description": "x402 payment is required or existing quote/signature is invalid/expired.", - "headers": { - "X-PAYMENT-REQUIRED": { - "description": "Always true for this response.", - "schema": { - "type": "string", - "enum": [ - "true" - ] - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "payment_required": { - "value": { - "error": { - "code": "payment_required", - "message": "Payment is required for this endpoint.", - "request_id": "req_01HTJA86S4J1Y1P7DHE66QY7TF", - "payment": { - "quote_id": "qt_5f7f7de9d2304f0dbcb2f0c2", - "network": "base", - "asset": "USDC", - "amount_base_units": "1000", - "amount_display": "0.001", - "facilitator_address": "0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A", - "nonce": "2f6be0e38df14ec4a9e6294f2f0b9952", - "expires_at": "2026-03-04T13:12:00Z", - "signature_payload": "x402-1\nGET\n/v1/search?q=openapi%203.1%20changelog&limit=5\ne3b0c44298fc1c149afbf4c8996fb924\n1000\nUSDC\n0x6F6f4f3B4D9f02E6a4e7Bc0f7E0A372bD2D6f52A\n2f6be0e38df14ec4a9e6294f2f0b9952\n2026-03-04T13:11:00Z\n2026-03-04T13:12:00Z" - } - } - } - } - } + "examples": { + "date": { + "value": "date" } } }, - "ValidationError": { - "description": "Request failed schema or parameter validation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "invalid_limit": { - "value": { - "error": { - "code": "validation_error", - "message": "Query parameters failed validation.", - "request_id": "req_01HTJACQ4PZ8D0WMY8CEN2C1DZ", - "details": { - "fields": [ - { - "field": "limit", - "message": "Must be <= 50." - } - ] - } - } - } - } - } + "fromDate": { + "name": "from", + "in": "query", + "required": false, + "description": "Lower bound publication date (inclusive).", + "schema": { + "type": "string", + "format": "date" + }, + "examples": { + "from": { + "value": "2026-02-01" } } }, - "RateLimited": { - "description": "Rate limit exceeded.", - "headers": { - "Retry-After": { - "description": "Seconds until request can be retried.", - "schema": { - "type": "integer", - "minimum": 1 - } - } + "toDate": { + "name": "to", + "in": "query", + "required": false, + "description": "Upper bound publication date (inclusive).", + "schema": { + "type": "string", + "format": "date" }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "too_many_requests": { - "value": { - "error": { - "code": "rate_limited", - "message": "Rate limit exceeded. Retry later.", - "request_id": "req_01HTJAFR8C30GHQ8A8G3G0Q8H1", - "details": { - "retry_after_s": 12 - } - } - } - } - } + "examples": { + "to": { + "value": "2026-03-04" } } }, - "InternalServerError": { - "description": "Unexpected server error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internal_error": { - "value": { - "error": { - "code": "internal_error", - "message": "An unexpected error occurred.", - "request_id": "req_01HTJAH2RBGN4MNW6QK24E4M7Y" - } - } - } - } - } + "x402AddressHeader": { + "name": "X-402-Address", + "in": "header", + "required": false, + "description": "Payer wallet address on Base.", + "schema": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + } + }, + "x402TimestampHeader": { + "name": "X-402-Timestamp", + "in": "header", + "required": false, + "description": "Unix epoch timestamp in seconds used in the signature payload.", + "schema": { + "type": "integer", + "minimum": 0 + } + }, + "x402SignatureHeader": { + "name": "X-402-Signature", + "in": "header", + "required": false, + "description": "Signature of canonical x402 string (EIP-191 personal_sign).", + "schema": { + "type": "string", + "minLength": 40 } } }, "schemas": { "HealthResponse": { "type": "object", + "additionalProperties": false, "required": [ "status", + "service", "version", - "uptime_s", - "timestamp" + "timestamp", + "uptime_seconds" ], "properties": { "status": { @@ -694,24 +260,68 @@ "ok" ] }, - "version": { - "type": "string" + "service": { + "type": "string", + "example": "queryx-api" }, - "uptime_s": { - "type": "integer", - "minimum": 0 + "version": { + "type": "string", + "example": "1.0.0" }, "timestamp": { "type": "string", "format": "date-time" + }, + "uptime_seconds": { + "type": "number", + "minimum": 0 } - }, - "additionalProperties": false + } + }, + "Usage": { + "type": "object", + "additionalProperties": false, + "required": [ + "endpoint", + "cost_base_units", + "cost_usdc", + "rate_limit_limit", + "rate_limit_remaining", + "rate_limit_reset_seconds" + ], + "properties": { + "endpoint": { + "type": "string", + "example": "/v1/search" + }, + "cost_base_units": { + "type": "integer", + "minimum": 0, + "description": "USDC base units where 1 USDC = 1,000,000 base units." + }, + "cost_usdc": { + "type": "string", + "pattern": "^\\d+(\\.\\d{1,6})?$", + "example": "0.025" + }, + "rate_limit_limit": { + "type": "integer", + "minimum": 1 + }, + "rate_limit_remaining": { + "type": "integer", + "minimum": 0 + }, + "rate_limit_reset_seconds": { + "type": "integer", + "minimum": 0 + } + } }, "SearchResult": { "type": "object", + "additionalProperties": false, "required": [ - "rank", "title", "url", "snippet", @@ -719,10 +329,38 @@ "score" ], "properties": { - "rank": { - "type": "integer", - "minimum": 1 + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" }, + "source": { + "type": "string" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "NewsResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "title", + "url", + "snippet", + "source", + "score", + "published_at" + ], + "properties": { "title": { "type": "string" }, @@ -742,90 +380,202 @@ "maximum": 1 }, "published_at": { - "type": [ - "string", - "null" - ], + "type": "string", "format": "date-time" + }, + "image_url": { + "type": "string", + "format": "uri" } - }, - "additionalProperties": false + } }, - "NewsResult": { - "allOf": [ - { - "$ref": "#/components/schemas/SearchResult" + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "query", + "type", + "results", + "latency_ms", + "usage" + ], + "properties": { + "request_id": { + "type": "string", + "example": "req_01JNF89R6G3H2EA0R9N81A8NKT" }, - { - "type": "object", - "required": [ - "published_at" - ], - "properties": { - "outlet": { - "type": "string" - }, - "author": { - "type": [ - "string", - "null" - ] - } - }, - "additionalProperties": false + "query": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "web" + ] + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } + }, + "latency_ms": { + "type": "integer", + "minimum": 1 + }, + "usage": { + "$ref": "#/components/schemas/Usage" } - ] + } }, - "Charge": { + "NewsSearchResponse": { "type": "object", + "additionalProperties": false, "required": [ - "endpoint", - "amount_base_units", - "amount_display", - "asset", - "network", - "facilitator_address" + "request_id", + "query", + "type", + "results", + "latency_ms", + "usage" ], "properties": { - "endpoint": { + "request_id": { + "type": "string", + "example": "req_01JNF8A2NKVK9W8AB6A2RQ8C4S" + }, + "query": { "type": "string" }, - "amount_base_units": { + "type": { + "type": "string", + "enum": [ + "news" + ] + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsResult" + } + }, + "latency_ms": { + "type": "integer", + "minimum": 1 + }, + "usage": { + "$ref": "#/components/schemas/Usage" + } + } + }, + "DeepSearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "max_sources": { + "type": "integer", + "minimum": 3, + "maximum": 40, + "default": 12 + }, + "include_domains": { + "type": "array", + "maxItems": 50, + "items": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + }, + "exclude_domains": { + "type": "array", + "maxItems": 50, + "items": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + }, + "lang": { "type": "string", - "pattern": "^[0-9]+$" + "pattern": "^[a-z]{2}(-[A-Z]{2})?$", + "default": "en" }, - "amount_display": { + "region": { "type": "string", - "pattern": "^[0-9]+(\\.[0-9]+)?$" + "default": "US" }, - "asset": { + "safe": { "type": "string", "enum": [ - "USDC" - ] + "off", + "moderate", + "strict" + ], + "default": "moderate" }, - "network": { + "reasoning_depth": { "type": "string", "enum": [ - "base" - ] + "standard", + "high" + ], + "default": "standard" + } + } + }, + "DeepSource": { + "type": "object", + "additionalProperties": false, + "required": [ + "title", + "url", + "snippet", + "source", + "relevance" + ], + "properties": { + "title": { + "type": "string" }, - "facilitator_address": { + "url": { "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$" + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "source": { + "type": "string" + }, + "relevance": { + "type": "number", + "minimum": 0, + "maximum": 1 } - }, - "additionalProperties": false + } }, - "SearchResponse": { + "DeepSearchResponse": { "type": "object", + "additionalProperties": false, "required": [ "request_id", "query", - "total_results", + "summary", + "answer", + "key_points", + "sources", "latency_ms", - "results", - "cost" + "usage" ], "properties": { "request_id": { @@ -834,328 +584,732 @@ "query": { "type": "string" }, - "total_results": { - "type": "integer", - "minimum": 0 + "summary": { + "type": "string" }, - "latency_ms": { - "type": "integer", - "minimum": 0 + "answer": { + "type": "string" }, - "results": { + "key_points": { "type": "array", "items": { - "$ref": "#/components/schemas/SearchResult" + "type": "string" + } + }, + "sources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeepSource" } }, - "cost": { - "$ref": "#/components/schemas/Charge" + "latency_ms": { + "type": "integer", + "minimum": 1 + }, + "usage": { + "$ref": "#/components/schemas/Usage" } - }, - "additionalProperties": false + } }, - "NewsSearchResponse": { + "ErrorDetail": { "type": "object", + "additionalProperties": false, "required": [ - "request_id", - "query", - "total_results", - "latency_ms", - "results", - "cost" + "code", + "message" ], "properties": { - "request_id": { - "type": "string" + "code": { + "type": "string", + "enum": [ + "payment_required", + "validation_error", + "rate_limited", + "internal_error" + ] }, - "query": { + "message": { "type": "string" }, - "total_results": { - "type": "integer", - "minimum": 0 + "request_id": { + "type": "string" }, - "latency_ms": { + "retry_after_seconds": { "type": "integer", "minimum": 0 }, - "results": { + "invalid_fields": { "type": "array", "items": { - "$ref": "#/components/schemas/NewsResult" + "type": "object", + "additionalProperties": false, + "required": [ + "field", + "reason" + ], + "properties": { + "field": { + "type": "string" + }, + "reason": { + "type": "string" + } + } } - }, - "cost": { - "$ref": "#/components/schemas/Charge" } - }, - "additionalProperties": false + } }, - "DeepSearchRequest": { + "PaymentRequirement": { "type": "object", + "additionalProperties": false, "required": [ - "query" + "network", + "chain_id", + "asset", + "amount_base_units", + "amount", + "payment_id", + "facilitator", + "expires_at", + "signature_payload" ], "properties": { - "query": { + "network": { "type": "string", - "minLength": 3, - "maxLength": 2000 + "example": "base" }, - "max_results": { + "chain_id": { "type": "integer", - "minimum": 5, - "maximum": 100, - "default": 20 + "example": 8453 }, - "depth": { + "asset": { "type": "string", - "enum": [ - "quick", - "standard", - "comprehensive" - ], - "default": "standard" + "example": "USDC" + }, + "amount_base_units": { + "type": "integer", + "minimum": 1, + "example": 25000 + }, + "amount": { + "type": "string", + "pattern": "^\\d+(\\.\\d{1,6})?$", + "example": "0.025" + }, + "payment_id": { + "type": "string", + "example": "pay_01JNF8C2KQ43P4FQRTQ6BRWWA8" }, - "include_answer": { - "type": "boolean", - "default": true + "facilitator": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "example": "0x6c7ad4e1bfa9c20e4a9e0467fd20170d1aa05c11" }, - "include_raw_content": { - "type": "boolean", - "default": false + "expires_at": { + "type": "string", + "format": "date-time" }, - "time_range": { + "signature_payload": { "type": "object", + "additionalProperties": false, "required": [ - "start", - "end" + "version", + "scheme", + "message" ], "properties": { - "start": { + "version": { + "type": "string", + "example": "QUERYX-X402-V1" + }, + "scheme": { "type": "string", - "format": "date" + "example": "eip191" }, - "end": { + "message": { "type": "string", - "format": "date" + "description": "Canonical string to sign with payer wallet key." } - }, - "additionalProperties": false + } } - }, - "additionalProperties": false + } }, - "Citation": { + "ErrorResponse": { "type": "object", + "additionalProperties": false, "required": [ - "id", - "title", - "url", - "source" + "error" ], "properties": { - "id": { - "type": "integer", - "minimum": 0 + "error": { + "$ref": "#/components/schemas/ErrorDetail" }, - "title": { - "type": "string" + "payment": { + "$ref": "#/components/schemas/PaymentRequirement" + } + } + } + }, + "responses": { + "PaymentRequired": { + "description": "x402 payment required before request can be processed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "paymentRequired": { + "value": { + "error": { + "code": "payment_required", + "message": "x402 payment is required for this endpoint.", + "request_id": "req_01JNF8D7F4FB7CV0W5XKQ6QCMF" + }, + "payment": { + "network": "base", + "chain_id": 8453, + "asset": "USDC", + "amount_base_units": 25000, + "amount": "0.025", + "payment_id": "pay_01JNF8C2KQ43P4FQRTQ6BRWWA8", + "facilitator": "0x6c7ad4e1bfa9c20e4a9e0467fd20170d1aa05c11", + "expires_at": "2026-03-04T12:00:00Z", + "signature_payload": { + "version": "QUERYX-X402-V1", + "scheme": "eip191", + "message": "QUERYX-X402-V1\nGET\n/v1/search?q=best+LLM+eval+frameworks&limit=3\n47DEQpj8HBSa__TImW-5JCeuQeRkm5NMpJWZG3hSuFU\npay_01JNF8C2KQ43P4FQRTQ6BRWWA8\n25000\nUSDC\nbase\n8453\n1709558400" + } + } + } + } + } + } + } + }, + "ValidationError": { + "description": "Input failed validation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "validation": { + "value": { + "error": { + "code": "validation_error", + "message": "Validation failed for query parameters.", + "request_id": "req_01JNF8E15N4MZV34H1N0NTHTW4", + "invalid_fields": [ + { + "field": "limit", + "reason": "must be less than or equal to 20" + } + ] + } + } + } + } + } + } + }, + "RateLimitError": { + "description": "Rate limit exceeded.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "rateLimit": { + "value": { + "error": { + "code": "rate_limited", + "message": "Too many requests.", + "request_id": "req_01JNF8ET3Q6R6PE7Q3SEFBRM9H", + "retry_after_seconds": 12 + } + } + } + } + } + } + }, + "InternalServerError": { + "description": "Unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "internal": { + "value": { + "error": { + "code": "internal_error", + "message": "Unexpected internal error.", + "request_id": "req_01JNF8FRQ28CG3YSA9NQXJ61AQ" + } + } + } + } + } + } + } + } + }, + "paths": { + "/health": { + "get": { + "tags": [ + "health" + ], + "summary": "Health check", + "operationId": "getHealth", + "security": [], + "responses": { + "200": { + "description": "Service is healthy.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HealthResponse" + }, + "examples": { + "ok": { + "value": { + "status": "ok", + "service": "queryx-api", + "version": "1.0.0", + "timestamp": "2026-03-04T10:15:30Z", + "uptime_seconds": 91324.12 + } + } + } + } + } }, - "url": { - "type": "string", - "format": "uri" + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v1/search": { + "get": { + "tags": [ + "search" + ], + "summary": "Web search", + "description": "Low-latency web search endpoint billed per request with x402.", + "operationId": "searchWeb", + "security": [ + { + "x402": [] + } + ], + "x-pricing": { + "asset": "USDC", + "base_units": 25000, + "human_readable": "0.025", + "network": "base" + }, + "x-rate-limits": { + "requests_per_minute": 120 + }, + "parameters": [ + { + "$ref": "#/components/parameters/q" }, - "source": { - "type": "string" + { + "$ref": "#/components/parameters/limit" }, - "published_at": { - "type": [ - "string", - "null" - ], - "format": "date-time" + { + "$ref": "#/components/parameters/offset" + }, + { + "$ref": "#/components/parameters/lang" + }, + { + "$ref": "#/components/parameters/region" + }, + { + "$ref": "#/components/parameters/safe" + }, + { + "$ref": "#/components/parameters/freshness" + }, + { + "$ref": "#/components/parameters/x402AddressHeader" + }, + { + "$ref": "#/components/parameters/x402TimestampHeader" + }, + { + "$ref": "#/components/parameters/x402SignatureHeader" } - }, - "additionalProperties": false - }, - "DeepFinding": { - "type": "object", - "required": [ - "title", - "insight", - "evidence_level", - "citations" ], - "properties": { - "title": { - "type": "string" + "responses": { + "200": { + "description": "Search results.", + "headers": { + "X-RateLimit-Limit": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Reset": { + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "examples": { + "webResults": { + "value": { + "request_id": "req_01JNF89R6G3H2EA0R9N81A8NKT", + "query": "best LLM eval frameworks", + "type": "web", + "results": [ + { + "title": "LLM Evaluation Methods", + "url": "https://queryx.run/example/llm-eval-methods", + "snippet": "A practical guide to automated and human-in-the-loop LLM evaluation.", + "source": "Queryx Demo", + "score": 0.94 + }, + { + "title": "Benchmarking LLM Systems", + "url": "https://queryx.run/example/benchmarking-llms", + "snippet": "Coverage of retrieval-aware benchmarks and rubric scoring.", + "source": "Queryx Demo", + "score": 0.91 + } + ], + "latency_ms": 388, + "usage": { + "endpoint": "/v1/search", + "cost_base_units": 25000, + "cost_usdc": "0.025", + "rate_limit_limit": 120, + "rate_limit_remaining": 119, + "rate_limit_reset_seconds": 60 + } + } + } + } + } + } }, - "insight": { - "type": "string" + "402": { + "$ref": "#/components/responses/PaymentRequired" }, - "evidence_level": { - "type": "string", - "enum": [ - "low", - "medium", - "high" - ] + "422": { + "$ref": "#/components/responses/ValidationError" }, - "citations": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - } + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" } - }, - "additionalProperties": false - }, - "DeepSearchResponse": { - "type": "object", - "required": [ - "request_id", - "query", - "summary", - "confidence", - "latency_ms", - "findings", - "citations", - "cost" + } + } + }, + "/v1/search/news": { + "get": { + "tags": [ + "search" ], - "properties": { - "request_id": { - "type": "string" + "summary": "News search", + "description": "News-focused search endpoint with optional date filtering, billed with x402.", + "operationId": "searchNews", + "security": [ + { + "x402": [] + } + ], + "x-pricing": { + "asset": "USDC", + "base_units": 35000, + "human_readable": "0.035", + "network": "base" + }, + "x-rate-limits": { + "requests_per_minute": 90 + }, + "parameters": [ + { + "$ref": "#/components/parameters/q" }, - "query": { - "type": "string" + { + "$ref": "#/components/parameters/limit" }, - "summary": { - "type": "string" + { + "$ref": "#/components/parameters/offset" }, - "confidence": { - "type": "number", - "minimum": 0, - "maximum": 1 + { + "$ref": "#/components/parameters/lang" }, - "latency_ms": { - "type": "integer", - "minimum": 0 + { + "$ref": "#/components/parameters/region" }, - "findings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DeepFinding" - } + { + "$ref": "#/components/parameters/safe" }, - "citations": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Citation" - } + { + "$ref": "#/components/parameters/newsSort" }, - "cost": { - "$ref": "#/components/schemas/Charge" - } - }, - "additionalProperties": false - }, - "PaymentQuote": { - "type": "object", - "required": [ - "quote_id", - "network", - "asset", - "amount_base_units", - "amount_display", - "facilitator_address", - "nonce", - "expires_at", - "signature_payload" - ], - "properties": { - "quote_id": { - "type": "string" + { + "$ref": "#/components/parameters/fromDate" }, - "network": { - "type": "string", - "enum": [ - "base" - ] + { + "$ref": "#/components/parameters/toDate" }, - "asset": { - "type": "string", - "enum": [ - "USDC" - ] + { + "$ref": "#/components/parameters/x402AddressHeader" }, - "amount_base_units": { - "type": "string", - "pattern": "^[0-9]+$" + { + "$ref": "#/components/parameters/x402TimestampHeader" }, - "amount_display": { - "type": "string", - "pattern": "^[0-9]+(\\.[0-9]+)?$" + { + "$ref": "#/components/parameters/x402SignatureHeader" + } + ], + "responses": { + "200": { + "description": "News results.", + "headers": { + "X-RateLimit-Limit": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Reset": { + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NewsSearchResponse" + }, + "examples": { + "newsResults": { + "value": { + "request_id": "req_01JNF8A2NKVK9W8AB6A2RQ8C4S", + "query": "ai chip funding rounds", + "type": "news", + "results": [ + { + "title": "AI Chip Startup Raises New Round", + "url": "https://queryx.run/example/ai-chip-round", + "snippet": "The company announced an oversubscribed round led by strategic investors.", + "source": "Queryx Newswire", + "score": 0.97, + "published_at": "2026-03-03T14:10:00Z", + "image_url": "https://queryx.run/example/images/ai-chip-round.jpg" + } + ], + "latency_ms": 442, + "usage": { + "endpoint": "/v1/search/news", + "cost_base_units": 35000, + "cost_usdc": "0.035", + "rate_limit_limit": 90, + "rate_limit_remaining": 89, + "rate_limit_reset_seconds": 60 + } + } + } + } + } + } }, - "facilitator_address": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$" + "402": { + "$ref": "#/components/responses/PaymentRequired" }, - "nonce": { - "type": "string" + "422": { + "$ref": "#/components/responses/ValidationError" }, - "expires_at": { - "type": "string", - "format": "date-time" + "429": { + "$ref": "#/components/responses/RateLimitError" }, - "signature_payload": { - "type": "string", - "description": "Canonical multiline payload to sign with payer wallet." + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v1/search/deep": { + "post": { + "tags": [ + "research" + ], + "summary": "Deep research search", + "description": "Multi-source deep research with synthesis and citations, billed with x402.", + "operationId": "searchDeep", + "security": [ + { + "x402": [] } + ], + "x-pricing": { + "asset": "USDC", + "base_units": 125000, + "human_readable": "0.125", + "network": "base" }, - "additionalProperties": false - }, - "ErrorResponse": { - "type": "object", - "required": [ - "error" + "x-rate-limits": { + "requests_per_minute": 30 + }, + "parameters": [ + { + "$ref": "#/components/parameters/x402AddressHeader" + }, + { + "$ref": "#/components/parameters/x402TimestampHeader" + }, + { + "$ref": "#/components/parameters/x402SignatureHeader" + } ], - "properties": { - "error": { - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "string", - "enum": [ - "payment_required", - "validation_error", - "rate_limited", - "internal_error" - ] - }, - "message": { - "type": "string" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchRequest" }, - "request_id": { - "type": "string" + "examples": { + "deepQuery": { + "value": { + "query": "What are the tradeoffs between sparse and dense retrieval for enterprise RAG?", + "max_sources": 10, + "include_domains": [ + "queryx.run" + ], + "exclude_domains": [ + "ads.queryx.run" + ], + "lang": "en", + "region": "US", + "safe": "moderate", + "reasoning_depth": "high" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Deep research response.", + "headers": { + "X-RateLimit-Limit": { + "schema": { + "type": "integer" + } }, - "details": { - "type": "object", - "additionalProperties": true + "X-RateLimit-Remaining": { + "schema": { + "type": "integer" + } }, - "payment": { - "$ref": "#/components/schemas/PaymentQuote" + "X-RateLimit-Reset": { + "schema": { + "type": "integer" + } } }, - "additionalProperties": false + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchResponse" + }, + "examples": { + "deepResults": { + "value": { + "request_id": "req_01JNF8B2AXYHJ6YEKMN6BYBFFM", + "query": "What are the tradeoffs between sparse and dense retrieval for enterprise RAG?", + "summary": "Dense retrieval improves semantic recall while sparse retrieval remains strong for lexical precision, transparency, and lower infra overhead.", + "answer": "For enterprise RAG, sparse retrieval is typically cheaper, easier to audit, and robust for exact-match intents. Dense retrieval improves semantic matching and multilingual recall but requires embedding lifecycle management and vector infra. Hybrid retrieval often gives the best overall relevance and resilience.", + "key_points": [ + "Sparse methods excel on exact keywords and compliance traceability.", + "Dense methods improve semantic recall and paraphrase tolerance.", + "Hybrid fusion usually outperforms either method alone in production." + ], + "sources": [ + { + "title": "Hybrid Retrieval in RAG Systems", + "url": "https://queryx.run/example/hybrid-rag", + "snippet": "A benchmark-oriented look at lexical, vector, and fused retrieval.", + "source": "Queryx Research", + "relevance": 0.96 + }, + { + "title": "Dense vs Sparse Retrieval Tradeoffs", + "url": "https://queryx.run/example/dense-vs-sparse", + "snippet": "Operational tradeoffs for enterprise search deployments.", + "source": "Queryx Research", + "relevance": 0.93 + } + ], + "latency_ms": 1488, + "usage": { + "endpoint": "/v1/search/deep", + "cost_base_units": 125000, + "cost_usdc": "0.125", + "rate_limit_limit": 30, + "rate_limit_remaining": 29, + "rate_limit_reset_seconds": 60 + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" } - }, - "additionalProperties": false + } } } } From 8035a24e417b869f937678aabad33d169be7a2f0 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:11:12 +0000 Subject: [PATCH 05/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- openapi.json | 2000 ++++++++++++++++++++++++-------------------------- 1 file changed, 942 insertions(+), 1058 deletions(-) diff --git a/openapi.json b/openapi.json index c0a78a1..5885536 100644 --- a/openapi.json +++ b/openapi.json @@ -1,11 +1,10 @@ { + "$schema": "https://spec.openapis.org/oas/3.1/dialect/base", "openapi": "3.1.0", - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", "version": "1.0.0", - "summary": "x402-metered web and research search API", - "description": "Queryx provides metered search endpoints secured with x402 payments on Base USDC." + "description": "Queryx provides paid web search, news search, and deep research endpoints secured by x402 on Base." }, "servers": [ { @@ -15,231 +14,703 @@ ], "tags": [ { - "name": "health", - "description": "Service health and readiness" + "name": "Health", + "description": "Service health and readiness." }, { - "name": "search", - "description": "Web and news search endpoints" + "name": "Search", + "description": "General web search." }, { - "name": "research", - "description": "Deep research endpoint" + "name": "News", + "description": "News-focused search." + }, + { + "name": "Deep", + "description": "Multi-step deep research workflow." + } + ], + "security": [ + { + "x402": [] } ], + "x-x402": { + "network": "base", + "asset": "USDC", + "decimals": 6, + "facilitator_address": "0x5A6f7A2b9f7B92E8d6A55E2d88cbf8EeCd8A4B13" + }, + "paths": { + "/health": { + "get": { + "tags": [ + "Health" + ], + "summary": "Health check", + "operationId": "getHealth", + "security": [], + "responses": { + "200": { + "description": "Service is healthy.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HealthResponse" + }, + "examples": { + "ok": { + "value": { + "status": "ok", + "version": "1.0.0", + "uptime_s": 38192, + "now": "2026-03-04T12:41:53Z" + } + } + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v1/search": { + "get": { + "tags": [ + "Search" + ], + "summary": "Web search", + "description": "Returns ranked web results for the given query.", + "operationId": "searchWeb", + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "description": "Search query.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "examples": { + "basic": { + "value": "base ecosystem funding rounds" + } + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of results.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "default": 10 + }, + "examples": { + "small": { + "value": 5 + } + } + }, + { + "name": "region", + "in": "query", + "required": false, + "description": "Two-letter region code.", + "schema": { + "type": "string", + "pattern": "^[A-Z]{2}$", + "default": "US" + }, + "examples": { + "us": { + "value": "US" + } + } + }, + { + "name": "safe_search", + "in": "query", + "required": false, + "description": "Safe search mode.", + "schema": { + "type": "string", + "enum": [ + "off", + "moderate", + "strict" + ], + "default": "moderate" + } + }, + { + "name": "freshness", + "in": "query", + "required": false, + "description": "Recency filter.", + "schema": { + "type": "string", + "enum": [ + "any", + "day", + "week", + "month" + ], + "default": "any" + } + } + ], + "responses": { + "200": { + "description": "Search results.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + }, + "X-RateLimit-Limit": { + "$ref": "#/components/headers/X-RateLimit-Limit" + }, + "X-RateLimit-Remaining": { + "$ref": "#/components/headers/X-RateLimit-Remaining" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/X-RateLimit-Reset" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebSearchResponse" + }, + "examples": { + "success": { + "value": { + "query": "base ecosystem funding rounds", + "took_ms": 143, + "total": 2, + "results": [ + { + "title": "Q1 Base Ecosystem Funding Summary", + "url": "https://queryx.run/mock/source/base-funding-q1", + "snippet": "An overview of major funding rounds announced in the Base ecosystem in Q1.", + "source": "Queryx Mock Source", + "published_at": "2026-02-27T10:20:11Z", + "score": 0.93 + }, + { + "title": "Developer Tooling Raises for Base Builders", + "url": "https://queryx.run/mock/source/base-tooling-funding", + "snippet": "Roundup of developer infrastructure and tooling startups raising capital on Base.", + "source": "Queryx Mock Source", + "published_at": "2026-02-24T08:11:00Z", + "score": 0.88 + } + ], + "cost": { + "asset": "USDC", + "amount_base_units": "2500", + "amount": "0.0025" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationFailed" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v1/search/news": { + "get": { + "tags": [ + "News" + ], + "summary": "News search", + "description": "Returns recent and relevant news results.", + "operationId": "searchNews", + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "description": "News query.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "examples": { + "basic": { + "value": "base developer grants" + } + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of results.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + } + }, + { + "name": "since", + "in": "query", + "required": false, + "description": "Only include articles published at or after this timestamp.", + "schema": { + "type": "string", + "format": "date-time" + }, + "examples": { + "recent": { + "value": "2026-02-01T00:00:00Z" + } + } + }, + { + "name": "sort", + "in": "query", + "required": false, + "description": "Sort mode.", + "schema": { + "type": "string", + "enum": [ + "relevancy", + "date" + ], + "default": "relevancy" + } + } + ], + "responses": { + "200": { + "description": "News results.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + }, + "X-RateLimit-Limit": { + "$ref": "#/components/headers/X-RateLimit-Limit" + }, + "X-RateLimit-Remaining": { + "$ref": "#/components/headers/X-RateLimit-Remaining" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/X-RateLimit-Reset" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NewsSearchResponse" + }, + "examples": { + "success": { + "value": { + "query": "base developer grants", + "took_ms": 167, + "total": 2, + "results": [ + { + "title": "Base Expands Developer Grants Program", + "url": "https://queryx.run/mock/news/base-grants-expansion", + "snippet": "The grants initiative adds new tracks for infrastructure and education.", + "source": "Queryx Mock News", + "outlet": "Queryx Daily", + "published_at": "2026-03-02T07:11:18Z", + "score": 0.96, + "category": "technology" + }, + { + "title": "How Builders Are Using Base Grant Funding", + "url": "https://queryx.run/mock/news/base-grants-case-studies", + "snippet": "Interview-driven piece on successful grant-funded teams.", + "source": "Queryx Mock News", + "outlet": "Builder Wire", + "published_at": "2026-03-01T14:20:00Z", + "score": 0.89, + "category": "business" + } + ], + "cost": { + "asset": "USDC", + "amount_base_units": "4000", + "amount": "0.004" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationFailed" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v1/search/deep": { + "post": { + "tags": [ + "Deep" + ], + "summary": "Deep research", + "description": "Performs multi-step retrieval and synthesis with citations.", + "operationId": "deepSearch", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchRequest" + }, + "examples": { + "default": { + "value": { + "query": "What are the main risks and opportunities for Base ecosystem startups in 2026?", + "max_results": 12, + "search_depth": "standard", + "include_news": true, + "include_citations": true, + "freshness": "month" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Deep research report.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + }, + "X-RateLimit-Limit": { + "$ref": "#/components/headers/X-RateLimit-Limit" + }, + "X-RateLimit-Remaining": { + "$ref": "#/components/headers/X-RateLimit-Remaining" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/X-RateLimit-Reset" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeepSearchResponse" + }, + "examples": { + "success": { + "value": { + "query": "What are the main risks and opportunities for Base ecosystem startups in 2026?", + "answer": "The dominant opportunity is distribution leverage via wallet-native channels and stablecoin rails, while the dominant risk is margin compression in undifferentiated tooling segments.", + "key_findings": [ + "Developer tooling remains crowded, forcing differentiation via workflow depth and enterprise features.", + "Consumer apps with built-in onchain payments are showing stronger retention than utility-only products.", + "Compliance and treasury operations are becoming a larger share of total startup cost." + ], + "citations": [ + { + "title": "2026 Base Builder Landscape", + "url": "https://queryx.run/mock/research/base-builder-landscape-2026", + "snippet": "Annual report covering funding, retention, and monetization by segment.", + "source": "Queryx Mock Research", + "published_at": "2026-02-20T09:30:00Z" + }, + { + "title": "Stablecoin Settlement Trends on Base", + "url": "https://queryx.run/mock/research/base-stablecoin-settlement", + "snippet": "Quarterly analysis of transaction volume and business use-cases.", + "source": "Queryx Mock Research", + "published_at": "2026-02-28T15:02:00Z" + } + ], + "results": [ + { + "title": "Base Builder Landscape 2026", + "url": "https://queryx.run/mock/research/base-builder-landscape-2026", + "snippet": "Survey and metrics for startup outcomes on Base.", + "source": "Queryx Mock Research", + "published_at": "2026-02-20T09:30:00Z", + "score": 0.95 + }, + { + "title": "Stablecoin Settlement Trends on Base", + "url": "https://queryx.run/mock/research/base-stablecoin-settlement", + "snippet": "Analysis of onchain payment growth.", + "source": "Queryx Mock Research", + "published_at": "2026-02-28T15:02:00Z", + "score": 0.9 + } + ], + "took_ms": 1320, + "total": 12, + "cost": { + "asset": "USDC", + "amount_base_units": "25000", + "amount": "0.025" + } + } + } + } + } + } + }, + "402": { + "$ref": "#/components/responses/PaymentRequired" + }, + "422": { + "$ref": "#/components/responses/ValidationFailed" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + } + }, "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", - "name": "X-402-Payment", - "description": "x402 payment envelope. For paid retries this is a base64url-encoded JSON object containing quote and payer metadata." + "name": "X-PAYMENT", + "description": "Base64url-encoded x402 payment envelope signed by the payer wallet. Required for paid endpoints." } }, - "parameters": { - "q": { - "name": "q", - "in": "query", - "required": true, - "description": "Natural-language search query.", + "headers": { + "X-Request-Id": { + "description": "Request correlation id.", "schema": { - "type": "string", - "minLength": 1, - "maxLength": 1024 - }, - "examples": { - "basic": { - "value": "best LLM eval frameworks" - } + "type": "string" } }, - "limit": { - "name": "limit", - "in": "query", - "required": false, - "description": "Maximum number of results.", + "X-RateLimit-Limit": { + "description": "Allowed requests in the current rate-limit window.", "schema": { - "type": "integer", - "minimum": 1, - "maximum": 20, - "default": 8 - }, - "examples": { - "default": { - "value": 8 - } + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "description": "Remaining requests in the current rate-limit window.", + "schema": { + "type": "integer" } }, - "offset": { - "name": "offset", - "in": "query", - "required": false, - "description": "Zero-based pagination offset.", + "X-RateLimit-Reset": { + "description": "Unix timestamp when the current rate-limit window resets.", + "schema": { + "type": "integer" + } + }, + "Retry-After": { + "description": "Seconds to wait before retrying.", "schema": { "type": "integer", - "minimum": 0, - "maximum": 200, - "default": 0 - }, - "examples": { - "firstPage": { - "value": 0 - } + "minimum": 1 } }, - "lang": { - "name": "lang", - "in": "query", - "required": false, - "description": "Language hint (ISO-like code).", + "X-402-Required": { + "description": "Set to true when payment is required.", "schema": { - "type": "string", - "pattern": "^[a-z]{2}(-[A-Z]{2})?$", - "default": "en" - }, - "examples": { - "english": { - "value": "en" - } + "type": "boolean" } }, - "region": { - "name": "region", - "in": "query", - "required": false, - "description": "Region/country hint for ranking.", + "X-402-Challenge": { + "description": "Base64url-encoded x402 challenge JSON used to construct a payment envelope.", "schema": { - "type": "string", - "minLength": 2, - "maxLength": 8, - "default": "US" + "type": "string" + } + } + }, + "responses": { + "PaymentRequired": { + "description": "Payment required. Retry the same request with a valid x402 payment envelope.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + }, + "X-402-Required": { + "$ref": "#/components/headers/X-402-Required" + }, + "X-402-Challenge": { + "$ref": "#/components/headers/X-402-Challenge" + } }, - "examples": { - "us": { - "value": "US" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentRequiredError" + }, + "examples": { + "paymentRequired": { + "value": { + "error": { + "code": "PAYMENT_REQUIRED", + "message": "Valid x402 payment is required for this endpoint.", + "request_id": "req_402_a12f09" + }, + "payment": { + "scheme": "x402", + "network": "base", + "asset": "USDC", + "decimals": 6, + "amount_base_units": "2500", + "amount": "0.0025", + "facilitator_address": "0x5A6f7A2b9f7B92E8d6A55E2d88cbf8EeCd8A4B13", + "pay_to": "0xD4D1A8F4c37a0eaD8B61B7f957f9f93f8AA3d815", + "nonce": "n_4fc31ced33", + "expires_at": "2026-03-04T12:45:00Z", + "request_hash": "0x9b9be318c8659e8ec9f49de22f77fd62b745cecc6f6ec9d4fa0d4f6cf15d2a40" + } + } + } + } } } }, - "safe": { - "name": "safe", - "in": "query", - "required": false, - "description": "Safety filter level.", - "schema": { - "type": "string", - "enum": [ - "off", - "moderate", - "strict" - ], - "default": "moderate" + "ValidationFailed": { + "description": "Validation failed.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + } }, - "examples": { - "moderate": { - "value": "moderate" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationError" + }, + "examples": { + "invalidInput": { + "value": { + "error": { + "code": "VALIDATION_ERROR", + "message": "One or more fields are invalid.", + "request_id": "req_422_93f1c8", + "details": [ + { + "path": "q", + "message": "q must be at least 1 character." + } + ] + } + } + } + } } } }, - "freshness": { - "name": "freshness", - "in": "query", - "required": false, - "description": "Freshness window used for ranking.", - "schema": { - "type": "string", - "enum": [ - "any", - "day", - "week", - "month", - "year" - ], - "default": "any" - }, - "examples": { - "week": { - "value": "week" + "TooManyRequests": { + "description": "Rate limit exceeded.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" + }, + "Retry-After": { + "$ref": "#/components/headers/Retry-After" + }, + "X-RateLimit-Limit": { + "$ref": "#/components/headers/X-RateLimit-Limit" + }, + "X-RateLimit-Remaining": { + "$ref": "#/components/headers/X-RateLimit-Remaining" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/X-RateLimit-Reset" } - } - }, - "newsSort": { - "name": "sort", - "in": "query", - "required": false, - "description": "Sort strategy for news results.", - "schema": { - "type": "string", - "enum": [ - "relevance", - "date" - ], - "default": "relevance" }, - "examples": { - "date": { - "value": "date" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + }, + "examples": { + "rateLimited": { + "value": { + "error": { + "code": "RATE_LIMITED", + "message": "Rate limit exceeded. Retry later.", + "request_id": "req_429_7723c1" + }, + "retry_after_seconds": 8 + } + } + } } } }, - "fromDate": { - "name": "from", - "in": "query", - "required": false, - "description": "Lower bound publication date (inclusive).", - "schema": { - "type": "string", - "format": "date" - }, - "examples": { - "from": { - "value": "2026-02-01" + "InternalServerError": { + "description": "Unexpected server-side error.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/X-Request-Id" } - } - }, - "toDate": { - "name": "to", - "in": "query", - "required": false, - "description": "Upper bound publication date (inclusive).", - "schema": { - "type": "string", - "format": "date" }, - "examples": { - "to": { - "value": "2026-03-04" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalError" + }, + "examples": { + "internal": { + "value": { + "error": { + "code": "INTERNAL_ERROR", + "message": "Unexpected server error.", + "request_id": "req_500_5fca11" + } + } + } + } } } - }, - "x402AddressHeader": { - "name": "X-402-Address", - "in": "header", - "required": false, - "description": "Payer wallet address on Base.", - "schema": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$" - } - }, - "x402TimestampHeader": { - "name": "X-402-Timestamp", - "in": "header", - "required": false, - "description": "Unix epoch timestamp in seconds used in the signature payload.", - "schema": { - "type": "integer", - "minimum": 0 - } - }, - "x402SignatureHeader": { - "name": "X-402-Signature", - "in": "header", - "required": false, - "description": "Signature of canonical x402 string (EIP-191 personal_sign).", - "schema": { - "type": "string", - "minLength": 40 - } } }, "schemas": { @@ -248,10 +719,9 @@ "additionalProperties": false, "required": [ "status", - "service", "version", - "timestamp", - "uptime_seconds" + "uptime_s", + "now" ], "properties": { "status": { @@ -260,61 +730,41 @@ "ok" ] }, - "service": { - "type": "string", - "example": "queryx-api" - }, "version": { - "type": "string", - "example": "1.0.0" + "type": "string" + }, + "uptime_s": { + "type": "integer", + "minimum": 0 }, - "timestamp": { + "now": { "type": "string", "format": "date-time" - }, - "uptime_seconds": { - "type": "number", - "minimum": 0 } } }, - "Usage": { + "Cost": { "type": "object", "additionalProperties": false, "required": [ - "endpoint", - "cost_base_units", - "cost_usdc", - "rate_limit_limit", - "rate_limit_remaining", - "rate_limit_reset_seconds" + "asset", + "amount_base_units", + "amount" ], "properties": { - "endpoint": { + "asset": { "type": "string", - "example": "/v1/search" - }, - "cost_base_units": { - "type": "integer", - "minimum": 0, - "description": "USDC base units where 1 USDC = 1,000,000 base units." + "enum": [ + "USDC" + ] }, - "cost_usdc": { + "amount_base_units": { "type": "string", - "pattern": "^\\d+(\\.\\d{1,6})?$", - "example": "0.025" - }, - "rate_limit_limit": { - "type": "integer", - "minimum": 1 + "pattern": "^[0-9]+$" }, - "rate_limit_remaining": { - "type": "integer", - "minimum": 0 - }, - "rate_limit_reset_seconds": { - "type": "integer", - "minimum": 0 + "amount": { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, @@ -326,6 +776,7 @@ "url", "snippet", "source", + "published_at", "score" ], "properties": { @@ -342,6 +793,10 @@ "source": { "type": "string" }, + "published_at": { + "type": "string", + "format": "date-time" + }, "score": { "type": "number", "minimum": 0, @@ -350,6 +805,29 @@ } }, "NewsResult": { + "allOf": [ + { + "$ref": "#/components/schemas/SearchResult" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "outlet", + "category" + ], + "properties": { + "outlet": { + "type": "string" + }, + "category": { + "type": "string" + } + } + } + ] + }, + "Citation": { "type": "object", "additionalProperties": false, "required": [ @@ -357,7 +835,6 @@ "url", "snippet", "source", - "score", "published_at" ], "properties": { @@ -374,942 +851,349 @@ "source": { "type": "string" }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, "published_at": { "type": "string", "format": "date-time" - }, - "image_url": { - "type": "string", - "format": "uri" - } - } - }, - "SearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "request_id", - "query", - "type", - "results", - "latency_ms", - "usage" - ], - "properties": { - "request_id": { - "type": "string", - "example": "req_01JNF89R6G3H2EA0R9N81A8NKT" - }, - "query": { - "type": "string" - }, - "type": { - "type": "string", - "enum": [ - "web" - ] - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchResult" - } - }, - "latency_ms": { - "type": "integer", - "minimum": 1 - }, - "usage": { - "$ref": "#/components/schemas/Usage" } } }, - "NewsSearchResponse": { + "WebSearchResponse": { "type": "object", "additionalProperties": false, "required": [ - "request_id", "query", - "type", + "took_ms", + "total", "results", - "latency_ms", - "usage" + "cost" ], "properties": { - "request_id": { - "type": "string", - "example": "req_01JNF8A2NKVK9W8AB6A2RQ8C4S" - }, "query": { "type": "string" }, - "type": { - "type": "string", - "enum": [ - "news" - ] - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NewsResult" - } - }, - "latency_ms": { + "took_ms": { "type": "integer", - "minimum": 1 - }, - "usage": { - "$ref": "#/components/schemas/Usage" - } - } - }, - "DeepSearchRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "minLength": 1, - "maxLength": 1024 + "minimum": 0 }, - "max_sources": { + "total": { "type": "integer", - "minimum": 3, - "maximum": 40, - "default": 12 - }, - "include_domains": { - "type": "array", - "maxItems": 50, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 255 - } - }, - "exclude_domains": { - "type": "array", - "maxItems": 50, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 255 - } - }, - "lang": { - "type": "string", - "pattern": "^[a-z]{2}(-[A-Z]{2})?$", - "default": "en" - }, - "region": { - "type": "string", - "default": "US" - }, - "safe": { - "type": "string", - "enum": [ - "off", - "moderate", - "strict" - ], - "default": "moderate" - }, - "reasoning_depth": { - "type": "string", - "enum": [ - "standard", - "high" - ], - "default": "standard" - } - } - }, - "DeepSource": { - "type": "object", - "additionalProperties": false, - "required": [ - "title", - "url", - "snippet", - "source", - "relevance" - ], - "properties": { - "title": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "source": { - "type": "string" - }, - "relevance": { - "type": "number", - "minimum": 0, - "maximum": 1 - } - } - }, - "DeepSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "request_id", - "query", - "summary", - "answer", - "key_points", - "sources", - "latency_ms", - "usage" - ], - "properties": { - "request_id": { - "type": "string" - }, - "query": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "answer": { - "type": "string" - }, - "key_points": { - "type": "array", - "items": { - "type": "string" - } + "minimum": 0 }, - "sources": { + "results": { "type": "array", "items": { - "$ref": "#/components/schemas/DeepSource" + "$ref": "#/components/schemas/SearchResult" } }, - "latency_ms": { - "type": "integer", - "minimum": 1 - }, - "usage": { - "$ref": "#/components/schemas/Usage" + "cost": { + "$ref": "#/components/schemas/Cost" } } }, - "ErrorDetail": { + "NewsSearchResponse": { "type": "object", "additionalProperties": false, "required": [ - "code", - "message" + "query", + "took_ms", + "total", + "results", + "cost" ], "properties": { - "code": { - "type": "string", - "enum": [ - "payment_required", - "validation_error", - "rate_limited", - "internal_error" - ] - }, - "message": { + "query": { "type": "string" }, - "request_id": { - "type": "string" + "took_ms": { + "type": "integer", + "minimum": 0 }, - "retry_after_seconds": { + "total": { "type": "integer", "minimum": 0 }, - "invalid_fields": { + "results": { "type": "array", "items": { - "type": "object", - "additionalProperties": false, - "required": [ - "field", - "reason" - ], - "properties": { - "field": { - "type": "string" - }, - "reason": { - "type": "string" - } - } + "$ref": "#/components/schemas/NewsResult" } + }, + "cost": { + "$ref": "#/components/schemas/Cost" } } }, - "PaymentRequirement": { + "DeepSearchRequest": { "type": "object", "additionalProperties": false, "required": [ - "network", - "chain_id", - "asset", - "amount_base_units", - "amount", - "payment_id", - "facilitator", - "expires_at", - "signature_payload" + "query" ], "properties": { - "network": { - "type": "string", - "example": "base" - }, - "chain_id": { - "type": "integer", - "example": 8453 - }, - "asset": { + "query": { "type": "string", - "example": "USDC" + "minLength": 1, + "maxLength": 2000 }, - "amount_base_units": { + "max_results": { "type": "integer", "minimum": 1, - "example": 25000 + "maximum": 50, + "default": 10 }, - "amount": { + "search_depth": { "type": "string", - "pattern": "^\\d+(\\.\\d{1,6})?$", - "example": "0.025" + "enum": [ + "quick", + "standard", + "exhaustive" + ], + "default": "standard" }, - "payment_id": { - "type": "string", - "example": "pay_01JNF8C2KQ43P4FQRTQ6BRWWA8" + "include_news": { + "type": "boolean", + "default": true }, - "facilitator": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "example": "0x6c7ad4e1bfa9c20e4a9e0467fd20170d1aa05c11" + "include_citations": { + "type": "boolean", + "default": true }, - "expires_at": { + "freshness": { "type": "string", - "format": "date-time" - }, - "signature_payload": { - "type": "object", - "additionalProperties": false, - "required": [ - "version", - "scheme", - "message" + "enum": [ + "any", + "day", + "week", + "month" ], - "properties": { - "version": { - "type": "string", - "example": "QUERYX-X402-V1" - }, - "scheme": { - "type": "string", - "example": "eip191" - }, - "message": { - "type": "string", - "description": "Canonical string to sign with payer wallet key." - } - } + "default": "month" } } }, - "ErrorResponse": { + "DeepSearchResponse": { "type": "object", "additionalProperties": false, "required": [ - "error" + "query", + "answer", + "key_findings", + "citations", + "results", + "took_ms", + "total", + "cost" ], "properties": { - "error": { - "$ref": "#/components/schemas/ErrorDetail" - }, - "payment": { - "$ref": "#/components/schemas/PaymentRequirement" - } - } - } - }, - "responses": { - "PaymentRequired": { - "description": "x402 payment required before request can be processed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "paymentRequired": { - "value": { - "error": { - "code": "payment_required", - "message": "x402 payment is required for this endpoint.", - "request_id": "req_01JNF8D7F4FB7CV0W5XKQ6QCMF" - }, - "payment": { - "network": "base", - "chain_id": 8453, - "asset": "USDC", - "amount_base_units": 25000, - "amount": "0.025", - "payment_id": "pay_01JNF8C2KQ43P4FQRTQ6BRWWA8", - "facilitator": "0x6c7ad4e1bfa9c20e4a9e0467fd20170d1aa05c11", - "expires_at": "2026-03-04T12:00:00Z", - "signature_payload": { - "version": "QUERYX-X402-V1", - "scheme": "eip191", - "message": "QUERYX-X402-V1\nGET\n/v1/search?q=best+LLM+eval+frameworks&limit=3\n47DEQpj8HBSa__TImW-5JCeuQeRkm5NMpJWZG3hSuFU\npay_01JNF8C2KQ43P4FQRTQ6BRWWA8\n25000\nUSDC\nbase\n8453\n1709558400" - } - } - } - } - } - } - } - }, - "ValidationError": { - "description": "Input failed validation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "validation": { - "value": { - "error": { - "code": "validation_error", - "message": "Validation failed for query parameters.", - "request_id": "req_01JNF8E15N4MZV34H1N0NTHTW4", - "invalid_fields": [ - { - "field": "limit", - "reason": "must be less than or equal to 20" - } - ] - } - } - } - } - } - } - }, - "RateLimitError": { - "description": "Rate limit exceeded.", - "headers": { - "Retry-After": { - "description": "Seconds to wait before retrying.", - "schema": { - "type": "integer", - "minimum": 1 - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "rateLimit": { - "value": { - "error": { - "code": "rate_limited", - "message": "Too many requests.", - "request_id": "req_01JNF8ET3Q6R6PE7Q3SEFBRM9H", - "retry_after_seconds": 12 - } - } - } - } - } - } - }, - "InternalServerError": { - "description": "Unexpected server error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internal": { - "value": { - "error": { - "code": "internal_error", - "message": "Unexpected internal error.", - "request_id": "req_01JNF8FRQ28CG3YSA9NQXJ61AQ" - } - } - } - } - } - } - } - } - }, - "paths": { - "/health": { - "get": { - "tags": [ - "health" - ], - "summary": "Health check", - "operationId": "getHealth", - "security": [], - "responses": { - "200": { - "description": "Service is healthy.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HealthResponse" - }, - "examples": { - "ok": { - "value": { - "status": "ok", - "service": "queryx-api", - "version": "1.0.0", - "timestamp": "2026-03-04T10:15:30Z", - "uptime_seconds": 91324.12 - } - } - } - } - } - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - } - } - }, - "/v1/search": { - "get": { - "tags": [ - "search" - ], - "summary": "Web search", - "description": "Low-latency web search endpoint billed per request with x402.", - "operationId": "searchWeb", - "security": [ - { - "x402": [] - } - ], - "x-pricing": { - "asset": "USDC", - "base_units": 25000, - "human_readable": "0.025", - "network": "base" - }, - "x-rate-limits": { - "requests_per_minute": 120 - }, - "parameters": [ - { - "$ref": "#/components/parameters/q" - }, - { - "$ref": "#/components/parameters/limit" - }, - { - "$ref": "#/components/parameters/offset" - }, - { - "$ref": "#/components/parameters/lang" - }, - { - "$ref": "#/components/parameters/region" - }, - { - "$ref": "#/components/parameters/safe" - }, - { - "$ref": "#/components/parameters/freshness" - }, - { - "$ref": "#/components/parameters/x402AddressHeader" - }, - { - "$ref": "#/components/parameters/x402TimestampHeader" + "query": { + "type": "string" }, - { - "$ref": "#/components/parameters/x402SignatureHeader" - } - ], - "responses": { - "200": { - "description": "Search results.", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchResponse" - }, - "examples": { - "webResults": { - "value": { - "request_id": "req_01JNF89R6G3H2EA0R9N81A8NKT", - "query": "best LLM eval frameworks", - "type": "web", - "results": [ - { - "title": "LLM Evaluation Methods", - "url": "https://queryx.run/example/llm-eval-methods", - "snippet": "A practical guide to automated and human-in-the-loop LLM evaluation.", - "source": "Queryx Demo", - "score": 0.94 - }, - { - "title": "Benchmarking LLM Systems", - "url": "https://queryx.run/example/benchmarking-llms", - "snippet": "Coverage of retrieval-aware benchmarks and rubric scoring.", - "source": "Queryx Demo", - "score": 0.91 - } - ], - "latency_ms": 388, - "usage": { - "endpoint": "/v1/search", - "cost_base_units": 25000, - "cost_usdc": "0.025", - "rate_limit_limit": 120, - "rate_limit_remaining": 119, - "rate_limit_reset_seconds": 60 - } - } - } - } - } + "answer": { + "type": "string" + }, + "key_findings": { + "type": "array", + "items": { + "type": "string" } }, - "402": { - "$ref": "#/components/responses/PaymentRequired" + "citations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Citation" + } }, - "422": { - "$ref": "#/components/responses/ValidationError" + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } }, - "429": { - "$ref": "#/components/responses/RateLimitError" + "took_ms": { + "type": "integer", + "minimum": 0 }, - "500": { - "$ref": "#/components/responses/InternalServerError" + "total": { + "type": "integer", + "minimum": 0 + }, + "cost": { + "$ref": "#/components/schemas/Cost" } } - } - }, - "/v1/search/news": { - "get": { - "tags": [ - "search" + }, + "ValidationIssue": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "message" ], - "summary": "News search", - "description": "News-focused search endpoint with optional date filtering, billed with x402.", - "operationId": "searchNews", - "security": [ - { - "x402": [] + "properties": { + "path": { + "type": "string" + }, + "message": { + "type": "string" } + } + }, + "ErrorObject": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "message", + "request_id" ], - "x-pricing": { - "asset": "USDC", - "base_units": 35000, - "human_readable": "0.035", - "network": "base" - }, - "x-rate-limits": { - "requests_per_minute": 90 - }, - "parameters": [ - { - "$ref": "#/components/parameters/q" + "properties": { + "code": { + "type": "string" }, - { - "$ref": "#/components/parameters/limit" + "message": { + "type": "string" }, - { - "$ref": "#/components/parameters/offset" + "request_id": { + "type": "string" }, + "details": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationIssue" + } + } + } + }, + "ErrorEnvelope": { + "type": "object", + "additionalProperties": false, + "required": [ + "error" + ], + "properties": { + "error": { + "$ref": "#/components/schemas/ErrorObject" + } + } + }, + "ValidationError": { + "allOf": [ { - "$ref": "#/components/parameters/lang" - }, + "$ref": "#/components/schemas/ErrorEnvelope" + } + ] + }, + "RateLimitError": { + "allOf": [ { - "$ref": "#/components/parameters/region" + "$ref": "#/components/schemas/ErrorEnvelope" }, { - "$ref": "#/components/parameters/safe" + "type": "object", + "additionalProperties": false, + "required": [ + "retry_after_seconds" + ], + "properties": { + "retry_after_seconds": { + "type": "integer", + "minimum": 1 + } + } + } + ] + }, + "PaymentRequirement": { + "type": "object", + "additionalProperties": false, + "required": [ + "scheme", + "network", + "asset", + "decimals", + "amount_base_units", + "amount", + "facilitator_address", + "pay_to", + "nonce", + "expires_at", + "request_hash" + ], + "properties": { + "scheme": { + "type": "string", + "enum": [ + "x402" + ] }, - { - "$ref": "#/components/parameters/newsSort" + "network": { + "type": "string", + "enum": [ + "base" + ] }, - { - "$ref": "#/components/parameters/fromDate" + "asset": { + "type": "string", + "enum": [ + "USDC" + ] }, - { - "$ref": "#/components/parameters/toDate" + "decimals": { + "type": "integer", + "enum": [ + 6 + ] }, - { - "$ref": "#/components/parameters/x402AddressHeader" + "amount_base_units": { + "type": "string", + "pattern": "^[0-9]+$" }, - { - "$ref": "#/components/parameters/x402TimestampHeader" + "amount": { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]+)?$" }, - { - "$ref": "#/components/parameters/x402SignatureHeader" - } - ], - "responses": { - "200": { - "description": "News results.", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewsSearchResponse" - }, - "examples": { - "newsResults": { - "value": { - "request_id": "req_01JNF8A2NKVK9W8AB6A2RQ8C4S", - "query": "ai chip funding rounds", - "type": "news", - "results": [ - { - "title": "AI Chip Startup Raises New Round", - "url": "https://queryx.run/example/ai-chip-round", - "snippet": "The company announced an oversubscribed round led by strategic investors.", - "source": "Queryx Newswire", - "score": 0.97, - "published_at": "2026-03-03T14:10:00Z", - "image_url": "https://queryx.run/example/images/ai-chip-round.jpg" - } - ], - "latency_ms": 442, - "usage": { - "endpoint": "/v1/search/news", - "cost_base_units": 35000, - "cost_usdc": "0.035", - "rate_limit_limit": 90, - "rate_limit_remaining": 89, - "rate_limit_reset_seconds": 60 - } - } - } - } - } - } + "facilitator_address": { + "type": "string" }, - "402": { - "$ref": "#/components/responses/PaymentRequired" + "pay_to": { + "type": "string" }, - "422": { - "$ref": "#/components/responses/ValidationError" + "nonce": { + "type": "string" }, - "429": { - "$ref": "#/components/responses/RateLimitError" + "expires_at": { + "type": "string", + "format": "date-time" }, - "500": { - "$ref": "#/components/responses/InternalServerError" + "request_hash": { + "type": "string" } } - } - }, - "/v1/search/deep": { - "post": { - "tags": [ - "research" - ], - "summary": "Deep research search", - "description": "Multi-source deep research with synthesis and citations, billed with x402.", - "operationId": "searchDeep", - "security": [ - { - "x402": [] - } - ], - "x-pricing": { - "asset": "USDC", - "base_units": 125000, - "human_readable": "0.125", - "network": "base" - }, - "x-rate-limits": { - "requests_per_minute": 30 - }, - "parameters": [ - { - "$ref": "#/components/parameters/x402AddressHeader" - }, + }, + "PaymentRequiredError": { + "allOf": [ { - "$ref": "#/components/parameters/x402TimestampHeader" + "$ref": "#/components/schemas/ErrorEnvelope" }, { - "$ref": "#/components/parameters/x402SignatureHeader" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeepSearchRequest" - }, - "examples": { - "deepQuery": { - "value": { - "query": "What are the tradeoffs between sparse and dense retrieval for enterprise RAG?", - "max_sources": 10, - "include_domains": [ - "queryx.run" - ], - "exclude_domains": [ - "ads.queryx.run" - ], - "lang": "en", - "region": "US", - "safe": "moderate", - "reasoning_depth": "high" - } - } + "type": "object", + "additionalProperties": false, + "required": [ + "payment" + ], + "properties": { + "payment": { + "$ref": "#/components/schemas/PaymentRequirement" } } } - }, - "responses": { - "200": { - "description": "Deep research response.", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeepSearchResponse" - }, - "examples": { - "deepResults": { - "value": { - "request_id": "req_01JNF8B2AXYHJ6YEKMN6BYBFFM", - "query": "What are the tradeoffs between sparse and dense retrieval for enterprise RAG?", - "summary": "Dense retrieval improves semantic recall while sparse retrieval remains strong for lexical precision, transparency, and lower infra overhead.", - "answer": "For enterprise RAG, sparse retrieval is typically cheaper, easier to audit, and robust for exact-match intents. Dense retrieval improves semantic matching and multilingual recall but requires embedding lifecycle management and vector infra. Hybrid retrieval often gives the best overall relevance and resilience.", - "key_points": [ - "Sparse methods excel on exact keywords and compliance traceability.", - "Dense methods improve semantic recall and paraphrase tolerance.", - "Hybrid fusion usually outperforms either method alone in production." - ], - "sources": [ - { - "title": "Hybrid Retrieval in RAG Systems", - "url": "https://queryx.run/example/hybrid-rag", - "snippet": "A benchmark-oriented look at lexical, vector, and fused retrieval.", - "source": "Queryx Research", - "relevance": 0.96 - }, - { - "title": "Dense vs Sparse Retrieval Tradeoffs", - "url": "https://queryx.run/example/dense-vs-sparse", - "snippet": "Operational tradeoffs for enterprise search deployments.", - "source": "Queryx Research", - "relevance": 0.93 - } - ], - "latency_ms": 1488, - "usage": { - "endpoint": "/v1/search/deep", - "cost_base_units": 125000, - "cost_usdc": "0.125", - "rate_limit_limit": 30, - "rate_limit_remaining": 29, - "rate_limit_reset_seconds": 60 - } - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/PaymentRequired" - }, - "422": { - "$ref": "#/components/responses/ValidationError" - }, - "429": { - "$ref": "#/components/responses/RateLimitError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" + ] + }, + "InternalError": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorEnvelope" } - } + ] } } } From e36064e446cafadf1e3a87a9b29728186bdbf03e Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:17:19 +0000 Subject: [PATCH 06/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- openapi.json | 1286 ++++++++++++++++++++++++++------------------------ 1 file changed, 666 insertions(+), 620 deletions(-) diff --git a/openapi.json b/openapi.json index 5885536..6d738cf 100644 --- a/openapi.json +++ b/openapi.json @@ -1,10 +1,14 @@ { - "$schema": "https://spec.openapis.org/oas/3.1/dialect/base", "openapi": "3.1.0", + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", "version": "1.0.0", - "description": "Queryx provides paid web search, news search, and deep research endpoints secured by x402 on Base." + "summary": "x402-native web and research search API", + "description": "Queryx provides paid web search, news search, and deep research endpoints protected by x402 payments on Base.", + "license": { + "name": "MIT" + } }, "servers": [ { @@ -14,20 +18,16 @@ ], "tags": [ { - "name": "Health", - "description": "Service health and readiness." - }, - { - "name": "Search", - "description": "General web search." + "name": "health", + "description": "Service health checks" }, { - "name": "News", - "description": "News-focused search." + "name": "search", + "description": "Web and news retrieval" }, { - "name": "Deep", - "description": "Multi-step deep research workflow." + "name": "research", + "description": "Multi-hop deep research" } ], "security": [ @@ -35,29 +35,19 @@ "x402": [] } ], - "x-x402": { - "network": "base", - "asset": "USDC", - "decimals": 6, - "facilitator_address": "0x5A6f7A2b9f7B92E8d6A55E2d88cbf8EeCd8A4B13" - }, "paths": { "/health": { "get": { "tags": [ - "Health" + "health" ], - "summary": "Health check", "operationId": "getHealth", + "summary": "Health check", + "description": "Returns service health status. This endpoint is free and does not require x402 payment.", "security": [], "responses": { "200": { - "description": "Service is healthy.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" - } - }, + "description": "Service is healthy", "content": { "application/json": { "schema": { @@ -67,18 +57,15 @@ "ok": { "value": { "status": "ok", + "service": "queryx", "version": "1.0.0", - "uptime_s": 38192, - "now": "2026-03-04T12:41:53Z" + "uptime_s": 92831 } } } } } }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, "500": { "$ref": "#/components/responses/InternalServerError" } @@ -88,143 +75,150 @@ "/v1/search": { "get": { "tags": [ - "Search" + "search" ], - "summary": "Web search", - "description": "Returns ranked web results for the given query.", "operationId": "searchWeb", + "summary": "Web search", + "description": "Returns ranked web results with optional synthesized answer.", + "x-pricing": { + "asset": "USDC", + "usdc_base_units": "5000", + "usdc_human": "0.005" + }, "parameters": [ { "name": "q", "in": "query", "required": true, - "description": "Search query.", + "description": "Search query", "schema": { "type": "string", "minLength": 1, - "maxLength": 512 + "maxLength": 500 }, "examples": { "basic": { - "value": "base ecosystem funding rounds" + "value": "best rust web framework 2026" } } }, { - "name": "limit", + "name": "count", "in": "query", "required": false, - "description": "Maximum number of results.", + "description": "Number of results to return", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 - }, - "examples": { - "small": { - "value": 5 - } } }, { - "name": "region", + "name": "lang", "in": "query", "required": false, - "description": "Two-letter region code.", + "description": "Language code (ISO 639-1)", "schema": { "type": "string", - "pattern": "^[A-Z]{2}$", - "default": "US" - }, - "examples": { - "us": { - "value": "US" - } + "minLength": 2, + "maxLength": 5, + "default": "en" } }, { - "name": "safe_search", + "name": "country", "in": "query", "required": false, - "description": "Safe search mode.", + "description": "Country code (ISO 3166-1 alpha-2)", "schema": { "type": "string", - "enum": [ - "off", - "moderate", - "strict" - ], - "default": "moderate" + "minLength": 2, + "maxLength": 2 } }, { "name": "freshness", "in": "query", "required": false, - "description": "Recency filter.", + "description": "Optional recency filter", "schema": { "type": "string", "enum": [ - "any", - "day", - "week", - "month" + "24h", + "7d", + "30d", + "365d", + "all" ], - "default": "any" + "default": "all" } } ], "responses": { "200": { - "description": "Search results.", + "description": "Web search results", "headers": { "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" + "description": "Unique request identifier", + "schema": { + "type": "string" + } }, "X-RateLimit-Limit": { - "$ref": "#/components/headers/X-RateLimit-Limit" + "description": "Requests allowed in the current window", + "schema": { + "type": "integer" + } }, "X-RateLimit-Remaining": { - "$ref": "#/components/headers/X-RateLimit-Remaining" + "description": "Remaining requests in the current window", + "schema": { + "type": "integer" + } }, "X-RateLimit-Reset": { - "$ref": "#/components/headers/X-RateLimit-Reset" + "description": "Unix epoch seconds when window resets", + "schema": { + "type": "integer" + } } }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WebSearchResponse" + "$ref": "#/components/schemas/SearchResponse" }, "examples": { "success": { "value": { - "query": "base ecosystem funding rounds", - "took_ms": 143, - "total": 2, + "query": "best rust web framework 2026", + "answer": "Actix Web and Axum remain the most commonly adopted Rust web frameworks for high-performance production APIs.", "results": [ { - "title": "Q1 Base Ecosystem Funding Summary", - "url": "https://queryx.run/mock/source/base-funding-q1", - "snippet": "An overview of major funding rounds announced in the Base ecosystem in Q1.", - "source": "Queryx Mock Source", - "published_at": "2026-02-27T10:20:11Z", + "title": "Axum vs Actix: performance benchmark 2026", + "url": "https://example.com/axum-vs-actix-2026", + "snippet": "Benchmarks show both frameworks perform strongly, with tradeoffs in ergonomics and ecosystem.", + "source": "example.com", + "published_at": "2026-01-22T13:03:00Z", "score": 0.93 }, { - "title": "Developer Tooling Raises for Base Builders", - "url": "https://queryx.run/mock/source/base-tooling-funding", - "snippet": "Roundup of developer infrastructure and tooling startups raising capital on Base.", - "source": "Queryx Mock Source", - "published_at": "2026-02-24T08:11:00Z", + "title": "Building APIs with Axum", + "url": "https://example.com/building-apis-axum", + "snippet": "A practical guide to middleware, extraction, and state patterns in Axum.", + "source": "example.com", + "published_at": "2025-11-19T09:00:00Z", "score": 0.88 } ], - "cost": { + "took_ms": 247, + "request_id": "req_9f89b9e85ef345f1", + "billing": { + "endpoint": "/v1/search", "asset": "USDC", - "amount_base_units": "2500", - "amount": "0.0025" + "amount_base_units": "5000", + "amount": "0.005" } } } @@ -236,7 +230,7 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationFailed" + "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -250,33 +244,38 @@ "/v1/search/news": { "get": { "tags": [ - "News" + "search" ], - "summary": "News search", - "description": "Returns recent and relevant news results.", "operationId": "searchNews", + "summary": "News search", + "description": "Returns recent and relevant news articles.", + "x-pricing": { + "asset": "USDC", + "usdc_base_units": "7500", + "usdc_human": "0.0075" + }, "parameters": [ { "name": "q", "in": "query", "required": true, - "description": "News query.", + "description": "News query", "schema": { "type": "string", "minLength": 1, - "maxLength": 512 + "maxLength": 500 }, "examples": { "basic": { - "value": "base developer grants" + "value": "base layer 2 ecosystem funding" } } }, { - "name": "limit", + "name": "count", "in": "query", "required": false, - "description": "Maximum number of results.", + "description": "Number of articles to return", "schema": { "type": "integer", "minimum": 1, @@ -285,50 +284,88 @@ } }, { - "name": "since", + "name": "lang", "in": "query", "required": false, - "description": "Only include articles published at or after this timestamp.", + "description": "Language code (ISO 639-1)", "schema": { "type": "string", - "format": "date-time" - }, - "examples": { - "recent": { - "value": "2026-02-01T00:00:00Z" - } + "default": "en" + } + }, + { + "name": "country", + "in": "query", + "required": false, + "description": "Country code (ISO 3166-1 alpha-2)", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 2 + } + }, + { + "name": "from", + "in": "query", + "required": false, + "description": "Lower bound publication date (inclusive)", + "schema": { + "type": "string", + "format": "date" + } + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "Upper bound publication date (inclusive)", + "schema": { + "type": "string", + "format": "date" } }, { "name": "sort", "in": "query", "required": false, - "description": "Sort mode.", + "description": "Sorting strategy", "schema": { "type": "string", "enum": [ - "relevancy", + "relevance", "date" ], - "default": "relevancy" + "default": "relevance" } } ], "responses": { "200": { - "description": "News results.", + "description": "News results", "headers": { "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" + "description": "Unique request identifier", + "schema": { + "type": "string" + } }, "X-RateLimit-Limit": { - "$ref": "#/components/headers/X-RateLimit-Limit" + "description": "Requests allowed in the current window", + "schema": { + "type": "integer" + } }, "X-RateLimit-Remaining": { - "$ref": "#/components/headers/X-RateLimit-Remaining" + "description": "Remaining requests in the current window", + "schema": { + "type": "integer" + } }, "X-RateLimit-Reset": { - "$ref": "#/components/headers/X-RateLimit-Reset" + "description": "Unix epoch seconds when window resets", + "schema": { + "type": "integer" + } } }, "content": { @@ -339,35 +376,32 @@ "examples": { "success": { "value": { - "query": "base developer grants", - "took_ms": 167, - "total": 2, - "results": [ + "query": "base layer 2 ecosystem funding", + "articles": [ { - "title": "Base Expands Developer Grants Program", - "url": "https://queryx.run/mock/news/base-grants-expansion", - "snippet": "The grants initiative adds new tracks for infrastructure and education.", - "source": "Queryx Mock News", - "outlet": "Queryx Daily", - "published_at": "2026-03-02T07:11:18Z", - "score": 0.96, - "category": "technology" + "title": "L2 startup raises growth round", + "url": "https://example.com/l2-funding-round", + "snippet": "A Base-native infrastructure company announced a new funding round for ecosystem expansion.", + "source": "example.com", + "published_at": "2026-02-19T08:24:00Z", + "image_url": "https://example.com/image.jpg" }, { - "title": "How Builders Are Using Base Grant Funding", - "url": "https://queryx.run/mock/news/base-grants-case-studies", - "snippet": "Interview-driven piece on successful grant-funded teams.", - "source": "Queryx Mock News", - "outlet": "Builder Wire", - "published_at": "2026-03-01T14:20:00Z", - "score": 0.89, - "category": "business" + "title": "Institutional interest in L2s increases", + "url": "https://example.com/institutional-l2-interest", + "snippet": "Analysts cite lower settlement costs and improving tooling as growth drivers.", + "source": "example.com", + "published_at": "2026-02-18T14:02:00Z", + "image_url": null } ], - "cost": { + "took_ms": 198, + "request_id": "req_8490ba42a2e14c44", + "billing": { + "endpoint": "/v1/search/news", "asset": "USDC", - "amount_base_units": "4000", - "amount": "0.004" + "amount_base_units": "7500", + "amount": "0.0075" } } } @@ -379,7 +413,7 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationFailed" + "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -393,11 +427,16 @@ "/v1/search/deep": { "post": { "tags": [ - "Deep" + "research" ], - "summary": "Deep research", - "description": "Performs multi-step retrieval and synthesis with citations.", "operationId": "deepSearch", + "summary": "Deep research search", + "description": "Runs multi-hop retrieval and synthesis for complex research queries.", + "x-pricing": { + "asset": "USDC", + "usdc_base_units": "25000", + "usdc_human": "0.025" + }, "requestBody": { "required": true, "content": { @@ -406,14 +445,17 @@ "$ref": "#/components/schemas/DeepSearchRequest" }, "examples": { - "default": { + "basic": { "value": { - "query": "What are the main risks and opportunities for Base ecosystem startups in 2026?", - "max_results": 12, - "search_depth": "standard", - "include_news": true, - "include_citations": true, - "freshness": "month" + "query": "Compare retrieval-augmented generation frameworks for production observability", + "max_depth": 2, + "max_branches": 4, + "max_results": 20, + "time_range": "365d", + "include_domains": [ + "example.com", + "example.org" + ] } } } @@ -422,19 +464,31 @@ }, "responses": { "200": { - "description": "Deep research report.", + "description": "Deep research results", "headers": { "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" + "description": "Unique request identifier", + "schema": { + "type": "string" + } }, "X-RateLimit-Limit": { - "$ref": "#/components/headers/X-RateLimit-Limit" + "description": "Requests allowed in the current window", + "schema": { + "type": "integer" + } }, "X-RateLimit-Remaining": { - "$ref": "#/components/headers/X-RateLimit-Remaining" + "description": "Remaining requests in the current window", + "schema": { + "type": "integer" + } }, "X-RateLimit-Reset": { - "$ref": "#/components/headers/X-RateLimit-Reset" + "description": "Unix epoch seconds when window resets", + "schema": { + "type": "integer" + } } }, "content": { @@ -445,50 +499,57 @@ "examples": { "success": { "value": { - "query": "What are the main risks and opportunities for Base ecosystem startups in 2026?", - "answer": "The dominant opportunity is distribution leverage via wallet-native channels and stablecoin rails, while the dominant risk is margin compression in undifferentiated tooling segments.", - "key_findings": [ - "Developer tooling remains crowded, forcing differentiation via workflow depth and enterprise features.", - "Consumer apps with built-in onchain payments are showing stronger retention than utility-only products.", - "Compliance and treasury operations are becoming a larger share of total startup cost." - ], - "citations": [ + "query": "Compare retrieval-augmented generation frameworks for production observability", + "summary": "Framework A offers strong tracing integrations and lower operational complexity, while Framework B provides broader connector coverage but requires more custom instrumentation.", + "findings": [ { - "title": "2026 Base Builder Landscape", - "url": "https://queryx.run/mock/research/base-builder-landscape-2026", - "snippet": "Annual report covering funding, retention, and monetization by segment.", - "source": "Queryx Mock Research", - "published_at": "2026-02-20T09:30:00Z" + "title": "Operational visibility is the biggest differentiator", + "analysis": "Teams selecting a framework for long-term production use prioritize traceability, cache introspection, and replay tooling over pure benchmark throughput.", + "confidence": 0.91, + "citation_ids": [ + 1, + 2 + ] }, { - "title": "Stablecoin Settlement Trends on Base", - "url": "https://queryx.run/mock/research/base-stablecoin-settlement", - "snippet": "Quarterly analysis of transaction volume and business use-cases.", - "source": "Queryx Mock Research", - "published_at": "2026-02-28T15:02:00Z" + "title": "Connector ecosystem impacts time-to-value", + "analysis": "Framework B has more built-in connectors but less opinionated defaults, increasing implementation variance.", + "confidence": 0.84, + "citation_ids": [ + 3 + ] } ], - "results": [ + "citations": [ + { + "id": 1, + "title": "Observability patterns in modern RAG systems", + "url": "https://example.com/rag-observability", + "snippet": "Tracing and evaluation loops reduce production incidents and debugging time.", + "source": "example.com", + "published_at": "2025-09-10T12:00:00Z" + }, { - "title": "Base Builder Landscape 2026", - "url": "https://queryx.run/mock/research/base-builder-landscape-2026", - "snippet": "Survey and metrics for startup outcomes on Base.", - "source": "Queryx Mock Research", - "published_at": "2026-02-20T09:30:00Z", - "score": 0.95 + "id": 2, + "title": "Production lessons from RAG deployments", + "url": "https://example.org/rag-lessons", + "snippet": "Latency and quality regressions are easiest to catch with continuous offline and online evals.", + "source": "example.org", + "published_at": "2026-01-12T08:15:00Z" }, { - "title": "Stablecoin Settlement Trends on Base", - "url": "https://queryx.run/mock/research/base-stablecoin-settlement", - "snippet": "Analysis of onchain payment growth.", - "source": "Queryx Mock Research", - "published_at": "2026-02-28T15:02:00Z", - "score": 0.9 + "id": 3, + "title": "Comparing connector ecosystems", + "url": "https://example.net/connector-ecosystems", + "snippet": "Connector breadth can accelerate pilots but increases maintenance surface area.", + "source": "example.net", + "published_at": "2025-12-02T16:44:00Z" } ], - "took_ms": 1320, - "total": 12, - "cost": { + "took_ms": 1683, + "request_id": "req_1f2b53f8c6e248f5", + "billing": { + "endpoint": "/v1/search/deep", "asset": "USDC", "amount_base_units": "25000", "amount": "0.025" @@ -503,7 +564,7 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationFailed" + "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -521,237 +582,51 @@ "type": "apiKey", "in": "header", "name": "X-PAYMENT", - "description": "Base64url-encoded x402 payment envelope signed by the payer wallet. Required for paid endpoints." - } - }, - "headers": { - "X-Request-Id": { - "description": "Request correlation id.", - "schema": { - "type": "string" - } - }, - "X-RateLimit-Limit": { - "description": "Allowed requests in the current rate-limit window.", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "description": "Remaining requests in the current rate-limit window.", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "description": "Unix timestamp when the current rate-limit window resets.", - "schema": { - "type": "integer" - } - }, - "Retry-After": { - "description": "Seconds to wait before retrying.", - "schema": { - "type": "integer", - "minimum": 1 - } - }, - "X-402-Required": { - "description": "Set to true when payment is required.", - "schema": { - "type": "boolean" - } - }, - "X-402-Challenge": { - "description": "Base64url-encoded x402 challenge JSON used to construct a payment envelope.", - "schema": { - "type": "string" - } - } - }, - "responses": { - "PaymentRequired": { - "description": "Payment required. Retry the same request with a valid x402 payment envelope.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" - }, - "X-402-Required": { - "$ref": "#/components/headers/X-402-Required" - }, - "X-402-Challenge": { - "$ref": "#/components/headers/X-402-Challenge" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PaymentRequiredError" - }, - "examples": { - "paymentRequired": { - "value": { - "error": { - "code": "PAYMENT_REQUIRED", - "message": "Valid x402 payment is required for this endpoint.", - "request_id": "req_402_a12f09" - }, - "payment": { - "scheme": "x402", - "network": "base", - "asset": "USDC", - "decimals": 6, - "amount_base_units": "2500", - "amount": "0.0025", - "facilitator_address": "0x5A6f7A2b9f7B92E8d6A55E2d88cbf8EeCd8A4B13", - "pay_to": "0xD4D1A8F4c37a0eaD8B61B7f957f9f93f8AA3d815", - "nonce": "n_4fc31ced33", - "expires_at": "2026-03-04T12:45:00Z", - "request_hash": "0x9b9be318c8659e8ec9f49de22f77fd62b745cecc6f6ec9d4fa0d4f6cf15d2a40" - } - } - } - } - } - } - }, - "ValidationFailed": { - "description": "Validation failed.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ValidationError" - }, - "examples": { - "invalidInput": { - "value": { - "error": { - "code": "VALIDATION_ERROR", - "message": "One or more fields are invalid.", - "request_id": "req_422_93f1c8", - "details": [ - { - "path": "q", - "message": "q must be at least 1 character." - } - ] - } - } - } - } - } - } - }, - "TooManyRequests": { - "description": "Rate limit exceeded.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" - }, - "Retry-After": { - "$ref": "#/components/headers/Retry-After" - }, - "X-RateLimit-Limit": { - "$ref": "#/components/headers/X-RateLimit-Limit" - }, - "X-RateLimit-Remaining": { - "$ref": "#/components/headers/X-RateLimit-Remaining" - }, - "X-RateLimit-Reset": { - "$ref": "#/components/headers/X-RateLimit-Reset" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RateLimitError" - }, - "examples": { - "rateLimited": { - "value": { - "error": { - "code": "RATE_LIMITED", - "message": "Rate limit exceeded. Retry later.", - "request_id": "req_429_7723c1" - }, - "retry_after_seconds": 8 - } - } - } - } - } - }, - "InternalServerError": { - "description": "Unexpected server-side error.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/X-Request-Id" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InternalError" - }, - "examples": { - "internal": { - "value": { - "error": { - "code": "INTERNAL_ERROR", - "message": "Unexpected server error.", - "request_id": "req_500_5fca11" - } - } - } - } - } - } + "description": "x402 payment envelope. Format: x402... Payload must include method/path/query/body hash, amount, asset, chain_id, timestamp, nonce, and signer address." } }, "schemas": { "HealthResponse": { "type": "object", - "additionalProperties": false, "required": [ "status", + "service", "version", - "uptime_s", - "now" + "uptime_s" ], "properties": { "status": { "type": "string", "enum": [ - "ok" + "ok", + "degraded" ] }, + "service": { + "type": "string" + }, "version": { "type": "string" }, "uptime_s": { "type": "integer", "minimum": 0 - }, - "now": { - "type": "string", - "format": "date-time" } - } + }, + "additionalProperties": false }, - "Cost": { + "BillingSummary": { "type": "object", - "additionalProperties": false, "required": [ + "endpoint", "asset", "amount_base_units", "amount" ], "properties": { + "endpoint": { + "type": "string" + }, "asset": { "type": "string", "enum": [ @@ -766,11 +641,11 @@ "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" } - } + }, + "additionalProperties": false }, - "SearchResult": { + "SearchResultItem": { "type": "object", - "additionalProperties": false, "required": [ "title", "url", @@ -802,40 +677,56 @@ "minimum": 0, "maximum": 1 } - } + }, + "additionalProperties": false }, - "NewsResult": { - "allOf": [ - { - "$ref": "#/components/schemas/SearchResult" + "SearchResponse": { + "type": "object", + "required": [ + "query", + "results", + "took_ms", + "request_id", + "billing" + ], + "properties": { + "query": { + "type": "string" }, - { - "type": "object", - "additionalProperties": false, - "required": [ - "outlet", - "category" - ], - "properties": { - "outlet": { - "type": "string" - }, - "category": { - "type": "string" - } + "answer": { + "type": [ + "string", + "null" + ] + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResultItem" } + }, + "took_ms": { + "type": "integer", + "minimum": 0 + }, + "request_id": { + "type": "string" + }, + "billing": { + "$ref": "#/components/schemas/BillingSummary" } - ] + }, + "additionalProperties": false }, - "Citation": { + "NewsArticle": { "type": "object", - "additionalProperties": false, "required": [ "title", "url", "snippet", "source", - "published_at" + "published_at", + "image_url" ], "properties": { "title": { @@ -854,146 +745,193 @@ "published_at": { "type": "string", "format": "date-time" + }, + "image_url": { + "type": [ + "string", + "null" + ], + "format": "uri" } - } + }, + "additionalProperties": false }, - "WebSearchResponse": { + "NewsSearchResponse": { "type": "object", - "additionalProperties": false, "required": [ "query", + "articles", "took_ms", - "total", - "results", - "cost" + "request_id", + "billing" ], "properties": { "query": { "type": "string" }, - "took_ms": { - "type": "integer", - "minimum": 0 + "articles": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsArticle" + } }, - "total": { + "took_ms": { "type": "integer", "minimum": 0 }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchResult" - } + "request_id": { + "type": "string" }, - "cost": { - "$ref": "#/components/schemas/Cost" + "billing": { + "$ref": "#/components/schemas/BillingSummary" } - } + }, + "additionalProperties": false }, - "NewsSearchResponse": { + "DeepSearchRequest": { "type": "object", - "additionalProperties": false, "required": [ - "query", - "took_ms", - "total", - "results", - "cost" + "query" ], "properties": { "query": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 1000 }, - "took_ms": { + "max_depth": { "type": "integer", - "minimum": 0 + "minimum": 1, + "maximum": 5, + "default": 2 }, - "total": { + "max_branches": { "type": "integer", - "minimum": 0 + "minimum": 1, + "maximum": 10, + "default": 4 }, - "results": { + "max_results": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "time_range": { + "type": "string", + "enum": [ + "24h", + "7d", + "30d", + "365d", + "all" + ], + "default": "365d" + }, + "include_domains": { "type": "array", "items": { - "$ref": "#/components/schemas/NewsResult" - } + "type": "string" + }, + "maxItems": 50 }, - "cost": { - "$ref": "#/components/schemas/Cost" + "exclude_domains": { + "type": "array", + "items": { + "type": "string" + }, + "maxItems": 50 } - } + }, + "additionalProperties": false }, - "DeepSearchRequest": { + "DeepFinding": { "type": "object", - "additionalProperties": false, "required": [ - "query" + "title", + "analysis", + "confidence", + "citation_ids" ], "properties": { - "query": { - "type": "string", - "minLength": 1, - "maxLength": 2000 + "title": { + "type": "string" }, - "max_results": { + "analysis": { + "type": "string" + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "citation_ids": { + "type": "array", + "items": { + "type": "integer", + "minimum": 1 + } + } + }, + "additionalProperties": false + }, + "Citation": { + "type": "object", + "required": [ + "id", + "title", + "url", + "snippet", + "source", + "published_at" + ], + "properties": { + "id": { "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 + "minimum": 1 }, - "search_depth": { + "title": { + "type": "string" + }, + "url": { "type": "string", - "enum": [ - "quick", - "standard", - "exhaustive" - ], - "default": "standard" + "format": "uri" }, - "include_news": { - "type": "boolean", - "default": true + "snippet": { + "type": "string" }, - "include_citations": { - "type": "boolean", - "default": true + "source": { + "type": "string" }, - "freshness": { + "published_at": { "type": "string", - "enum": [ - "any", - "day", - "week", - "month" - ], - "default": "month" + "format": "date-time" } - } + }, + "additionalProperties": false }, "DeepSearchResponse": { "type": "object", - "additionalProperties": false, "required": [ "query", - "answer", - "key_findings", + "summary", + "findings", "citations", - "results", "took_ms", - "total", - "cost" + "request_id", + "billing" ], "properties": { "query": { "type": "string" }, - "answer": { + "summary": { "type": "string" }, - "key_findings": { + "findings": { "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/DeepFinding" } }, "citations": { @@ -1002,198 +940,306 @@ "$ref": "#/components/schemas/Citation" } }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchResult" - } - }, "took_ms": { "type": "integer", "minimum": 0 }, - "total": { - "type": "integer", - "minimum": 0 + "request_id": { + "type": "string" }, - "cost": { - "$ref": "#/components/schemas/Cost" + "billing": { + "$ref": "#/components/schemas/BillingSummary" } - } + }, + "additionalProperties": false }, - "ValidationIssue": { + "ValidationError": { "type": "object", - "additionalProperties": false, "required": [ - "path", + "field", "message" ], "properties": { - "path": { + "field": { "type": "string" }, "message": { "type": "string" } - } + }, + "additionalProperties": false }, - "ErrorObject": { + "RateLimitDetails": { "type": "object", - "additionalProperties": false, "required": [ - "code", - "message", - "request_id" + "limit", + "remaining", + "reset_epoch_seconds", + "retry_after_seconds" ], "properties": { - "code": { - "type": "string" - }, - "message": { - "type": "string" + "limit": { + "type": "integer", + "minimum": 1 }, - "request_id": { - "type": "string" + "remaining": { + "type": "integer", + "minimum": 0 }, - "details": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ValidationIssue" - } - } - } - }, - "ErrorEnvelope": { - "type": "object", - "additionalProperties": false, - "required": [ - "error" - ], - "properties": { - "error": { - "$ref": "#/components/schemas/ErrorObject" - } - } - }, - "ValidationError": { - "allOf": [ - { - "$ref": "#/components/schemas/ErrorEnvelope" - } - ] - }, - "RateLimitError": { - "allOf": [ - { - "$ref": "#/components/schemas/ErrorEnvelope" + "reset_epoch_seconds": { + "type": "integer", + "minimum": 0 }, - { - "type": "object", - "additionalProperties": false, - "required": [ - "retry_after_seconds" - ], - "properties": { - "retry_after_seconds": { - "type": "integer", - "minimum": 1 - } - } + "retry_after_seconds": { + "type": "integer", + "minimum": 1 } - ] + }, + "additionalProperties": false }, - "PaymentRequirement": { + "PaymentRequiredDetails": { "type": "object", - "additionalProperties": false, "required": [ - "scheme", - "network", "asset", - "decimals", - "amount_base_units", - "amount", + "chain_id", "facilitator_address", - "pay_to", - "nonce", + "required_amount_base_units", + "required_amount", "expires_at", - "request_hash" + "reason" ], "properties": { - "scheme": { - "type": "string", - "enum": [ - "x402" - ] - }, - "network": { - "type": "string", - "enum": [ - "base" - ] - }, "asset": { "type": "string", "enum": [ "USDC" ] }, - "decimals": { + "chain_id": { "type": "integer", "enum": [ - 6 + 8453 ] }, - "amount_base_units": { + "facilitator_address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + }, + "required_amount_base_units": { "type": "string", "pattern": "^[0-9]+$" }, - "amount": { + "required_amount": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, - "facilitator_address": { - "type": "string" + "expires_at": { + "type": "string", + "format": "date-time" }, - "pay_to": { + "reason": { + "type": "string" + } + }, + "additionalProperties": false + }, + "ErrorObject": { + "type": "object", + "required": [ + "code", + "message", + "status", + "request_id", + "retryable" + ], + "properties": { + "code": { "type": "string" }, - "nonce": { + "message": { "type": "string" }, - "expires_at": { - "type": "string", - "format": "date-time" + "status": { + "type": "integer" }, - "request_hash": { + "request_id": { "type": "string" + }, + "retryable": { + "type": "boolean" + }, + "payment": { + "oneOf": [ + { + "$ref": "#/components/schemas/PaymentRequiredDetails" + }, + { + "type": "null" + } + ] + }, + "validation_errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationError" + } + }, + "rate_limit": { + "oneOf": [ + { + "$ref": "#/components/schemas/RateLimitDetails" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "ErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "$ref": "#/components/schemas/ErrorObject" + } + }, + "additionalProperties": false + } + }, + "responses": { + "PaymentRequired": { + "description": "Payment is required or payment envelope is invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "paymentRequired": { + "value": { + "error": { + "code": "payment_required", + "message": "Valid x402 payment required for this endpoint.", + "status": 402, + "request_id": "req_8f9982136bbd43db", + "retryable": true, + "payment": { + "asset": "USDC", + "chain_id": 8453, + "facilitator_address": "0x6A0F1C8A3B5D5BA43B2E2B4A4B8D7C9A5E4F0123", + "required_amount_base_units": "5000", + "required_amount": "0.005", + "expires_at": "2026-03-04T12:00:00Z", + "reason": "missing_or_invalid_payment_header" + }, + "validation_errors": [], + "rate_limit": null + } + } + } + } } } }, - "PaymentRequiredError": { - "allOf": [ - { - "$ref": "#/components/schemas/ErrorEnvelope" - }, - { - "type": "object", - "additionalProperties": false, - "required": [ - "payment" - ], - "properties": { - "payment": { - "$ref": "#/components/schemas/PaymentRequirement" + "UnprocessableEntity": { + "description": "Request validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "validation": { + "value": { + "error": { + "code": "validation_error", + "message": "Invalid request parameters.", + "status": 422, + "request_id": "req_3ab11ed8f2df4d58", + "retryable": false, + "payment": null, + "validation_errors": [ + { + "field": "q", + "message": "q is required" + } + ], + "rate_limit": null + } + } } } } - ] + } }, - "InternalError": { - "allOf": [ - { - "$ref": "#/components/schemas/ErrorEnvelope" + "TooManyRequests": { + "description": "Rate limit exceeded.", + "headers": { + "Retry-After": { + "description": "Seconds until the next retry is allowed", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "rateLimit": { + "value": { + "error": { + "code": "rate_limited", + "message": "Rate limit exceeded.", + "status": 429, + "request_id": "req_64c0b35b7f934624", + "retryable": true, + "payment": null, + "validation_errors": [], + "rate_limit": { + "limit": 120, + "remaining": 0, + "reset_epoch_seconds": 1772629800, + "retry_after_seconds": 18 + } + } + } + } + } } - ] + } + }, + "InternalServerError": { + "description": "Unexpected internal server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "serverError": { + "value": { + "error": { + "code": "internal_error", + "message": "Unexpected internal error.", + "status": 500, + "request_id": "req_7f8f87e2d1554c84", + "retryable": true, + "payment": null, + "validation_errors": [], + "rate_limit": null + } + } + } + } + } + } } } } From 3352e9f6e0803d11109f6cbd3db4ba8dbcd8f978 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:23:44 +0000 Subject: [PATCH 07/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 938 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 715 insertions(+), 223 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index fa975dc..f3b33e3 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -4,7 +4,7 @@ "info": { "title": "Queryx API", "version": "1.0.0", - "description": "Queryx is an x402-paid search API on Base. This spec covers web search, news search, deep research, and health endpoints." + "description": "Queryx provides paid web search, news search, and deep research endpoints secured with x402 payment headers." }, "servers": [ { @@ -14,43 +14,44 @@ ], "tags": [ { - "name": "System", - "description": "Service status and health operations." + "name": "system", + "description": "Service status endpoints" }, { - "name": "Search", - "description": "Paid search and research endpoints secured by x402." - } - ], - "security": [ + "name": "search", + "description": "Web and news search endpoints" + }, { - "x402": [] + "name": "research", + "description": "Multi-source deep research endpoint" } ], "paths": { "/health": { "get": { "tags": [ - "System" + "system" ], "summary": "Health check", - "description": "Returns service liveness and basic runtime metadata.", "operationId": "getHealth", - "security": [], "responses": { "200": { - "description": "Service is healthy.", + "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, - "example": { - "status": "ok", - "service": "queryx", - "version": "1.0.0", - "timestamp": "2026-03-04T12:00:00Z", - "uptime_seconds": 86423 + "examples": { + "ok": { + "value": { + "status": "ok", + "service": "queryx", + "version": "1.0.0", + "timestamp": "2026-03-04T12:00:00Z", + "uptime_seconds": 987654 + } + } } } } @@ -64,69 +65,59 @@ "/v1/search": { "get": { "tags": [ - "Search" + "search" ], - "summary": "Web search", - "description": "Search the web and optionally return a concise synthesized answer with citations.", + "summary": "Search the web", "operationId": "searchWeb", "security": [ { "x402": [] } ], - "x-pricing": { - "asset": "USDC", - "chain": "base", - "cost_base_units": 1000, - "cost_usdc": "0.001" - }, "parameters": [ { - "$ref": "#/components/parameters/XPaymentHeader" + "$ref": "#/components/parameters/QParam" }, { - "$ref": "#/components/parameters/XPaymentSignatureHeader" - }, - { - "$ref": "#/components/parameters/XPaymentTimestampHeader" + "$ref": "#/components/parameters/LimitParam" }, { - "$ref": "#/components/parameters/XPaymentAddressHeader" + "$ref": "#/components/parameters/LangParam" }, { - "$ref": "#/components/parameters/QueryParam" + "$ref": "#/components/parameters/RegionParam" }, { - "$ref": "#/components/parameters/CountryParam" + "$ref": "#/components/parameters/SafeSearchParam" }, { - "$ref": "#/components/parameters/LanguageParam" + "$ref": "#/components/parameters/IncludeAnswerParam" }, { - "$ref": "#/components/parameters/FreshnessParam" + "$ref": "#/components/parameters/IncludeRawParam" }, { - "$ref": "#/components/parameters/LimitParam" + "$ref": "#/components/parameters/XPaymentHeader" }, { - "$ref": "#/components/parameters/PageParam" + "$ref": "#/components/parameters/XPaymentSignatureHeader" }, { - "$ref": "#/components/parameters/IncludeAnswerParam" + "$ref": "#/components/parameters/XPaymentAddressHeader" } ], "responses": { "200": { - "description": "Successful web search response.", + "description": "Search results", "headers": { "X-RateLimit-Limit": { - "$ref": "#/components/headers/RateLimitLimitHeader" + "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { - "$ref": "#/components/headers/RateLimitRemainingHeader" + "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { - "$ref": "#/components/headers/RateLimitResetHeader" + "$ref": "#/components/headers/XRateLimitReset" } }, "content": { @@ -134,48 +125,49 @@ "schema": { "$ref": "#/components/schemas/SearchResponse" }, - "example": { - "object": "search.result", - "id": "srch_01HQX4AHQ3W3H8W9CC61J0M2VE", - "query": "latest base network ecosystem updates", - "answer": "Base ecosystem activity continues to grow, with tooling and agent integrations expanding in early 2026.", - "results": [ - { - "position": 1, - "title": "Queryx", - "url": "https://queryx.run", - "snippet": "x402-paid search API on Base for web, news, and deep research.", - "source": "queryx", - "relevance": 0.98, - "published_at": "2026-03-02T16:00:00Z" - }, - { - "position": 2, - "title": "Queryx health endpoint", - "url": "https://queryx.run", - "snippet": "Use /health to verify service status before issuing paid calls.", - "source": "queryx", - "relevance": 0.77, - "published_at": null - } - ], - "citations": [ - { - "index": 1, - "title": "Queryx", - "url": "https://queryx.run" + "examples": { + "default": { + "value": { + "request_id": "req_01JNSD8SDAXA3WB5S4J95A0QWF", + "query": "best vector database for rag", + "took_ms": 412, + "answer": "For most teams, PostgreSQL + pgvector or Qdrant are strong choices for RAG based on cost/performance and ecosystem.", + "results": [ + { + "title": "Qdrant Documentation", + "url": "https://qdrant.tech/documentation/", + "snippet": "Qdrant is an open-source vector database and similarity search engine.", + "source": "qdrant.tech", + "score": 0.93, + "published_at": null + }, + { + "title": "pgvector README", + "url": "https://github.com/pgvector/pgvector", + "snippet": "Open-source vector similarity search for Postgres.", + "source": "github.com", + "score": 0.9, + "published_at": null + } + ], + "usage": { + "endpoint": "/v1/search", + "billed_units": 1, + "price_usdc_base_units": "2500", + "price_usdc": "0.0025" + }, + "payment": { + "payment_id": "pay_01JNSD8SP7RRA9TNDQXG1HVB7K", + "network": "base", + "asset": "USDC", + "amount_base_units": "2500", + "amount_usdc": "0.0025", + "facilitator": "0x0000000000000000000000000000000000000402", + "tx_hash": "0x3f84e5f80ba67f932fd91935f1f2f640ef0f69f6ab8da53f50dd6842e8f5bc61", + "settled_at": "2026-03-04T12:01:02Z" + } } - ], - "usage": { - "endpoint": "/v1/search", - "query_units": 1, - "cost_base_units": 1000, - "cost_usdc": "0.001", - "latency_ms": 241, - "rate_limit_remaining": 119, - "request_id": "req_01HQX4AHZ4A3H9N81YE60P5N0R" - }, - "generated_at": "2026-03-04T12:00:01Z" + } } } } @@ -184,7 +176,7 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationFailed" + "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" @@ -198,75 +190,56 @@ "/v1/search/news": { "get": { "tags": [ - "Search" + "search" ], - "summary": "News search", - "description": "Search current news articles with publication metadata.", + "summary": "Search recent news", "operationId": "searchNews", "security": [ { "x402": [] } ], - "x-pricing": { - "asset": "USDC", - "chain": "base", - "cost_base_units": 2000, - "cost_usdc": "0.002" - }, "parameters": [ { - "$ref": "#/components/parameters/XPaymentHeader" - }, - { - "$ref": "#/components/parameters/XPaymentSignatureHeader" - }, - { - "$ref": "#/components/parameters/XPaymentTimestampHeader" - }, - { - "$ref": "#/components/parameters/XPaymentAddressHeader" + "$ref": "#/components/parameters/QParam" }, { - "$ref": "#/components/parameters/QueryParam" + "$ref": "#/components/parameters/NewsLimitParam" }, { - "$ref": "#/components/parameters/TopicParam" + "$ref": "#/components/parameters/LangParam" }, { - "$ref": "#/components/parameters/LanguageParam" + "$ref": "#/components/parameters/RegionParam" }, { - "$ref": "#/components/parameters/CountryParam" + "$ref": "#/components/parameters/SinceParam" }, { - "$ref": "#/components/parameters/FromDateParam" - }, - { - "$ref": "#/components/parameters/ToDateParam" + "$ref": "#/components/parameters/SortParam" }, { - "$ref": "#/components/parameters/SortParam" + "$ref": "#/components/parameters/XPaymentHeader" }, { - "$ref": "#/components/parameters/LimitParam" + "$ref": "#/components/parameters/XPaymentSignatureHeader" }, { - "$ref": "#/components/parameters/PageParam" + "$ref": "#/components/parameters/XPaymentAddressHeader" } ], "responses": { "200": { - "description": "Successful news search response.", + "description": "News search results", "headers": { "X-RateLimit-Limit": { - "$ref": "#/components/headers/RateLimitLimitHeader" + "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { - "$ref": "#/components/headers/RateLimitRemainingHeader" + "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { - "$ref": "#/components/headers/RateLimitResetHeader" + "$ref": "#/components/headers/XRateLimitReset" } }, "content": { @@ -274,33 +247,46 @@ "schema": { "$ref": "#/components/schemas/NewsSearchResponse" }, - "example": { - "object": "news.search.result", - "id": "news_01HQX4B04TRT1P9CFQJFKM1D8B", - "query": "agent infrastructure", - "clusters": 3, - "results": [ - { - "position": 1, - "title": "Queryx ships OpenAPI docs", - "url": "https://queryx.run", - "snippet": "The Queryx API now includes a complete OpenAPI 3.1 specification.", - "publisher": "Queryx", - "published_at": "2026-03-04T08:20:00Z", - "category": "technology", - "image_url": null + "examples": { + "default": { + "value": { + "request_id": "req_01JNSDAN1QY39WQ2S6P7JZG8KS", + "query": "base ecosystem funding round", + "took_ms": 528, + "results": [ + { + "title": "New Base ecosystem startup raises seed round", + "url": "https://example.com/news/base-startup-seed-round", + "snippet": "A startup building on Base announced a new funding round led by...", + "source": "example.com", + "published_at": "2026-03-03T15:20:00Z" + }, + { + "title": "VC activity grows on Base-aligned projects", + "url": "https://example.com/news/base-vc-activity", + "snippet": "Investors are increasing allocations to Base-native tooling...", + "source": "example.com", + "published_at": "2026-03-02T08:00:00Z" + } + ], + "usage": { + "endpoint": "/v1/search/news", + "billed_units": 1, + "price_usdc_base_units": "3000", + "price_usdc": "0.0030" + }, + "payment": { + "payment_id": "pay_01JNSDAN8DZQW0D5M7G7E59BP9", + "network": "base", + "asset": "USDC", + "amount_base_units": "3000", + "amount_usdc": "0.0030", + "facilitator": "0x0000000000000000000000000000000000000402", + "tx_hash": "0x18806a8ef213813be9160ef8d53df8692d75af47ded9ad4ac07661808f020d33", + "settled_at": "2026-03-04T12:05:44Z" + } } - ], - "usage": { - "endpoint": "/v1/search/news", - "query_units": 1, - "cost_base_units": 2000, - "cost_usdc": "0.002", - "latency_ms": 319, - "rate_limit_remaining": 89, - "request_id": "req_01HQX4B09QH6WJXRW7EGWQ4W0N" - }, - "generated_at": "2026-03-04T12:00:02Z" + } } } } @@ -309,7 +295,7 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationFailed" + "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" @@ -323,22 +309,15 @@ "/v1/search/deep": { "post": { "tags": [ - "Search" + "research" ], - "summary": "Deep research search", - "description": "Run a multi-source deep research workflow and return structured sections, supporting evidence, and takeaways.", + "summary": "Deep multi-source research", "operationId": "deepSearch", "security": [ { "x402": [] } ], - "x-pricing": { - "asset": "USDC", - "chain": "base", - "cost_base_units": 15000, - "cost_usdc": "0.015" - }, "parameters": [ { "$ref": "#/components/parameters/XPaymentHeader" @@ -346,14 +325,8 @@ { "$ref": "#/components/parameters/XPaymentSignatureHeader" }, - { - "$ref": "#/components/parameters/XPaymentTimestampHeader" - }, { "$ref": "#/components/parameters/XPaymentAddressHeader" - }, - { - "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { @@ -363,28 +336,36 @@ "schema": { "$ref": "#/components/schemas/DeepSearchRequest" }, - "example": { - "query": "What are the primary trade-offs between web-scale retrieval quality and response latency?", - "depth": "standard", - "max_sources": 25, - "include_raw_content": false, - "freshness": "month" + "examples": { + "default": { + "value": { + "query": "Compare retrieval quality tradeoffs between BM25, dense vectors, and hybrid search for enterprise support docs.", + "depth": "deep", + "max_sources": 30, + "include_citations": true, + "include_snippets": true, + "time_range": { + "from": "2023-01-01T00:00:00Z", + "to": "2026-03-04T00:00:00Z" + } + } + } } } } }, "responses": { "200": { - "description": "Successful deep research response.", + "description": "Deep research result", "headers": { "X-RateLimit-Limit": { - "$ref": "#/components/headers/RateLimitLimitHeader" + "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { - "$ref": "#/components/headers/RateLimitRemainingHeader" + "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { - "$ref": "#/components/headers/RateLimitResetHeader" + "$ref": "#/components/headers/XRateLimitReset" } }, "content": { @@ -392,50 +373,74 @@ "schema": { "$ref": "#/components/schemas/DeepSearchResponse" }, - "example": { - "object": "deep.search.result", - "id": "deep_01HQX4B3AV4EV8A9J3PDQARQ6N", - "query": "What are the primary trade-offs between web-scale retrieval quality and response latency?", - "executive_summary": "Higher retrieval quality usually requires broader candidate generation and heavier reranking, increasing latency and cost. Practical systems tune these with adaptive depth and caching.", - "sections": [ - { - "heading": "Latency vs relevance", - "summary": "Increasing candidate set size improves recall but can slow response time without tiered ranking.", - "evidence": [ + "examples": { + "default": { + "value": { + "request_id": "req_01JNSDGK2Y8NXM3XB95MG9Q1N4", + "query": "Compare retrieval quality tradeoffs between BM25, dense vectors, and hybrid search for enterprise support docs.", + "took_ms": 8242, + "summary": "Hybrid retrieval consistently improves recall for enterprise support corpora while preserving precision, especially when sparse lexical signals and dense semantic embeddings are both available.", + "findings": [ + { + "statement": "BM25 excels on exact term matching and fresh keyword-heavy content.", + "confidence": 0.88, + "citation_ids": [ + "c1", + "c3" + ] + }, + { + "statement": "Dense retrieval improves semantic recall for paraphrased user questions.", + "confidence": 0.91, + "citation_ids": [ + "c2", + "c4" + ] + }, { - "claim": "Two-stage retrieval commonly balances quality and speed.", - "source_index": 1, - "confidence": 0.89 + "statement": "Hybrid rank fusion generally outperforms either method in isolation on support QA benchmarks.", + "confidence": 0.93, + "citation_ids": [ + "c1", + "c2", + "c5" + ] } - ] - } - ], - "sources": [ - { - "index": 1, - "title": "Queryx", - "url": "https://queryx.run", - "snippet": "Queryx deep search endpoint for structured research output.", - "domain": "queryx.run", - "published_at": "2026-03-01T00:00:00Z", - "raw_content": null + ], + "citations": [ + { + "id": "c1", + "title": "Benchmarking hybrid retrieval for enterprise QA", + "url": "https://example.com/research/hybrid-retrieval-benchmark", + "excerpt": "Hybrid models improved nDCG@10 across 8 out of 9 datasets.", + "published_at": "2025-11-02T10:00:00Z" + }, + { + "id": "c2", + "title": "Dense vs sparse retrieval in customer support", + "url": "https://example.com/research/dense-vs-sparse-support", + "excerpt": "Dense methods recovered semantically related tickets missed by BM25.", + "published_at": "2025-08-14T09:15:00Z" + } + ], + "usage": { + "endpoint": "/v1/search/deep", + "billed_units": 1, + "price_usdc_base_units": "15000", + "price_usdc": "0.0150" + }, + "payment": { + "payment_id": "pay_01JNSDGK8A3DBS9VVT4E16D8AJ", + "network": "base", + "asset": "USDC", + "amount_base_units": "15000", + "amount_usdc": "0.0150", + "facilitator": "0x0000000000000000000000000000000000000402", + "tx_hash": "0xfc8f9db4fc6b1f68bc6eec80a0f40dbfb22f4c83883be3c38f11f8e9c2ea6d83", + "settled_at": "2026-03-04T12:10:11Z" + } } - ], - "takeaways": [ - "Use adaptive depth to reduce tail latency.", - "Cache stable sources and summaries.", - "Reserve comprehensive mode for high-value prompts." - ], - "usage": { - "endpoint": "/v1/search/deep", - "query_units": 1, - "cost_base_units": 15000, - "cost_usdc": "0.015", - "latency_ms": 1429, - "rate_limit_remaining": 29, - "request_id": "req_01HQX4B3CZ8WQ1SHX2R7XJ3A21" - }, - "generated_at": "2026-03-04T12:00:03Z" + } } } } @@ -444,7 +449,7 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/ValidationFailed" + "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" @@ -462,18 +467,505 @@ "type": "apiKey", "in": "header", "name": "X-Payment", - "description": "x402 payment payload (base64-encoded JSON). Also send X-Payment-Signature, X-Payment-Timestamp, and X-Payment-Address headers.", - "x-x402": { - "chain": "base", - "chain_id": 8453, - "asset": "USDC", - "facilitator_address": "0x9a2fE0f2f5f4A8E4f6D8dD68fAecbf3A4aB1aE52" - } + "description": "x402 payment envelope. Send together with X-Payment-Signature and X-Payment-Address." } }, "parameters": { + "QParam": { + "name": "q", + "in": "query", + "required": true, + "description": "Search query string.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "examples": { + "default": { + "value": "latest updates on retrieval augmented generation" + } + } + }, + "LimitParam": { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of web results.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "default": 10 + }, + "examples": { + "default": { + "value": 10 + } + } + }, + "NewsLimitParam": { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of news results.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + } + }, + "LangParam": { + "name": "lang", + "in": "query", + "required": false, + "description": "Language hint (BCP-47 style, e.g. en or en-US).", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 10, + "default": "en" + } + }, + "RegionParam": { + "name": "region", + "in": "query", + "required": false, + "description": "Regional market hint (e.g. US, EU).", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 16 + } + }, + "SafeSearchParam": { + "name": "safe_search", + "in": "query", + "required": false, + "description": "Safe search level.", + "schema": { + "type": "string", + "enum": [ + "off", + "moderate", + "strict" + ], + "default": "moderate" + } + }, + "IncludeAnswerParam": { + "name": "include_answer", + "in": "query", + "required": false, + "description": "Whether to include generated answer text.", + "schema": { + "type": "boolean", + "default": true + } + }, + "IncludeRawParam": { + "name": "include_raw", + "in": "query", + "required": false, + "description": "Whether to include raw provider metadata (if available).", + "schema": { + "type": "boolean", + "default": false + } + }, + "SinceParam": { + "name": "since", + "in": "query", + "required": false, + "description": "Only include news newer than this timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + "SortParam": { + "name": "sort", + "in": "query", + "required": false, + "description": "Sort strategy for news results.", + "schema": { + "type": "string", + "enum": [ + "relevance", + "date" + ], + "default": "relevance" + } + }, "XPaymentHeader": { "name": "X-Payment", "in": "header", "required": false, - "description": "Base64-encoded x402 payment payload JSON. Required on paid requests after receiving a \ No newline at end of file + "description": "Base64-encoded JSON payment envelope returned by a prior 402 response.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "XPaymentSignatureHeader": { + "name": "X-Payment-Signature", + "in": "header", + "required": false, + "description": "Wallet signature for the x402 signing payload.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "XPaymentAddressHeader": { + "name": "X-Payment-Address", + "in": "header", + "required": false, + "description": "Hex wallet address used to sign the payment payload.", + "schema": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + } + } + }, + "headers": { + "XRateLimitLimit": { + "description": "Requests allowed in the current window.", + "schema": { + "type": "integer" + } + }, + "XRateLimitRemaining": { + "description": "Remaining requests in the current window.", + "schema": { + "type": "integer" + } + }, + "XRateLimitReset": { + "description": "Unix timestamp when the current rate-limit window resets.", + "schema": { + "type": "integer" + } + } + }, + "responses": { + "PaymentRequired": { + "description": "Payment required; sign payload and retry with x402 headers.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentRequiredErrorResponse" + }, + "examples": { + "payment_required": { + "value": { + "request_id": "req_01JNSDRR2J5ATV5SWH5SDSV6P8", + "timestamp": "2026-03-04T12:12:00Z", + "error": { + "code": "payment_required", + "message": "This endpoint requires x402 payment." + }, + "payment_requirement": { + "scheme": "x402", + "network": "base", + "asset": "USDC", + "asset_address": "0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913", + "amount_base_units": "2500", + "amount_usdc": "0.0025", + "facilitator": "0x0000000000000000000000000000000000000402", + "payment_id": "pay_01JNSDRR5E6H0E9RWRP50WKTNE", + "expires_at": "2026-03-04T12:14:00Z", + "nonce": "ea5f22f8-f31f-4231-909a-dc68f1a1f31d", + "signature": { + "algorithm": "eip191", + "payload": "x402|pay_01JNSDRR5E6H0E9RWRP50WKTNE|2500|USDC|base|2026-03-04T12:14:00Z|ea5f22f8-f31f-4231-909a-dc68f1a1f31d", + "typed_data": null + } + } + } + } + } + } + } + }, + "ValidationError": { + "description": "Request validation failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorResponse" + }, + "examples": { + "invalid_query": { + "value": { + "request_id": "req_01JNSDSW2G0H4R6P2G7HP4AWDZ", + "timestamp": "2026-03-04T12:13:01Z", + "error": { + "code": "validation_error", + "message": "Invalid request parameters.", + "fields": [ + { + "field": "q", + "message": "q is required." + } + ] + } + } + } + } + } + } + }, + "RateLimitExceeded": { + "description": "Too many requests", + "headers": { + "Retry-After": { + "description": "Seconds before retrying.", + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Limit": { + "$ref": "#/components/headers/XRateLimitLimit" + }, + "X-RateLimit-Remaining": { + "$ref": "#/components/headers/XRateLimitRemaining" + }, + "X-RateLimit-Reset": { + "$ref": "#/components/headers/XRateLimitReset" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitErrorResponse" + }, + "examples": { + "rate_limited": { + "value": { + "request_id": "req_01JNSDTQWPVTT0Q8TQ3M8EJY50", + "timestamp": "2026-03-04T12:14:21Z", + "error": { + "code": "rate_limited", + "message": "Rate limit exceeded.", + "retry_after_seconds": 8 + } + } + } + } + } + } + }, + "InternalServerError": { + "description": "Unexpected server-side error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorResponse" + }, + "examples": { + "internal_error": { + "value": { + "request_id": "req_01JNSDV4A74SKKBFA3QYQJ4FMP", + "timestamp": "2026-03-04T12:15:05Z", + "error": { + "code": "internal_error", + "message": "An unexpected error occurred." + } + } + } + } + } + } + } + }, + "schemas": { + "HealthResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "status", + "service", + "version", + "timestamp", + "uptime_seconds" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "service": { + "type": "string" + }, + "version": { + "type": "string" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "uptime_seconds": { + "type": "integer", + "minimum": 0 + } + } + }, + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "query", + "took_ms", + "results", + "usage", + "payment" + ], + "properties": { + "request_id": { + "type": "string" + }, + "query": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "minimum": 0 + }, + "answer": { + "type": [ + "string", + "null" + ] + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } + }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "payment": { + "$ref": "#/components/schemas/PaymentReceipt" + } + } + }, + "SearchResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "title", + "url", + "snippet", + "source", + "score" + ], + "properties": { + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "source": { + "type": "string" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "published_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + }, + "NewsSearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "query", + "took_ms", + "results", + "usage", + "payment" + ], + "properties": { + "request_id": { + "type": "string" + }, + "query": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "minimum": 0 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsResult" + } + }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "payment": { + "$ref": "#/components/schemas/PaymentReceipt" + } + } + }, + "NewsResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "title", + "url", + "snippet", + "source", + "published_at" + ], + "properties": { + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "source": { + "type": "string" + }, + "published_at": { + "type": "string", + "format": "date-time" + } + } + }, + "DeepSearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query" + ], + "properties": { + "query": { + " \ No newline at end of file From 8645c7c98b644ca8e61764c103f7b3ff654afd25 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:29:04 +0000 Subject: [PATCH 08/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1028 +++++++++++++++++++++++++++------------------ 1 file changed, 623 insertions(+), 405 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index f3b33e3..9917079 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,10 +1,13 @@ === FILE: openapi.json === { + "$schema": "https://spec.openapis.org/oas/3.1/dialect/base", "openapi": "3.1.0", + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", - "version": "1.0.0", - "description": "Queryx provides paid web search, news search, and deep research endpoints secured with x402 payment headers." + "summary": "x402-native web search, news search, and deep research API", + "description": "Queryx provides low-latency web and news search plus deep research endpoints with x402 USDC micropayments on Base.", + "version": "1.0.0" }, "servers": [ { @@ -14,26 +17,23 @@ ], "tags": [ { - "name": "system", - "description": "Service status endpoints" + "name": "Health", + "description": "Service status endpoint" }, { - "name": "search", - "description": "Web and news search endpoints" - }, - { - "name": "research", - "description": "Multi-source deep research endpoint" + "name": "Search", + "description": "Web, news, and deep research search endpoints" } ], "paths": { "/health": { "get": { "tags": [ - "system" + "Health" ], - "summary": "Health check", "operationId": "getHealth", + "summary": "Health check", + "description": "Returns current service health and version information.", "responses": { "200": { "description": "Service is healthy", @@ -43,13 +43,13 @@ "$ref": "#/components/schemas/HealthResponse" }, "examples": { - "ok": { + "healthy": { "value": { "status": "ok", "service": "queryx", "version": "1.0.0", - "timestamp": "2026-03-04T12:00:00Z", - "uptime_seconds": 987654 + "uptime_seconds": 43812, + "timestamp": "2026-03-04T12:00:00Z" } } } @@ -57,7 +57,7 @@ } }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } @@ -65,10 +65,11 @@ "/v1/search": { "get": { "tags": [ - "search" + "Search" ], - "summary": "Search the web", "operationId": "searchWeb", + "summary": "Web search", + "description": "Runs a standard web search query. Paid endpoint secured by x402.", "security": [ { "x402": [] @@ -76,96 +77,89 @@ ], "parameters": [ { - "$ref": "#/components/parameters/QParam" + "$ref": "#/components/parameters/Query" + }, + { + "$ref": "#/components/parameters/Limit" }, { - "$ref": "#/components/parameters/LimitParam" + "$ref": "#/components/parameters/Offset" }, { - "$ref": "#/components/parameters/LangParam" + "$ref": "#/components/parameters/Language" }, { - "$ref": "#/components/parameters/RegionParam" + "$ref": "#/components/parameters/Country" }, { - "$ref": "#/components/parameters/SafeSearchParam" + "$ref": "#/components/parameters/SafeSearch" }, { - "$ref": "#/components/parameters/IncludeAnswerParam" + "$ref": "#/components/parameters/XPayment" }, { - "$ref": "#/components/parameters/IncludeRawParam" + "$ref": "#/components/parameters/XPaymentSignature" }, { - "$ref": "#/components/parameters/XPaymentHeader" + "$ref": "#/components/parameters/XPaymentAddress" }, { - "$ref": "#/components/parameters/XPaymentSignatureHeader" + "$ref": "#/components/parameters/XPaymentTimestamp" }, { - "$ref": "#/components/parameters/XPaymentAddressHeader" + "$ref": "#/components/parameters/XPaymentNonce" } ], "responses": { "200": { - "description": "Search results", - "headers": { - "X-RateLimit-Limit": { - "$ref": "#/components/headers/XRateLimitLimit" - }, - "X-RateLimit-Remaining": { - "$ref": "#/components/headers/XRateLimitRemaining" - }, - "X-RateLimit-Reset": { - "$ref": "#/components/headers/XRateLimitReset" - } - }, + "description": "Search results returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { - "default": { + "basicSearch": { "value": { - "request_id": "req_01JNSD8SDAXA3WB5S4J95A0QWF", - "query": "best vector database for rag", - "took_ms": 412, - "answer": "For most teams, PostgreSQL + pgvector or Qdrant are strong choices for RAG based on cost/performance and ecosystem.", + "request_id": "11a5ad0a-6de7-46a3-a76f-864d476fc74f", + "query": "best open source vector databases", + "count": 3, + "took_ms": 142, "results": [ { - "title": "Qdrant Documentation", - "url": "https://qdrant.tech/documentation/", - "snippet": "Qdrant is an open-source vector database and similarity search engine.", - "source": "qdrant.tech", - "score": 0.93, - "published_at": null + "id": "res_01", + "title": "Top Open Source Vector Databases in 2026", + "url": "https://example.com/vector-db-list", + "snippet": "A comparison of Milvus, Qdrant, Weaviate, and pgvector with benchmarks.", + "source": "example.com", + "published_at": "2026-02-12T10:05:00Z", + "score": 0.97, + "favicon_url": "https://example.com/favicon.ico", + "language": "en" + }, + { + "id": "res_02", + "title": "Milvus vs Qdrant: Feature Breakdown", + "url": "https://example.org/milvus-vs-qdrant", + "snippet": "Detailed comparison across indexing types, filtering, and hybrid search.", + "source": "example.org", + "published_at": "2026-01-03T08:00:00Z", + "score": 0.91, + "favicon_url": null, + "language": "en" }, { - "title": "pgvector README", - "url": "https://github.com/pgvector/pgvector", - "snippet": "Open-source vector similarity search for Postgres.", - "source": "github.com", - "score": 0.9, - "published_at": null + "id": "res_03", + "title": "pgvector for Production Search", + "url": "https://example.net/pgvector-production-guide", + "snippet": "How teams deploy pgvector for semantic retrieval in PostgreSQL.", + "source": "example.net", + "published_at": null, + "score": 0.86, + "favicon_url": null, + "language": "en" } - ], - "usage": { - "endpoint": "/v1/search", - "billed_units": 1, - "price_usdc_base_units": "2500", - "price_usdc": "0.0025" - }, - "payment": { - "payment_id": "pay_01JNSD8SP7RRA9TNDQXG1HVB7K", - "network": "base", - "asset": "USDC", - "amount_base_units": "2500", - "amount_usdc": "0.0025", - "facilitator": "0x0000000000000000000000000000000000000402", - "tx_hash": "0x3f84e5f80ba67f932fd91935f1f2f640ef0f69f6ab8da53f50dd6842e8f5bc61", - "settled_at": "2026-03-04T12:01:02Z" - } + ] } } } @@ -179,10 +173,10 @@ "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/RateLimitExceeded" + "$ref": "#/components/responses/RateLimitError" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } @@ -190,10 +184,11 @@ "/v1/search/news": { "get": { "tags": [ - "search" + "Search" ], - "summary": "Search recent news", "operationId": "searchNews", + "summary": "News search", + "description": "Runs a freshness-biased news query. Paid endpoint secured by x402.", "security": [ { "x402": [] @@ -201,90 +196,84 @@ ], "parameters": [ { - "$ref": "#/components/parameters/QParam" + "$ref": "#/components/parameters/Query" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/Language" }, { - "$ref": "#/components/parameters/NewsLimitParam" + "$ref": "#/components/parameters/Country" }, { - "$ref": "#/components/parameters/LangParam" + "$ref": "#/components/parameters/NewsFrom" }, { - "$ref": "#/components/parameters/RegionParam" + "$ref": "#/components/parameters/NewsTo" }, { - "$ref": "#/components/parameters/SinceParam" + "$ref": "#/components/parameters/NewsSort" }, { - "$ref": "#/components/parameters/SortParam" + "$ref": "#/components/parameters/XPayment" }, { - "$ref": "#/components/parameters/XPaymentHeader" + "$ref": "#/components/parameters/XPaymentSignature" }, { - "$ref": "#/components/parameters/XPaymentSignatureHeader" + "$ref": "#/components/parameters/XPaymentAddress" }, { - "$ref": "#/components/parameters/XPaymentAddressHeader" + "$ref": "#/components/parameters/XPaymentTimestamp" + }, + { + "$ref": "#/components/parameters/XPaymentNonce" } ], "responses": { "200": { - "description": "News search results", - "headers": { - "X-RateLimit-Limit": { - "$ref": "#/components/headers/XRateLimitLimit" - }, - "X-RateLimit-Remaining": { - "$ref": "#/components/headers/XRateLimitRemaining" - }, - "X-RateLimit-Reset": { - "$ref": "#/components/headers/XRateLimitReset" - } - }, + "description": "News results returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSearchResponse" }, "examples": { - "default": { + "newsSearch": { "value": { - "request_id": "req_01JNSDAN1QY39WQ2S6P7JZG8KS", - "query": "base ecosystem funding round", - "took_ms": 528, + "request_id": "f7f10c7a-1518-4418-8a97-fa25d449bc4e", + "query": "fed interest rate decision", + "count": 2, + "took_ms": 169, "results": [ { - "title": "New Base ecosystem startup raises seed round", - "url": "https://example.com/news/base-startup-seed-round", - "snippet": "A startup building on Base announced a new funding round led by...", - "source": "example.com", - "published_at": "2026-03-03T15:20:00Z" + "id": "news_01", + "title": "Federal Reserve Holds Rates Steady", + "url": "https://news.example.com/fed-holds-rates", + "snippet": "The central bank kept rates unchanged in a widely expected decision.", + "source": "news.example.com", + "published_at": "2026-03-03T18:30:00Z", + "image_url": "https://news.example.com/images/fed.jpg", + "category": "business", + "language": "en" }, { - "title": "VC activity grows on Base-aligned projects", - "url": "https://example.com/news/base-vc-activity", - "snippet": "Investors are increasing allocations to Base-native tooling...", - "source": "example.com", - "published_at": "2026-03-02T08:00:00Z" + "id": "news_02", + "title": "Markets React to Fed Guidance", + "url": "https://finance.example.org/market-reaction-fed", + "snippet": "Stocks moved higher after comments on inflation trends.", + "source": "finance.example.org", + "published_at": "2026-03-03T20:05:00Z", + "image_url": null, + "category": "finance", + "language": "en" } - ], - "usage": { - "endpoint": "/v1/search/news", - "billed_units": 1, - "price_usdc_base_units": "3000", - "price_usdc": "0.0030" - }, - "payment": { - "payment_id": "pay_01JNSDAN8DZQW0D5M7G7E59BP9", - "network": "base", - "asset": "USDC", - "amount_base_units": "3000", - "amount_usdc": "0.0030", - "facilitator": "0x0000000000000000000000000000000000000402", - "tx_hash": "0x18806a8ef213813be9160ef8d53df8692d75af47ded9ad4ac07661808f020d33", - "settled_at": "2026-03-04T12:05:44Z" - } + ] } } } @@ -298,10 +287,10 @@ "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/RateLimitExceeded" + "$ref": "#/components/responses/RateLimitError" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } @@ -309,10 +298,11 @@ "/v1/search/deep": { "post": { "tags": [ - "research" + "Search" ], - "summary": "Deep multi-source research", - "operationId": "deepSearch", + "operationId": "searchDeep", + "summary": "Deep research search", + "description": "Runs multi-step retrieval and synthesis to return a grounded answer with citations. Paid endpoint secured by x402.", "security": [ { "x402": [] @@ -320,13 +310,19 @@ ], "parameters": [ { - "$ref": "#/components/parameters/XPaymentHeader" + "$ref": "#/components/parameters/XPayment" }, { - "$ref": "#/components/parameters/XPaymentSignatureHeader" + "$ref": "#/components/parameters/XPaymentSignature" }, { - "$ref": "#/components/parameters/XPaymentAddressHeader" + "$ref": "#/components/parameters/XPaymentAddress" + }, + { + "$ref": "#/components/parameters/XPaymentTimestamp" + }, + { + "$ref": "#/components/parameters/XPaymentNonce" } ], "requestBody": { @@ -337,16 +333,24 @@ "$ref": "#/components/schemas/DeepSearchRequest" }, "examples": { - "default": { + "deepResearchRequest": { "value": { - "query": "Compare retrieval quality tradeoffs between BM25, dense vectors, and hybrid search for enterprise support docs.", - "depth": "deep", - "max_sources": 30, - "include_citations": true, - "include_snippets": true, - "time_range": { - "from": "2023-01-01T00:00:00Z", - "to": "2026-03-04T00:00:00Z" + "query": "Compare RAG chunking strategies for long technical manuals", + "max_sources": 12, + "max_depth": 2, + "include_domains": [ + "arxiv.org", + "acm.org", + "docs.example.com" + ], + "exclude_domains": [ + "pinterest.com" + ], + "response_format": "markdown", + "citations": true, + "context": { + "audience": "engineering manager", + "target_length": "short" } } } @@ -356,88 +360,54 @@ }, "responses": { "200": { - "description": "Deep research result", - "headers": { - "X-RateLimit-Limit": { - "$ref": "#/components/headers/XRateLimitLimit" - }, - "X-RateLimit-Remaining": { - "$ref": "#/components/headers/XRateLimitRemaining" - }, - "X-RateLimit-Reset": { - "$ref": "#/components/headers/XRateLimitReset" - } - }, + "description": "Deep research response returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearchResponse" }, "examples": { - "default": { + "deepResearchResponse": { "value": { - "request_id": "req_01JNSDGK2Y8NXM3XB95MG9Q1N4", - "query": "Compare retrieval quality tradeoffs between BM25, dense vectors, and hybrid search for enterprise support docs.", - "took_ms": 8242, - "summary": "Hybrid retrieval consistently improves recall for enterprise support corpora while preserving precision, especially when sparse lexical signals and dense semantic embeddings are both available.", - "findings": [ - { - "statement": "BM25 excels on exact term matching and fresh keyword-heavy content.", - "confidence": 0.88, - "citation_ids": [ - "c1", - "c3" - ] - }, + "request_id": "b4f32c3f-72d7-4f79-8f2d-420611f2b2c7", + "query": "Compare RAG chunking strategies for long technical manuals", + "summary": "Structure-aware chunking with semantic overlap is consistently strongest for long manuals.", + "answer": "Across long technical manuals, fixed-size chunking is simplest but loses section semantics and cross-reference context. Structure-aware chunking aligned to headings improves factual grounding and citation precision. Semantic chunking can improve recall but must be constrained by max token budgets and overlap windows. The best production pattern is structure-first chunking with adaptive overlap for tables/procedures, then reranking before final synthesis.", + "took_ms": 1894, + "citations": [ { - "statement": "Dense retrieval improves semantic recall for paraphrased user questions.", - "confidence": 0.91, - "citation_ids": [ - "c2", - "c4" - ] + "id": "c1", + "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks", + "url": "https://arxiv.org/abs/2005.11401", + "quote": "Chunk granularity significantly impacts retrieval relevance and generation quality." }, { - "statement": "Hybrid rank fusion generally outperforms either method in isolation on support QA benchmarks.", - "confidence": 0.93, - "citation_ids": [ - "c1", - "c2", - "c5" - ] + "id": "c2", + "title": "Practical Considerations for Document Chunking in RAG Systems", + "url": "https://example.com/rag-chunking-practical-guide", + "quote": "Heading-aware segmentation reduces context fragmentation in long-form documents." } ], - "citations": [ + "sources": [ { - "id": "c1", - "title": "Benchmarking hybrid retrieval for enterprise QA", - "url": "https://example.com/research/hybrid-retrieval-benchmark", - "excerpt": "Hybrid models improved nDCG@10 across 8 out of 9 datasets.", - "published_at": "2025-11-02T10:00:00Z" + "id": "s1", + "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks", + "url": "https://arxiv.org/abs/2005.11401", + "source_type": "paper", + "snippet": "The model combines parametric and non-parametric memory via retrieval." }, { - "id": "c2", - "title": "Dense vs sparse retrieval in customer support", - "url": "https://example.com/research/dense-vs-sparse-support", - "excerpt": "Dense methods recovered semantically related tickets missed by BM25.", - "published_at": "2025-08-14T09:15:00Z" + "id": "s2", + "title": "Practical Considerations for Document Chunking in RAG Systems", + "url": "https://example.com/rag-chunking-practical-guide", + "source_type": "article", + "snippet": "Structure-aware chunking is robust under strict context limits." } ], "usage": { - "endpoint": "/v1/search/deep", - "billed_units": 1, - "price_usdc_base_units": "15000", - "price_usdc": "0.0150" - }, - "payment": { - "payment_id": "pay_01JNSDGK8A3DBS9VVT4E16D8AJ", - "network": "base", - "asset": "USDC", - "amount_base_units": "15000", - "amount_usdc": "0.0150", - "facilitator": "0x0000000000000000000000000000000000000402", - "tx_hash": "0xfc8f9db4fc6b1f68bc6eec80a0f40dbfb22f4c83883be3c38f11f8e9c2ea6d83", - "settled_at": "2026-03-04T12:10:11Z" + "request_units": 1, + "sources_considered": 12, + "sources_used": 5 } } } @@ -452,10 +422,10 @@ "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/RateLimitExceeded" + "$ref": "#/components/responses/RateLimitError" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } @@ -467,83 +437,79 @@ "type": "apiKey", "in": "header", "name": "X-Payment", - "description": "x402 payment envelope. Send together with X-Payment-Signature and X-Payment-Address." + "description": "x402 payment envelope (base64url encoded JSON). Include X-Payment, X-Payment-Signature, X-Payment-Address, X-Payment-Timestamp, and X-Payment-Nonce for paid requests.", + "x-protocol": "x402", + "x-network": "base", + "x-currency": "USDC" } }, "parameters": { - "QParam": { + "Query": { "name": "q", "in": "query", "required": true, - "description": "Search query string.", + "description": "Search query text.", "schema": { "type": "string", "minLength": 1, - "maxLength": 512 + "maxLength": 1000 }, - "examples": { - "default": { - "value": "latest updates on retrieval augmented generation" - } - } + "example": "latest breakthroughs in battery technology" }, - "LimitParam": { + "Limit": { "name": "limit", "in": "query", "required": false, - "description": "Maximum number of web results.", + "description": "Maximum number of results to return.", "schema": { "type": "integer", "minimum": 1, - "maximum": 20, + "maximum": 50, "default": 10 }, - "examples": { - "default": { - "value": 10 - } - } + "example": 10 }, - "NewsLimitParam": { - "name": "limit", + "Offset": { + "name": "offset", "in": "query", "required": false, - "description": "Maximum number of news results.", + "description": "Result offset for pagination.", "schema": { "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 - } + "minimum": 0, + "maximum": 1000, + "default": 0 + }, + "example": 0 }, - "LangParam": { + "Language": { "name": "lang", "in": "query", "required": false, - "description": "Language hint (BCP-47 style, e.g. en or en-US).", + "description": "Language code, for example en or en-US.", "schema": { "type": "string", - "minLength": 2, - "maxLength": 10, + "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "default": "en" - } + }, + "example": "en" }, - "RegionParam": { - "name": "region", + "Country": { + "name": "country", "in": "query", "required": false, - "description": "Regional market hint (e.g. US, EU).", + "description": "Country code in ISO-3166 alpha-2 format.", "schema": { "type": "string", - "minLength": 2, - "maxLength": 16 - } + "pattern": "^[A-Z]{2}$" + }, + "example": "US" }, - "SafeSearchParam": { + "SafeSearch": { "name": "safe_search", "in": "query", "required": false, - "description": "Safe search level.", + "description": "Safe search filter level.", "schema": { "type": "string", "enum": [ @@ -552,136 +518,125 @@ "strict" ], "default": "moderate" - } - }, - "IncludeAnswerParam": { - "name": "include_answer", - "in": "query", - "required": false, - "description": "Whether to include generated answer text.", - "schema": { - "type": "boolean", - "default": true - } + }, + "example": "moderate" }, - "IncludeRawParam": { - "name": "include_raw", + "NewsFrom": { + "name": "from", "in": "query", "required": false, - "description": "Whether to include raw provider metadata (if available).", + "description": "Return news published on or after this timestamp.", "schema": { - "type": "boolean", - "default": false - } + "type": "string", + "format": "date-time" + }, + "example": "2026-03-01T00:00:00Z" }, - "SinceParam": { - "name": "since", + "NewsTo": { + "name": "to", "in": "query", "required": false, - "description": "Only include news newer than this timestamp.", + "description": "Return news published on or before this timestamp.", "schema": { "type": "string", "format": "date-time" - } + }, + "example": "2026-03-04T23:59:59Z" }, - "SortParam": { + "NewsSort": { "name": "sort", "in": "query", "required": false, - "description": "Sort strategy for news results.", + "description": "Sort order for news results.", "schema": { "type": "string", "enum": [ "relevance", - "date" + "latest" ], "default": "relevance" - } + }, + "example": "latest" }, - "XPaymentHeader": { + "XPayment": { "name": "X-Payment", "in": "header", "required": false, - "description": "Base64-encoded JSON payment envelope returned by a prior 402 response.", + "description": "x402 payment envelope as base64url(JSON). Required for paid request settlement.", "schema": { "type": "string", - "minLength": 1 + "minLength": 16 } }, - "XPaymentSignatureHeader": { + "XPaymentSignature": { "name": "X-Payment-Signature", "in": "header", "required": false, - "description": "Wallet signature for the x402 signing payload.", + "description": "secp256k1 signature over canonical request string.", "schema": { "type": "string", - "minLength": 1 + "minLength": 16 } }, - "XPaymentAddressHeader": { + "XPaymentAddress": { "name": "X-Payment-Address", "in": "header", "required": false, - "description": "Hex wallet address used to sign the payment payload.", + "description": "Payer wallet address on Base.", "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" - } - } - }, - "headers": { - "XRateLimitLimit": { - "description": "Requests allowed in the current window.", - "schema": { - "type": "integer" - } + }, + "example": "0x5b38Da6a701c568545dCfcB03FcB875f56beddC4" }, - "XRateLimitRemaining": { - "description": "Remaining requests in the current window.", + "XPaymentTimestamp": { + "name": "X-Payment-Timestamp", + "in": "header", + "required": false, + "description": "Unix timestamp (seconds) used in canonical signature.", "schema": { - "type": "integer" - } + "type": "integer", + "minimum": 1700000000 + }, + "example": 1772625600 }, - "XRateLimitReset": { - "description": "Unix timestamp when the current rate-limit window resets.", + "XPaymentNonce": { + "name": "X-Payment-Nonce", + "in": "header", + "required": false, + "description": "Client-generated unique nonce for replay protection.", "schema": { - "type": "integer" - } + "type": "string", + "minLength": 8, + "maxLength": 128 + }, + "example": "e7f1f403-4f11-4d9f-92f2-3f62c9acb5ee" } }, "responses": { "PaymentRequired": { - "description": "Payment required; sign payload and retry with x402 headers.", + "description": "Payment is required before this request can be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredErrorResponse" }, "examples": { - "payment_required": { + "paymentRequired": { "value": { - "request_id": "req_01JNSDRR2J5ATV5SWH5SDSV6P8", - "timestamp": "2026-03-04T12:12:00Z", + "request_id": "1c108f27-6154-4ee8-b6b1-72db6a93e83d", "error": { "code": "payment_required", - "message": "This endpoint requires x402 payment." + "message": "x402 payment required for this endpoint.", + "details": null }, - "payment_requirement": { - "scheme": "x402", + "payment": { "network": "base", "asset": "USDC", - "asset_address": "0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913", - "amount_base_units": "2500", - "amount_usdc": "0.0025", - "facilitator": "0x0000000000000000000000000000000000000402", - "payment_id": "pay_01JNSDRR5E6H0E9RWRP50WKTNE", - "expires_at": "2026-03-04T12:14:00Z", - "nonce": "ea5f22f8-f31f-4231-909a-dc68f1a1f31d", - "signature": { - "algorithm": "eip191", - "payload": "x402|pay_01JNSDRR5E6H0E9RWRP50WKTNE|2500|USDC|base|2026-03-04T12:14:00Z|ea5f22f8-f31f-4231-909a-dc68f1a1f31d", - "typed_data": null - } + "amount": "2500", + "amount_decimal": "0.0025", + "facilitator": "0x8fF5d1A6B7C35E4a2f90Aa64b1D9fA41A6a6b0C2", + "expires_at": "2026-03-04T12:01:00Z" } } } @@ -690,50 +645,42 @@ } }, "ValidationError": { - "description": "Request validation failed", + "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { - "invalid_query": { + "invalidQuery": { "value": { - "request_id": "req_01JNSDSW2G0H4R6P2G7HP4AWDZ", - "timestamp": "2026-03-04T12:13:01Z", + "request_id": "fcb16e8f-8f29-4f8d-b62a-37a8d5dd22d2", "error": { "code": "validation_error", - "message": "Invalid request parameters.", - "fields": [ - { - "field": "q", - "message": "q is required." - } - ] - } + "message": "Request validation failed.", + "details": null + }, + "errors": [ + { + "field": "q", + "message": "Query must be at least 1 character." + } + ] } } } } } }, - "RateLimitExceeded": { - "description": "Too many requests", + "RateLimitError": { + "description": "Rate limit exceeded.", "headers": { "Retry-After": { - "description": "Seconds before retrying.", + "description": "Seconds until another request may be attempted.", "schema": { - "type": "integer" + "type": "integer", + "minimum": 1 } - }, - "X-RateLimit-Limit": { - "$ref": "#/components/headers/XRateLimitLimit" - }, - "X-RateLimit-Remaining": { - "$ref": "#/components/headers/XRateLimitRemaining" - }, - "X-RateLimit-Reset": { - "$ref": "#/components/headers/XRateLimitReset" } }, "content": { @@ -742,36 +689,38 @@ "$ref": "#/components/schemas/RateLimitErrorResponse" }, "examples": { - "rate_limited": { + "tooManyRequests": { "value": { - "request_id": "req_01JNSDTQWPVTT0Q8TQ3M8EJY50", - "timestamp": "2026-03-04T12:14:21Z", + "request_id": "dce2e194-4229-4f04-8f34-a43b4eb7f436", "error": { "code": "rate_limited", "message": "Rate limit exceeded.", - "retry_after_seconds": 8 - } + "details": null + }, + "retry_after_ms": 2000, + "limit": 120, + "window_ms": 60000 } } } } } }, - "InternalServerError": { - "description": "Unexpected server-side error", + "InternalError": { + "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponse" }, "examples": { - "internal_error": { + "internalError": { "value": { - "request_id": "req_01JNSDV4A74SKKBFA3QYQJ4FMP", - "timestamp": "2026-03-04T12:15:05Z", + "request_id": "e0cd9e63-8b15-4d6f-9421-4ec14f75be80", "error": { "code": "internal_error", - "message": "An unexpected error occurred." + "message": "Unexpected internal error.", + "details": null } } } @@ -788,8 +737,8 @@ "status", "service", "version", - "timestamp", - "uptime_seconds" + "uptime_seconds", + "timestamp" ], "properties": { "status": { @@ -799,18 +748,79 @@ ] }, "service": { - "type": "string" + "type": "string", + "example": "queryx" }, "version": { - "type": "string" - }, - "timestamp": { "type": "string", - "format": "date-time" + "example": "1.0.0" }, "uptime_seconds": { "type": "integer", "minimum": 0 + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + } + }, + "SearchResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "title", + "url", + "snippet", + "source", + "published_at", + "score", + "favicon_url", + "language" + ], + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "snippet": { + "type": "string" + }, + "source": { + "type": "string" + }, + "published_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "favicon_url": { + "type": [ + "string", + "null" + ], + "format": "uri" + }, + "language": { + "type": [ + "string", + "null" + ], + "pattern": "^[a-z]{2}(-[A-Z]{2})?$" } } }, @@ -820,53 +830,52 @@ "required": [ "request_id", "query", + "count", "took_ms", - "results", - "usage", - "payment" + "results" ], "properties": { "request_id": { - "type": "string" + "type": "string", + "format": "uuid" }, "query": { "type": "string" }, - "took_ms": { + "count": { "type": "integer", "minimum": 0 }, - "answer": { - "type": [ - "string", - "null" - ] + "took_ms": { + "type": "integer", + "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } - }, - "usage": { - "$ref": "#/components/schemas/Usage" - }, - "payment": { - "$ref": "#/components/schemas/PaymentReceipt" } } }, - "SearchResult": { + "NewsResult": { "type": "object", "additionalProperties": false, "required": [ + "id", "title", "url", "snippet", "source", - "score" + "published_at", + "image_url", + "category", + "language" ], "properties": { + "id": { + "type": "string" + }, "title": { "type": "string" }, @@ -880,17 +889,29 @@ "source": { "type": "string" }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, "published_at": { + "type": "string", + "format": "date-time" + }, + "image_url": { "type": [ "string", "null" ], - "format": "date-time" + "format": "uri" + }, + "category": { + "type": [ + "string", + "null" + ] + }, + "language": { + "type": [ + "string", + "null" + ], + "pattern": "^[a-z]{2}(-[A-Z]{2})?$" } } }, @@ -900,18 +921,22 @@ "required": [ "request_id", "query", + "count", "took_ms", - "results", - "usage", - "payment" + "results" ], "properties": { "request_id": { - "type": "string" + "type": "string", + "format": "uuid" }, "query": { "type": "string" }, + "count": { + "type": "integer", + "minimum": 0 + }, "took_ms": { "type": "integer", "minimum": 0 @@ -921,26 +946,81 @@ "items": { "$ref": "#/components/schemas/NewsResult" } + } + } + }, + "DeepSearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "maxLength": 4000 }, - "usage": { - "$ref": "#/components/schemas/Usage" + "max_sources": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 12 + }, + "max_depth": { + "type": "integer", + "minimum": 1, + "maximum": 4, + "default": 2 + }, + "include_domains": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "exclude_domains": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "response_format": { + "type": "string", + "enum": [ + "markdown", + "json" + ], + "default": "markdown" + }, + "citations": { + "type": "boolean", + "default": true }, - "payment": { - "$ref": "#/components/schemas/PaymentReceipt" + "context": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "default": {} } } }, - "NewsResult": { + "DeepCitation": { "type": "object", "additionalProperties": false, "required": [ + "id", "title", "url", - "snippet", - "source", - "published_at" + "quote" ], "properties": { + "id": { + "type": "string" + }, "title": { "type": "string" }, @@ -948,24 +1028,162 @@ "type": "string", "format": "uri" }, - "snippet": { + "quote": { + "type": "string" + } + } + }, + "DeepSource": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "title", + "url", + "source_type", + "snippet" + ], + "properties": { + "id": { "type": "string" }, - "source": { + "title": { "type": "string" }, - "published_at": { + "url": { "type": "string", - "format": "date-time" + "format": "uri" + }, + "source_type": { + "type": "string", + "enum": [ + "article", + "paper", + "docs", + "other" + ] + }, + "snippet": { + "type": "string" } } }, - "DeepSearchRequest": { + "DeepUsage": { "type": "object", "additionalProperties": false, "required": [ - "query" + "request_units", + "sources_considered", + "sources_used" ], "properties": { + "request_units": { + "type": "integer", + "minimum": 1 + }, + "sources_considered": { + "type": "integer", + "minimum": 0 + }, + "sources_used": { + "type": "integer", + "minimum": 0 + } + } + }, + "DeepSearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "query", + "summary", + "answer", + "took_ms", + "citations", + "sources", + "usage" + ], + "properties": { + "request_id": { + "type": "string", + "format": "uuid" + }, "query": { - " \ No newline at end of file + "type": "string" + }, + "summary": { + "type": "string" + }, + "answer": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "minimum": 0 + }, + "citations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeepCitation" + } + }, + "sources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeepSource" + } + }, + "usage": { + "$ref": "#/components/schemas/DeepUsage" + } + } + }, + "ErrorObject": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "message", + "details" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "payment_required", + "validation_error", + "rate_limited", + "internal_error" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": [ + "object", + "null" + ], + "additionalProperties": true + } + } + }, + "BaseErrorResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "error" + ], + "properties": { + "request_id": { + "type": "string", + "format": "uuid" + }, + "error": { + "$ref": "#/components/schemas/ErrorObject" + } + } + }, + "PaymentRequirements \ No newline at end of file From 570546729e1620233b71df54cfa52c9c7c2f77fe Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:35:21 +0000 Subject: [PATCH 09/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1391 +++++++++++++++++++++++---------------------- 1 file changed, 701 insertions(+), 690 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index 9917079..32d8e71 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,14 +1,17 @@ === FILE: openapi.json === { - "$schema": "https://spec.openapis.org/oas/3.1/dialect/base", "openapi": "3.1.0", - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", "summary": "x402-native web search, news search, and deep research API", - "description": "Queryx provides low-latency web and news search plus deep research endpoints with x402 USDC micropayments on Base.", - "version": "1.0.0" + "description": "Queryx exposes paid search endpoints secured with x402 payment envelopes over Base USDC. Clients send an X-PAYMENT header for paid endpoints.", + "version": "1.0.0", + "contact": { + "name": "Queryx", + "url": "https://github.com/langoustine69/queryx" + } }, + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://queryx.run", @@ -17,23 +20,33 @@ ], "tags": [ { - "name": "Health", - "description": "Service status endpoint" + "name": "health", + "description": "Service health and readiness" + }, + { + "name": "search", + "description": "Web and news search endpoints" }, { - "name": "Search", - "description": "Web, news, and deep research search endpoints" + "name": "deep-search", + "description": "Deep research endpoint with synthesized answer and citations" + } + ], + "security": [ + { + "x402": [] } ], "paths": { "/health": { "get": { "tags": [ - "Health" + "health" ], "operationId": "getHealth", "summary": "Health check", - "description": "Returns current service health and version information.", + "description": "Returns service health, version, and uptime. This endpoint is free and does not require x402 payment.", + "security": [], "responses": { "200": { "description": "Service is healthy", @@ -48,8 +61,8 @@ "status": "ok", "service": "queryx", "version": "1.0.0", - "uptime_seconds": 43812, - "timestamp": "2026-03-04T12:00:00Z" + "timestamp": "2026-03-04T12:00:00Z", + "uptime_seconds": 86422 } } } @@ -57,7 +70,7 @@ } }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -65,101 +78,163 @@ "/v1/search": { "get": { "tags": [ - "Search" + "search" ], "operationId": "searchWeb", "summary": "Web search", - "description": "Runs a standard web search query. Paid endpoint secured by x402.", - "security": [ - { - "x402": [] - } - ], + "description": "Performs ranked web search for the provided query.", "parameters": [ { - "$ref": "#/components/parameters/Query" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/Language" - }, - { - "$ref": "#/components/parameters/Country" + "name": "q", + "in": "query", + "required": true, + "description": "Search query string.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "latest llm evaluation benchmarks" }, { - "$ref": "#/components/parameters/SafeSearch" + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of results to return.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "default": 10 + }, + "example": 10 }, { - "$ref": "#/components/parameters/XPayment" + "name": "offset", + "in": "query", + "required": false, + "description": "Pagination offset.", + "schema": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "example": 0 }, { - "$ref": "#/components/parameters/XPaymentSignature" + "name": "country", + "in": "query", + "required": false, + "description": "Optional ISO 3166-1 alpha-2 country filter.", + "schema": { + "type": "string", + "pattern": "^[A-Z]{2}$" + }, + "example": "US" }, { - "$ref": "#/components/parameters/XPaymentAddress" + "name": "lang", + "in": "query", + "required": false, + "description": "Optional ISO 639-1 language code filter.", + "schema": { + "type": "string", + "pattern": "^[a-z]{2}$" + }, + "example": "en" }, { - "$ref": "#/components/parameters/XPaymentTimestamp" + "name": "freshness", + "in": "query", + "required": false, + "description": "Time-based freshness filter.", + "schema": { + "type": "string", + "enum": [ + "any", + "day", + "week", + "month" + ], + "default": "any" + }, + "example": "week" }, { - "$ref": "#/components/parameters/XPaymentNonce" + "name": "safe_search", + "in": "query", + "required": false, + "description": "Safe search level.", + "schema": { + "type": "string", + "enum": [ + "off", + "moderate", + "strict" + ], + "default": "moderate" + }, + "example": "moderate" } ], "responses": { "200": { - "description": "Search results returned", + "description": "Search results", + "headers": { + "X-Request-Id": { + "description": "Unique request id for tracing.", + "schema": { + "type": "string" + } + }, + "X-Billed-Units": { + "description": "Amount charged in USDC base units (6 decimals).", + "schema": { + "type": "integer", + "minimum": 0 + } + } + }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { - "basicSearch": { + "webSearch": { "value": { - "request_id": "11a5ad0a-6de7-46a3-a76f-864d476fc74f", - "query": "best open source vector databases", - "count": 3, - "took_ms": 142, + "query": "latest llm evaluation benchmarks", + "count": 2, "results": [ { - "id": "res_01", - "title": "Top Open Source Vector Databases in 2026", - "url": "https://example.com/vector-db-list", - "snippet": "A comparison of Milvus, Qdrant, Weaviate, and pgvector with benchmarks.", - "source": "example.com", - "published_at": "2026-02-12T10:05:00Z", - "score": 0.97, - "favicon_url": "https://example.com/favicon.ico", - "language": "en" - }, - { - "id": "res_02", - "title": "Milvus vs Qdrant: Feature Breakdown", - "url": "https://example.org/milvus-vs-qdrant", - "snippet": "Detailed comparison across indexing types, filtering, and hybrid search.", - "source": "example.org", - "published_at": "2026-01-03T08:00:00Z", - "score": 0.91, - "favicon_url": null, - "language": "en" + "title": "State of LLM Evaluation 2026", + "url": "https://queryx.run/mock/state-of-llm-eval-2026", + "snippet": "A survey of modern benchmark design, contamination checks, and robustness criteria.", + "source": "queryx.run", + "rank": 1, + "score": 0.96, + "published_at": "2026-02-26T09:20:00Z", + "favicon_url": "https://queryx.run/mock/favicon.png" }, { - "id": "res_03", - "title": "pgvector for Production Search", - "url": "https://example.net/pgvector-production-guide", - "snippet": "How teams deploy pgvector for semantic retrieval in PostgreSQL.", - "source": "example.net", - "published_at": null, - "score": 0.86, - "favicon_url": null, - "language": "en" + "title": "Benchmark Drift in Agentic Systems", + "url": "https://queryx.run/mock/benchmark-drift-agentic-systems", + "snippet": "How long-lived systems overfit public test sets and how to detect it.", + "source": "queryx.run", + "rank": 2, + "score": 0.89, + "published_at": "2026-02-24T14:02:00Z", + "favicon_url": null } - ] + ], + "meta": { + "request_id": "req_01JNR9C4SE8X0F09M4PEKQ6W22", + "took_ms": 132, + "billed_units": 1000, + "billed_usdc": "0.001", + "limit": 10, + "offset": 0 + } } } } @@ -173,10 +248,10 @@ "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/RateLimitError" + "$ref": "#/components/responses/TooManyRequests" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -184,60 +259,127 @@ "/v1/search/news": { "get": { "tags": [ - "Search" + "search" ], "operationId": "searchNews", "summary": "News search", - "description": "Runs a freshness-biased news query. Paid endpoint secured by x402.", - "security": [ - { - "x402": [] - } - ], + "description": "Searches indexed news sources and returns ranked articles.", "parameters": [ { - "$ref": "#/components/parameters/Query" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/Language" - }, - { - "$ref": "#/components/parameters/Country" - }, - { - "$ref": "#/components/parameters/NewsFrom" + "name": "q", + "in": "query", + "required": true, + "description": "News query string.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "agentic browser updates" }, { - "$ref": "#/components/parameters/NewsTo" + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of articles to return.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + }, + "example": 10 }, { - "$ref": "#/components/parameters/NewsSort" + "name": "offset", + "in": "query", + "required": false, + "description": "Pagination offset.", + "schema": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "example": 0 }, { - "$ref": "#/components/parameters/XPayment" + "name": "country", + "in": "query", + "required": false, + "description": "Optional ISO 3166-1 alpha-2 country filter.", + "schema": { + "type": "string", + "pattern": "^[A-Z]{2}$" + }, + "example": "US" }, { - "$ref": "#/components/parameters/XPaymentSignature" + "name": "lang", + "in": "query", + "required": false, + "description": "Optional ISO 639-1 language code filter.", + "schema": { + "type": "string", + "pattern": "^[a-z]{2}$" + }, + "example": "en" }, { - "$ref": "#/components/parameters/XPaymentAddress" + "name": "from", + "in": "query", + "required": false, + "description": "Inclusive lower bound for publication time.", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-03-01T00:00:00Z" }, { - "$ref": "#/components/parameters/XPaymentTimestamp" + "name": "to", + "in": "query", + "required": false, + "description": "Inclusive upper bound for publication time.", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-03-04T23:59:59Z" }, { - "$ref": "#/components/parameters/XPaymentNonce" + "name": "sort", + "in": "query", + "required": false, + "description": "Sort strategy for news ranking.", + "schema": { + "type": "string", + "enum": [ + "relevance", + "latest" + ], + "default": "relevance" + }, + "example": "latest" } ], "responses": { "200": { - "description": "News results returned", + "description": "News search results", + "headers": { + "X-Request-Id": { + "description": "Unique request id for tracing.", + "schema": { + "type": "string" + } + }, + "X-Billed-Units": { + "description": "Amount charged in USDC base units (6 decimals).", + "schema": { + "type": "integer", + "minimum": 0 + } + } + }, "content": { "application/json": { "schema": { @@ -246,34 +388,41 @@ "examples": { "newsSearch": { "value": { - "request_id": "f7f10c7a-1518-4418-8a97-fa25d449bc4e", - "query": "fed interest rate decision", + "query": "agentic browser updates", "count": 2, - "took_ms": 169, "results": [ { - "id": "news_01", - "title": "Federal Reserve Holds Rates Steady", - "url": "https://news.example.com/fed-holds-rates", - "snippet": "The central bank kept rates unchanged in a widely expected decision.", - "source": "news.example.com", - "published_at": "2026-03-03T18:30:00Z", - "image_url": "https://news.example.com/images/fed.jpg", - "category": "business", - "language": "en" + "title": "Agentic Browser Capabilities Expand in 2026", + "url": "https://queryx.run/mock/agentic-browser-capabilities-2026", + "snippet": "Vendors shipped stronger tool-use APIs and safer autonomous browsing defaults.", + "publisher": "queryx.run", + "section": "technology", + "rank": 1, + "score": 0.93, + "published_at": "2026-03-03T10:30:00Z", + "image_url": "https://queryx.run/mock/news-image-1.jpg" }, { - "id": "news_02", - "title": "Markets React to Fed Guidance", - "url": "https://finance.example.org/market-reaction-fed", - "snippet": "Stocks moved higher after comments on inflation trends.", - "source": "finance.example.org", - "published_at": "2026-03-03T20:05:00Z", - "image_url": null, - "category": "finance", - "language": "en" + "title": "Research Teams Standardize Web Task Evaluation", + "url": "https://queryx.run/mock/web-task-evaluation-standardization", + "snippet": "A consortium proposed reproducible metrics for web-native agent benchmarks.", + "publisher": "queryx.run", + "section": "research", + "rank": 2, + "score": 0.88, + "published_at": "2026-03-02T17:05:00Z", + "image_url": null } - ] + ], + "meta": { + "request_id": "req_01JNR9Y1T8E9W3Y8FCNR0R6Q8A", + "took_ms": 155, + "billed_units": 1500, + "billed_usdc": "0.0015", + "limit": 10, + "offset": 0, + "sort": "latest" + } } } } @@ -287,10 +436,10 @@ "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/RateLimitError" + "$ref": "#/components/responses/TooManyRequests" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -298,33 +447,11 @@ "/v1/search/deep": { "post": { "tags": [ - "Search" + "deep-search" ], "operationId": "searchDeep", "summary": "Deep research search", - "description": "Runs multi-step retrieval and synthesis to return a grounded answer with citations. Paid endpoint secured by x402.", - "security": [ - { - "x402": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/XPayment" - }, - { - "$ref": "#/components/parameters/XPaymentSignature" - }, - { - "$ref": "#/components/parameters/XPaymentAddress" - }, - { - "$ref": "#/components/parameters/XPaymentTimestamp" - }, - { - "$ref": "#/components/parameters/XPaymentNonce" - } - ], + "description": "Runs multi-step retrieval and synthesis to produce a grounded answer with citations.", "requestBody": { "required": true, "content": { @@ -333,25 +460,19 @@ "$ref": "#/components/schemas/DeepSearchRequest" }, "examples": { - "deepResearchRequest": { + "deepRequest": { "value": { - "query": "Compare RAG chunking strategies for long technical manuals", - "max_sources": 12, - "max_depth": 2, + "query": "What changed in retrieval augmented generation best practices in 2025?", + "analysis_depth": "deep", + "max_sources": 10, + "recency": "30d", + "answer_format": "markdown", + "need_citations": true, "include_domains": [ - "arxiv.org", - "acm.org", - "docs.example.com" + "queryx.run" ], - "exclude_domains": [ - "pinterest.com" - ], - "response_format": "markdown", - "citations": true, - "context": { - "audience": "engineering manager", - "target_length": "short" - } + "exclude_domains": [], + "user_context": "Prioritize reproducibility and evaluation quality." } } } @@ -360,54 +481,61 @@ }, "responses": { "200": { - "description": "Deep research response returned", + "description": "Deep search answer with citations", + "headers": { + "X-Request-Id": { + "description": "Unique request id for tracing.", + "schema": { + "type": "string" + } + }, + "X-Billed-Units": { + "description": "Amount charged in USDC base units (6 decimals).", + "schema": { + "type": "integer", + "minimum": 0 + } + } + }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearchResponse" }, "examples": { - "deepResearchResponse": { + "deepResponse": { "value": { - "request_id": "b4f32c3f-72d7-4f79-8f2d-420611f2b2c7", - "query": "Compare RAG chunking strategies for long technical manuals", - "summary": "Structure-aware chunking with semantic overlap is consistently strongest for long manuals.", - "answer": "Across long technical manuals, fixed-size chunking is simplest but loses section semantics and cross-reference context. Structure-aware chunking aligned to headings improves factual grounding and citation precision. Semantic chunking can improve recall but must be constrained by max token budgets and overlap windows. The best production pattern is structure-first chunking with adaptive overlap for tables/procedures, then reranking before final synthesis.", - "took_ms": 1894, - "citations": [ - { - "id": "c1", - "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks", - "url": "https://arxiv.org/abs/2005.11401", - "quote": "Chunk granularity significantly impacts retrieval relevance and generation quality." - }, - { - "id": "c2", - "title": "Practical Considerations for Document Chunking in RAG Systems", - "url": "https://example.com/rag-chunking-practical-guide", - "quote": "Heading-aware segmentation reduces context fragmentation in long-form documents." - } + "query": "What changed in retrieval augmented generation best practices in 2025?", + "answer": "In 2025, teams shifted from single-pass retrieval to iterative retrieval loops with explicit verification. Common upgrades included dynamic chunk sizing, citation-level confidence scoring, and benchmark contamination audits before release.", + "highlights": [ + "Iterative retrieval replaced single-pass retrieval in most production systems.", + "Citation confidence became a first-class output field.", + "Evaluation shifted toward out-of-distribution and contamination-aware tests." ], - "sources": [ + "citations": [ { - "id": "s1", - "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks", - "url": "https://arxiv.org/abs/2005.11401", - "source_type": "paper", - "snippet": "The model combines parametric and non-parametric memory via retrieval." + "id": "src_1", + "title": "RAG Systems Report 2025", + "url": "https://queryx.run/mock/rag-systems-report-2025", + "snippet": "Iterative retrieval and verifier loops improved factual precision across long-form tasks.", + "relevance": 0.95 }, { - "id": "s2", - "title": "Practical Considerations for Document Chunking in RAG Systems", - "url": "https://example.com/rag-chunking-practical-guide", - "source_type": "article", - "snippet": "Structure-aware chunking is robust under strict context limits." + "id": "src_2", + "title": "Benchmark Hygiene for Retrieval Pipelines", + "url": "https://queryx.run/mock/benchmark-hygiene-retrieval", + "snippet": "Contamination checks are now standard for public benchmark publication.", + "relevance": 0.91 } ], - "usage": { - "request_units": 1, - "sources_considered": 12, - "sources_used": 5 + "meta": { + "request_id": "req_01JNRB79QGQK7N7WS8Z3S5FW31", + "took_ms": 1840, + "billed_units": 5000, + "billed_usdc": "0.005", + "sources_considered": 22, + "sources_used": 6, + "analysis_depth": "deep" } } } @@ -422,10 +550,10 @@ "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/RateLimitError" + "$ref": "#/components/responses/TooManyRequests" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/InternalServerError" } } } @@ -436,295 +564,17 @@ "x402": { "type": "apiKey", "in": "header", - "name": "X-Payment", - "description": "x402 payment envelope (base64url encoded JSON). Include X-Payment, X-Payment-Signature, X-Payment-Address, X-Payment-Timestamp, and X-Payment-Nonce for paid requests.", - "x-protocol": "x402", - "x-network": "base", - "x-currency": "USDC" - } - }, - "parameters": { - "Query": { - "name": "q", - "in": "query", - "required": true, - "description": "Search query text.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 1000 - }, - "example": "latest breakthroughs in battery technology" - }, - "Limit": { - "name": "limit", - "in": "query", - "required": false, - "description": "Maximum number of results to return.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 - }, - "example": 10 - }, - "Offset": { - "name": "offset", - "in": "query", - "required": false, - "description": "Result offset for pagination.", - "schema": { - "type": "integer", - "minimum": 0, - "maximum": 1000, - "default": 0 - }, - "example": 0 - }, - "Language": { - "name": "lang", - "in": "query", - "required": false, - "description": "Language code, for example en or en-US.", - "schema": { - "type": "string", - "pattern": "^[a-z]{2}(-[A-Z]{2})?$", - "default": "en" - }, - "example": "en" - }, - "Country": { - "name": "country", - "in": "query", - "required": false, - "description": "Country code in ISO-3166 alpha-2 format.", - "schema": { - "type": "string", - "pattern": "^[A-Z]{2}$" - }, - "example": "US" - }, - "SafeSearch": { - "name": "safe_search", - "in": "query", - "required": false, - "description": "Safe search filter level.", - "schema": { - "type": "string", - "enum": [ - "off", - "moderate", - "strict" - ], - "default": "moderate" - }, - "example": "moderate" - }, - "NewsFrom": { - "name": "from", - "in": "query", - "required": false, - "description": "Return news published on or after this timestamp.", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-03-01T00:00:00Z" - }, - "NewsTo": { - "name": "to", - "in": "query", - "required": false, - "description": "Return news published on or before this timestamp.", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-03-04T23:59:59Z" - }, - "NewsSort": { - "name": "sort", - "in": "query", - "required": false, - "description": "Sort order for news results.", - "schema": { - "type": "string", - "enum": [ - "relevance", - "latest" - ], - "default": "relevance" - }, - "example": "latest" - }, - "XPayment": { - "name": "X-Payment", - "in": "header", - "required": false, - "description": "x402 payment envelope as base64url(JSON). Required for paid request settlement.", - "schema": { - "type": "string", - "minLength": 16 - } - }, - "XPaymentSignature": { - "name": "X-Payment-Signature", - "in": "header", - "required": false, - "description": "secp256k1 signature over canonical request string.", - "schema": { - "type": "string", - "minLength": 16 - } - }, - "XPaymentAddress": { - "name": "X-Payment-Address", - "in": "header", - "required": false, - "description": "Payer wallet address on Base.", - "schema": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$" - }, - "example": "0x5b38Da6a701c568545dCfcB03FcB875f56beddC4" - }, - "XPaymentTimestamp": { - "name": "X-Payment-Timestamp", - "in": "header", - "required": false, - "description": "Unix timestamp (seconds) used in canonical signature.", - "schema": { - "type": "integer", - "minimum": 1700000000 - }, - "example": 1772625600 - }, - "XPaymentNonce": { - "name": "X-Payment-Nonce", - "in": "header", - "required": false, - "description": "Client-generated unique nonce for replay protection.", - "schema": { - "type": "string", - "minLength": 8, - "maxLength": 128 - }, - "example": "e7f1f403-4f11-4d9f-92f2-3f62c9acb5ee" - } - }, - "responses": { - "PaymentRequired": { - "description": "Payment is required before this request can be processed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PaymentRequiredErrorResponse" - }, - "examples": { - "paymentRequired": { - "value": { - "request_id": "1c108f27-6154-4ee8-b6b1-72db6a93e83d", - "error": { - "code": "payment_required", - "message": "x402 payment required for this endpoint.", - "details": null - }, - "payment": { - "network": "base", - "asset": "USDC", - "amount": "2500", - "amount_decimal": "0.0025", - "facilitator": "0x8fF5d1A6B7C35E4a2f90Aa64b1D9fA41A6a6b0C2", - "expires_at": "2026-03-04T12:01:00Z" - } - } - } - } - } - } - }, - "ValidationError": { - "description": "The request failed validation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ValidationErrorResponse" - }, - "examples": { - "invalidQuery": { - "value": { - "request_id": "fcb16e8f-8f29-4f8d-b62a-37a8d5dd22d2", - "error": { - "code": "validation_error", - "message": "Request validation failed.", - "details": null - }, - "errors": [ - { - "field": "q", - "message": "Query must be at least 1 character." - } - ] - } - } - } - } - } - }, - "RateLimitError": { - "description": "Rate limit exceeded.", - "headers": { - "Retry-After": { - "description": "Seconds until another request may be attempted.", - "schema": { - "type": "integer", - "minimum": 1 - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RateLimitErrorResponse" - }, - "examples": { - "tooManyRequests": { - "value": { - "request_id": "dce2e194-4229-4f04-8f34-a43b4eb7f436", - "error": { - "code": "rate_limited", - "message": "Rate limit exceeded.", - "details": null - }, - "retry_after_ms": 2000, - "limit": 120, - "window_ms": 60000 - } - } - } - } - } - }, - "InternalError": { - "description": "Unexpected server error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InternalErrorResponse" - }, - "examples": { - "internalError": { - "value": { - "request_id": "e0cd9e63-8b15-4d6f-9421-4ec14f75be80", - "error": { - "code": "internal_error", - "message": "Unexpected internal error.", - "details": null - } - } - } - } + "name": "X-PAYMENT", + "description": "x402 payment envelope encoded as base64url JSON. Required on paid endpoints.", + "x-x402": { + "version": "x402-1", + "network": "base", + "asset": "USDC", + "facilitator": "0x4E3b7E2c9C22f8f3A7fA9E6eD9Bd4F2c2A11bC09", + "pricing_base_units": { + "GET /v1/search": 1000, + "GET /v1/search/news": 1500, + "POST /v1/search/deep": 5000 } } } @@ -737,8 +587,8 @@ "status", "service", "version", - "uptime_seconds", - "timestamp" + "timestamp", + "uptime_seconds" ], "properties": { "status": { @@ -755,13 +605,13 @@ "type": "string", "example": "1.0.0" }, - "uptime_seconds": { - "type": "integer", - "minimum": 0 - }, "timestamp": { "type": "string", "format": "date-time" + }, + "uptime_seconds": { + "type": "integer", + "minimum": 0 } } }, @@ -769,20 +619,16 @@ "type": "object", "additionalProperties": false, "required": [ - "id", "title", "url", "snippet", "source", - "published_at", + "rank", "score", - "favicon_url", - "language" + "published_at", + "favicon_url" ], "properties": { - "id": { - "type": "string" - }, "title": { "type": "string" }, @@ -796,65 +642,28 @@ "source": { "type": "string" }, - "published_at": { - "type": [ - "string", - "null" - ], - "format": "date-time" + "rank": { + "type": "integer", + "minimum": 1 }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, - "favicon_url": { + "published_at": { "type": [ "string", "null" ], - "format": "uri" + "format": "date-time" }, - "language": { + "favicon_url": { "type": [ "string", "null" ], - "pattern": "^[a-z]{2}(-[A-Z]{2})?$" - } - } - }, - "SearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "request_id", - "query", - "count", - "took_ms", - "results" - ], - "properties": { - "request_id": { - "type": "string", - "format": "uuid" - }, - "query": { - "type": "string" - }, - "count": { - "type": "integer", - "minimum": 0 - }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchResult" - } + "format": "uri" } } }, @@ -862,20 +671,17 @@ "type": "object", "additionalProperties": false, "required": [ - "id", "title", "url", "snippet", - "source", + "publisher", + "section", + "rank", + "score", "published_at", - "image_url", - "category", - "language" + "image_url" ], "properties": { - "id": { - "type": "string" - }, "title": { "type": "string" }, @@ -886,9 +692,24 @@ "snippet": { "type": "string" }, - "source": { + "publisher": { "type": "string" }, + "section": { + "type": [ + "string", + "null" + ] + }, + "rank": { + "type": "integer", + "minimum": 1 + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, "published_at": { "type": "string", "format": "date-time" @@ -899,37 +720,124 @@ "null" ], "format": "uri" + } + } + }, + "SearchMeta": { + "type": "object", + "additionalProperties": false, + "required": [ + "request_id", + "took_ms", + "billed_units", + "billed_usdc", + "limit", + "offset" + ], + "properties": { + "request_id": { + "type": "string" }, - "category": { - "type": [ - "string", - "null" - ] + "took_ms": { + "type": "integer", + "minimum": 0 }, - "language": { - "type": [ - "string", - "null" - ], - "pattern": "^[a-z]{2}(-[A-Z]{2})?$" + "billed_units": { + "type": "integer", + "minimum": 0 + }, + "billed_usdc": { + "type": "string", + "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" + }, + "limit": { + "type": "integer", + "minimum": 1 + }, + "offset": { + "type": "integer", + "minimum": 0 } } }, - "NewsSearchResponse": { + "NewsSearchMeta": { + "allOf": [ + { + "$ref": "#/components/schemas/SearchMeta" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "sort" + ], + "properties": { + "sort": { + "type": "string", + "enum": [ + "relevance", + "latest" + ] + } + } + } + ] + }, + "DeepSearchMeta": { "type": "object", "additionalProperties": false, "required": [ "request_id", - "query", - "count", "took_ms", - "results" + "billed_units", + "billed_usdc", + "sources_considered", + "sources_used", + "analysis_depth" ], "properties": { "request_id": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "minimum": 0 + }, + "billed_units": { + "type": "integer", + "minimum": 0 + }, + "billed_usdc": { "type": "string", - "format": "uuid" + "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" }, + "sources_considered": { + "type": "integer", + "minimum": 0 + }, + "sources_used": { + "type": "integer", + "minimum": 0 + }, + "analysis_depth": { + "type": "string", + "enum": [ + "standard", + "deep" + ] + } + } + }, + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "count", + "results", + "meta" + ], + "properties": { "query": { "type": "string" }, @@ -937,7 +845,31 @@ "type": "integer", "minimum": 0 }, - "took_ms": { + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } + }, + "meta": { + "$ref": "#/components/schemas/SearchMeta" + } + } + }, + "NewsSearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "count", + "results", + "meta" + ], + "properties": { + "query": { + "type": "string" + }, + "count": { "type": "integer", "minimum": 0 }, @@ -946,6 +878,9 @@ "items": { "$ref": "#/components/schemas/NewsResult" } + }, + "meta": { + "$ref": "#/components/schemas/NewsSearchMeta" } } }, @@ -959,52 +894,68 @@ "query": { "type": "string", "minLength": 1, - "maxLength": 4000 + "maxLength": 2048 }, - "max_sources": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 12 + "analysis_depth": { + "type": "string", + "enum": [ + "standard", + "deep" + ], + "default": "standard" }, - "max_depth": { + "max_sources": { "type": "integer", "minimum": 1, - "maximum": 4, - "default": 2 + "maximum": 25, + "default": 8 }, "include_domains": { "type": "array", + "maxItems": 20, "items": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 255 }, "default": [] }, "exclude_domains": { "type": "array", + "maxItems": 20, "items": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 255 }, "default": [] }, - "response_format": { + "recency": { + "type": "string", + "enum": [ + "any", + "24h", + "7d", + "30d" + ], + "default": "any" + }, + "answer_format": { "type": "string", "enum": [ "markdown", + "text", "json" ], "default": "markdown" }, - "citations": { + "need_citations": { "type": "boolean", "default": true }, - "context": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "default": {} + "user_context": { + "type": "string", + "maxLength": 4000 } } }, @@ -1015,7 +966,8 @@ "id", "title", "url", - "quote" + "snippet", + "relevance" ], "properties": { "id": { @@ -1028,162 +980,221 @@ "type": "string", "format": "uri" }, - "quote": { + "snippet": { "type": "string" + }, + "relevance": { + "type": "number", + "minimum": 0, + "maximum": 1 } } }, - "DeepSource": { + "DeepSearchResponse": { "type": "object", "additionalProperties": false, "required": [ - "id", - "title", - "url", - "source_type", - "snippet" + "query", + "answer", + "highlights", + "citations", + "meta" ], "properties": { - "id": { + "query": { "type": "string" }, - "title": { + "answer": { "type": "string" }, - "url": { - "type": "string", - "format": "uri" + "highlights": { + "type": "array", + "items": { + "type": "string" + } }, - "source_type": { - "type": "string", - "enum": [ - "article", - "paper", - "docs", - "other" - ] + "citations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeepCitation" + } }, - "snippet": { + "meta": { + "$ref": "#/components/schemas/DeepSearchMeta" + } + } + }, + "ErrorObject": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "message" + ], + "properties": { + "code": { + "type": "string" + }, + "message": { "type": "string" } } }, - "DeepUsage": { + "PaymentRequirement": { "type": "object", "additionalProperties": false, "required": [ - "request_units", - "sources_considered", - "sources_used" + "network", + "asset", + "amount", + "facilitator", + "payment_header", + "resource", + "expires_at" ], "properties": { - "request_units": { - "type": "integer", - "minimum": 1 + "network": { + "type": "string", + "example": "base" }, - "sources_considered": { - "type": "integer", - "minimum": 0 + "asset": { + "type": "string", + "example": "USDC" }, - "sources_used": { - "type": "integer", - "minimum": 0 + "amount": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "USDC base units (6 decimals)." + }, + "facilitator": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + }, + "payment_header": { + "type": "string", + "example": "X-PAYMENT" + }, + "resource": { + "type": "string", + "example": "GET:/v1/search" + }, + "expires_at": { + "type": "string", + "format": "date-time" } } }, - "DeepSearchResponse": { + "PaymentRequiredResponse": { "type": "object", "additionalProperties": false, "required": [ + "error", "request_id", - "query", - "summary", - "answer", - "took_ms", - "citations", - "sources", - "usage" + "payment" ], "properties": { - "request_id": { - "type": "string", - "format": "uuid" + "error": { + "$ref": "#/components/schemas/ErrorObject" }, - "query": { + "request_id": { "type": "string" }, - "summary": { + "payment": { + "$ref": "#/components/schemas/PaymentRequirement" + } + } + }, + "ValidationIssue": { + "type": "object", + "additionalProperties": false, + "required": [ + "field", + "message" + ], + "properties": { + "field": { "type": "string" }, - "answer": { + "message": { "type": "string" + } + } + }, + "ValidationErrorResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "error", + "request_id", + "issues" + ], + "properties": { + "error": { + "$ref": "#/components/schemas/ErrorObject" }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "citations": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DeepCitation" - } + "request_id": { + "type": "string" }, - "sources": { + "issues": { "type": "array", "items": { - "$ref": "#/components/schemas/DeepSource" + "$ref": "#/components/schemas/ValidationIssue" } - }, - "usage": { - "$ref": "#/components/schemas/DeepUsage" } } }, - "ErrorObject": { + "RateLimitErrorResponse": { "type": "object", "additionalProperties": false, "required": [ - "code", - "message", - "details" + "error", + "request_id", + "retry_after_seconds" ], "properties": { - "code": { - "type": "string", - "enum": [ - "payment_required", - "validation_error", - "rate_limited", - "internal_error" - ] + "error": { + "$ref": "#/components/schemas/ErrorObject" }, - "message": { + "request_id": { "type": "string" }, - "details": { - "type": [ - "object", - "null" - ], - "additionalProperties": true + "retry_after_seconds": { + "type": "integer", + "minimum": 1 } } }, - "BaseErrorResponse": { + "InternalErrorResponse": { "type": "object", "additionalProperties": false, "required": [ - "request_id", - "error" + "error", + "request_id" ], "properties": { - "request_id": { - "type": "string", - "format": "uuid" - }, "error": { "$ref": "#/components/schemas/ErrorObject" + }, + "request_id": { + "type": "string" } } }, - "PaymentRequirements \ No newline at end of file + "PaymentEnvelope": { + "type": "object", + "additionalProperties": false, + "required": [ + "version", + "network", + "asset", + "amount", + "resource", + "nonce", + "timestamp", + "payer", + "signature" + ], + "properties": { + "version": { + "type": "string", + "example": " \ No newline at end of file From b1f70042a59b9b3c3eb93abc061e02f145f86231 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:41:38 +0000 Subject: [PATCH 10/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1253 +++++++++++++++++---------------------------- 1 file changed, 466 insertions(+), 787 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index 32d8e71..1bd4435 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,17 +1,15 @@ === FILE: openapi.json === { "openapi": "3.1.0", + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", - "summary": "x402-native web search, news search, and deep research API", - "description": "Queryx exposes paid search endpoints secured with x402 payment envelopes over Base USDC. Clients send an X-PAYMENT header for paid endpoints.", "version": "1.0.0", + "description": "Queryx is an x402-native search API on Base. Paid endpoints require x402 payment headers (`X-402-Payment` + `X-402-Signature`).", "contact": { - "name": "Queryx", - "url": "https://github.com/langoustine69/queryx" + "name": "Queryx" } }, - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://queryx.run", @@ -20,33 +18,23 @@ ], "tags": [ { - "name": "health", - "description": "Service health and readiness" - }, - { - "name": "search", - "description": "Web and news search endpoints" + "name": "Health", + "description": "Service health checks" }, { - "name": "deep-search", - "description": "Deep research endpoint with synthesized answer and citations" - } - ], - "security": [ - { - "x402": [] + "name": "Search", + "description": "Paid web/news/deep research endpoints" } ], "paths": { "/health": { "get": { "tags": [ - "health" + "Health" ], "operationId": "getHealth", "summary": "Health check", - "description": "Returns service health, version, and uptime. This endpoint is free and does not require x402 payment.", - "security": [], + "description": "Returns service liveness and build/runtime metadata.", "responses": { "200": { "description": "Service is healthy", @@ -56,13 +44,13 @@ "$ref": "#/components/schemas/HealthResponse" }, "examples": { - "healthy": { + "ok": { "value": { "status": "ok", "service": "queryx", "version": "1.0.0", - "timestamp": "2026-03-04T12:00:00Z", - "uptime_seconds": 86422 + "timestamp": "2026-03-04T10:12:45Z", + "uptimeSeconds": 532980 } } } @@ -70,7 +58,7 @@ } }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } @@ -78,121 +66,65 @@ "/v1/search": { "get": { "tags": [ - "search" + "Search" ], "operationId": "searchWeb", "summary": "Web search", - "description": "Performs ranked web search for the provided query.", + "description": "Searches the public web for a query. Requires x402 payment.", + "security": [ + { + "x402": [] + } + ], "parameters": [ { - "name": "q", - "in": "query", - "required": true, - "description": "Search query string.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "example": "latest llm evaluation benchmarks" + "$ref": "#/components/parameters/X402SignatureHeader" }, { - "name": "limit", - "in": "query", - "required": false, - "description": "Maximum number of results to return.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 20, - "default": 10 - }, - "example": 10 + "$ref": "#/components/parameters/QueryParam" }, { - "name": "offset", - "in": "query", - "required": false, - "description": "Pagination offset.", - "schema": { - "type": "integer", - "minimum": 0, - "default": 0 - }, - "example": 0 + "$ref": "#/components/parameters/LimitParam" }, { - "name": "country", - "in": "query", - "required": false, - "description": "Optional ISO 3166-1 alpha-2 country filter.", - "schema": { - "type": "string", - "pattern": "^[A-Z]{2}$" - }, - "example": "US" + "$ref": "#/components/parameters/LangParam" }, { - "name": "lang", - "in": "query", - "required": false, - "description": "Optional ISO 639-1 language code filter.", - "schema": { - "type": "string", - "pattern": "^[a-z]{2}$" - }, - "example": "en" + "$ref": "#/components/parameters/RegionParam" }, { - "name": "freshness", - "in": "query", - "required": false, - "description": "Time-based freshness filter.", - "schema": { - "type": "string", - "enum": [ - "any", - "day", - "week", - "month" - ], - "default": "any" - }, - "example": "week" + "$ref": "#/components/parameters/SafeSearchParam" }, { - "name": "safe_search", - "in": "query", - "required": false, - "description": "Safe search level.", - "schema": { - "type": "string", - "enum": [ - "off", - "moderate", - "strict" - ], - "default": "moderate" - }, - "example": "moderate" + "$ref": "#/components/parameters/TimeRangeParam" + }, + { + "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { - "description": "Search results", + "description": "Web search results", "headers": { - "X-Request-Id": { - "description": "Unique request id for tracing.", + "X-RateLimit-Limit": { "schema": { - "type": "string" - } + "type": "integer", + "example": 120 + }, + "description": "Requests allowed per rolling 60-second window for this endpoint." }, - "X-Billed-Units": { - "description": "Amount charged in USDC base units (6 decimals).", + "X-RateLimit-Remaining": { "schema": { "type": "integer", - "minimum": 0 + "example": 119 } + }, + "X-RateLimit-Reset": { + "schema": { + "type": "integer", + "example": 1710000059 + }, + "description": "Unix epoch seconds when the current window resets." } }, "content": { @@ -201,39 +133,40 @@ "$ref": "#/components/schemas/SearchResponse" }, "examples": { - "webSearch": { + "success": { "value": { - "query": "latest llm evaluation benchmarks", - "count": 2, + "id": "srch_01JP5B4V2Y1X4W7N9A3ZQ8M2P0", + "query": "best vector database for rag", + "tookMs": 412, + "page": 1, + "limit": 5, + "totalEstimatedResults": 1240000, "results": [ { - "title": "State of LLM Evaluation 2026", - "url": "https://queryx.run/mock/state-of-llm-eval-2026", - "snippet": "A survey of modern benchmark design, contamination checks, and robustness criteria.", - "source": "queryx.run", - "rank": 1, - "score": 0.96, - "published_at": "2026-02-26T09:20:00Z", - "favicon_url": "https://queryx.run/mock/favicon.png" + "title": "Vector Databases for Retrieval-Augmented Generation", + "url": "https://example.com/vector-db-rag", + "snippet": "A practical comparison of Pinecone, Weaviate, Qdrant, and pgvector for RAG workloads.", + "source": "example.com", + "publishedAt": "2026-02-18T13:00:00Z", + "score": 0.98, + "faviconUrl": "https://example.com/favicon.ico" }, { - "title": "Benchmark Drift in Agentic Systems", - "url": "https://queryx.run/mock/benchmark-drift-agentic-systems", - "snippet": "How long-lived systems overfit public test sets and how to detect it.", - "source": "queryx.run", - "rank": 2, - "score": 0.89, - "published_at": "2026-02-24T14:02:00Z", - "favicon_url": null + "title": "pgvector vs Dedicated Vector DBs", + "url": "https://example.org/pgvector-vs-dedicated", + "snippet": "When Postgres with pgvector is enough, and when to move to a specialized store.", + "source": "example.org", + "publishedAt": "2026-01-29T08:22:11Z", + "score": 0.94, + "faviconUrl": "https://example.org/favicon.png" } ], - "meta": { - "request_id": "req_01JNR9C4SE8X0F09M4PEKQ6W22", - "took_ms": 132, - "billed_units": 1000, - "billed_usdc": "0.001", - "limit": 10, - "offset": 0 + "nextPage": 2, + "charge": { + "asset": "USDC", + "chain": "base", + "amountBaseUnits": "2500", + "amount": "0.0025" } } } @@ -242,141 +175,82 @@ } }, "402": { - "$ref": "#/components/responses/PaymentRequired" + "$ref": "#/components/responses/PaymentRequiredSearch" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/TooManyRequests" + "$ref": "#/components/responses/RateLimitExceeded" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } + }, + "x-pricing": { + "asset": "USDC", + "chain": "base", + "amountBaseUnits": "2500", + "amount": "0.0025" } } }, "/v1/search/news": { "get": { "tags": [ - "search" + "Search" ], "operationId": "searchNews", "summary": "News search", - "description": "Searches indexed news sources and returns ranked articles.", + "description": "Searches recent news sources with recency-aware ranking. Requires x402 payment.", + "security": [ + { + "x402": [] + } + ], "parameters": [ { - "name": "q", - "in": "query", - "required": true, - "description": "News query string.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "example": "agentic browser updates" + "$ref": "#/components/parameters/X402SignatureHeader" }, { - "name": "limit", - "in": "query", - "required": false, - "description": "Maximum number of articles to return.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 - }, - "example": 10 + "$ref": "#/components/parameters/QueryParam" }, { - "name": "offset", - "in": "query", - "required": false, - "description": "Pagination offset.", - "schema": { - "type": "integer", - "minimum": 0, - "default": 0 - }, - "example": 0 + "$ref": "#/components/parameters/LimitParam" }, { - "name": "country", - "in": "query", - "required": false, - "description": "Optional ISO 3166-1 alpha-2 country filter.", - "schema": { - "type": "string", - "pattern": "^[A-Z]{2}$" - }, - "example": "US" + "$ref": "#/components/parameters/LangParam" }, { - "name": "lang", - "in": "query", - "required": false, - "description": "Optional ISO 639-1 language code filter.", - "schema": { - "type": "string", - "pattern": "^[a-z]{2}$" - }, - "example": "en" + "$ref": "#/components/parameters/RegionParam" }, { - "name": "from", - "in": "query", - "required": false, - "description": "Inclusive lower bound for publication time.", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-03-01T00:00:00Z" + "$ref": "#/components/parameters/NewsFromParam" }, { - "name": "to", - "in": "query", - "required": false, - "description": "Inclusive upper bound for publication time.", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-03-04T23:59:59Z" - }, - { - "name": "sort", - "in": "query", - "required": false, - "description": "Sort strategy for news ranking.", - "schema": { - "type": "string", - "enum": [ - "relevance", - "latest" - ], - "default": "relevance" - }, - "example": "latest" + "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "News search results", "headers": { - "X-Request-Id": { - "description": "Unique request id for tracing.", + "X-RateLimit-Limit": { + "schema": { + "type": "integer", + "example": 90 + } + }, + "X-RateLimit-Remaining": { "schema": { - "type": "string" + "type": "integer", + "example": 89 } }, - "X-Billed-Units": { - "description": "Amount charged in USDC base units (6 decimals).", + "X-RateLimit-Reset": { "schema": { "type": "integer", - "minimum": 0 + "example": 1710000059 } } }, @@ -386,42 +260,42 @@ "$ref": "#/components/schemas/NewsSearchResponse" }, "examples": { - "newsSearch": { + "success": { "value": { - "query": "agentic browser updates", - "count": 2, + "id": "news_01JP5BFJGDXM8R4NCC2P8XQ2N1", + "query": "fed interest rates", + "tookMs": 376, + "page": 1, + "limit": 3, + "totalEstimatedResults": 18200, "results": [ { - "title": "Agentic Browser Capabilities Expand in 2026", - "url": "https://queryx.run/mock/agentic-browser-capabilities-2026", - "snippet": "Vendors shipped stronger tool-use APIs and safer autonomous browsing defaults.", - "publisher": "queryx.run", - "section": "technology", - "rank": 1, - "score": 0.93, - "published_at": "2026-03-03T10:30:00Z", - "image_url": "https://queryx.run/mock/news-image-1.jpg" + "title": "Federal Reserve Holds Rates Steady", + "url": "https://news.example.com/fed-holds-rates", + "snippet": "Officials signaled they still expect cuts later this year if inflation cools.", + "source": "news.example.com", + "outlet": "Example News", + "publishedAt": "2026-03-03T18:34:00Z", + "imageUrl": "https://news.example.com/images/fed.jpg", + "score": 0.97 }, { - "title": "Research Teams Standardize Web Task Evaluation", - "url": "https://queryx.run/mock/web-task-evaluation-standardization", - "snippet": "A consortium proposed reproducible metrics for web-native agent benchmarks.", - "publisher": "queryx.run", - "section": "research", - "rank": 2, - "score": 0.88, - "published_at": "2026-03-02T17:05:00Z", - "image_url": null + "title": "Markets React to Fed Decision", + "url": "https://markets.example.org/fed-market-reaction", + "snippet": "Treasury yields dipped while equities turned mixed after the announcement.", + "source": "markets.example.org", + "outlet": "Markets Daily", + "publishedAt": "2026-03-03T19:08:00Z", + "imageUrl": "https://markets.example.org/images/rates.png", + "score": 0.95 } ], - "meta": { - "request_id": "req_01JNR9Y1T8E9W3Y8FCNR0R6Q8A", - "took_ms": 155, - "billed_units": 1500, - "billed_usdc": "0.0015", - "limit": 10, - "offset": 0, - "sort": "latest" + "nextPage": 2, + "charge": { + "asset": "USDC", + "chain": "base", + "amountBaseUnits": "3500", + "amount": "0.0035" } } } @@ -430,28 +304,44 @@ } }, "402": { - "$ref": "#/components/responses/PaymentRequired" + "$ref": "#/components/responses/PaymentRequiredNews" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/TooManyRequests" + "$ref": "#/components/responses/RateLimitExceeded" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } + }, + "x-pricing": { + "asset": "USDC", + "chain": "base", + "amountBaseUnits": "3500", + "amount": "0.0035" } } }, "/v1/search/deep": { "post": { "tags": [ - "deep-search" + "Search" ], "operationId": "searchDeep", "summary": "Deep research search", - "description": "Runs multi-step retrieval and synthesis to produce a grounded answer with citations.", + "description": "Runs a multi-source deep research pass and returns a synthesized report with citations. Requires x402 payment.", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/X402SignatureHeader" + } + ], "requestBody": { "required": true, "content": { @@ -460,19 +350,29 @@ "$ref": "#/components/schemas/DeepSearchRequest" }, "examples": { - "deepRequest": { + "standard": { "value": { - "query": "What changed in retrieval augmented generation best practices in 2025?", - "analysis_depth": "deep", - "max_sources": 10, - "recency": "30d", - "answer_format": "markdown", - "need_citations": true, - "include_domains": [ - "queryx.run" + "query": "compare open-source observability stacks for kubernetes", + "depth": "standard", + "maxSources": 10, + "includeDomains": [ + "cncf.io", + "opentelemetry.io" ], - "exclude_domains": [], - "user_context": "Prioritize reproducibility and evaluation quality." + "excludeDomains": [ + "reddit.com" + ], + "style": "balanced", + "includeRawResults": false + } + }, + "comprehensive": { + "value": { + "query": "state of solid-state battery commercialization timelines", + "depth": "comprehensive", + "maxSources": 20, + "style": "thorough", + "includeRawResults": true } } } @@ -481,19 +381,24 @@ }, "responses": { "200": { - "description": "Deep search answer with citations", + "description": "Deep research report", "headers": { - "X-Request-Id": { - "description": "Unique request id for tracing.", + "X-RateLimit-Limit": { + "schema": { + "type": "integer", + "example": 30 + } + }, + "X-RateLimit-Remaining": { "schema": { - "type": "string" + "type": "integer", + "example": 29 } }, - "X-Billed-Units": { - "description": "Amount charged in USDC base units (6 decimals).", + "X-RateLimit-Reset": { "schema": { "type": "integer", - "minimum": 0 + "example": 1710000059 } } }, @@ -503,39 +408,43 @@ "$ref": "#/components/schemas/DeepSearchResponse" }, "examples": { - "deepResponse": { + "success": { "value": { - "query": "What changed in retrieval augmented generation best practices in 2025?", - "answer": "In 2025, teams shifted from single-pass retrieval to iterative retrieval loops with explicit verification. Common upgrades included dynamic chunk sizing, citation-level confidence scoring, and benchmark contamination audits before release.", - "highlights": [ - "Iterative retrieval replaced single-pass retrieval in most production systems.", - "Citation confidence became a first-class output field.", - "Evaluation shifted toward out-of-distribution and contamination-aware tests." + "id": "deep_01JP5BR2B3FDMZ1W9W5V8PNN7X", + "query": "state of solid-state battery commercialization timelines", + "depth": "comprehensive", + "tookMs": 4821, + "summary": "Solid-state batteries are moving from pilot to early commercial deployments, with meaningful scale expected between 2027 and 2030.", + "report": "## Commercialization outlook\nMost manufacturers remain in pilot-scale or limited-volume production...", + "keyFindings": [ + "Pilot lines are live across automotive suppliers in Asia, Europe, and the U.S.", + "Cost parity with high-nickel lithium-ion is unlikely before late 2028 for most use cases.", + "Automotive deployments are expected to lead consumer electronics in absolute pack volume." ], "citations": [ { - "id": "src_1", - "title": "RAG Systems Report 2025", - "url": "https://queryx.run/mock/rag-systems-report-2025", - "snippet": "Iterative retrieval and verifier loops improved factual precision across long-form tasks.", - "relevance": 0.95 + "id": "c1", + "title": "Automaker Roadmap for Solid-State Cells", + "url": "https://example.com/automaker-solid-state-roadmap", + "snippet": "Volume production target moved to 2028 with pilot fleet testing in 2027.", + "source": "example.com", + "publishedAt": "2026-01-15T09:30:00Z" }, { - "id": "src_2", - "title": "Benchmark Hygiene for Retrieval Pipelines", - "url": "https://queryx.run/mock/benchmark-hygiene-retrieval", - "snippet": "Contamination checks are now standard for public benchmark publication.", - "relevance": 0.91 + "id": "c2", + "title": "Electrolyte Manufacturing Constraints", + "url": "https://example.org/electrolyte-manufacturing", + "snippet": "Sulfide electrolyte scale-up remains a bottleneck through 2027.", + "source": "example.org", + "publishedAt": "2025-12-02T14:04:00Z" } ], - "meta": { - "request_id": "req_01JNRB79QGQK7N7WS8Z3S5FW31", - "took_ms": 1840, - "billed_units": 5000, - "billed_usdc": "0.005", - "sources_considered": 22, - "sources_used": 6, - "analysis_depth": "deep" + "searchResultsAnalyzed": 20, + "charge": { + "asset": "USDC", + "chain": "base", + "amountBaseUnits": "15000", + "amount": "0.0150" } } } @@ -544,17 +453,23 @@ } }, "402": { - "$ref": "#/components/responses/PaymentRequired" + "$ref": "#/components/responses/PaymentRequiredDeep" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/TooManyRequests" + "$ref": "#/components/responses/RateLimitExceeded" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } + }, + "x-pricing": { + "asset": "USDC", + "chain": "base", + "amountBaseUnits": "15000", + "amount": "0.0150" } } } @@ -564,31 +479,133 @@ "x402": { "type": "apiKey", "in": "header", - "name": "X-PAYMENT", - "description": "x402 payment envelope encoded as base64url JSON. Required on paid endpoints.", - "x-x402": { - "version": "x402-1", - "network": "base", - "asset": "USDC", - "facilitator": "0x4E3b7E2c9C22f8f3A7fA9E6eD9Bd4F2c2A11bC09", - "pricing_base_units": { - "GET /v1/search": 1000, - "GET /v1/search/news": 1500, - "POST /v1/search/deep": 5000 - } + "name": "X-402-Payment", + "description": "Base64-encoded JSON x402 payment payload. Must be accompanied by `X-402-Signature`." + } + }, + "parameters": { + "X402SignatureHeader": { + "name": "X-402-Signature", + "in": "header", + "required": true, + "description": "Hex ECDSA signature for the canonical payment message.", + "schema": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{130}$", + "example": "0x2f9d0019f5ea73f5d9882e5365f28f84a7ea6a2b00823fb2047680cc7f1f3dcd4f8cc127f0d3e29d0a9f16ed1782cfa884c42091efdb7ee64fd4495cf9ef4f4e1b" } + }, + "QueryParam": { + "name": "q", + "in": "query", + "required": true, + "description": "Search query string.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 1000 + }, + "example": "open telemetry collector scaling best practices" + }, + "LimitParam": { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of results to return.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + }, + "example": 10 + }, + "LangParam": { + "name": "lang", + "in": "query", + "required": false, + "description": "Language code for ranking preference.", + "schema": { + "type": "string", + "pattern": "^[a-z]{2}(-[A-Z]{2})?$", + "default": "en" + }, + "example": "en" + }, + "RegionParam": { + "name": "region", + "in": "query", + "required": false, + "description": "Region code for localized ranking.", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 5 + }, + "example": "US" + }, + "SafeSearchParam": { + "name": "safe_search", + "in": "query", + "required": false, + "description": "Filters explicit content from search results.", + "schema": { + "type": "boolean", + "default": true + }, + "example": true + }, + "TimeRangeParam": { + "name": "time_range", + "in": "query", + "required": false, + "description": "Recency filter for web results.", + "schema": { + "type": "string", + "enum": [ + "24h", + "7d", + "30d", + "365d", + "all" + ], + "default": "all" + }, + "example": "30d" + }, + "NewsFromParam": { + "name": "from", + "in": "query", + "required": false, + "description": "Only return news newer than this ISO-8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-03-01T00:00:00Z" + }, + "PageParam": { + "name": "page", + "in": "query", + "required": false, + "description": "1-based page index.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 1 + }, + "example": 1 } }, "schemas": { "HealthResponse": { "type": "object", - "additionalProperties": false, "required": [ "status", "service", "version", "timestamp", - "uptime_seconds" + "uptimeSeconds" ], "properties": { "status": { @@ -609,77 +626,52 @@ "type": "string", "format": "date-time" }, - "uptime_seconds": { + "uptimeSeconds": { "type": "integer", "minimum": 0 } } }, - "SearchResult": { + "Charge": { "type": "object", - "additionalProperties": false, "required": [ - "title", - "url", - "snippet", - "source", - "rank", - "score", - "published_at", - "favicon_url" + "asset", + "chain", + "amountBaseUnits", + "amount" ], "properties": { - "title": { - "type": "string" - }, - "url": { + "asset": { "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "source": { - "type": "string" - }, - "rank": { - "type": "integer", - "minimum": 1 + "enum": [ + "USDC" + ] }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 + "chain": { + "type": "string", + "enum": [ + "base" + ] }, - "published_at": { - "type": [ - "string", - "null" - ], - "format": "date-time" + "amountBaseUnits": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "USDC base units (6 decimals)." }, - "favicon_url": { - "type": [ - "string", - "null" - ], - "format": "uri" + "amount": { + "type": "string", + "pattern": "^[0-9]+(\\.[0-9]{1,6})?$", + "description": "Human-readable USDC amount." } } }, - "NewsResult": { + "SearchResult": { "type": "object", - "additionalProperties": false, "required": [ "title", "url", "snippet", - "publisher", - "section", - "rank", - "score", - "published_at", - "image_url" + "source" ], "properties": { "title": { @@ -692,156 +684,56 @@ "snippet": { "type": "string" }, - "publisher": { + "source": { "type": "string" }, - "section": { - "type": [ - "string", - "null" - ] - }, - "rank": { - "type": "integer", - "minimum": 1 + "publishedAt": { + "type": "string", + "format": "date-time" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, - "published_at": { + "faviconUrl": { "type": "string", - "format": "date-time" - }, - "image_url": { - "type": [ - "string", - "null" - ], "format": "uri" } } }, - "SearchMeta": { + "SearchResponse": { "type": "object", - "additionalProperties": false, "required": [ - "request_id", - "took_ms", - "billed_units", - "billed_usdc", + "id", + "query", + "tookMs", + "page", "limit", - "offset" + "totalEstimatedResults", + "results", + "charge" ], "properties": { - "request_id": { + "id": { "type": "string" }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "billed_units": { - "type": "integer", - "minimum": 0 - }, - "billed_usdc": { - "type": "string", - "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" - }, - "limit": { - "type": "integer", - "minimum": 1 - }, - "offset": { - "type": "integer", - "minimum": 0 - } - } - }, - "NewsSearchMeta": { - "allOf": [ - { - "$ref": "#/components/schemas/SearchMeta" - }, - { - "type": "object", - "additionalProperties": false, - "required": [ - "sort" - ], - "properties": { - "sort": { - "type": "string", - "enum": [ - "relevance", - "latest" - ] - } - } - } - ] - }, - "DeepSearchMeta": { - "type": "object", - "additionalProperties": false, - "required": [ - "request_id", - "took_ms", - "billed_units", - "billed_usdc", - "sources_considered", - "sources_used", - "analysis_depth" - ], - "properties": { - "request_id": { + "query": { "type": "string" }, - "took_ms": { + "tookMs": { "type": "integer", "minimum": 0 }, - "billed_units": { - "type": "integer", - "minimum": 0 - }, - "billed_usdc": { - "type": "string", - "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" - }, - "sources_considered": { + "page": { "type": "integer", - "minimum": 0 + "minimum": 1 }, - "sources_used": { + "limit": { "type": "integer", - "minimum": 0 - }, - "analysis_depth": { - "type": "string", - "enum": [ - "standard", - "deep" - ] - } - } - }, - "SearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "query", - "count", - "results", - "meta" - ], - "properties": { - "query": { - "type": "string" + "minimum": 1 }, - "count": { + "totalEstimatedResults": { "type": "integer", "minimum": 0 }, @@ -851,128 +743,29 @@ "$ref": "#/components/schemas/SearchResult" } }, - "meta": { - "$ref": "#/components/schemas/SearchMeta" - } - } - }, - "NewsSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "query", - "count", - "results", - "meta" - ], - "properties": { - "query": { - "type": "string" - }, - "count": { - "type": "integer", - "minimum": 0 - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NewsResult" - } - }, - "meta": { - "$ref": "#/components/schemas/NewsSearchMeta" - } - } - }, - "DeepSearchRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "minLength": 1, - "maxLength": 2048 - }, - "analysis_depth": { - "type": "string", - "enum": [ - "standard", - "deep" - ], - "default": "standard" - }, - "max_sources": { - "type": "integer", - "minimum": 1, - "maximum": 25, - "default": 8 - }, - "include_domains": { - "type": "array", - "maxItems": 20, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 255 - }, - "default": [] - }, - "exclude_domains": { - "type": "array", - "maxItems": 20, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 255 - }, - "default": [] - }, - "recency": { - "type": "string", - "enum": [ - "any", - "24h", - "7d", - "30d" - ], - "default": "any" - }, - "answer_format": { - "type": "string", - "enum": [ - "markdown", - "text", - "json" + "nextPage": { + "type": [ + "integer", + "null" ], - "default": "markdown" - }, - "need_citations": { - "type": "boolean", - "default": true + "minimum": 2 }, - "user_context": { - "type": "string", - "maxLength": 4000 + "charge": { + "$ref": "#/components/schemas/Charge" } } }, - "DeepCitation": { + "NewsResult": { "type": "object", - "additionalProperties": false, "required": [ - "id", "title", "url", "snippet", - "relevance" + "source", + "outlet", + "publishedAt" ], "properties": { - "id": { - "type": "string" - }, "title": { "type": "string" }, @@ -983,218 +776,104 @@ "snippet": { "type": "string" }, - "relevance": { - "type": "number", - "minimum": 0, - "maximum": 1 - } - } - }, - "DeepSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "query", - "answer", - "highlights", - "citations", - "meta" - ], - "properties": { - "query": { - "type": "string" - }, - "answer": { - "type": "string" - }, - "highlights": { - "type": "array", - "items": { - "type": "string" - } - }, - "citations": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DeepCitation" - } - }, - "meta": { - "$ref": "#/components/schemas/DeepSearchMeta" - } - } - }, - "ErrorObject": { - "type": "object", - "additionalProperties": false, - "required": [ - "code", - "message" - ], - "properties": { - "code": { + "source": { "type": "string" }, - "message": { + "outlet": { "type": "string" - } - } - }, - "PaymentRequirement": { - "type": "object", - "additionalProperties": false, - "required": [ - "network", - "asset", - "amount", - "facilitator", - "payment_header", - "resource", - "expires_at" - ], - "properties": { - "network": { - "type": "string", - "example": "base" - }, - "asset": { - "type": "string", - "example": "USDC" }, - "amount": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "USDC base units (6 decimals)." - }, - "facilitator": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$" - }, - "payment_header": { + "publishedAt": { "type": "string", - "example": "X-PAYMENT" + "format": "date-time" }, - "resource": { + "imageUrl": { "type": "string", - "example": "GET:/v1/search" + "format": "uri" }, - "expires_at": { - "type": "string", - "format": "date-time" + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 } } }, - "PaymentRequiredResponse": { + "NewsSearchResponse": { "type": "object", - "additionalProperties": false, "required": [ - "error", - "request_id", - "payment" + "id", + "query", + "tookMs", + "page", + "limit", + "totalEstimatedResults", + "results", + "charge" ], "properties": { - "error": { - "$ref": "#/components/schemas/ErrorObject" - }, - "request_id": { + "id": { "type": "string" }, - "payment": { - "$ref": "#/components/schemas/PaymentRequirement" - } - } - }, - "ValidationIssue": { - "type": "object", - "additionalProperties": false, - "required": [ - "field", - "message" - ], - "properties": { - "field": { + "query": { "type": "string" }, - "message": { - "type": "string" - } - } - }, - "ValidationErrorResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "error", - "request_id", - "issues" - ], - "properties": { - "error": { - "$ref": "#/components/schemas/ErrorObject" + "tookMs": { + "type": "integer", + "minimum": 0 }, - "request_id": { - "type": "string" + "page": { + "type": "integer", + "minimum": 1 }, - "issues": { + "limit": { + "type": "integer", + "minimum": 1 + }, + "totalEstimatedResults": { + "type": "integer", + "minimum": 0 + }, + "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ValidationIssue" + "$ref": "#/components/schemas/NewsResult" } - } - } - }, - "RateLimitErrorResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "error", - "request_id", - "retry_after_seconds" - ], - "properties": { - "error": { - "$ref": "#/components/schemas/ErrorObject" }, - "request_id": { - "type": "string" + "nextPage": { + "type": [ + "integer", + "null" + ], + "minimum": 2 }, - "retry_after_seconds": { - "type": "integer", - "minimum": 1 + "charge": { + "$ref": "#/components/schemas/Charge" } } }, - "InternalErrorResponse": { + "DeepSearchRequest": { "type": "object", - "additionalProperties": false, "required": [ - "error", - "request_id" + "query" ], "properties": { - "error": { - "$ref": "#/components/schemas/ErrorObject" + "query": { + "type": "string", + "minLength": 1, + "maxLength": 2000 }, - "request_id": { - "type": "string" - } - } - }, - "PaymentEnvelope": { - "type": "object", - "additionalProperties": false, - "required": [ - "version", - "network", - "asset", - "amount", - "resource", - "nonce", - "timestamp", - "payer", - "signature" - ], - "properties": { - "version": { + "depth": { "type": "string", - "example": " \ No newline at end of file + "enum": [ + "standard", + "comprehensive" + ], + "default": "standard" + }, + "maxSources": { + "type": "integer", + "minimum": 3, + "maximum": 50, + "default": 12 + }, + "includeDomains": { + "type": " \ No newline at end of file From 3ae8ae494fcd3e7f36fef125446bdc3c0d7ed3ce Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:47:48 +0000 Subject: [PATCH 11/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1283 ++++++++++++++++++++++++++------------------- 1 file changed, 745 insertions(+), 538 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index 1bd4435..41fdf09 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,14 +1,11 @@ === FILE: openapi.json === { "openapi": "3.1.0", - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", "version": "1.0.0", - "description": "Queryx is an x402-native search API on Base. Paid endpoints require x402 payment headers (`X-402-Payment` + `X-402-Signature`).", - "contact": { - "name": "Queryx" - } + "summary": "Paid web, news, and deep research search API using x402 micropayments.", + "description": "Queryx provides high-quality search and research endpoints with per-request x402 payment on Base (USDC)." }, "servers": [ { @@ -18,59 +15,27 @@ ], "tags": [ { - "name": "Health", - "description": "Service health checks" + "name": "Search", + "description": "Web and news search endpoints." }, { - "name": "Search", - "description": "Paid web/news/deep research endpoints" + "name": "Deep Research", + "description": "Higher-cost endpoint for synthesized research answers with citations." + }, + { + "name": "Health", + "description": "Service health and readiness." } ], "paths": { - "/health": { - "get": { - "tags": [ - "Health" - ], - "operationId": "getHealth", - "summary": "Health check", - "description": "Returns service liveness and build/runtime metadata.", - "responses": { - "200": { - "description": "Service is healthy", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HealthResponse" - }, - "examples": { - "ok": { - "value": { - "status": "ok", - "service": "queryx", - "version": "1.0.0", - "timestamp": "2026-03-04T10:12:45Z", - "uptimeSeconds": 532980 - } - } - } - } - } - }, - "500": { - "$ref": "#/components/responses/InternalError" - } - } - } - }, "/v1/search": { "get": { "tags": [ "Search" ], "operationId": "searchWeb", - "summary": "Web search", - "description": "Searches the public web for a query. Requires x402 payment.", + "summary": "Search the web", + "description": "Returns ranked web search results for a query. Requires x402 payment via X-PAYMENT header.", "security": [ { "x402": [] @@ -78,55 +43,125 @@ ], "parameters": [ { - "$ref": "#/components/parameters/X402SignatureHeader" + "name": "q", + "in": "query", + "required": true, + "description": "Search query string.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "base chain x402 micropayments" }, { - "$ref": "#/components/parameters/QueryParam" + "name": "limit", + "in": "query", + "required": false, + "description": "Number of results to return.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "default": 10 + }, + "example": 5 }, { - "$ref": "#/components/parameters/LimitParam" + "name": "include_domains", + "in": "query", + "required": false, + "description": "Comma-separated domains to include.", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "maxItems": 20 + }, + "style": "form", + "explode": false, + "example": "queryx.run" }, { - "$ref": "#/components/parameters/LangParam" + "name": "exclude_domains", + "in": "query", + "required": false, + "description": "Comma-separated domains to exclude.", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "maxItems": 20 + }, + "style": "form", + "explode": false, + "example": "ads.queryx.run" }, { - "$ref": "#/components/parameters/RegionParam" + "name": "hl", + "in": "query", + "required": false, + "description": "Language code.", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 10, + "default": "en" + }, + "example": "en" }, { - "$ref": "#/components/parameters/SafeSearchParam" + "name": "gl", + "in": "query", + "required": false, + "description": "Geographic region code.", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 2 + }, + "example": "US" }, { - "$ref": "#/components/parameters/TimeRangeParam" + "name": "freshness", + "in": "query", + "required": false, + "description": "Time filter for indexed documents.", + "schema": { + "type": "string", + "enum": [ + "day", + "week", + "month", + "year", + "anytime" + ], + "default": "anytime" + }, + "example": "month" }, { - "$ref": "#/components/parameters/PageParam" + "name": "safe_search", + "in": "query", + "required": false, + "description": "Safe-search policy.", + "schema": { + "type": "string", + "enum": [ + "strict", + "moderate", + "off" + ], + "default": "moderate" + }, + "example": "moderate" } ], "responses": { "200": { - "description": "Web search results", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer", - "example": 120 - }, - "description": "Requests allowed per rolling 60-second window for this endpoint." - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer", - "example": 119 - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer", - "example": 1710000059 - }, - "description": "Unix epoch seconds when the current window resets." - } - }, + "description": "Search results.", "content": { "application/json": { "schema": { @@ -134,40 +169,30 @@ }, "examples": { "success": { + "summary": "Web search success", "value": { - "id": "srch_01JP5B4V2Y1X4W7N9A3ZQ8M2P0", - "query": "best vector database for rag", - "tookMs": 412, - "page": 1, - "limit": 5, - "totalEstimatedResults": 1240000, + "query": "base chain x402 micropayments", + "request_id": "req_01HTZ6Q2X7R7N0G9QWR5Q0Y6EA", + "took_ms": 182, + "total_results": 12840, "results": [ { - "title": "Vector Databases for Retrieval-Augmented Generation", - "url": "https://example.com/vector-db-rag", - "snippet": "A practical comparison of Pinecone, Weaviate, Qdrant, and pgvector for RAG workloads.", - "source": "example.com", - "publishedAt": "2026-02-18T13:00:00Z", + "title": "Queryx x402 overview", + "url": "https://queryx.run/content/x402-overview", + "snippet": "Queryx supports x402 payment for metered API access over Base USDC.", + "source": "queryx.run", "score": 0.98, - "faviconUrl": "https://example.com/favicon.ico" + "published_at": "2026-02-28T18:05:10Z" }, { - "title": "pgvector vs Dedicated Vector DBs", - "url": "https://example.org/pgvector-vs-dedicated", - "snippet": "When Postgres with pgvector is enough, and when to move to a specialized store.", - "source": "example.org", - "publishedAt": "2026-01-29T08:22:11Z", - "score": 0.94, - "faviconUrl": "https://example.org/favicon.png" + "title": "Building paid agents with Queryx", + "url": "https://queryx.run/content/paid-agents", + "snippet": "Agent-ready examples for paid search with deterministic retries.", + "source": "queryx.run", + "score": 0.93, + "published_at": "2026-02-20T11:40:55Z" } - ], - "nextPage": 2, - "charge": { - "asset": "USDC", - "chain": "base", - "amountBaseUnits": "2500", - "amount": "0.0025" - } + ] } } } @@ -175,24 +200,25 @@ } }, "402": { - "$ref": "#/components/responses/PaymentRequiredSearch" + "$ref": "#/components/responses/Error402" }, "422": { - "$ref": "#/components/responses/ValidationError" + "$ref": "#/components/responses/Error422" }, "429": { - "$ref": "#/components/responses/RateLimitExceeded" + "$ref": "#/components/responses/Error429" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/Error500" } }, - "x-pricing": { - "asset": "USDC", - "chain": "base", - "amountBaseUnits": "2500", - "amount": "0.0025" - } + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -sS -G 'https://queryx.run/v1/search' \\\n --data-urlencode 'q=base chain x402 micropayments' \\\n --data-urlencode 'limit=5' \\\n -H 'X-PAYMENT: '" + } + ] } }, "/v1/search/news": { @@ -201,8 +227,8 @@ "Search" ], "operationId": "searchNews", - "summary": "News search", - "description": "Searches recent news sources with recency-aware ranking. Requires x402 payment.", + "summary": "Search recent news", + "description": "Returns ranked and time-aware news results. Requires x402 payment via X-PAYMENT header.", "security": [ { "x402": [] @@ -210,50 +236,81 @@ ], "parameters": [ { - "$ref": "#/components/parameters/X402SignatureHeader" - }, - { - "$ref": "#/components/parameters/QueryParam" + "name": "q", + "in": "query", + "required": true, + "description": "News query string.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "example": "base ecosystem funding" }, { - "$ref": "#/components/parameters/LimitParam" + "name": "limit", + "in": "query", + "required": false, + "description": "Number of news articles to return.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 50, + "default": 10 + }, + "example": 10 }, { - "$ref": "#/components/parameters/LangParam" + "name": "from", + "in": "query", + "required": false, + "description": "Lower bound publication date (inclusive, ISO 8601 date).", + "schema": { + "type": "string", + "format": "date" + }, + "example": "2026-02-01" }, { - "$ref": "#/components/parameters/RegionParam" + "name": "to", + "in": "query", + "required": false, + "description": "Upper bound publication date (inclusive, ISO 8601 date).", + "schema": { + "type": "string", + "format": "date" + }, + "example": "2026-03-04" }, { - "$ref": "#/components/parameters/NewsFromParam" + "name": "hl", + "in": "query", + "required": false, + "description": "Language code.", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 10, + "default": "en" + }, + "example": "en" }, { - "$ref": "#/components/parameters/PageParam" + "name": "gl", + "in": "query", + "required": false, + "description": "Geographic region code.", + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 2 + }, + "example": "US" } ], "responses": { "200": { - "description": "News search results", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer", - "example": 90 - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer", - "example": 89 - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer", - "example": 1710000059 - } - } - }, + "description": "News search results.", "content": { "application/json": { "schema": { @@ -261,42 +318,32 @@ }, "examples": { "success": { + "summary": "News search success", "value": { - "id": "news_01JP5BFJGDXM8R4NCC2P8XQ2N1", - "query": "fed interest rates", - "tookMs": 376, - "page": 1, - "limit": 3, - "totalEstimatedResults": 18200, + "query": "base ecosystem funding", + "request_id": "req_01HTZ7C9F6Y5M3E1X0M4KJ7W91", + "took_ms": 204, + "total_results": 187, "results": [ { - "title": "Federal Reserve Holds Rates Steady", - "url": "https://news.example.com/fed-holds-rates", - "snippet": "Officials signaled they still expect cuts later this year if inflation cools.", - "source": "news.example.com", - "outlet": "Example News", - "publishedAt": "2026-03-03T18:34:00Z", - "imageUrl": "https://news.example.com/images/fed.jpg", - "score": 0.97 + "title": "Ecosystem grant expansion announced", + "url": "https://queryx.run/content/news/ecosystem-grants", + "snippet": "New grants target developer tooling and AI agents.", + "source": "queryx.run", + "publisher": "Queryx Newsroom", + "score": 0.95, + "published_at": "2026-03-03T14:10:00Z" }, { - "title": "Markets React to Fed Decision", - "url": "https://markets.example.org/fed-market-reaction", - "snippet": "Treasury yields dipped while equities turned mixed after the announcement.", - "source": "markets.example.org", - "outlet": "Markets Daily", - "publishedAt": "2026-03-03T19:08:00Z", - "imageUrl": "https://markets.example.org/images/rates.png", - "score": 0.95 + "title": "Onchain payments for API access keep growing", + "url": "https://queryx.run/content/news/onchain-api-payments", + "snippet": "x402 usage expands across search and data APIs.", + "source": "queryx.run", + "publisher": "Queryx Newsroom", + "score": 0.91, + "published_at": "2026-03-02T09:00:00Z" } - ], - "nextPage": 2, - "charge": { - "asset": "USDC", - "chain": "base", - "amountBaseUnits": "3500", - "amount": "0.0035" - } + ] } } } @@ -304,44 +351,40 @@ } }, "402": { - "$ref": "#/components/responses/PaymentRequiredNews" + "$ref": "#/components/responses/Error402" }, "422": { - "$ref": "#/components/responses/ValidationError" + "$ref": "#/components/responses/Error422" }, "429": { - "$ref": "#/components/responses/RateLimitExceeded" + "$ref": "#/components/responses/Error429" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/Error500" } }, - "x-pricing": { - "asset": "USDC", - "chain": "base", - "amountBaseUnits": "3500", - "amount": "0.0035" - } + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -sS -G 'https://queryx.run/v1/search/news' \\\n --data-urlencode 'q=base ecosystem funding' \\\n --data-urlencode 'limit=10' \\\n -H 'X-PAYMENT: '" + } + ] } }, "/v1/search/deep": { "post": { "tags": [ - "Search" + "Deep Research" ], "operationId": "searchDeep", - "summary": "Deep research search", - "description": "Runs a multi-source deep research pass and returns a synthesized report with citations. Requires x402 payment.", + "summary": "Deep research query with synthesized answer", + "description": "Performs multi-source retrieval and synthesis with citations. Higher cost than standard search. Requires x402 payment via X-PAYMENT header.", "security": [ { "x402": [] } ], - "parameters": [ - { - "$ref": "#/components/parameters/X402SignatureHeader" - } - ], "requestBody": { "required": true, "content": { @@ -350,29 +393,18 @@ "$ref": "#/components/schemas/DeepSearchRequest" }, "examples": { - "standard": { + "default": { + "summary": "Deep query request", "value": { - "query": "compare open-source observability stacks for kubernetes", - "depth": "standard", - "maxSources": 10, - "includeDomains": [ - "cncf.io", - "opentelemetry.io" - ], - "excludeDomains": [ - "reddit.com" + "query": "What changed in x402 payment adoption over the last 6 months?", + "objective": "Summarize key trends, include concrete adoption signals and likely implications for agent builders.", + "max_sources": 10, + "include_domains": [ + "queryx.run" ], - "style": "balanced", - "includeRawResults": false - } - }, - "comprehensive": { - "value": { - "query": "state of solid-state battery commercialization timelines", - "depth": "comprehensive", - "maxSources": 20, - "style": "thorough", - "includeRawResults": true + "exclude_domains": [], + "recency": "year", + "output_format": "markdown" } } } @@ -381,27 +413,7 @@ }, "responses": { "200": { - "description": "Deep research report", - "headers": { - "X-RateLimit-Limit": { - "schema": { - "type": "integer", - "example": 30 - } - }, - "X-RateLimit-Remaining": { - "schema": { - "type": "integer", - "example": 29 - } - }, - "X-RateLimit-Reset": { - "schema": { - "type": "integer", - "example": 1710000059 - } - } - }, + "description": "Synthesized deep-research response.", "content": { "application/json": { "schema": { @@ -409,43 +421,35 @@ }, "examples": { "success": { + "summary": "Deep research success", "value": { - "id": "deep_01JP5BR2B3FDMZ1W9W5V8PNN7X", - "query": "state of solid-state battery commercialization timelines", - "depth": "comprehensive", - "tookMs": 4821, - "summary": "Solid-state batteries are moving from pilot to early commercial deployments, with meaningful scale expected between 2027 and 2030.", - "report": "## Commercialization outlook\nMost manufacturers remain in pilot-scale or limited-volume production...", - "keyFindings": [ - "Pilot lines are live across automotive suppliers in Asia, Europe, and the U.S.", - "Cost parity with high-nickel lithium-ion is unlikely before late 2028 for most use cases.", - "Automotive deployments are expected to lead consumer electronics in absolute pack volume." + "query": "What changed in x402 payment adoption over the last 6 months?", + "request_id": "req_01HTZ8JQNX7Q2S2N9A6M8K7BXR", + "took_ms": 2950, + "summary": "x402 adoption accelerated as API providers shifted from subscriptions to per-call micropayments. Growth concentrated in search and data APIs where deterministic unit pricing is important for autonomous agents.", + "key_findings": [ + "Micropayment acceptance broadened among API-first products.", + "USDC settlement on Base reduced payment friction for agent workflows.", + "402-first retry logic became standard in SDK patterns." ], "citations": [ { - "id": "c1", - "title": "Automaker Roadmap for Solid-State Cells", - "url": "https://example.com/automaker-solid-state-roadmap", - "snippet": "Volume production target moved to 2028 with pilot fleet testing in 2027.", - "source": "example.com", - "publishedAt": "2026-01-15T09:30:00Z" + "title": "Queryx x402 overview", + "url": "https://queryx.run/content/x402-overview", + "snippet": "Protocol and payment envelope details.", + "source": "queryx.run", + "relevance": 0.97 }, { - "id": "c2", - "title": "Electrolyte Manufacturing Constraints", - "url": "https://example.org/electrolyte-manufacturing", - "snippet": "Sulfide electrolyte scale-up remains a bottleneck through 2027.", - "source": "example.org", - "publishedAt": "2025-12-02T14:04:00Z" + "title": "Building paid agents with Queryx", + "url": "https://queryx.run/content/paid-agents", + "snippet": "Implementation patterns and retry flow.", + "source": "queryx.run", + "relevance": 0.92 } ], - "searchResultsAnalyzed": 20, - "charge": { - "asset": "USDC", - "chain": "base", - "amountBaseUnits": "15000", - "amount": "0.0150" - } + "sources_searched": 10, + "model": "queryx-deep-v1" } } } @@ -453,24 +457,69 @@ } }, "402": { - "$ref": "#/components/responses/PaymentRequiredDeep" + "$ref": "#/components/responses/Error402" }, "422": { - "$ref": "#/components/responses/ValidationError" + "$ref": "#/components/responses/Error422" }, "429": { - "$ref": "#/components/responses/RateLimitExceeded" + "$ref": "#/components/responses/Error429" }, "500": { - "$ref": "#/components/responses/InternalError" + "$ref": "#/components/responses/Error500" } }, - "x-pricing": { - "asset": "USDC", - "chain": "base", - "amountBaseUnits": "15000", - "amount": "0.0150" - } + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -sS 'https://queryx.run/v1/search/deep' \\\n -X POST \\\n -H 'Content-Type: application/json' \\\n -H 'X-PAYMENT: ' \\\n -d '{\"query\":\"What changed in x402 payment adoption over the last 6 months?\",\"max_sources\":10}'" + } + ] + } + }, + "/health": { + "get": { + "tags": [ + "Health" + ], + "operationId": "healthCheck", + "summary": "Service health check", + "description": "Returns service status and basic runtime metadata.", + "security": [], + "responses": { + "200": { + "description": "Service is healthy.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HealthResponse" + }, + "examples": { + "healthy": { + "summary": "Healthy response", + "value": { + "status": "ok", + "version": "1.0.0", + "uptime_seconds": 86432, + "timestamp": "2026-03-04T16:30:22Z" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/Error500" + } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -sS 'https://queryx.run/health'" + } + ] } } }, @@ -479,199 +528,127 @@ "x402": { "type": "apiKey", "in": "header", - "name": "X-402-Payment", - "description": "Base64-encoded JSON x402 payment payload. Must be accompanied by `X-402-Signature`." - } - }, - "parameters": { - "X402SignatureHeader": { - "name": "X-402-Signature", - "in": "header", - "required": true, - "description": "Hex ECDSA signature for the canonical payment message.", - "schema": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{130}$", - "example": "0x2f9d0019f5ea73f5d9882e5365f28f84a7ea6a2b00823fb2047680cc7f1f3dcd4f8cc127f0d3e29d0a9f16ed1782cfa884c42091efdb7ee64fd4495cf9ef4f4e1b" - } - }, - "QueryParam": { - "name": "q", - "in": "query", - "required": true, - "description": "Search query string.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 1000 - }, - "example": "open telemetry collector scaling best practices" - }, - "LimitParam": { - "name": "limit", - "in": "query", - "required": false, - "description": "Number of results to return.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 - }, - "example": 10 - }, - "LangParam": { - "name": "lang", - "in": "query", - "required": false, - "description": "Language code for ranking preference.", - "schema": { - "type": "string", - "pattern": "^[a-z]{2}(-[A-Z]{2})?$", - "default": "en" - }, - "example": "en" - }, - "RegionParam": { - "name": "region", - "in": "query", - "required": false, - "description": "Region code for localized ranking.", - "schema": { - "type": "string", - "minLength": 2, - "maxLength": 5 - }, - "example": "US" - }, - "SafeSearchParam": { - "name": "safe_search", - "in": "query", - "required": false, - "description": "Filters explicit content from search results.", - "schema": { - "type": "boolean", - "default": true - }, - "example": true - }, - "TimeRangeParam": { - "name": "time_range", - "in": "query", - "required": false, - "description": "Recency filter for web results.", - "schema": { - "type": "string", - "enum": [ - "24h", - "7d", - "30d", - "365d", - "all" - ], - "default": "all" - }, - "example": "30d" - }, - "NewsFromParam": { - "name": "from", - "in": "query", - "required": false, - "description": "Only return news newer than this ISO-8601 timestamp.", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-03-01T00:00:00Z" - }, - "PageParam": { - "name": "page", - "in": "query", - "required": false, - "description": "1-based page index.", - "schema": { - "type": "integer", - "minimum": 1, - "default": 1 - }, - "example": 1 + "name": "X-PAYMENT", + "description": "x402 payment envelope. Send a base64url-encoded JSON object with fields: payment_id, address, nonce, timestamp, signature, signature_algorithm. Signature is generated from canonical_message returned in the 402 response details." } }, "schemas": { - "HealthResponse": { + "SearchResponse": { "type": "object", + "additionalProperties": false, "required": [ - "status", - "service", - "version", - "timestamp", - "uptimeSeconds" + "query", + "request_id", + "took_ms", + "total_results", + "results" ], "properties": { - "status": { - "type": "string", - "enum": [ - "ok" - ] - }, - "service": { - "type": "string", - "example": "queryx" + "query": { + "type": "string" }, - "version": { - "type": "string", - "example": "1.0.0" + "request_id": { + "type": "string" }, - "timestamp": { - "type": "string", - "format": "date-time" + "took_ms": { + "type": "integer", + "minimum": 0 }, - "uptimeSeconds": { + "total_results": { "type": "integer", "minimum": 0 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + } } } }, - "Charge": { + "SearchResult": { "type": "object", + "additionalProperties": false, "required": [ - "asset", - "chain", - "amountBaseUnits", - "amount" + "title", + "url", + "snippet", + "source", + "score", + "published_at" ], "properties": { - "asset": { - "type": "string", - "enum": [ - "USDC" - ] + "title": { + "type": "string" }, - "chain": { + "url": { "type": "string", - "enum": [ - "base" - ] + "format": "uri" }, - "amountBaseUnits": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "USDC base units (6 decimals)." + "snippet": { + "type": "string" }, - "amount": { - "type": "string", - "pattern": "^[0-9]+(\\.[0-9]{1,6})?$", - "description": "Human-readable USDC amount." + "source": { + "type": "string" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "published_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" } } }, - "SearchResult": { + "NewsSearchResponse": { "type": "object", + "additionalProperties": false, + "required": [ + "query", + "request_id", + "took_ms", + "total_results", + "results" + ], + "properties": { + "query": { + "type": "string" + }, + "request_id": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "minimum": 0 + }, + "total_results": { + "type": "integer", + "minimum": 0 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsResult" + } + } + } + }, + "NewsResult": { + "type": "object", + "additionalProperties": false, "required": [ "title", "url", "snippet", - "source" + "source", + "publisher", + "score", + "published_at" ], "properties": { "title": { @@ -687,83 +664,134 @@ "source": { "type": "string" }, - "publishedAt": { - "type": "string", - "format": "date-time" + "publisher": { + "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, - "faviconUrl": { + "published_at": { "type": "string", - "format": "uri" + "format": "date-time" } } }, - "SearchResponse": { + "DeepSearchRequest": { "type": "object", + "additionalProperties": false, + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "objective": { + "type": "string", + "maxLength": 4000 + }, + "max_sources": { + "type": "integer", + "minimum": 1, + "maximum": 25, + "default": 10 + }, + "include_domains": { + "type": "array", + "items": { + "type": "string" + }, + "maxItems": 50 + }, + "exclude_domains": { + "type": "array", + "items": { + "type": "string" + }, + "maxItems": 50 + }, + "recency": { + "type": "string", + "enum": [ + "day", + "week", + "month", + "year", + "anytime" + ], + "default": "anytime" + }, + "output_format": { + "type": "string", + "enum": [ + "markdown", + "json" + ], + "default": "markdown" + } + } + }, + "DeepSearchResponse": { + "type": "object", + "additionalProperties": false, "required": [ - "id", "query", - "tookMs", - "page", - "limit", - "totalEstimatedResults", - "results", - "charge" + "request_id", + "took_ms", + "summary", + "key_findings", + "citations", + "sources_searched", + "model" ], "properties": { - "id": { + "query": { "type": "string" }, - "query": { + "request_id": { "type": "string" }, - "tookMs": { + "took_ms": { "type": "integer", "minimum": 0 }, - "page": { - "type": "integer", - "minimum": 1 - }, - "limit": { - "type": "integer", - "minimum": 1 + "summary": { + "type": "string" }, - "totalEstimatedResults": { - "type": "integer", - "minimum": 0 + "key_findings": { + "type": "array", + "items": { + "type": "string" + } }, - "results": { + "citations": { "type": "array", "items": { - "$ref": "#/components/schemas/SearchResult" + "$ref": "#/components/schemas/Citation" } }, - "nextPage": { - "type": [ - "integer", - "null" - ], - "minimum": 2 + "sources_searched": { + "type": "integer", + "minimum": 0 }, - "charge": { - "$ref": "#/components/schemas/Charge" + "model": { + "type": "string" } } }, - "NewsResult": { + "Citation": { "type": "object", + "additionalProperties": false, "required": [ "title", "url", "snippet", "source", - "outlet", - "publishedAt" + "relevance" ], "properties": { "title": { @@ -779,101 +807,280 @@ "source": { "type": "string" }, - "outlet": { + "relevance": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "HealthResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "status", + "version", + "uptime_seconds", + "timestamp" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "version": { "type": "string" }, - "publishedAt": { + "uptime_seconds": { + "type": "integer", + "minimum": 0 + }, + "timestamp": { "type": "string", "format": "date-time" + } + } + }, + "ErrorResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "error", + "code", + "message", + "request_id", + "retryable" + ], + "properties": { + "error": { + "type": "string" }, - "imageUrl": { - "type": "string", - "format": "uri" + "code": { + "type": "string" }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 + "message": { + "type": "string" + }, + "request_id": { + "type": "string" + }, + "retryable": { + "type": "boolean" + }, + "details": { + "oneOf": [ + { + "$ref": "#/components/schemas/PaymentRequiredDetails" + }, + { + "$ref": "#/components/schemas/ValidationErrorDetails" + }, + { + "$ref": "#/components/schemas/RateLimitErrorDetails" + }, + { + "$ref": "#/components/schemas/InternalErrorDetails" + } + ] } } }, - "NewsSearchResponse": { + "PaymentRequiredDetails": { "type": "object", + "additionalProperties": false, "required": [ - "id", - "query", - "tookMs", - "page", - "limit", - "totalEstimatedResults", - "results", - "charge" + "payment_id", + "asset", + "token_address", + "chain_id", + "facilitator_address", + "amount_base_units", + "amount_usdc", + "nonce", + "timestamp", + "expires_at", + "signature_algorithm", + "canonical_message" ], "properties": { - "id": { + "payment_id": { "type": "string" }, - "query": { + "asset": { + "type": "string", + "enum": [ + "USDC" + ] + }, + "token_address": { "type": "string" }, - "tookMs": { + "chain_id": { "type": "integer", - "minimum": 0 + "enum": [ + 8453 + ] }, - "page": { - "type": "integer", - "minimum": 1 + "facilitator_address": { + "type": "string" }, - "limit": { - "type": "integer", - "minimum": 1 + "amount_base_units": { + "type": "string", + "description": "USDC base units (6 decimals)." }, - "totalEstimatedResults": { - "type": "integer", - "minimum": 0 + "amount_usdc": { + "type": "string" }, - "results": { + "nonce": { + "type": "string" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "signature_algorithm": { + "type": "string", + "enum": [ + "eip191_personal_sign" + ] + }, + "canonical_message": { + "type": "string", + "description": "Exact message that must be signed by the payer wallet." + } + } + }, + "ValidationErrorDetails": { + "type": "object", + "additionalProperties": false, + "required": [ + "errors" + ], + "properties": { + "errors": { "type": "array", "items": { - "$ref": "#/components/schemas/NewsResult" + "$ref": "#/components/schemas/FieldValidationError" } + } + } + }, + "FieldValidationError": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "message" + ], + "properties": { + "path": { + "type": "string" }, - "nextPage": { - "type": [ - "integer", - "null" - ], - "minimum": 2 - }, - "charge": { - "$ref": "#/components/schemas/Charge" + "message": { + "type": "string" } } }, - "DeepSearchRequest": { + "RateLimitErrorDetails": { "type": "object", + "additionalProperties": false, "required": [ - "query" + "limit", + "remaining", + "reset_at", + "retry_after_seconds" ], "properties": { - "query": { - "type": "string", - "minLength": 1, - "maxLength": 2000 + "limit": { + "type": "integer", + "minimum": 1 }, - "depth": { + "remaining": { + "type": "integer", + "minimum": 0 + }, + "reset_at": { "type": "string", - "enum": [ - "standard", - "comprehensive" - ], - "default": "standard" + "format": "date-time" }, - "maxSources": { + "retry_after_seconds": { "type": "integer", - "minimum": 3, - "maximum": 50, - "default": 12 - }, - "includeDomains": { - "type": " \ No newline at end of file + "minimum": 1 + } + } + }, + "InternalErrorDetails": { + "type": "object", + "additionalProperties": false, + "required": [ + "support_code" + ], + "properties": { + "support_code": { + "type": "string" + } + } + } + }, + "headers": { + "X-RateLimit-Limit": { + "description": "Maximum requests allowed in the current window.", + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Remaining": { + "description": "Remaining requests in the current window.", + "schema": { + "type": "integer" + } + }, + "X-RateLimit-Reset": { + "description": "Epoch seconds when rate limit resets.", + "schema": { + "type": "integer" + } + }, + "Retry-After": { + "description": "Seconds to wait before retrying.", + "schema": { + "type": "integer" + } + } + }, + "responses": { + "Error402": { + "description": "Payment required. Client must construct x402 payment signature and retry.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "paymentRequired": { + "summary": "x402 challenge", + "value": { + "error": "payment_required", + "code": "payment_required", + "message": "Payment required for this endpoint.", + "request_id": "req_01HTZA2CVG8YPB8BKX4E2V0J5F", + "retryable": true, + "details": { + "payment_id": "pay_01HTZA2CVQY2Z5T9RA2ZES2J8T", + "asset": "USDC", + "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bDa02913", + "chain_id": 8453, + "facilitator_address": "0x2B3a5cA6D4E2Ff0dA9fD3C4e8B7A1c2D6E5f9012", + "amount_base_units": "2500", + "amount_usdc": "0.0025", + "nonce": "6f5f9f99b4b64726a1b26c9d8f407ec6", + "timestamp": "2026-03-04T16:30:22Z", + "expires_at": "2026-03-04T16:32:22Z", + "signature_algorithm": "eip191_personal_sign", + "canonical_message": "pay_01HTZA2CVQY2Z5T9RA2ZES2J8T\nGET\n/v1/search\nq=base+chain+x402+micropayments&limit=5\n2500\nUS \ No newline at end of file From 2b097da13e497dba2d9d7c072a2c76da0c519ef6 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:53:03 +0000 Subject: [PATCH 12/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- openapi.json | 1399 ++++++++++++++++++++++++++------------------------ 1 file changed, 723 insertions(+), 676 deletions(-) diff --git a/openapi.json b/openapi.json index 6d738cf..592b3bd 100644 --- a/openapi.json +++ b/openapi.json @@ -1,14 +1,9 @@ { "openapi": "3.1.0", - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Queryx API", "version": "1.0.0", - "summary": "x402-native web and research search API", - "description": "Queryx provides paid web search, news search, and deep research endpoints protected by x402 payments on Base.", - "license": { - "name": "MIT" - } + "description": "Queryx provides paid web search, news search, and deep research endpoints secured with x402 on Base." }, "servers": [ { @@ -18,33 +13,23 @@ ], "tags": [ { - "name": "health", - "description": "Service health checks" - }, - { - "name": "search", - "description": "Web and news retrieval" + "name": "System", + "description": "Service health and runtime status" }, { - "name": "research", - "description": "Multi-hop deep research" - } - ], - "security": [ - { - "x402": [] + "name": "Search", + "description": "Core search endpoints" } ], "paths": { "/health": { "get": { + "operationId": "healthCheck", "tags": [ - "health" + "System" ], - "operationId": "getHealth", "summary": "Health check", - "description": "Returns service health status. This endpoint is free and does not require x402 payment.", - "security": [], + "description": "Returns service health and version metadata.", "responses": { "200": { "description": "Service is healthy", @@ -59,7 +44,7 @@ "status": "ok", "service": "queryx", "version": "1.0.0", - "uptime_s": 92831 + "timestamp": "2026-03-04T00:00:00Z" } } } @@ -67,123 +52,112 @@ } }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } }, "/v1/search": { "get": { + "operationId": "searchWeb", "tags": [ - "search" + "Search" ], - "operationId": "searchWeb", "summary": "Web search", - "description": "Returns ranked web results with optional synthesized answer.", - "x-pricing": { - "asset": "USDC", - "usdc_base_units": "5000", - "usdc_human": "0.005" - }, + "description": "Returns ranked web results and optional short synthesis for a query.", + "security": [ + { + "x402": [] + } + ], "parameters": [ { "name": "q", "in": "query", "required": true, - "description": "Search query", + "description": "Search query text.", "schema": { "type": "string", "minLength": 1, - "maxLength": 500 + "maxLength": 400 }, - "examples": { - "basic": { - "value": "best rust web framework 2026" - } - } + "example": "best vector databases for rag" }, { - "name": "count", + "name": "limit", "in": "query", "required": false, - "description": "Number of results to return", + "description": "Maximum number of results.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 - } + }, + "example": 10 }, { "name": "lang", "in": "query", "required": false, - "description": "Language code (ISO 639-1)", + "description": "ISO-639-1 language code.", "schema": { "type": "string", - "minLength": 2, - "maxLength": 5, + "pattern": "^[a-z]{2}$", "default": "en" - } + }, + "example": "en" }, { "name": "country", "in": "query", "required": false, - "description": "Country code (ISO 3166-1 alpha-2)", + "description": "ISO-3166-1 alpha-2 country code.", "schema": { "type": "string", - "minLength": 2, - "maxLength": 2 - } + "pattern": "^[A-Z]{2}$", + "default": "US" + }, + "example": "US" }, { - "name": "freshness", + "name": "safe", "in": "query", "required": false, - "description": "Optional recency filter", + "description": "Safe search mode.", "schema": { "type": "string", "enum": [ - "24h", - "7d", - "30d", - "365d", - "all" + "off", + "moderate", + "strict" ], - "default": "all" - } + "default": "moderate" + }, + "example": "moderate" + }, + { + "$ref": "#/components/parameters/X402AddressHeader" + }, + { + "$ref": "#/components/parameters/X402AmountHeader" + }, + { + "$ref": "#/components/parameters/X402AssetHeader" + }, + { + "$ref": "#/components/parameters/X402TimestampHeader" + }, + { + "$ref": "#/components/parameters/X402NonceHeader" + }, + { + "$ref": "#/components/parameters/X402ChainIdHeader" } ], "responses": { "200": { - "description": "Web search results", - "headers": { - "X-Request-Id": { - "description": "Unique request identifier", - "schema": { - "type": "string" - } - }, - "X-RateLimit-Limit": { - "description": "Requests allowed in the current window", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "description": "Remaining requests in the current window", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "description": "Unix epoch seconds when window resets", - "schema": { - "type": "integer" - } - } - }, + "description": "Search results returned", "content": { "application/json": { "schema": { @@ -192,33 +166,37 @@ "examples": { "success": { "value": { - "query": "best rust web framework 2026", - "answer": "Actix Web and Axum remain the most commonly adopted Rust web frameworks for high-performance production APIs.", + "requestId": "req_7f8d971d", + "query": "best vector databases for rag", + "tookMs": 143, + "answer": "For most RAG workloads, managed vector databases with strong filtering and hybrid retrieval support are the easiest place to start.", "results": [ { - "title": "Axum vs Actix: performance benchmark 2026", - "url": "https://example.com/axum-vs-actix-2026", - "snippet": "Benchmarks show both frameworks perform strongly, with tradeoffs in ergonomics and ecosystem.", - "source": "example.com", - "published_at": "2026-01-22T13:03:00Z", - "score": 0.93 + "title": "Queryx API", + "url": "https://queryx.run", + "snippet": "Queryx provides web, news, and deep research search endpoints secured with x402.", + "source": "queryx.run", + "publishedAt": null, + "score": 0.94 }, { - "title": "Building APIs with Axum", - "url": "https://example.com/building-apis-axum", - "snippet": "A practical guide to middleware, extraction, and state patterns in Axum.", - "source": "example.com", - "published_at": "2025-11-19T09:00:00Z", - "score": 0.88 + "title": "langoustine69/queryx", + "url": "https://github.com/langoustine69/queryx", + "snippet": "Open source repository for Queryx service and specs.", + "source": "github.com", + "publishedAt": "2026-03-01T12:00:00Z", + "score": 0.89 } ], - "took_ms": 247, - "request_id": "req_9f89b9e85ef345f1", + "pagination": { + "limit": 10, + "nextCursor": null + }, "billing": { "endpoint": "/v1/search", "asset": "USDC", - "amount_base_units": "5000", - "amount": "0.005" + "amount": "0.0025", + "amountBaseUnits": "2500" } } } @@ -230,144 +208,127 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/UnprocessableEntity" + "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/TooManyRequests" + "$ref": "#/components/responses/RateLimited" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } }, "/v1/search/news": { "get": { + "operationId": "searchNews", "tags": [ - "search" + "Search" ], - "operationId": "searchNews", "summary": "News search", - "description": "Returns recent and relevant news articles.", - "x-pricing": { - "asset": "USDC", - "usdc_base_units": "7500", - "usdc_human": "0.0075" - }, + "description": "Returns ranked recent news results for a query.", + "security": [ + { + "x402": [] + } + ], "parameters": [ { "name": "q", "in": "query", "required": true, - "description": "News query", + "description": "News query text.", "schema": { "type": "string", "minLength": 1, - "maxLength": 500 + "maxLength": 400 }, - "examples": { - "basic": { - "value": "base layer 2 ecosystem funding" - } - } + "example": "base ecosystem updates" }, { - "name": "count", + "name": "limit", "in": "query", "required": false, - "description": "Number of articles to return", + "description": "Maximum number of news results.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 - } - }, - { - "name": "lang", - "in": "query", - "required": false, - "description": "Language code (ISO 639-1)", - "schema": { - "type": "string", - "default": "en" - } + }, + "example": 10 }, { - "name": "country", + "name": "from", "in": "query", "required": false, - "description": "Country code (ISO 3166-1 alpha-2)", + "description": "Start date (inclusive).", "schema": { "type": "string", - "minLength": 2, - "maxLength": 2 - } + "format": "date" + }, + "example": "2026-03-01" }, { - "name": "from", + "name": "to", "in": "query", "required": false, - "description": "Lower bound publication date (inclusive)", + "description": "End date (inclusive).", "schema": { "type": "string", "format": "date" - } + }, + "example": "2026-03-04" }, { - "name": "to", + "name": "lang", "in": "query", "required": false, - "description": "Upper bound publication date (inclusive)", + "description": "ISO-639-1 language code.", "schema": { "type": "string", - "format": "date" - } + "pattern": "^[a-z]{2}$", + "default": "en" + }, + "example": "en" }, { "name": "sort", "in": "query", "required": false, - "description": "Sorting strategy", + "description": "Result ordering strategy.", "schema": { "type": "string", "enum": [ "relevance", - "date" + "recency" ], - "default": "relevance" - } + "default": "recency" + }, + "example": "recency" + }, + { + "$ref": "#/components/parameters/X402AddressHeader" + }, + { + "$ref": "#/components/parameters/X402AmountHeader" + }, + { + "$ref": "#/components/parameters/X402AssetHeader" + }, + { + "$ref": "#/components/parameters/X402TimestampHeader" + }, + { + "$ref": "#/components/parameters/X402NonceHeader" + }, + { + "$ref": "#/components/parameters/X402ChainIdHeader" } ], "responses": { "200": { - "description": "News results", - "headers": { - "X-Request-Id": { - "description": "Unique request identifier", - "schema": { - "type": "string" - } - }, - "X-RateLimit-Limit": { - "description": "Requests allowed in the current window", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "description": "Remaining requests in the current window", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "description": "Unix epoch seconds when window resets", - "schema": { - "type": "integer" - } - } - }, + "description": "News results returned", "content": { "application/json": { "schema": { @@ -376,32 +337,34 @@ "examples": { "success": { "value": { - "query": "base layer 2 ecosystem funding", - "articles": [ + "requestId": "req_b6db6f3a", + "query": "base ecosystem updates", + "tookMs": 178, + "results": [ { - "title": "L2 startup raises growth round", - "url": "https://example.com/l2-funding-round", - "snippet": "A Base-native infrastructure company announced a new funding round for ecosystem expansion.", - "source": "example.com", - "published_at": "2026-02-19T08:24:00Z", - "image_url": "https://example.com/image.jpg" + "title": "Queryx launch update", + "url": "https://queryx.run", + "snippet": "Queryx added a production OpenAPI 3.1 specification and x402 agent guide.", + "publisher": "queryx.run", + "publishedAt": "2026-03-04T09:30:00Z", + "topic": "technology", + "score": 0.92 }, { - "title": "Institutional interest in L2s increases", - "url": "https://example.com/institutional-l2-interest", - "snippet": "Analysts cite lower settlement costs and improving tooling as growth drivers.", - "source": "example.com", - "published_at": "2026-02-18T14:02:00Z", - "image_url": null + "title": "Repository update", + "url": "https://github.com/langoustine69/queryx", + "snippet": "New docs and pricing details were committed.", + "publisher": "github.com", + "publishedAt": "2026-03-03T16:15:00Z", + "topic": "developer-tools", + "score": 0.86 } ], - "took_ms": 198, - "request_id": "req_8490ba42a2e14c44", "billing": { "endpoint": "/v1/search/news", "asset": "USDC", - "amount_base_units": "7500", - "amount": "0.0075" + "amount": "0.0040", + "amountBaseUnits": "4000" } } } @@ -413,30 +376,50 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/UnprocessableEntity" + "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/TooManyRequests" + "$ref": "#/components/responses/RateLimited" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } }, "/v1/search/deep": { "post": { + "operationId": "deepSearch", "tags": [ - "research" + "Search" ], - "operationId": "deepSearch", "summary": "Deep research search", - "description": "Runs multi-hop retrieval and synthesis for complex research queries.", - "x-pricing": { - "asset": "USDC", - "usdc_base_units": "25000", - "usdc_human": "0.025" - }, + "description": "Runs multi-step retrieval and synthesis, returning structured findings and citations.", + "security": [ + { + "x402": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/X402AddressHeader" + }, + { + "$ref": "#/components/parameters/X402AmountHeader" + }, + { + "$ref": "#/components/parameters/X402AssetHeader" + }, + { + "$ref": "#/components/parameters/X402TimestampHeader" + }, + { + "$ref": "#/components/parameters/X402NonceHeader" + }, + { + "$ref": "#/components/parameters/X402ChainIdHeader" + } + ], "requestBody": { "required": true, "content": { @@ -445,17 +428,18 @@ "$ref": "#/components/schemas/DeepSearchRequest" }, "examples": { - "basic": { + "default": { "value": { - "query": "Compare retrieval-augmented generation frameworks for production observability", - "max_depth": 2, - "max_branches": 4, - "max_results": 20, - "time_range": "365d", - "include_domains": [ - "example.com", - "example.org" - ] + "query": "Summarize Queryx capabilities and usage model", + "maxDepth": 3, + "maxSources": 12, + "includeDomains": [ + "queryx.run", + "github.com" + ], + "excludeDomains": [], + "style": "balanced", + "includeRawExcerpts": false } } } @@ -464,33 +448,7 @@ }, "responses": { "200": { - "description": "Deep research results", - "headers": { - "X-Request-Id": { - "description": "Unique request identifier", - "schema": { - "type": "string" - } - }, - "X-RateLimit-Limit": { - "description": "Requests allowed in the current window", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "description": "Remaining requests in the current window", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "description": "Unix epoch seconds when window resets", - "schema": { - "type": "integer" - } - } - }, + "description": "Deep research result returned", "content": { "application/json": { "schema": { @@ -499,60 +457,43 @@ "examples": { "success": { "value": { - "query": "Compare retrieval-augmented generation frameworks for production observability", - "summary": "Framework A offers strong tracing integrations and lower operational complexity, while Framework B provides broader connector coverage but requires more custom instrumentation.", + "requestId": "req_2de03f66", + "query": "Summarize Queryx capabilities and usage model", + "tookMs": 1439, + "summary": "Queryx offers paid web, news, and deep research search endpoints over x402 with USDC settlement on Base.", "findings": [ { - "title": "Operational visibility is the biggest differentiator", - "analysis": "Teams selecting a framework for long-term production use prioritize traceability, cache introspection, and replay tooling over pure benchmark throughput.", - "confidence": 0.91, - "citation_ids": [ - 1, - 2 - ] + "title": "API surface", + "detail": "The API exposes /v1/search, /v1/search/news, /v1/search/deep, and /health.", + "confidence": 0.97 }, { - "title": "Connector ecosystem impacts time-to-value", - "analysis": "Framework B has more built-in connectors but less opinionated defaults, increasing implementation variance.", - "confidence": 0.84, - "citation_ids": [ - 3 - ] + "title": "Payment model", + "detail": "Paid endpoints return 402 with quote metadata if payment headers are missing or invalid.", + "confidence": 0.94 } ], "citations": [ { - "id": 1, - "title": "Observability patterns in modern RAG systems", - "url": "https://example.com/rag-observability", - "snippet": "Tracing and evaluation loops reduce production incidents and debugging time.", - "source": "example.com", - "published_at": "2025-09-10T12:00:00Z" + "id": "c1", + "title": "Queryx API", + "url": "https://queryx.run", + "excerpt": "Web, news, and deep search endpoints secured with x402.", + "relevance": 0.95 }, { - "id": 2, - "title": "Production lessons from RAG deployments", - "url": "https://example.org/rag-lessons", - "snippet": "Latency and quality regressions are easiest to catch with continuous offline and online evals.", - "source": "example.org", - "published_at": "2026-01-12T08:15:00Z" - }, - { - "id": 3, - "title": "Comparing connector ecosystems", - "url": "https://example.net/connector-ecosystems", - "snippet": "Connector breadth can accelerate pilots but increases maintenance surface area.", - "source": "example.net", - "published_at": "2025-12-02T16:44:00Z" + "id": "c2", + "title": "langoustine69/queryx", + "url": "https://github.com/langoustine69/queryx", + "excerpt": "Repository includes specs and documentation.", + "relevance": 0.9 } ], - "took_ms": 1683, - "request_id": "req_1f2b53f8c6e248f5", "billing": { "endpoint": "/v1/search/deep", "asset": "USDC", - "amount_base_units": "25000", - "amount": "0.025" + "amount": "0.0200", + "amountBaseUnits": "20000" } } } @@ -564,13 +505,13 @@ "$ref": "#/components/responses/PaymentRequired" }, "422": { - "$ref": "#/components/responses/UnprocessableEntity" + "$ref": "#/components/responses/ValidationError" }, "429": { - "$ref": "#/components/responses/TooManyRequests" + "$ref": "#/components/responses/RateLimited" }, "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/InternalError" } } } @@ -581,77 +522,245 @@ "x402": { "type": "apiKey", "in": "header", - "name": "X-PAYMENT", - "description": "x402 payment envelope. Format: x402... Payload must include method/path/query/body hash, amount, asset, chain_id, timestamp, nonce, and signer address." + "name": "X-402-Signature", + "description": "x402 payment signature. Paid requests must also include X-402-Address, X-402-Amount, X-402-Asset, X-402-Timestamp, X-402-Nonce, and X-402-Chain-Id." + } + }, + "parameters": { + "X402AddressHeader": { + "name": "X-402-Address", + "in": "header", + "required": true, + "description": "Payer wallet address.", + "schema": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$" + }, + "example": "0x1111111111111111111111111111111111111111" + }, + "X402AmountHeader": { + "name": "X-402-Amount", + "in": "header", + "required": true, + "description": "Quoted payment amount in USDC base units (6 decimals).", + "schema": { + "type": "string", + "pattern": "^[0-9]+$" + }, + "example": "2500" + }, + "X402AssetHeader": { + "name": "X-402-Asset", + "in": "header", + "required": true, + "description": "Payment asset ticker.", + "schema": { + "type": "string", + "enum": [ + "USDC" + ] + }, + "example": "USDC" + }, + "X402TimestampHeader": { + "name": "X-402-Timestamp", + "in": "header", + "required": true, + "description": "Unix timestamp in seconds.", + "schema": { + "type": "string", + "pattern": "^[0-9]{10}$" + }, + "example": "1772582400" + }, + "X402NonceHeader": { + "name": "X-402-Nonce", + "in": "header", + "required": true, + "description": "Unique per-request nonce.", + "schema": { + "type": "string", + "minLength": 8, + "maxLength": 128 + }, + "example": "4a50d72f-6e30-49c2-a7da-9a3de95ac381" + }, + "X402ChainIdHeader": { + "name": "X-402-Chain-Id", + "in": "header", + "required": true, + "description": "Chain ID for settlement.", + "schema": { + "type": "integer", + "enum": [ + 8453 + ] + }, + "example": 8453 + } + }, + "responses": { + "PaymentRequired": { + "description": "Payment required before processing request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorEnvelope" + }, + "examples": { + "paymentRequired": { + "value": { + "error": { + "code": "PAYMENT_REQUIRED", + "message": "Missing or invalid x402 payment signature", + "details": { + "endpoint": "/v1/search", + "amountBaseUnits": "2500", + "amount": "0.0025", + "asset": "USDC", + "chainId": 8453, + "facilitator": "0x1111111111111111111111111111111111111111", + "expiresAt": "2026-03-04T00:10:00Z", + "accepts": [ + { + "header": "X-402-Signature", + "description": "Signature over canonical request payload" + } + ] + }, + "requestId": "req_f2a49533" + } + } + } + } + } + } + }, + "ValidationError": { + "description": "Request validation failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorEnvelope" + }, + "examples": { + "validationError": { + "value": { + "error": { + "code": "VALIDATION_ERROR", + "message": "Invalid request parameters", + "details": { + "fields": [ + { + "field": "q", + "issue": "Required" + }, + { + "field": "limit", + "issue": "Must be <= 20" + } + ] + }, + "requestId": "req_a91f365b" + } + } + } + } + } + } + }, + "RateLimited": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorEnvelope" + }, + "examples": { + "rateLimited": { + "value": { + "error": { + "code": "RATE_LIMITED", + "message": "Too many requests", + "details": { + "limit": 120, + "remaining": 0, + "window": "1m", + "resetsAt": "2026-03-04T00:01:00Z" + }, + "requestId": "req_71eb1f9e" + } + } + } + } + } + } + }, + "InternalError": { + "description": "Unexpected server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorEnvelope" + }, + "examples": { + "internalError": { + "value": { + "error": { + "code": "INTERNAL_ERROR", + "message": "Unexpected internal failure", + "details": { + "retryable": true + }, + "requestId": "req_2f8df0a7" + } + } + } + } + } + } } }, "schemas": { "HealthResponse": { "type": "object", + "additionalProperties": false, "required": [ "status", "service", "version", - "uptime_s" + "timestamp" ], "properties": { "status": { "type": "string", "enum": [ - "ok", - "degraded" + "ok" ] }, "service": { - "type": "string" + "type": "string", + "enum": [ + "queryx" + ] }, "version": { "type": "string" }, - "uptime_s": { - "type": "integer", - "minimum": 0 + "timestamp": { + "type": "string", + "format": "date-time" } - }, - "additionalProperties": false + } }, - "BillingSummary": { - "type": "object", - "required": [ - "endpoint", - "asset", - "amount_base_units", - "amount" - ], - "properties": { - "endpoint": { - "type": "string" - }, - "asset": { - "type": "string", - "enum": [ - "USDC" - ] - }, - "amount_base_units": { - "type": "string", - "pattern": "^[0-9]+$" - }, - "amount": { - "type": "string", - "pattern": "^[0-9]+(\\.[0-9]+)?$" - } - }, - "additionalProperties": false - }, - "SearchResultItem": { + "SearchResult": { "type": "object", + "additionalProperties": false, "required": [ "title", "url", "snippet", "source", - "published_at", "score" ], "properties": { @@ -659,8 +768,7 @@ "type": "string" }, "url": { - "type": "string", - "format": "uri" + "type": "string" }, "snippet": { "type": "string" @@ -668,8 +776,11 @@ "source": { "type": "string" }, - "published_at": { - "type": "string", + "publishedAt": { + "type": [ + "string", + "null" + ], "format": "date-time" }, "score": { @@ -677,22 +788,78 @@ "minimum": 0, "maximum": 1 } - }, - "additionalProperties": false + } + }, + "BillingInfo": { + "type": "object", + "additionalProperties": false, + "required": [ + "endpoint", + "asset", + "amount", + "amountBaseUnits" + ], + "properties": { + "endpoint": { + "type": "string" + }, + "asset": { + "type": "string", + "enum": [ + "USDC" + ] + }, + "amount": { + "type": "string" + }, + "amountBaseUnits": { + "type": "string", + "pattern": "^[0-9]+$" + } + } + }, + "PaginationInfo": { + "type": "object", + "additionalProperties": false, + "required": [ + "limit", + "nextCursor" + ], + "properties": { + "limit": { + "type": "integer", + "minimum": 1 + }, + "nextCursor": { + "type": [ + "string", + "null" + ] + } + } }, "SearchResponse": { "type": "object", + "additionalProperties": false, "required": [ + "requestId", "query", + "tookMs", "results", - "took_ms", - "request_id", + "pagination", "billing" ], "properties": { + "requestId": { + "type": "string" + }, "query": { "type": "string" }, + "tookMs": { + "type": "integer", + "minimum": 0 + }, "answer": { "type": [ "string", @@ -702,94 +869,91 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/SearchResultItem" + "$ref": "#/components/schemas/SearchResult" } }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "request_id": { - "type": "string" + "pagination": { + "$ref": "#/components/schemas/PaginationInfo" }, "billing": { - "$ref": "#/components/schemas/BillingSummary" + "$ref": "#/components/schemas/BillingInfo" } - }, - "additionalProperties": false + } }, - "NewsArticle": { + "NewsResult": { "type": "object", + "additionalProperties": false, "required": [ "title", "url", "snippet", - "source", - "published_at", - "image_url" + "publisher", + "publishedAt", + "topic", + "score" ], "properties": { "title": { "type": "string" }, "url": { - "type": "string", - "format": "uri" + "type": "string" }, "snippet": { "type": "string" }, - "source": { + "publisher": { "type": "string" }, - "published_at": { + "publishedAt": { "type": "string", "format": "date-time" }, - "image_url": { - "type": [ - "string", - "null" - ], - "format": "uri" + "topic": { + "type": "string" + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1 } - }, - "additionalProperties": false + } }, "NewsSearchResponse": { "type": "object", + "additionalProperties": false, "required": [ + "requestId", "query", - "articles", - "took_ms", - "request_id", + "tookMs", + "results", "billing" ], "properties": { - "query": { + "requestId": { "type": "string" }, - "articles": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NewsArticle" - } + "query": { + "type": "string" }, - "took_ms": { + "tookMs": { "type": "integer", "minimum": 0 }, - "request_id": { - "type": "string" + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsResult" + } }, "billing": { - "$ref": "#/components/schemas/BillingSummary" + "$ref": "#/components/schemas/BillingInfo" } - }, - "additionalProperties": false + } }, "DeepSearchRequest": { "type": "object", + "additionalProperties": false, "required": [ "query" ], @@ -799,132 +963,122 @@ "minLength": 1, "maxLength": 1000 }, - "max_depth": { + "maxDepth": { "type": "integer", "minimum": 1, "maximum": 5, "default": 2 }, - "max_branches": { + "maxSources": { "type": "integer", "minimum": 1, - "maximum": 10, - "default": 4 - }, - "max_results": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 20 - }, - "time_range": { - "type": "string", - "enum": [ - "24h", - "7d", - "30d", - "365d", - "all" - ], - "default": "365d" + "maximum": 50, + "default": 15 }, - "include_domains": { + "includeDomains": { "type": "array", "items": { "type": "string" }, - "maxItems": 50 + "default": [] }, - "exclude_domains": { + "excludeDomains": { "type": "array", "items": { "type": "string" }, - "maxItems": 50 + "default": [] + }, + "style": { + "type": "string", + "enum": [ + "brief", + "balanced", + "detailed" + ], + "default": "balanced" + }, + "includeRawExcerpts": { + "type": "boolean", + "default": false } - }, - "additionalProperties": false + } }, "DeepFinding": { "type": "object", + "additionalProperties": false, "required": [ "title", - "analysis", - "confidence", - "citation_ids" + "detail", + "confidence" ], "properties": { "title": { "type": "string" }, - "analysis": { + "detail": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 - }, - "citation_ids": { - "type": "array", - "items": { - "type": "integer", - "minimum": 1 - } } - }, - "additionalProperties": false + } }, - "Citation": { + "DeepCitation": { "type": "object", + "additionalProperties": false, "required": [ "id", "title", "url", - "snippet", - "source", - "published_at" + "excerpt", + "relevance" ], "properties": { "id": { - "type": "integer", - "minimum": 1 + "type": "string" }, "title": { "type": "string" }, "url": { - "type": "string", - "format": "uri" - }, - "snippet": { "type": "string" }, - "source": { + "excerpt": { "type": "string" }, - "published_at": { - "type": "string", - "format": "date-time" + "relevance": { + "type": "number", + "minimum": 0, + "maximum": 1 } - }, - "additionalProperties": false + } }, "DeepSearchResponse": { "type": "object", + "additionalProperties": false, "required": [ + "requestId", "query", + "tookMs", "summary", "findings", "citations", - "took_ms", - "request_id", "billing" ], "properties": { + "requestId": { + "type": "string" + }, "query": { "type": "string" }, + "tookMs": { + "type": "integer", + "minimum": 0 + }, "summary": { "type": "string" }, @@ -937,307 +1091,200 @@ "citations": { "type": "array", "items": { - "$ref": "#/components/schemas/Citation" + "$ref": "#/components/schemas/DeepCitation" } }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "request_id": { - "type": "string" - }, "billing": { - "$ref": "#/components/schemas/BillingSummary" + "$ref": "#/components/schemas/BillingInfo" } - }, - "additionalProperties": false + } }, - "ValidationError": { + "ErrorEnvelope": { "type": "object", + "additionalProperties": false, "required": [ - "field", - "message" + "error" ], "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" + "error": { + "$ref": "#/components/schemas/ErrorObject" } - }, - "additionalProperties": false + } }, - "RateLimitDetails": { + "ErrorObject": { "type": "object", + "additionalProperties": false, "required": [ - "limit", - "remaining", - "reset_epoch_seconds", - "retry_after_seconds" + "code", + "message", + "requestId" ], "properties": { - "limit": { - "type": "integer", - "minimum": 1 + "code": { + "type": "string", + "enum": [ + "PAYMENT_REQUIRED", + "VALIDATION_ERROR", + "RATE_LIMITED", + "INTERNAL_ERROR" + ] }, - "remaining": { - "type": "integer", - "minimum": 0 + "message": { + "type": "string" }, - "reset_epoch_seconds": { - "type": "integer", - "minimum": 0 + "details": { + "oneOf": [ + { + "$ref": "#/components/schemas/PaymentRequiredDetails" + }, + { + "$ref": "#/components/schemas/ValidationErrorDetails" + }, + { + "$ref": "#/components/schemas/RateLimitDetails" + }, + { + "$ref": "#/components/schemas/InternalErrorDetails" + }, + { + "type": "object" + } + ] }, - "retry_after_seconds": { - "type": "integer", - "minimum": 1 + "requestId": { + "type": "string" } - }, - "additionalProperties": false + } }, "PaymentRequiredDetails": { "type": "object", + "additionalProperties": false, "required": [ + "endpoint", + "amountBaseUnits", + "amount", "asset", - "chain_id", - "facilitator_address", - "required_amount_base_units", - "required_amount", - "expires_at", - "reason" + "chainId", + "facilitator", + "expiresAt", + "accepts" ], "properties": { + "endpoint": { + "type": "string" + }, + "amountBaseUnits": { + "type": "string", + "pattern": "^[0-9]+$" + }, + "amount": { + "type": "string" + }, "asset": { "type": "string", "enum": [ "USDC" ] }, - "chain_id": { + "chainId": { "type": "integer", "enum": [ 8453 ] }, - "facilitator_address": { + "facilitator": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, - "required_amount_base_units": { - "type": "string", - "pattern": "^[0-9]+$" - }, - "required_amount": { - "type": "string", - "pattern": "^[0-9]+(\\.[0-9]+)?$" - }, - "expires_at": { + "expiresAt": { "type": "string", "format": "date-time" }, - "reason": { - "type": "string" - } - }, - "additionalProperties": false - }, - "ErrorObject": { - "type": "object", - "required": [ - "code", - "message", - "status", - "request_id", - "retryable" - ], - "properties": { - "code": { - "type": "string" - }, - "message": { - "type": "string" - }, - "status": { - "type": "integer" - }, - "request_id": { - "type": "string" - }, - "retryable": { - "type": "boolean" - }, - "payment": { - "oneOf": [ - { - "$ref": "#/components/schemas/PaymentRequiredDetails" - }, - { - "type": "null" - } - ] - }, - "validation_errors": { + "accepts": { "type": "array", "items": { - "$ref": "#/components/schemas/ValidationError" - } - }, - "rate_limit": { - "oneOf": [ - { - "$ref": "#/components/schemas/RateLimitDetails" - }, - { - "type": "null" + "type": "object", + "additionalProperties": false, + "required": [ + "header", + "description" + ], + "properties": { + "header": { + "type": "string" + }, + "description": { + "type": "string" + } } - ] + } } - }, - "additionalProperties": false + } }, - "ErrorResponse": { + "ValidationErrorDetails": { "type": "object", + "additionalProperties": false, "required": [ - "error" + "fields" ], "properties": { - "error": { - "$ref": "#/components/schemas/ErrorObject" - } - }, - "additionalProperties": false - } - }, - "responses": { - "PaymentRequired": { - "description": "Payment is required or payment envelope is invalid.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "paymentRequired": { - "value": { - "error": { - "code": "payment_required", - "message": "Valid x402 payment required for this endpoint.", - "status": 402, - "request_id": "req_8f9982136bbd43db", - "retryable": true, - "payment": { - "asset": "USDC", - "chain_id": 8453, - "facilitator_address": "0x6A0F1C8A3B5D5BA43B2E2B4A4B8D7C9A5E4F0123", - "required_amount_base_units": "5000", - "required_amount": "0.005", - "expires_at": "2026-03-04T12:00:00Z", - "reason": "missing_or_invalid_payment_header" - }, - "validation_errors": [], - "rate_limit": null - } - } - } - } - } - } - }, - "UnprocessableEntity": { - "description": "Request validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "validation": { - "value": { - "error": { - "code": "validation_error", - "message": "Invalid request parameters.", - "status": 422, - "request_id": "req_3ab11ed8f2df4d58", - "retryable": false, - "payment": null, - "validation_errors": [ - { - "field": "q", - "message": "q is required" - } - ], - "rate_limit": null - } + "fields": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "field", + "issue" + ], + "properties": { + "field": { + "type": "string" + }, + "issue": { + "type": "string" } } } } } }, - "TooManyRequests": { - "description": "Rate limit exceeded.", - "headers": { - "Retry-After": { - "description": "Seconds until the next retry is allowed", - "schema": { - "type": "integer" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "rateLimit": { - "value": { - "error": { - "code": "rate_limited", - "message": "Rate limit exceeded.", - "status": 429, - "request_id": "req_64c0b35b7f934624", - "retryable": true, - "payment": null, - "validation_errors": [], - "rate_limit": { - "limit": 120, - "remaining": 0, - "reset_epoch_seconds": 1772629800, - "retry_after_seconds": 18 - } - } - } - } - } + "RateLimitDetails": { + "type": "object", + "additionalProperties": false, + "required": [ + "limit", + "remaining", + "window", + "resetsAt" + ], + "properties": { + "limit": { + "type": "integer", + "minimum": 1 + }, + "remaining": { + "type": "integer", + "minimum": 0 + }, + "window": { + "type": "string" + }, + "resetsAt": { + "type": "string", + "format": "date-time" } } }, - "InternalServerError": { - "description": "Unexpected internal server error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "serverError": { - "value": { - "error": { - "code": "internal_error", - "message": "Unexpected internal error.", - "status": 500, - "request_id": "req_7f8f87e2d1554c84", - "retryable": true, - "payment": null, - "validation_errors": [], - "rate_limit": null - } - } - } - } + "InternalErrorDetails": { + "type": "object", + "additionalProperties": false, + "required": [ + "retryable" + ], + "properties": { + "retryable": { + "type": "boolean" } } } From 5897de3f65de4c69f3d58123d2f50f009ec8fda4 Mon Sep 17 00:00:00 2001 From: Jackson Date: Wed, 4 Mar 2026 16:55:42 +0000 Subject: [PATCH 13/13] feat: implement task 0xf68668ba9a9b017610 via TaskMarket agent #24583 --- IMPLEMENTATION.md | 1086 --------------------------------------------- 1 file changed, 1086 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index 41fdf09..e69de29 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,1086 +0,0 @@ -=== FILE: openapi.json === -{ - "openapi": "3.1.0", - "info": { - "title": "Queryx API", - "version": "1.0.0", - "summary": "Paid web, news, and deep research search API using x402 micropayments.", - "description": "Queryx provides high-quality search and research endpoints with per-request x402 payment on Base (USDC)." - }, - "servers": [ - { - "url": "https://queryx.run", - "description": "Production" - } - ], - "tags": [ - { - "name": "Search", - "description": "Web and news search endpoints." - }, - { - "name": "Deep Research", - "description": "Higher-cost endpoint for synthesized research answers with citations." - }, - { - "name": "Health", - "description": "Service health and readiness." - } - ], - "paths": { - "/v1/search": { - "get": { - "tags": [ - "Search" - ], - "operationId": "searchWeb", - "summary": "Search the web", - "description": "Returns ranked web search results for a query. Requires x402 payment via X-PAYMENT header.", - "security": [ - { - "x402": [] - } - ], - "parameters": [ - { - "name": "q", - "in": "query", - "required": true, - "description": "Search query string.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "example": "base chain x402 micropayments" - }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "Number of results to return.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 20, - "default": 10 - }, - "example": 5 - }, - { - "name": "include_domains", - "in": "query", - "required": false, - "description": "Comma-separated domains to include.", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "maxItems": 20 - }, - "style": "form", - "explode": false, - "example": "queryx.run" - }, - { - "name": "exclude_domains", - "in": "query", - "required": false, - "description": "Comma-separated domains to exclude.", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "maxItems": 20 - }, - "style": "form", - "explode": false, - "example": "ads.queryx.run" - }, - { - "name": "hl", - "in": "query", - "required": false, - "description": "Language code.", - "schema": { - "type": "string", - "minLength": 2, - "maxLength": 10, - "default": "en" - }, - "example": "en" - }, - { - "name": "gl", - "in": "query", - "required": false, - "description": "Geographic region code.", - "schema": { - "type": "string", - "minLength": 2, - "maxLength": 2 - }, - "example": "US" - }, - { - "name": "freshness", - "in": "query", - "required": false, - "description": "Time filter for indexed documents.", - "schema": { - "type": "string", - "enum": [ - "day", - "week", - "month", - "year", - "anytime" - ], - "default": "anytime" - }, - "example": "month" - }, - { - "name": "safe_search", - "in": "query", - "required": false, - "description": "Safe-search policy.", - "schema": { - "type": "string", - "enum": [ - "strict", - "moderate", - "off" - ], - "default": "moderate" - }, - "example": "moderate" - } - ], - "responses": { - "200": { - "description": "Search results.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchResponse" - }, - "examples": { - "success": { - "summary": "Web search success", - "value": { - "query": "base chain x402 micropayments", - "request_id": "req_01HTZ6Q2X7R7N0G9QWR5Q0Y6EA", - "took_ms": 182, - "total_results": 12840, - "results": [ - { - "title": "Queryx x402 overview", - "url": "https://queryx.run/content/x402-overview", - "snippet": "Queryx supports x402 payment for metered API access over Base USDC.", - "source": "queryx.run", - "score": 0.98, - "published_at": "2026-02-28T18:05:10Z" - }, - { - "title": "Building paid agents with Queryx", - "url": "https://queryx.run/content/paid-agents", - "snippet": "Agent-ready examples for paid search with deterministic retries.", - "source": "queryx.run", - "score": 0.93, - "published_at": "2026-02-20T11:40:55Z" - } - ] - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/Error402" - }, - "422": { - "$ref": "#/components/responses/Error422" - }, - "429": { - "$ref": "#/components/responses/Error429" - }, - "500": { - "$ref": "#/components/responses/Error500" - } - }, - "x-codeSamples": [ - { - "lang": "bash", - "label": "cURL", - "source": "curl -sS -G 'https://queryx.run/v1/search' \\\n --data-urlencode 'q=base chain x402 micropayments' \\\n --data-urlencode 'limit=5' \\\n -H 'X-PAYMENT: '" - } - ] - } - }, - "/v1/search/news": { - "get": { - "tags": [ - "Search" - ], - "operationId": "searchNews", - "summary": "Search recent news", - "description": "Returns ranked and time-aware news results. Requires x402 payment via X-PAYMENT header.", - "security": [ - { - "x402": [] - } - ], - "parameters": [ - { - "name": "q", - "in": "query", - "required": true, - "description": "News query string.", - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "example": "base ecosystem funding" - }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "Number of news articles to return.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 50, - "default": 10 - }, - "example": 10 - }, - { - "name": "from", - "in": "query", - "required": false, - "description": "Lower bound publication date (inclusive, ISO 8601 date).", - "schema": { - "type": "string", - "format": "date" - }, - "example": "2026-02-01" - }, - { - "name": "to", - "in": "query", - "required": false, - "description": "Upper bound publication date (inclusive, ISO 8601 date).", - "schema": { - "type": "string", - "format": "date" - }, - "example": "2026-03-04" - }, - { - "name": "hl", - "in": "query", - "required": false, - "description": "Language code.", - "schema": { - "type": "string", - "minLength": 2, - "maxLength": 10, - "default": "en" - }, - "example": "en" - }, - { - "name": "gl", - "in": "query", - "required": false, - "description": "Geographic region code.", - "schema": { - "type": "string", - "minLength": 2, - "maxLength": 2 - }, - "example": "US" - } - ], - "responses": { - "200": { - "description": "News search results.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewsSearchResponse" - }, - "examples": { - "success": { - "summary": "News search success", - "value": { - "query": "base ecosystem funding", - "request_id": "req_01HTZ7C9F6Y5M3E1X0M4KJ7W91", - "took_ms": 204, - "total_results": 187, - "results": [ - { - "title": "Ecosystem grant expansion announced", - "url": "https://queryx.run/content/news/ecosystem-grants", - "snippet": "New grants target developer tooling and AI agents.", - "source": "queryx.run", - "publisher": "Queryx Newsroom", - "score": 0.95, - "published_at": "2026-03-03T14:10:00Z" - }, - { - "title": "Onchain payments for API access keep growing", - "url": "https://queryx.run/content/news/onchain-api-payments", - "snippet": "x402 usage expands across search and data APIs.", - "source": "queryx.run", - "publisher": "Queryx Newsroom", - "score": 0.91, - "published_at": "2026-03-02T09:00:00Z" - } - ] - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/Error402" - }, - "422": { - "$ref": "#/components/responses/Error422" - }, - "429": { - "$ref": "#/components/responses/Error429" - }, - "500": { - "$ref": "#/components/responses/Error500" - } - }, - "x-codeSamples": [ - { - "lang": "bash", - "label": "cURL", - "source": "curl -sS -G 'https://queryx.run/v1/search/news' \\\n --data-urlencode 'q=base ecosystem funding' \\\n --data-urlencode 'limit=10' \\\n -H 'X-PAYMENT: '" - } - ] - } - }, - "/v1/search/deep": { - "post": { - "tags": [ - "Deep Research" - ], - "operationId": "searchDeep", - "summary": "Deep research query with synthesized answer", - "description": "Performs multi-source retrieval and synthesis with citations. Higher cost than standard search. Requires x402 payment via X-PAYMENT header.", - "security": [ - { - "x402": [] - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeepSearchRequest" - }, - "examples": { - "default": { - "summary": "Deep query request", - "value": { - "query": "What changed in x402 payment adoption over the last 6 months?", - "objective": "Summarize key trends, include concrete adoption signals and likely implications for agent builders.", - "max_sources": 10, - "include_domains": [ - "queryx.run" - ], - "exclude_domains": [], - "recency": "year", - "output_format": "markdown" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Synthesized deep-research response.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeepSearchResponse" - }, - "examples": { - "success": { - "summary": "Deep research success", - "value": { - "query": "What changed in x402 payment adoption over the last 6 months?", - "request_id": "req_01HTZ8JQNX7Q2S2N9A6M8K7BXR", - "took_ms": 2950, - "summary": "x402 adoption accelerated as API providers shifted from subscriptions to per-call micropayments. Growth concentrated in search and data APIs where deterministic unit pricing is important for autonomous agents.", - "key_findings": [ - "Micropayment acceptance broadened among API-first products.", - "USDC settlement on Base reduced payment friction for agent workflows.", - "402-first retry logic became standard in SDK patterns." - ], - "citations": [ - { - "title": "Queryx x402 overview", - "url": "https://queryx.run/content/x402-overview", - "snippet": "Protocol and payment envelope details.", - "source": "queryx.run", - "relevance": 0.97 - }, - { - "title": "Building paid agents with Queryx", - "url": "https://queryx.run/content/paid-agents", - "snippet": "Implementation patterns and retry flow.", - "source": "queryx.run", - "relevance": 0.92 - } - ], - "sources_searched": 10, - "model": "queryx-deep-v1" - } - } - } - } - } - }, - "402": { - "$ref": "#/components/responses/Error402" - }, - "422": { - "$ref": "#/components/responses/Error422" - }, - "429": { - "$ref": "#/components/responses/Error429" - }, - "500": { - "$ref": "#/components/responses/Error500" - } - }, - "x-codeSamples": [ - { - "lang": "bash", - "label": "cURL", - "source": "curl -sS 'https://queryx.run/v1/search/deep' \\\n -X POST \\\n -H 'Content-Type: application/json' \\\n -H 'X-PAYMENT: ' \\\n -d '{\"query\":\"What changed in x402 payment adoption over the last 6 months?\",\"max_sources\":10}'" - } - ] - } - }, - "/health": { - "get": { - "tags": [ - "Health" - ], - "operationId": "healthCheck", - "summary": "Service health check", - "description": "Returns service status and basic runtime metadata.", - "security": [], - "responses": { - "200": { - "description": "Service is healthy.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HealthResponse" - }, - "examples": { - "healthy": { - "summary": "Healthy response", - "value": { - "status": "ok", - "version": "1.0.0", - "uptime_seconds": 86432, - "timestamp": "2026-03-04T16:30:22Z" - } - } - } - } - } - }, - "500": { - "$ref": "#/components/responses/Error500" - } - }, - "x-codeSamples": [ - { - "lang": "bash", - "label": "cURL", - "source": "curl -sS 'https://queryx.run/health'" - } - ] - } - } - }, - "components": { - "securitySchemes": { - "x402": { - "type": "apiKey", - "in": "header", - "name": "X-PAYMENT", - "description": "x402 payment envelope. Send a base64url-encoded JSON object with fields: payment_id, address, nonce, timestamp, signature, signature_algorithm. Signature is generated from canonical_message returned in the 402 response details." - } - }, - "schemas": { - "SearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "query", - "request_id", - "took_ms", - "total_results", - "results" - ], - "properties": { - "query": { - "type": "string" - }, - "request_id": { - "type": "string" - }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "total_results": { - "type": "integer", - "minimum": 0 - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchResult" - } - } - } - }, - "SearchResult": { - "type": "object", - "additionalProperties": false, - "required": [ - "title", - "url", - "snippet", - "source", - "score", - "published_at" - ], - "properties": { - "title": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "source": { - "type": "string" - }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "published_at": { - "type": [ - "string", - "null" - ], - "format": "date-time" - } - } - }, - "NewsSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "query", - "request_id", - "took_ms", - "total_results", - "results" - ], - "properties": { - "query": { - "type": "string" - }, - "request_id": { - "type": "string" - }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "total_results": { - "type": "integer", - "minimum": 0 - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NewsResult" - } - } - } - }, - "NewsResult": { - "type": "object", - "additionalProperties": false, - "required": [ - "title", - "url", - "snippet", - "source", - "publisher", - "score", - "published_at" - ], - "properties": { - "title": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "source": { - "type": "string" - }, - "publisher": { - "type": "string" - }, - "score": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "published_at": { - "type": "string", - "format": "date-time" - } - } - }, - "DeepSearchRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "objective": { - "type": "string", - "maxLength": 4000 - }, - "max_sources": { - "type": "integer", - "minimum": 1, - "maximum": 25, - "default": 10 - }, - "include_domains": { - "type": "array", - "items": { - "type": "string" - }, - "maxItems": 50 - }, - "exclude_domains": { - "type": "array", - "items": { - "type": "string" - }, - "maxItems": 50 - }, - "recency": { - "type": "string", - "enum": [ - "day", - "week", - "month", - "year", - "anytime" - ], - "default": "anytime" - }, - "output_format": { - "type": "string", - "enum": [ - "markdown", - "json" - ], - "default": "markdown" - } - } - }, - "DeepSearchResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "query", - "request_id", - "took_ms", - "summary", - "key_findings", - "citations", - "sources_searched", - "model" - ], - "properties": { - "query": { - "type": "string" - }, - "request_id": { - "type": "string" - }, - "took_ms": { - "type": "integer", - "minimum": 0 - }, - "summary": { - "type": "string" - }, - "key_findings": { - "type": "array", - "items": { - "type": "string" - } - }, - "citations": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Citation" - } - }, - "sources_searched": { - "type": "integer", - "minimum": 0 - }, - "model": { - "type": "string" - } - } - }, - "Citation": { - "type": "object", - "additionalProperties": false, - "required": [ - "title", - "url", - "snippet", - "source", - "relevance" - ], - "properties": { - "title": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri" - }, - "snippet": { - "type": "string" - }, - "source": { - "type": "string" - }, - "relevance": { - "type": "number", - "minimum": 0, - "maximum": 1 - } - } - }, - "HealthResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "status", - "version", - "uptime_seconds", - "timestamp" - ], - "properties": { - "status": { - "type": "string", - "enum": [ - "ok" - ] - }, - "version": { - "type": "string" - }, - "uptime_seconds": { - "type": "integer", - "minimum": 0 - }, - "timestamp": { - "type": "string", - "format": "date-time" - } - } - }, - "ErrorResponse": { - "type": "object", - "additionalProperties": false, - "required": [ - "error", - "code", - "message", - "request_id", - "retryable" - ], - "properties": { - "error": { - "type": "string" - }, - "code": { - "type": "string" - }, - "message": { - "type": "string" - }, - "request_id": { - "type": "string" - }, - "retryable": { - "type": "boolean" - }, - "details": { - "oneOf": [ - { - "$ref": "#/components/schemas/PaymentRequiredDetails" - }, - { - "$ref": "#/components/schemas/ValidationErrorDetails" - }, - { - "$ref": "#/components/schemas/RateLimitErrorDetails" - }, - { - "$ref": "#/components/schemas/InternalErrorDetails" - } - ] - } - } - }, - "PaymentRequiredDetails": { - "type": "object", - "additionalProperties": false, - "required": [ - "payment_id", - "asset", - "token_address", - "chain_id", - "facilitator_address", - "amount_base_units", - "amount_usdc", - "nonce", - "timestamp", - "expires_at", - "signature_algorithm", - "canonical_message" - ], - "properties": { - "payment_id": { - "type": "string" - }, - "asset": { - "type": "string", - "enum": [ - "USDC" - ] - }, - "token_address": { - "type": "string" - }, - "chain_id": { - "type": "integer", - "enum": [ - 8453 - ] - }, - "facilitator_address": { - "type": "string" - }, - "amount_base_units": { - "type": "string", - "description": "USDC base units (6 decimals)." - }, - "amount_usdc": { - "type": "string" - }, - "nonce": { - "type": "string" - }, - "timestamp": { - "type": "string", - "format": "date-time" - }, - "expires_at": { - "type": "string", - "format": "date-time" - }, - "signature_algorithm": { - "type": "string", - "enum": [ - "eip191_personal_sign" - ] - }, - "canonical_message": { - "type": "string", - "description": "Exact message that must be signed by the payer wallet." - } - } - }, - "ValidationErrorDetails": { - "type": "object", - "additionalProperties": false, - "required": [ - "errors" - ], - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FieldValidationError" - } - } - } - }, - "FieldValidationError": { - "type": "object", - "additionalProperties": false, - "required": [ - "path", - "message" - ], - "properties": { - "path": { - "type": "string" - }, - "message": { - "type": "string" - } - } - }, - "RateLimitErrorDetails": { - "type": "object", - "additionalProperties": false, - "required": [ - "limit", - "remaining", - "reset_at", - "retry_after_seconds" - ], - "properties": { - "limit": { - "type": "integer", - "minimum": 1 - }, - "remaining": { - "type": "integer", - "minimum": 0 - }, - "reset_at": { - "type": "string", - "format": "date-time" - }, - "retry_after_seconds": { - "type": "integer", - "minimum": 1 - } - } - }, - "InternalErrorDetails": { - "type": "object", - "additionalProperties": false, - "required": [ - "support_code" - ], - "properties": { - "support_code": { - "type": "string" - } - } - } - }, - "headers": { - "X-RateLimit-Limit": { - "description": "Maximum requests allowed in the current window.", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Remaining": { - "description": "Remaining requests in the current window.", - "schema": { - "type": "integer" - } - }, - "X-RateLimit-Reset": { - "description": "Epoch seconds when rate limit resets.", - "schema": { - "type": "integer" - } - }, - "Retry-After": { - "description": "Seconds to wait before retrying.", - "schema": { - "type": "integer" - } - } - }, - "responses": { - "Error402": { - "description": "Payment required. Client must construct x402 payment signature and retry.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "paymentRequired": { - "summary": "x402 challenge", - "value": { - "error": "payment_required", - "code": "payment_required", - "message": "Payment required for this endpoint.", - "request_id": "req_01HTZA2CVG8YPB8BKX4E2V0J5F", - "retryable": true, - "details": { - "payment_id": "pay_01HTZA2CVQY2Z5T9RA2ZES2J8T", - "asset": "USDC", - "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bDa02913", - "chain_id": 8453, - "facilitator_address": "0x2B3a5cA6D4E2Ff0dA9fD3C4e8B7A1c2D6E5f9012", - "amount_base_units": "2500", - "amount_usdc": "0.0025", - "nonce": "6f5f9f99b4b64726a1b26c9d8f407ec6", - "timestamp": "2026-03-04T16:30:22Z", - "expires_at": "2026-03-04T16:32:22Z", - "signature_algorithm": "eip191_personal_sign", - "canonical_message": "pay_01HTZA2CVQY2Z5T9RA2ZES2J8T\nGET\n/v1/search\nq=base+chain+x402+micropayments&limit=5\n2500\nUS \ No newline at end of file