{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Clervo Search, AI, Secure Sandbox, Prediction Intelligence, Crypto Intelligence API", "version": "2026-07-29.1", "description": "Publicly callable previews: raw cited Search, bounded paid AI, bounded one-shot Secure Sandbox execution, derived Prediction Intelligence, bounded provider-neutral Crypto Intelligence. Lifecycle and proof state are generated from the probed live registry; unavailable operations fail closed.", "contact": { "name": "Clervo", "email": "mo@clervo.dev", "url": "https://github.com/clervo/clervo" }, "x-guidance": "Use POST /v1/search/free for a bounded no-payment sample. Paid routes return x402 v2 and MPP EVM charge challenges before execution. Supply the required JSON body and a stable Idempotency-Key, inspect the exact payment requirements, and send either PAYMENT-SIGNATURE for x402 or Authorization: Payment for MPP only after approval. Reuse the same key to recover or replay a completed result without a second charge. Every unsupported capability fails closed." }, "paths": { "/v1/search/free": { "post": { "summary": "Execute a bounded search preview", "description": "Public idempotent raw web-search sample. Set synthesize to false; synthesized answers are unavailable.", "operationId": "searchPreview", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "default": "x402scan-clervo-probe" }, "example": "x402scan-clervo-probe" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "synthesize" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000, "default": "current x402 protocol documentation" }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 }, "synthesize": { "type": "boolean", "const": false, "default": false }, "language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "default": "en" }, "region": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US" } }, "additionalProperties": false }, "example": { "query": "current x402 protocol documentation", "maxResults": 3, "synthesize": false, "language": "en", "region": "US" } } } }, "responses": { "200": { "description": "Preview completed", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "state", "replayed", "requestHash" ], "properties": { "operationId": { "type": "string" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "receipt": { "type": "object", "additionalProperties": true }, "output": { "type": "object", "properties": { "route": { "type": "object", "required": [ "routeId", "qualificationId", "servingAdapters", "degraded", "fallback", "cost" ], "properties": { "routeId": { "type": "string" }, "qualificationId": { "type": "string" }, "servingAdapters": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "fallback": { "type": "boolean" }, "cost": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "429": { "description": "Preview quota exceeded", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "502": { "description": "Executor failed closed", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "503": { "description": "Requested capability unavailable", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } } }, "security": [] } }, "/v1/search/paid": { "post": { "summary": "Request or settle a raw Search payment", "description": "Returns an exact x402 challenge for raw cited web retrieval. The same idempotency key replays the completed receipt without another charge. Set synthesize to false.", "operationId": "searchPaymentChallenge", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "default": "x402scan-clervo-probe" }, "example": "x402scan-clervo-probe" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "synthesize" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000, "default": "current x402 protocol documentation" }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 }, "synthesize": { "type": "boolean", "const": false, "default": false }, "language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "default": "en" }, "region": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US" } }, "additionalProperties": false }, "example": { "query": "current x402 protocol documentation", "maxResults": 3, "synthesize": false, "language": "en", "region": "US" } } } }, "responses": { "200": { "description": "Raw cited Search completed or replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "state", "replayed", "requestHash" ], "properties": { "operationId": { "type": "string" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "receipt": { "type": "object", "additionalProperties": true }, "output": { "type": "object", "properties": { "route": { "type": "object", "required": [ "routeId", "qualificationId", "servingAdapters", "degraded", "fallback", "cost" ], "properties": { "routeId": { "type": "string" }, "qualificationId": { "type": "string" }, "servingAdapters": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "fallback": { "type": "boolean" }, "cost": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "402": { "description": "x402 or MPP payment required", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string", "contentEncoding": "base64" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "409": { "description": "Idempotency conflict", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "502": { "description": "Mock test execution failed closed", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "503": { "description": "Requested capability or settlement unavailable", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.006000" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } ] } } }, "/v1/ai/execute": { "post": { "summary": "Execute a provider-neutral Clervo AI model", "description": "Free models execute without payment within the published quota. Paid models return an exact request-bound x402 or MPP quote before execution. A completed idempotency key replays the same result and, when paid, the same receipt without another charge.", "operationId": "aiExecute", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable replay key. When omitted before payment, the service generates one and returns it in the response headers.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "default": "x402scan-clervo-probe" }, "example": "x402scan-clervo-probe" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input", "maximumOutputTokens" ], "properties": { "model": { "type": "string", "enum": [ "clervo/gpt-5.6-luna" ], "default": "clervo/gpt-5.6-luna" }, "input": { "type": "object", "required": [ "kind", "messages", "responseFormat", "stream" ], "properties": { "kind": { "type": "string", "const": "chat", "default": "chat" }, "messages": { "type": "array", "minItems": 1, "maxItems": 128, "default": [ { "role": "user", "content": "Reply with the single word ready." } ], "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user" ], "default": "user" }, "content": { "type": "string", "minLength": 1, "maxLength": 100000, "default": "Reply with the single word ready." } }, "additionalProperties": false } }, "responseFormat": { "type": "string", "enum": [ "text" ], "default": "text" }, "stream": { "type": "boolean", "const": false, "default": false } }, "additionalProperties": false, "default": { "kind": "chat", "messages": [ { "role": "user", "content": "Reply with the single word ready." } ], "responseFormat": "text", "stream": false } }, "maximumOutputTokens": { "type": "integer", "minimum": 1, "maximum": 16384, "default": 16 } }, "additionalProperties": false }, "example": { "model": "clervo/gpt-5.6-luna", "input": { "kind": "chat", "messages": [ { "role": "user", "content": "Reply with the single word ready." } ], "responseFormat": "text", "stream": false }, "maximumOutputTokens": 16 } } } }, "responses": { "200": { "description": "Free or paid AI operation completed or replayed; paid results include truthful usage and settlement receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "state", "replayed", "requestHash" ], "properties": { "operationId": { "type": "string" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "receipt": { "type": "object", "additionalProperties": true }, "output": { "type": "object", "properties": { "route": { "type": "object", "required": [ "routeId", "qualificationId", "servingAdapters", "degraded", "fallback", "cost" ], "properties": { "routeId": { "type": "string" }, "qualificationId": { "type": "string" }, "servingAdapters": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "fallback": { "type": "boolean" }, "cost": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid bounded AI request", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "402": { "description": "x402 or MPP payment required", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string", "contentEncoding": "base64" } }, "WWW-Authenticate": { "schema": { "type": "string" } } } }, "409": { "description": "Idempotency or quote conflict", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "429": { "description": "Published free-tier quota exhausted; the request is not silently converted into a paid operation", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "503": { "description": "No qualified route, capacity, or settlement path is available", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } } }, "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "0.000001", "max": "2.621440" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } ] } } }, "/v1/models": { "get": { "summary": "List the authoritative provider-neutral Clervo AI catalog", "description": "Returns 85 frozen canonical model IDs and 4 stable aliases with capabilities, availability, health, free/paid state, pricing, and commerce metadata. Canonical IDs never silently substitute another model.", "operationId": "aiListModels", "security": [], "responses": { "200": { "description": "OpenAI-compatible model list with authoritative Clervo commercial metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "clervo" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "owned_by", "clervo" ] } }, "clervo": { "type": "object" } } } } } } } } }, "/v1/sandbox/execute": { "post": { "summary": "Request or settle a bounded one-shot Secure Sandbox execution", "description": "Runs one command in the pinned qualified Node.js gVisor image with no network, strict resources, cleanup, a receipt, and no-charge replay. The short class is 0.010 USDC; larger bounded requests quote the standard class. Sessions and artifact retrieval are not yet public.", "operationId": "sandboxExecute", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "default": "x402scan-clervo-probe" }, "example": "x402scan-clervo-probe" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "command" ], "additionalProperties": false, "properties": { "command": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "default": [ "node", "-e", "process.stdout.write('ready')" ] }, "stdinBase64": { "type": "string" }, "limits": { "type": "object", "additionalProperties": false, "default": { "cpuMillis": 5000, "memoryBytes": 268435456, "processes": 16, "diskBytes": 67108864, "outputBytes": 65536, "artifactBytes": 1048576, "wallTimeMs": 10000 }, "properties": { "cpuMillis": { "type": "integer", "minimum": 1, "maximum": 30000 }, "memoryBytes": { "type": "integer", "minimum": 16777216, "maximum": 536870912 }, "processes": { "type": "integer", "minimum": 1, "maximum": 64 }, "diskBytes": { "type": "integer", "minimum": 1048576, "maximum": 1073741824 }, "outputBytes": { "type": "integer", "minimum": 1, "maximum": 1048576 }, "artifactBytes": { "type": "integer", "minimum": 1, "maximum": 10485760 }, "wallTimeMs": { "type": "integer", "minimum": 100, "maximum": 60000 } } } } }, "example": { "command": [ "node", "-e", "process.stdout.write('ready')" ], "limits": { "cpuMillis": 5000, "memoryBytes": 268435456, "processes": 16, "diskBytes": 67108864, "outputBytes": 65536, "artifactBytes": 1048576, "wallTimeMs": 10000 } } } } }, "responses": { "200": { "description": "Sandbox execution completed or replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "state", "replayed", "requestHash" ], "properties": { "operationId": { "type": "string" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "receipt": { "type": "object", "additionalProperties": true }, "output": { "type": "object", "properties": { "route": { "type": "object", "required": [ "routeId", "qualificationId", "servingAdapters", "degraded", "fallback", "cost" ], "properties": { "routeId": { "type": "string" }, "qualificationId": { "type": "string" }, "servingAdapters": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "fallback": { "type": "boolean" }, "cost": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid bounded Sandbox request", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "402": { "description": "x402 or MPP payment required", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string", "contentEncoding": "base64" } }, "WWW-Authenticate": { "schema": { "type": "string" } } } }, "409": { "description": "Idempotency, quote, or execution reconciliation conflict", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "503": { "description": "Capacity, execution, cleanup, or settlement path unavailable", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } } }, "x-payment-info": { "price": { "mode": "dynamic_class", "currency": "USD", "minimum": "0.010000", "maximum": "0.060000" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } ] } } }, "/v1/prediction/execute": { "post": { "summary": "Request or settle a bounded Prediction Intelligence operation", "description": "Discovers or analyzes prediction markets through stable Clervo identities, conservative matching, durable normalized observations, freshness, provenance, attribution, receipts, and no-charge replay.", "operationId": "predictionExecute", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "default": "x402scan-clervo-probe" }, "example": "x402scan-clervo-probe" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "enum": [ "search", "markets" ], "default": "markets" }, "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "category": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "enum": [ "open", "closed", "resolved", "cancelled" ], "default": "open" }, "venues": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "enum": [ "polymarket", "kalshi", "manifold", "limitless" ] } }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 3 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 2048 } } }, { "type": "object", "required": [ "kind", "marketRef" ], "additionalProperties": false, "properties": { "kind": { "const": "market" }, "marketRef": { "type": "string", "pattern": "^pmkt_[a-f0-9]{32}$" } } }, { "type": "object", "required": [ "kind", "marketRefs" ], "additionalProperties": false, "properties": { "kind": { "const": "compare" }, "marketRefs": { "type": "array", "minItems": 2, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "pattern": "^pmkt_[a-f0-9]{32}$" } } } }, { "type": "object", "required": [ "kind", "marketRef" ], "additionalProperties": false, "properties": { "kind": { "const": "history" }, "marketRef": { "type": "string", "pattern": "^pmkt_[a-f0-9]{32}$" }, "afterSequence": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } }, { "type": "object", "required": [ "kind", "marketRef" ], "additionalProperties": false, "properties": { "kind": { "const": "signal" }, "marketRef": { "type": "string", "pattern": "^pmkt_[a-f0-9]{32}$" }, "compareMarketRef": { "type": "string", "pattern": "^pmkt_[a-f0-9]{32}$" } } } ] }, "example": { "kind": "markets", "status": "open", "limit": 3 } } } }, "responses": { "200": { "description": "Prediction operation completed or replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "state", "replayed", "requestHash" ], "properties": { "operationId": { "type": "string" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "receipt": { "type": "object", "additionalProperties": true }, "output": { "type": "object", "properties": { "route": { "type": "object", "required": [ "routeId", "qualificationId", "servingAdapters", "degraded", "fallback", "cost" ], "properties": { "routeId": { "type": "string" }, "qualificationId": { "type": "string" }, "servingAdapters": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "fallback": { "type": "boolean" }, "cost": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid bounded Prediction request", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "402": { "description": "x402 or MPP payment required", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string", "contentEncoding": "base64" } }, "WWW-Authenticate": { "schema": { "type": "string" } } } }, "404": { "description": "Requested stable market identity was not found", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "409": { "description": "Idempotency or quote conflict", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "503": { "description": "Qualified supply, durable state, or settlement is unavailable", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } } }, "x-payment-info": { "price": { "mode": "request_derived_per_operation", "currency": "USD", "min": "0.002000", "max": "0.003000" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } ] } } }, "/v1/crypto/execute": { "post": { "summary": "Request or settle bounded Crypto Intelligence", "description": "Returns provider-neutral observed wallet facts and deterministic Clervo derivations for Ethereum and Base. It never infers wallet identity, provides an opaque risk score, signs, trades, or resells raw upstream responses.", "operationId": "cryptoExecute", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "default": "x402scan-clervo-probe" }, "example": "x402scan-clervo-probe" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "kind", "address", "chains" ], "additionalProperties": false, "properties": { "kind": { "const": "balances" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "chains": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "eip155:1", "eip155:8453" ] } } } }, { "type": "object", "required": [ "kind", "address", "chains" ], "additionalProperties": false, "properties": { "kind": { "const": "tokens" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "chains": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "eip155:1", "eip155:8453" ] } } } }, { "type": "object", "required": [ "kind", "address", "chains", "lookbackDays", "limit" ], "additionalProperties": false, "properties": { "kind": { "const": "transactions" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "chains": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "eip155:1", "eip155:8453" ] } }, "lookbackDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, { "type": "object", "required": [ "kind", "address", "chains", "lookbackDays", "limit" ], "additionalProperties": false, "properties": { "kind": { "const": "report" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "chains": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "eip155:1", "eip155:8453" ] } }, "lookbackDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } } ] }, "example": { "kind": "report", "address": "0x0000000000000000000000000000000000000000", "chains": [ "eip155:1", "eip155:8453" ], "lookbackDays": 30, "limit": 50 } } } }, "responses": { "200": { "description": "Crypto Intelligence operation completed or replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "state", "replayed", "requestHash" ], "properties": { "operationId": { "type": "string" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "receipt": { "type": "object", "additionalProperties": true }, "output": { "type": "object", "properties": { "route": { "type": "object", "required": [ "routeId", "qualificationId", "servingAdapters", "degraded", "fallback", "cost" ], "properties": { "routeId": { "type": "string" }, "qualificationId": { "type": "string" }, "servingAdapters": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "fallback": { "type": "boolean" }, "cost": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid bounded Crypto Intelligence request", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "402": { "description": "x402 or MPP payment required", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string", "contentEncoding": "base64" } }, "WWW-Authenticate": { "schema": { "type": "string" } } } }, "409": { "description": "Idempotency or quote conflict", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } }, "503": { "description": "Qualified supply, durable state, or settlement is unavailable", "content": { "application/problem+json": { "schema": { "type": "object", "description": "Fail-closed RFC 9457-style problem details.", "additionalProperties": true } } } } }, "x-payment-info": { "price": { "mode": "request_derived_per_operation", "currency": "USD", "min": "0.002000", "max": "0.004000" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } ] } } } }, "components": { "schemas": { "AiHttpRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/ai-http-request.schema.json", "title": "Clervo public bounded AI request", "$defs": { "evidence": { "type": "object", "required": [ "citationId", "resultId", "canonicalUrl", "quote" ], "properties": { "citationId": { "type": "string", "pattern": "^cite_[A-Za-z0-9]{20,64}$" }, "resultId": { "type": "string", "pattern": "^sr_[A-Za-z0-9]{20,64}$" }, "canonicalUrl": { "type": "string", "format": "uri" }, "quote": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "additionalProperties": false }, "chatContent": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100000 }, { "type": "array", "minItems": 1, "maxItems": 32, "items": { "oneOf": [ { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^data:image/(?:png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$", "maxLength": 8000000 } }, "additionalProperties": false } }, "additionalProperties": false } ] } } ] } }, "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 160 }, "maximumOutputTokens": { "type": "integer", "minimum": 0, "maximum": 65536 }, "maximumReasoningTokens": { "type": "integer", "minimum": 0, "maximum": 65536 }, "input": { "oneOf": [ { "type": "object", "required": [ "kind", "messages", "responseFormat", "stream" ], "properties": { "kind": { "const": "chat" }, "messages": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "$ref": "#/$defs/chatContent" } }, "additionalProperties": false } }, "responseFormat": { "enum": [ "text", "json_object" ] }, "stream": { "type": "boolean" }, "evidence": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/$defs/evidence" } } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "inputs" ], "properties": { "kind": { "const": "embedding" }, "inputs": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "prompt", "size", "quality", "count" ], "properties": { "kind": { "const": "image" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 }, "size": { "enum": [ "1024x1024", "1024x1536", "1536x1024" ] }, "quality": { "enum": [ "low", "medium", "high" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 16 } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "input", "voice", "responseFormat" ], "properties": { "kind": { "const": "speech" }, "input": { "type": "string", "minLength": 1, "maxLength": 100000 }, "voice": { "type": "string", "minLength": 1, "maxLength": 64 }, "responseFormat": { "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "prompt", "durationSeconds", "aspectRatio", "resolution" ], "properties": { "kind": { "const": "video" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 }, "durationSeconds": { "type": "integer", "minimum": 3, "maximum": 8 }, "aspectRatio": { "enum": [ "16:9", "9:16" ] }, "resolution": { "enum": [ "720p", "1080p" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "prompt", "durationSeconds", "instrumental" ], "properties": { "kind": { "const": "music" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 }, "durationSeconds": { "type": "integer", "minimum": 5, "maximum": 180 }, "instrumental": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "personImageBase64", "productImageBase64" ], "properties": { "kind": { "const": "virtual_try_on" }, "personImageBase64": { "type": "string", "pattern": "^[A-Za-z0-9+/]+={0,2}$", "maxLength": 5000000 }, "productImageBase64": { "type": "string", "pattern": "^[A-Za-z0-9+/]+={0,2}$", "maxLength": 5000000 } }, "additionalProperties": false } ] } }, "additionalProperties": false }, "AiHttpResult": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/ai-http-result.schema.json", "title": "Clervo public verified AI result envelope", "$defs": { "usage": { "type": "object", "required": [ "inputTokens", "cachedInputTokens", "outputTokens", "reasoningTokens", "images", "audioCharacters" ], "properties": { "inputTokens": { "type": "integer", "minimum": 0 }, "cachedInputTokens": { "type": "integer", "minimum": 0 }, "outputTokens": { "type": "integer", "minimum": 0 }, "reasoningTokens": { "type": "integer", "minimum": 0 }, "images": { "type": "integer", "minimum": 0 }, "audioCharacters": { "type": "integer", "minimum": 0 }, "videoSeconds": { "type": "integer", "minimum": 0 }, "musicGenerations": { "type": "integer", "minimum": 0 }, "virtualTryOnImages": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "output": { "oneOf": [ { "type": "object", "required": [ "kind", "content", "finishReason" ], "properties": { "kind": { "const": "chat" }, "content": { "type": "string", "minLength": 1, "maxLength": 1000000 }, "finishReason": { "enum": [ "stop", "length", "tool_calls" ] }, "claims": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "text", "citationIds" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "citationIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^cite_[A-Za-z0-9]{20,64}$" } } }, "additionalProperties": false } } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "vectors" ], "properties": { "kind": { "const": "embedding" }, "vectors": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "object", "required": [ "index", "embedding" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "embedding": { "type": "array", "minItems": 1, "maxItems": 4096, "items": { "type": "number" } } }, "additionalProperties": false } } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "artifacts" ], "properties": { "kind": { "const": "image" }, "artifacts": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "artifactUri", "sha256", "mimeType", "width", "height" ], "properties": { "artifactUri": { "type": "string", "pattern": "^artifact://[A-Za-z0-9._/-]{8,256}$" }, "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "mimeType": { "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "artifact" ], "properties": { "kind": { "const": "speech" }, "artifact": { "type": "object", "required": [ "artifactUri", "sha256", "mimeType", "bytes" ], "properties": { "artifactUri": { "type": "string", "pattern": "^artifact://[A-Za-z0-9._/-]{8,256}$" }, "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "mimeType": { "enum": [ "audio/mpeg", "audio/ogg", "audio/aac", "audio/flac", "audio/wav", "audio/pcm" ] }, "bytes": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "artifact" ], "properties": { "kind": { "const": "video" }, "artifact": { "type": "object", "required": [ "artifactUri", "sha256", "mimeType", "bytes", "durationSeconds" ], "properties": { "artifactUri": { "type": "string", "pattern": "^artifact://[A-Za-z0-9._/-]{8,256}$" }, "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "mimeType": { "const": "video/mp4" }, "bytes": { "type": "integer", "minimum": 1 }, "durationSeconds": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "artifact" ], "properties": { "kind": { "const": "music" }, "artifact": { "type": "object", "required": [ "artifactUri", "sha256", "mimeType", "bytes", "durationSeconds" ], "properties": { "artifactUri": { "type": "string", "pattern": "^artifact://[A-Za-z0-9._/-]{8,256}$" }, "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "mimeType": { "enum": [ "audio/mpeg", "audio/wav" ] }, "bytes": { "type": "integer", "minimum": 1 }, "durationSeconds": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "artifact" ], "properties": { "kind": { "const": "virtual_try_on" }, "artifact": { "type": "object", "required": [ "artifactUri", "sha256", "mimeType", "bytes" ], "properties": { "artifactUri": { "type": "string", "pattern": "^artifact://[A-Za-z0-9._/-]{8,256}$" }, "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "mimeType": { "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "bytes": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false } ] } }, "type": "object", "required": [ "contractVersion", "schemaVersion", "operationId", "operation", "productId", "model", "exactModelId", "state", "replayed", "fundingMode", "requestHash", "result" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "schemaVersion": { "const": "ai-http-result.v1" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "operation": { "const": "ai.execute" }, "productId": { "enum": [ "ai.chat", "ai.embed", "ai.image", "ai.speech", "ai.video", "ai.music", "ai.virtual_try_on" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 160 }, "exactModelId": { "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "enum": [ "RECEIPTED", "COMPLETED" ] }, "replayed": { "type": "boolean" }, "fundingMode": { "enum": [ "paid", "free" ] }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "result": { "type": "object", "required": [ "requestedModel", "exactModelId", "completedAt", "usage", "output", "resultHash" ], "properties": { "requestedModel": { "type": "string", "minLength": 1, "maxLength": 160 }, "exactModelId": { "type": "string", "minLength": 1, "maxLength": 160 }, "completedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/$defs/usage" }, "output": { "$ref": "#/$defs/output" }, "resultHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } }, "additionalProperties": false }, "receipt": { "$ref": "operation-receipt.schema.json" } }, "allOf": [ { "if": { "properties": { "fundingMode": { "const": "paid" } }, "required": [ "fundingMode" ] }, "then": { "properties": { "receipt": {}, "state": { "const": "RECEIPTED" } }, "required": [ "receipt" ] } }, { "if": { "properties": { "fundingMode": { "const": "free" } }, "required": [ "fundingMode" ] }, "then": { "properties": { "state": { "const": "COMPLETED" } }, "not": { "properties": { "receipt": {} }, "required": [ "receipt" ] } } } ], "additionalProperties": false }, "CatalogEntry": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/catalog-entry.schema.json", "title": "Clervo catalog entry", "$defs": { "amount": { "type": "object", "required": [ "asset", "amountAtomic", "decimals" ], "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._/-]{1,127}$" }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,77})$" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 30 } }, "additionalProperties": false } }, "type": "object", "required": [ "contractVersion", "catalogVersion", "productId", "title", "summary", "status", "identity", "capabilities", "deliveryModes", "inputSchema", "outputSchema", "pricing", "qualifiedAdapterIds", "terms", "dataPolicy", "updatedAt" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "catalogVersion": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}\\.[1-9][0-9]*$" }, "productId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)+$" }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "enum": [ "draft", "qualified", "active", "degraded", "disabled", "blocked_by_terms", "retired" ] }, "identity": { "type": "object", "required": [ "kind", "name", "substitutionPolicy" ], "properties": { "kind": { "enum": [ "exact", "alias" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "substitutionPolicy": { "enum": [ "none", "qualified_equivalent" ] } }, "additionalProperties": false }, "capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,63}$" } }, "deliveryModes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": [ "sync", "async" ] } }, "inputSchema": { "type": "string", "format": "uri" }, "outputSchema": { "type": "string", "format": "uri" }, "pricing": { "type": "object", "required": [ "model", "maximumChargeRequired", "priceVersion" ], "properties": { "model": { "enum": [ "free", "fixed", "metered", "quoted" ] }, "displayPrice": { "$ref": "#/$defs/amount" }, "maximumChargeRequired": { "type": "boolean" }, "priceVersion": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" } }, "additionalProperties": false }, "qualifiedAdapterIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^adapter_[a-z0-9][a-z0-9._-]{2,63}$" } }, "terms": { "type": "object", "required": [ "status", "reference" ], "properties": { "status": { "enum": [ "approved", "restricted", "blocked", "unreviewed" ] }, "reviewedAt": { "type": "string", "format": "date-time" }, "reference": { "type": "string", "format": "uri", "maxLength": 500 }, "notes": { "type": "string", "maxLength": 500 } }, "additionalProperties": false }, "dataPolicy": { "type": "object", "required": [ "classification", "payloadRetention", "maximumRetentionSeconds" ], "properties": { "classification": { "enum": [ "public", "customer_confidential", "sensitive" ] }, "payloadRetention": { "enum": [ "none", "bounded" ] }, "maximumRetentionSeconds": { "type": "integer", "minimum": 0, "maximum": 31536000 } }, "additionalProperties": false }, "updatedAt": { "type": "string", "format": "date-time" } }, "allOf": [ { "if": { "properties": { "status": { "enum": [ "active", "degraded" ] } }, "required": [ "status" ] }, "then": { "properties": { "qualifiedAdapterIds": { "type": "array", "minItems": 1 }, "terms": { "type": "object", "properties": { "status": { "enum": [ "approved", "restricted" ] } }, "required": [ "status" ] } } } }, { "if": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "kind": { "const": "exact" } }, "required": [ "kind" ] } }, "required": [ "identity" ] }, "then": { "properties": { "identity": { "type": "object", "properties": { "substitutionPolicy": { "const": "none" } } } } } }, { "if": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "model": { "not": { "const": "free" } } }, "required": [ "model" ] } }, "required": [ "pricing" ] }, "then": { "properties": { "pricing": { "type": "object", "properties": { "maximumChargeRequired": { "const": true } } } } } } ], "additionalProperties": false }, "MockPaymentRequired": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/mock-payment-required.schema.json", "title": "Clervo non-payable mock x402 v2 PaymentRequired", "$defs": { "hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } }, "type": "object", "required": [ "x402Version", "error", "resource", "accepts", "extensions" ], "properties": { "x402Version": { "const": 2 }, "error": { "const": "PAYMENT-SIGNATURE header is required" }, "resource": { "type": "object", "required": [ "url", "description", "mimeType" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "mimeType": { "const": "application/json" } }, "additionalProperties": false }, "accepts": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "const": "exact" }, "network": { "type": "string", "pattern": "^[a-z0-9]+:[A-Za-z0-9._-]+$" }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,77})$" }, "asset": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._/-]{1,127}$" }, "payTo": { "type": "string", "pattern": "^mock:[A-Za-z0-9._-]{8,128}$" }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "extra": { "type": "object", "required": [ "mock", "payable", "clervo" ], "properties": { "mock": { "const": true }, "payable": { "const": false }, "clervo": { "type": "object", "required": [ "quoteId", "quoteHash", "requestHash", "priceVersion", "quoteExpiresAt" ], "properties": { "quoteId": { "type": "string", "pattern": "^quote_[A-Za-z0-9]{20,64}$" }, "quoteHash": { "$ref": "#/$defs/hash" }, "requestHash": { "$ref": "#/$defs/hash" }, "priceVersion": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "quoteExpiresAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "extensions": { "type": "object", "required": [ "clervo" ], "properties": { "clervo": { "type": "object", "required": [ "mode", "paymentSignatureAccepted", "verificationImplemented", "facilitatorConfigured", "authorizationImplemented", "settlementImplemented", "executionAllowed" ], "properties": { "mode": { "const": "mock" }, "paymentSignatureAccepted": { "const": false }, "verificationImplemented": { "const": false }, "facilitatorConfigured": { "const": false }, "authorizationImplemented": { "const": false }, "settlementImplemented": { "const": false }, "executionAllowed": { "const": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "OperationReceipt": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/operation-receipt.schema.json", "title": "Clervo immutable operation receipt", "$defs": { "hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "amount": { "type": "object", "required": [ "asset", "amountAtomic", "decimals" ], "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._/-]{1,127}$" }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,77})$" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 30 } }, "additionalProperties": false } }, "type": "object", "required": [ "contractVersion", "receiptId", "operationId", "productId", "requestHash", "quoteId", "quoteHash", "fundingMode", "customerCharge", "supplierCost", "settlement", "resultHash", "provenance", "completedAt", "receiptHash" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "receiptId": { "type": "string", "pattern": "^rcpt_[A-Za-z0-9]{20,64}$" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "productId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)+$" }, "requestHash": { "$ref": "#/$defs/hash" }, "quoteId": { "type": "string", "pattern": "^quote_[A-Za-z0-9]{20,64}$" }, "quoteHash": { "$ref": "#/$defs/hash" }, "fundingMode": { "enum": [ "free", "sponsored", "paid" ] }, "customerCharge": { "$ref": "#/$defs/amount" }, "supplierCost": { "$ref": "#/$defs/amount" }, "settlement": { "type": "object", "required": [ "status" ], "properties": { "status": { "enum": [ "not_required", "settled" ] }, "referenceHash": { "$ref": "#/$defs/hash" } }, "additionalProperties": false }, "resultHash": { "$ref": "#/$defs/hash" }, "provenance": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "adapterId", "qualificationId", "providerReferenceHash" ], "properties": { "adapterId": { "type": "string", "pattern": "^adapter_[a-z0-9][a-z0-9._-]{2,63}$" }, "qualificationId": { "type": "string", "pattern": "^qual_[A-Za-z0-9]{20,64}$" }, "providerReferenceHash": { "$ref": "#/$defs/hash" }, "routeId": { "type": "string", "pattern": "^clervo\\.[a-z0-9][a-z0-9._-]{2,127}$" }, "degraded": { "type": "boolean" }, "costBasisId": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{2,127}$" } }, "additionalProperties": false } }, "completedAt": { "type": "string", "format": "date-time" }, "previousReceiptHash": { "$ref": "#/$defs/hash" }, "receiptHash": { "$ref": "#/$defs/hash" } }, "allOf": [ { "if": { "type": "object", "properties": { "fundingMode": { "const": "paid" } }, "required": [ "fundingMode" ] }, "then": { "properties": { "settlement": { "type": "object", "properties": { "status": { "const": "settled" }, "referenceHash": { "$ref": "#/$defs/hash" } }, "required": [ "status", "referenceHash" ] } } } }, { "if": { "type": "object", "properties": { "settlement": { "type": "object", "properties": { "status": { "const": "not_required" } }, "required": [ "status" ] } }, "required": [ "settlement" ] }, "then": { "properties": { "settlement": { "type": "object", "not": { "type": "object", "properties": { "referenceHash": { "$ref": "#/$defs/hash" } }, "required": [ "referenceHash" ] } } } } } ], "additionalProperties": false }, "OperationRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/operation-request.schema.json", "title": "Clervo operation request", "type": "object", "required": [ "contractVersion", "operation", "input" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "operation": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)+$", "maxLength": 120 }, "input": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "OperationResult": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/operation-result.schema.json", "title": "Clervo successful operation result", "type": "object", "required": [ "contractVersion", "operationId", "operation", "state", "replayed", "output" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "operation": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)+$" }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "output": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "OperationSnapshot": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/operation-snapshot.schema.json", "title": "Clervo durable operation snapshot", "type": "object", "required": [ "contractVersion", "operationId", "operation", "idempotencyKey", "requestHash", "state", "createdAt", "updatedAt" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "operation": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)+$" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$" }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "enum": [ "RECEIVED", "VALIDATED", "QUOTED", "PAYMENT_REQUIRED", "AUTHORIZED", "RESERVED", "EXECUTING", "EXECUTION_UNKNOWN", "EXECUTED", "VERIFYING", "VERIFIED", "SETTLING", "SETTLEMENT_UNKNOWN", "SETTLED", "RECEIPTED", "RECONCILING", "FAILED" ] }, "quoteExpiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Problem": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/problem.schema.json", "title": "Clervo RFC 9457 problem detail", "type": "object", "required": [ "type", "title", "status", "detail", "instance", "code", "retryable" ], "properties": { "type": { "type": "string", "format": "uri", "pattern": "^https://api\\.clervo\\.dev/problems/" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "minLength": 1, "maxLength": 2000 }, "instance": { "type": "string", "format": "uri-reference" }, "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "retryable": { "type": "boolean" } }, "additionalProperties": false }, "ProductScope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/product-scope.schema.json", "title": "Clervo product release scope", "type": "object", "required": [ "scopeVersion", "company", "productCore", "firstRevenueRelease", "pillars" ], "properties": { "scopeVersion": { "const": "2026-08-01.3" }, "company": { "type": "object", "required": [ "name", "identity", "permanentNarrative" ], "properties": { "name": { "const": "Clervo" }, "identity": { "const": "outcome infrastructure for agents" }, "permanentNarrative": { "const": [ "find", "understand", "act" ] } }, "additionalProperties": false }, "productCore": { "type": "object", "required": [ "requiredPillars", "interfacesFrozen", "compatibilityVerified", "ready" ], "properties": { "requiredPillars": { "const": [ "search", "ai", "sandbox", "rpc", "prediction", "crypto_intelligence" ] }, "interfacesFrozen": { "type": "boolean" }, "compatibilityVerified": { "type": "boolean" }, "ready": { "type": "boolean" } }, "allOf": [ { "if": { "type": "object", "properties": { "ready": { "const": true } }, "required": [ "ready" ] }, "then": { "type": "object", "properties": { "interfacesFrozen": { "const": true }, "compatibilityVerified": { "const": true } } } } ], "additionalProperties": false }, "firstRevenueRelease": { "type": "object", "required": [ "productId", "productName", "requiredPillars", "requirements", "ready" ], "properties": { "productId": { "const": "clervo.platform" }, "productName": { "const": "Clervo Platform" }, "requiredPillars": { "const": [ "search", "ai", "sandbox", "rpc", "prediction", "crypto_intelligence" ] }, "requirements": { "type": "array", "minItems": 9, "maxItems": 9, "prefixItems": [ { "$ref": "#/$defs/requirementApi" }, { "$ref": "#/$defs/requirementMcpSdk" }, { "$ref": "#/$defs/requirementPricing" }, { "$ref": "#/$defs/requirementOnboarding" }, { "$ref": "#/$defs/requirementPublicExperience" }, { "$ref": "#/$defs/requirementDeployment" }, { "$ref": "#/$defs/requirementDemonstrations" }, { "$ref": "#/$defs/requirementSettlement" }, { "$ref": "#/$defs/requirementExternalResult" } ], "items": false }, "ready": { "type": "boolean" } }, "additionalProperties": false }, "pillars": { "type": "array", "minItems": 6, "maxItems": 6, "prefixItems": [ { "allOf": [ { "$ref": "#/$defs/pillar" }, { "type": "object", "properties": { "pillarId": { "const": "search" } } } ] }, { "allOf": [ { "$ref": "#/$defs/pillar" }, { "type": "object", "properties": { "pillarId": { "const": "ai" } } } ] }, { "allOf": [ { "$ref": "#/$defs/pillar" }, { "type": "object", "properties": { "pillarId": { "const": "sandbox" } } } ] }, { "allOf": [ { "$ref": "#/$defs/pillar" }, { "type": "object", "properties": { "pillarId": { "const": "rpc" } } } ] }, { "allOf": [ { "$ref": "#/$defs/pillar" }, { "type": "object", "properties": { "pillarId": { "const": "prediction" } } } ] }, { "allOf": [ { "$ref": "#/$defs/pillar" }, { "type": "object", "properties": { "pillarId": { "const": "crypto_intelligence" } } } ] } ], "items": false } }, "$defs": { "requirement": { "type": "object", "required": [ "requirementId", "verified" ], "properties": { "requirementId": { "type": "string" }, "verified": { "type": "boolean" } }, "additionalProperties": false }, "requirementApi": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "machine_readable_api" } } } ] }, "requirementMcpSdk": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "mcp_sdk_access" } } } ] }, "requirementPricing": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "bounded_pricing_receipts" } } } ] }, "requirementOnboarding": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "tested_onboarding" } } } ] }, "requirementPublicExperience": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "unified_public_experience_distribution" } } } ] }, "requirementDeployment": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "production_deployment" } } } ] }, "requirementDemonstrations": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "real_demonstrations" } } } ] }, "requirementSettlement": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "bounded_real_settlement" } } } ] }, "requirementExternalResult": { "allOf": [ { "$ref": "#/$defs/requirement" }, { "type": "object", "properties": { "requirementId": { "const": "external_useful_paid_result" } } } ] }, "pillar": { "type": "object", "required": [ "pillarId", "release", "lifecycle", "coreQualified", "capabilityIds" ], "properties": { "pillarId": { "enum": [ "search", "ai", "sandbox", "rpc", "prediction", "crypto_intelligence" ] }, "release": { "const": "first_revenue_release" }, "lifecycle": { "enum": [ "available", "degraded", "preview", "unavailable" ] }, "coreQualified": { "type": "boolean" }, "capabilityIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[._][a-z][a-z0-9]*)+$" } } }, "allOf": [ { "if": { "type": "object", "properties": { "lifecycle": { "enum": [ "available", "degraded" ] } }, "required": [ "lifecycle" ] }, "then": { "type": "object", "properties": { "coreQualified": { "const": true } } } } ], "additionalProperties": false } }, "additionalProperties": false }, "Quote": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/quote.schema.json", "title": "Clervo maximum-charge quote", "$defs": { "hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "amount": { "type": "object", "required": [ "asset", "amountAtomic", "decimals" ], "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._/-]{1,127}$" }, "amountAtomic": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,77})$" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 30 } }, "additionalProperties": false } }, "type": "object", "required": [ "contractVersion", "quoteId", "operationId", "productId", "requestHash", "priceVersion", "maximumCharge", "issuedAt", "expiresAt", "quoteHash" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "quoteId": { "type": "string", "pattern": "^quote_[A-Za-z0-9]{20,64}$" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "productId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)+$" }, "requestHash": { "$ref": "#/$defs/hash" }, "priceVersion": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "maximumCharge": { "$ref": "#/$defs/amount" }, "issuedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "quoteHash": { "$ref": "#/$defs/hash" } }, "additionalProperties": false }, "RetrievalSynthesis": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/retrieval-synthesis.schema.json", "title": "Clervo bounded citation-preserving retrieval synthesis report", "$defs": { "invocation": { "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "enum": [ "not_invoked", "succeeded", "failed", "deadline_exceeded", "cancelled", "output_rejected" ] }, "failureCode": { "enum": [ "adapter_failed", "deadline_exceeded", "caller_cancelled", "invalid_model_output" ] } }, "allOf": [ { "if": { "properties": { "outcome": { "enum": [ "not_invoked", "succeeded" ] } }, "required": [ "outcome" ] }, "then": { "properties": { "failureCode": false } } }, { "if": { "properties": { "outcome": { "enum": [ "failed", "deadline_exceeded", "cancelled", "output_rejected" ] } }, "required": [ "outcome" ] }, "then": { "required": [ "failureCode" ] } } ], "additionalProperties": false }, "claim": { "type": "object", "required": [ "claimId", "text", "citationIds" ], "properties": { "claimId": { "type": "string", "pattern": "^claim_[1-9][0-9]*$" }, "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "citationIds": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "pattern": "^cite_[A-Za-z0-9]{20,64}$" } } }, "additionalProperties": false }, "citation": { "type": "object", "required": [ "citationId", "resultId", "canonicalUrl", "quote", "startOffset", "endOffset", "observationId", "pathId", "providerId", "sourceOrdinal", "rawResponseSha256", "fetchId", "extractionId", "sourceBodySha256", "normalizedTextSha256", "title", "rank" ], "properties": { "citationId": { "type": "string", "pattern": "^cite_[A-Za-z0-9]{20,64}$" }, "resultId": { "type": "string", "pattern": "^sr_[A-Za-z0-9]{20,64}$" }, "canonicalUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "quote": { "type": "string", "minLength": 1, "maxLength": 1000 }, "startOffset": { "type": "integer", "minimum": 0 }, "endOffset": { "type": "integer", "minimum": 1, "maximum": 100000 }, "observationId": { "type": "string", "pattern": "^obs_[A-Za-z0-9_]{20,90}$" }, "pathId": { "type": "string", "pattern": "^retrieval_[a-z0-9][a-z0-9._-]{2,63}$" }, "providerId": { "type": "string", "pattern": "^provider_[a-z0-9][a-z0-9._-]{2,63}$" }, "sourceOrdinal": { "type": "integer", "minimum": 1, "maximum": 100 }, "rawResponseSha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "fetchId": { "type": "string", "pattern": "^fetch_[A-Za-z0-9]{20,64}$" }, "extractionId": { "type": "string", "pattern": "^extract_[A-Za-z0-9]{20,64}$" }, "sourceBodySha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "normalizedTextSha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 512 }, "rank": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } }, "type": "object", "required": [ "contractVersion", "synthesisId", "assemblyId", "assemblySha256", "operationId", "query", "createdAt", "deadlineAt", "policyId", "evidenceCount", "outcome", "invocation", "claims", "citations", "synthesisPerformed" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "synthesisId": { "type": "string", "pattern": "^syn_[A-Za-z0-9]{20,64}$" }, "assemblyId": { "type": "string", "pattern": "^asm_[A-Za-z0-9]{20,55}$" }, "assemblySha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "query": { "type": "string", "minLength": 1, "maxLength": 2000 }, "createdAt": { "type": "string", "format": "date-time" }, "deadlineAt": { "type": "string", "format": "date-time" }, "policyId": { "const": "retrieval_cited_claims_v1" }, "evidenceCount": { "type": "integer", "minimum": 0, "maximum": 20 }, "outcome": { "enum": [ "synthesized", "insufficient_evidence", "failed", "cancelled" ] }, "invocation": { "$ref": "#/$defs/invocation" }, "answer": { "type": "string", "minLength": 1, "maxLength": 6000 }, "claims": { "type": "array", "maxItems": 10, "items": { "$ref": "#/$defs/claim" } }, "citations": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/citation" } }, "synthesisPerformed": { "type": "boolean" } }, "allOf": [ { "if": { "properties": { "outcome": { "const": "synthesized" } }, "required": [ "outcome" ] }, "then": { "required": [ "answer" ], "properties": { "answer": { "type": "string", "minLength": 1, "maxLength": 6000 }, "invocation": { "type": "object", "properties": { "outcome": { "const": "succeeded" } }, "required": [ "outcome" ] }, "claims": { "type": "array", "minItems": 1 }, "citations": { "type": "array", "minItems": 1 }, "synthesisPerformed": { "const": true } } }, "else": { "properties": { "answer": false, "claims": { "type": "array", "maxItems": 0 }, "citations": { "type": "array", "maxItems": 0 }, "synthesisPerformed": { "const": false } } } } ], "additionalProperties": false }, "SearchCacheDisclosure": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/search-cache-disclosure.schema.json", "title": "Clervo search cache freshness and revalidation disclosure", "type": "object", "required": [ "policyId", "outcome", "requestSha256", "responseSha256", "observedAt", "maximumResults", "freshnessLifetimeSeconds", "ageSeconds", "residentAgeSeconds", "freshnessRemainingSeconds", "revalidationPerformed" ], "properties": { "policyId": { "const": "search_cache_disclosure_v1" }, "outcome": { "enum": [ "miss", "fresh_hit", "stale_revalidated" ] }, "requestSha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "responseSha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "observedAt": { "type": "string", "format": "date-time" }, "maximumResults": { "type": "integer", "minimum": 1, "maximum": 100 }, "freshnessLifetimeSeconds": { "type": "integer", "minimum": 0, "maximum": 31536000 }, "ageSeconds": { "type": "integer", "minimum": 0, "maximum": 31536000 }, "residentAgeSeconds": { "type": "integer", "minimum": 0 }, "freshnessRemainingSeconds": { "type": "integer", "minimum": 0, "maximum": 31536000 }, "revalidationPerformed": { "type": "boolean" }, "storedAt": { "type": "string", "format": "date-time" }, "validatedAt": { "type": "string", "format": "date-time" }, "previousValidatedAt": { "type": "string", "format": "date-time" } }, "allOf": [ { "if": { "properties": { "outcome": { "const": "miss" } }, "required": [ "outcome" ] }, "then": { "properties": { "freshnessLifetimeSeconds": { "const": 0 }, "ageSeconds": { "const": 0 }, "residentAgeSeconds": { "const": 0 }, "freshnessRemainingSeconds": { "const": 0 }, "revalidationPerformed": { "const": false }, "storedAt": false, "validatedAt": false, "previousValidatedAt": false } } }, { "if": { "properties": { "outcome": { "const": "fresh_hit" } }, "required": [ "outcome" ] }, "then": { "required": [ "storedAt", "validatedAt" ], "properties": { "freshnessLifetimeSeconds": { "type": "integer", "minimum": 1 }, "freshnessRemainingSeconds": { "type": "integer", "minimum": 1 }, "revalidationPerformed": { "const": false }, "previousValidatedAt": false } } }, { "if": { "properties": { "outcome": { "const": "stale_revalidated" } }, "required": [ "outcome" ] }, "then": { "required": [ "storedAt", "validatedAt", "previousValidatedAt" ], "properties": { "freshnessLifetimeSeconds": { "type": "integer", "minimum": 1 }, "ageSeconds": { "type": "integer", "const": 0 }, "revalidationPerformed": { "const": true } } } } ], "additionalProperties": false }, "SearchHttpRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/search-http-request.schema.json", "title": "Clervo bounded search HTTP request", "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 }, "synthesize": { "type": "boolean", "default": true }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "default": "en" }, "region": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US" } }, "additionalProperties": false }, "SearchHttpResult": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/search-http-result.schema.json", "title": "Clervo search HTTP result envelope", "type": "object", "required": [ "contractVersion", "operationId", "operation", "productId", "state", "replayed", "fundingMode", "requestHash", "output" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "operation": { "const": "search.query" }, "productId": { "enum": [ "search.web", "search.answer" ] }, "state": { "const": "RECEIPTED" }, "replayed": { "type": "boolean" }, "fundingMode": { "enum": [ "free", "paid" ] }, "requestHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "output": { "type": "object", "required": [ "searchResponse" ], "properties": { "searchResponse": { "$ref": "search-response.schema.json" }, "synthesisReport": { "$ref": "retrieval-synthesis.schema.json" } }, "additionalProperties": false }, "receipt": { "$ref": "operation-receipt.schema.json" } }, "additionalProperties": false }, "SearchResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.clervo.dev/schemas/2026-07-29.1/search-response.schema.json", "title": "Clervo deterministic search response", "$defs": { "score": { "type": "object", "required": [ "freshness", "authority", "relevance", "diversity", "totalBasisPoints" ], "properties": { "freshness": { "type": "integer", "minimum": 0, "maximum": 100 }, "authority": { "type": "integer", "minimum": 0, "maximum": 100 }, "relevance": { "type": "integer", "minimum": 0, "maximum": 100 }, "diversity": { "enum": [ 40, 100 ] }, "totalBasisPoints": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "additionalProperties": false }, "result": { "type": "object", "required": [ "resultId", "sourceId", "url", "canonicalUrl", "hostname", "title", "snippet", "evidenceText", "retrievedAt", "authorityScore", "relevanceScore", "rank", "score" ], "properties": { "resultId": { "type": "string", "pattern": "^sr_[A-Za-z0-9]{20,64}$" }, "sourceId": { "type": "string", "pattern": "^adapter_[a-z0-9][a-z0-9._-]{2,63}$" }, "url": { "type": "string", "format": "uri", "pattern": "^https?://" }, "canonicalUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "title": { "type": "string", "minLength": 1, "maxLength": 512 }, "snippet": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceText": { "type": "string", "minLength": 1, "maxLength": 100000 }, "retrievedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "authorityScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "relevanceScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "rank": { "type": "integer", "minimum": 1, "maximum": 100 }, "score": { "$ref": "#/$defs/score" }, "attribution": { "type": "object", "required": [ "sourceName", "sourceUrl", "license", "notice" ], "properties": { "sourceName": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "license": { "type": "string", "minLength": 1, "maxLength": 512 }, "notice": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "additionalProperties": false } }, "additionalProperties": false }, "citation": { "type": "object", "required": [ "citationId", "resultId", "canonicalUrl", "quote", "startOffset", "endOffset" ], "properties": { "citationId": { "type": "string", "pattern": "^cite_[A-Za-z0-9]{20,64}$" }, "resultId": { "type": "string", "pattern": "^sr_[A-Za-z0-9]{20,64}$" }, "canonicalUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "quote": { "type": "string", "minLength": 1, "maxLength": 10000 }, "startOffset": { "type": "integer", "minimum": 0 }, "endOffset": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "type": "object", "required": [ "contractVersion", "operationId", "query", "language", "region", "generatedAt", "deduplicatedCount", "results", "citations", "cache" ], "properties": { "contractVersion": { "const": "2026-07-29.1" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{20,64}$" }, "query": { "type": "string", "minLength": 1, "maxLength": 2000 }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "region": { "type": "string", "pattern": "^[A-Z]{2}$" }, "generatedAt": { "type": "string", "format": "date-time" }, "deduplicatedCount": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/result" } }, "citations": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/$defs/citation" } }, "cache": { "$ref": "search-cache-disclosure.schema.json" } }, "additionalProperties": false } } }, "x-clervo-status": { "lifecycle": "preview", "distribution": "public_preview", "noPublicDistribution": false, "publicCallable": true, "paymentImplemented": true, "deploymentVerified": true, "releaseCandidateId": "clervo-private-core-2026-08-02.2", "interfaceHash": "sha256:2773690eda2ed6c89461c98f1537fccc5ae648f37845eb7a5a620952647a39b4", "operationIds": [ "search.web", "ai.chat", "ai.embed", "ai.image", "ai.speech", "ai.video", "ai.music", "ai.virtual_try_on", "sandbox.run", "prediction.markets", "prediction.market", "prediction.compare", "prediction.history", "prediction.signal", "crypto.wallet.balances", "crypto.wallet.tokens", "crypto.wallet.transactions", "crypto.wallet.report" ], "runtimeRelease": "802527f49f87b1aa9323c329bf52c07ffce6d659" }, "servers": [ { "url": "https://api.clervo.dev" } ] }