{ "openapi": "3.1.0", "info": { "title": "grist.tools", "version": "1.0.0", "summary": "Deterministic HTTP micro-utilities for AI agents, paid per call via x402.", "description": "One endpoint does one thing, always the same way, for a fraction of a cent. Payment is verified before the handler runs and settled only after it succeeds, so a rejected or failed call is never a charged call.", "x-guidance": "POST a JSON body to /v1/. A paid operation answers 402 with the x402 payment requirements (price, asset, network, pay-to address, max_timeout_seconds); repeat the same request with a signed payment in the payment-signature header. Payment is verified before the handler runs and settled only after it succeeds. GET /v1//schema is free for every operation and returns the input schema, price and examples.", "contact": { "email": "inbox@grist.tools" } }, "servers": [ { "url": "https://grist.tools" } ], "tags": [ { "name": "archives" }, { "name": "av" }, { "name": "images" }, { "name": "documents" }, { "name": "domain" }, { "name": "feeds" }, { "name": "fetch" } ], "paths": { "/v1/archive-extract-file": { "post": { "operationId": "archive-extract-file", "summary": "Extracts one named entry from a remote zip, tar or tar.gz and returns its bytes (base64) with a sha256.", "description": "Pulling a single file out of an archive without unpacking the whole thing needs a real reader, a hardened fetch and the decompression-bomb care that caps a single entry twice, not something an agent should run inline.\n\nDeclared timeout: 90000ms. Response size cap: 26214400 bytes.", "tags": [ "archives" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the archive (at most 25 MB, also the cap on an inflated tar.gz), up to 2048 characters; redirects are followed and the format (zip, tar or gzip-compressed tar) is decided from the magic bytes, not the extension." }, "entry": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Exact entry path to extract, 1 to 4096 characters, matched case-sensitively against the names archive-inspect lists; directories, links, encrypted entries and entries over 25 MB are refused." } }, "required": [ "url", "entry" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/archives/bundle.zip", "entry": "data/squares.csv" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "kind": { "type": "string", "enum": [ "zip", "tar" ] }, "entry_name": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "compression": { "type": "string" }, "crc32": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "type": "string" }, "content_base64": { "type": "string" } }, "required": [ "source_url", "kind", "entry_name", "size", "compression", "crc32", "sha256", "content_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/archives/bundle.zip", "kind": "zip", "entry_name": "data/squares.csv", "size": 31, "compression": "deflate", "crc32": "89761172", "sha256": "202663eb5661a93d557520ce47e40bb6ccdcd7fded543fca46592d2291e2c8cf", "content_base64": "bixzcXVhcmUKMSwxCjIsNAozLDkKNCwxNgo1LDI1Cg==" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/archive-extract-file", "description": "Extracts one named entry from a remote zip, tar or tar.gz and returns its bytes (base64) with a sha256.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "archives" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 111, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 111, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/archive-extract-file/schema": { "get": { "operationId": "archive-extract-file-schema", "summary": "Schema, price and examples for archive-extract-file. Always free.", "tags": [ "archives" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/archive-inspect": { "post": { "operationId": "archive-inspect", "summary": "Lists the entries of a remote zip, tar or tar.gz (paths, sizes, compression and CRC) without extracting any of them.", "description": "Seeing inside an archive without extracting it needs a real zip/tar reader and a hardened fetch, plus the decompression-bomb care that reads declared sizes instead of inflating, not something an agent does inline.\n\nDeclared timeout: 60000ms. Response size cap: 104857600 bytes.", "tags": [ "archives" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the archive (at most 100 MB, also the cap on an inflated tar.gz), up to 2048 characters; redirects are followed and the format (zip, tar or gzip-compressed tar) is decided from the magic bytes, not the extension." }, "max_entries": { "default": 1000, "description": "How many entries to list, 1 to 10000 (default 1000), taken in archive order and then sorted by name; any beyond the limit still count in total_entries and set truncated.", "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/archives/bundle.zip", "max_entries": 1000 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "kind": { "type": "string", "enum": [ "zip", "tar" ] }, "compression": { "type": "string", "enum": [ "none", "gzip" ] }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_entries": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_uncompressed_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "encrypted": { "type": "boolean" }, "truncated": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "is_directory": { "type": "boolean" }, "entry_type": { "type": "string", "enum": [ "file", "directory", "symlink", "hardlink", "other" ] }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "compressed_size": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "compression": { "type": "string" }, "encrypted": { "type": "boolean" }, "crc32": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "is_directory", "entry_type", "size", "compressed_size", "compression", "encrypted", "crc32" ], "additionalProperties": false } } }, "required": [ "source_url", "kind", "compression", "entry_count", "total_entries", "total_uncompressed_bytes", "encrypted", "truncated", "entries" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/archives/bundle.zip", "kind": "zip", "compression": "none", "entry_count": 5, "total_entries": 5, "total_uncompressed_bytes": 159, "encrypted": false, "truncated": false, "entries": [ { "name": "data/", "is_directory": true, "entry_type": "directory", "size": 0, "compressed_size": 0, "compression": "none", "encrypted": false, "crc32": "00000000" }, { "name": "data/squares.csv", "is_directory": false, "entry_type": "file", "size": 31, "compressed_size": 33, "compression": "deflate", "encrypted": false, "crc32": "89761172" }, { "name": "docs/", "is_directory": true, "entry_type": "directory", "size": 0, "compressed_size": 0, "compression": "none", "encrypted": false, "crc32": "00000000" }, { "name": "docs/readme.md", "is_directory": false, "entry_type": "file", "size": 116, "compressed_size": 94, "compression": "deflate", "encrypted": false, "crc32": "b6cd27c3" }, { "name": "hello.txt", "is_directory": false, "entry_type": "file", "size": 12, "compressed_size": 12, "compression": "store", "encrypted": false, "crc32": "af083b2d" } ] }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/archive-inspect", "description": "Lists the entries of a remote zip, tar or tar.gz (paths, sizes, compression and CRC) without extracting any of them.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "archives" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/archive-inspect/schema": { "get": { "operationId": "archive-inspect-schema", "summary": "Schema, price and examples for archive-inspect. Always free.", "tags": [ "archives" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/audio-convert": { "post": { "operationId": "audio-convert", "summary": "Transcodes an audio file between WAV, MP3, FLAC, AAC and Opus, with an optional bit rate and sample rate.", "description": "Re-encoding audio needs ffmpeg AND a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an ffmpeg per call is not something an agent does inline.\n\nDeclared timeout: 94000ms. Response size cap: 104857600 bytes. Maximum input duration: 3600 s. Longer input is refused with too_large (413), and input whose duration cannot be measured with unprocessable (422). Both are decided before any encoding, so the call is never settled.\n\nWith to set to aac, bitrate_kbps is at most 192; a higher value is refused with invalid_input (400).", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the source file, up to 2048 characters; the first audio stream of a recognised container (MP4/MOV, Matroska/WebM, AVI, Ogg, WAV, FLAC, AIFF or MP3) is converted, and it must last at most 3600 seconds." }, "to": { "default": "mp3", "description": "Output format: wav (16-bit PCM), mp3 (LAME), flac, aac (ADTS stream) or opus (in an Ogg container); defaults to mp3.", "type": "string", "enum": [ "wav", "mp3", "flac", "aac", "opus" ] }, "bitrate_kbps": { "description": "Target bit rate in kbps, lossy formats only (mp3, aac, opus): 8 to 512, and at most 192 for aac.", "type": "integer", "minimum": 8, "maximum": 512 }, "sample_rate": { "description": "Output sample rate in Hz, one of 8000, 11025, 16000, 22050, 32000, 44100 or 48000; when omitted ffmpeg chooses the rate, normally the source rate.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/convert-beeps.flac", "to": "wav" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source_container": { "type": "string", "enum": [ "mp4", "matroska", "wav", "avi", "mp3", "ogg", "flac", "aiff" ] }, "format": { "type": "string", "enum": [ "wav", "mp3", "flac", "aac", "opus" ] }, "bitrate_kbps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sample_rate": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "audio_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "audio_base64": { "type": "string" } }, "required": [ "source_url", "bytes", "source_container", "format", "bitrate_kbps", "sample_rate", "audio_bytes", "audio_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/convert-beeps.flac", "bytes": 32086, "source_container": "flac", "format": "wav", "bitrate_kbps": null, "sample_rate": null, "audio_bytes": 32044, "audio_base64": "UklGRiR9AABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQB9AAAA4ADo..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/audio-convert", "description": "Transcodes an audio file between WAV, MP3, FLAC, AAC and Opus, with an optional bit rate and sample rate.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 115, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 115, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/audio-convert/schema": { "get": { "operationId": "audio-convert-schema", "summary": "Schema, price and examples for audio-convert. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/audio-extract": { "post": { "operationId": "audio-extract", "summary": "Extracts the audio track from a video (or any container) and returns it in a chosen audio format.", "description": "Demuxing and re-encoding an audio track needs ffmpeg AND a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an ffmpeg per call is not something an agent does inline.\n\nDeclared timeout: 94000ms. Response size cap: 209715200 bytes. Maximum input duration: 3600 s. Longer input is refused with too_large (413), and input whose duration cannot be measured with unprocessable (422). Both are decided before any encoding, so the call is never settled.", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of a video or audio file, up to 2048 characters, in a recognised container (MP4/MOV, Matroska/WebM, AVI, Ogg, WAV, FLAC, AIFF or MP3); the selected audio stream must last at most 3600 seconds." }, "stream": { "default": 0, "description": "Zero-based index among the audio streams only (0 is the first audio track), 0 to 63; an index the file does not have is refused as unprocessable.", "type": "integer", "minimum": 0, "maximum": 63 }, "to": { "default": "mp3", "description": "Output format for the extracted track: wav (16-bit PCM), mp3 (LAME), flac, aac (ADTS stream) or opus (in an Ogg container); defaults to mp3.", "type": "string", "enum": [ "wav", "mp3", "flac", "aac", "opus" ] } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/probe-clip.mov", "stream": 0, "to": "wav" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "container": { "type": "string", "enum": [ "mp4", "matroska", "wav", "avi", "mp3", "ogg", "flac", "aiff" ] }, "stream_index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "wav", "mp3", "flac", "aac", "opus" ] }, "audio_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "audio_base64": { "type": "string" } }, "required": [ "source_url", "bytes", "container", "stream_index", "format", "audio_bytes", "audio_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/probe-clip.mov", "bytes": 33850, "container": "mp4", "stream_index": 0, "format": "wav", "audio_bytes": 32044, "audio_base64": "UklGRiR9AABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQB9AAAA4ADo..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/audio-extract", "description": "Extracts the audio track from a video (or any container) and returns it in a chosen audio format.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 115, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 115, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/audio-extract/schema": { "get": { "operationId": "audio-extract-schema", "summary": "Schema, price and examples for audio-extract. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/color-palette-extract": { "post": { "operationId": "color-palette-extract", "summary": "Extracts an image's dominant colours as a small palette (hex, RGB and coverage fraction).", "description": "Extracting a palette safely needs a real decoder and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and a byte-reproducible quantiser is not something an agent writes inline.\n\nDeclared timeout: 60000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the image, up to 2048 characters; redirects are followed and the format is detected from the bytes, not the content-type." }, "colors": { "default": 5, "description": "Maximum number of palette colours to return, 1 to 16, most common first; fewer come back when the image has fewer distinct colour buckets.", "type": "integer", "minimum": 1, "maximum": 16 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/palette-bands.png", "colors": 5 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "source_format": { "type": "string", "enum": [ "jpeg", "png", "gif", "webp", "tiff", "avif", "heic", "svg" ] }, "sample_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "dominant": { "type": "string" }, "colors": { "type": "array", "items": { "type": "object", "properties": { "hex": { "type": "string" }, "rgb": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "fraction": { "type": "number" } }, "required": [ "hex", "rgb", "fraction" ], "additionalProperties": false } } }, "required": [ "source_url", "source_format", "sample_size", "count", "dominant", "colors" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/palette-bands.png", "source_format": "png", "sample_size": 64, "count": 5, "dominant": "#3b4a5a", "colors": [ { "hex": "#3b4a5a", "rgb": [ 59, 74, 90 ], "fraction": 0.375 }, { "hex": "#d8c9a3", "rgb": [ 216, 201, 163 ], "fraction": 0.25 }, { "hex": "#2f8f83", "rgb": [ 47, 143, 131 ], "fraction": 0.1875 }, { "hex": "#e0735a", "rgb": [ 224, 115, 90 ], "fraction": 0.125 }, { "hex": "#f4efe6", "rgb": [ 244, 239, 230 ], "fraction": 0.0625 } ] }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/color-palette-extract", "description": "Extracts an image's dominant colours as a small palette (hex, RGB and coverage fraction).", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/color-palette-extract/schema": { "get": { "operationId": "color-palette-extract-schema", "summary": "Schema, price and examples for color-palette-extract. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/csv-to-json": { "post": { "operationId": "csv-to-json", "summary": "Parses a CSV/TSV document into JSON rows, keyed by a header row or as arrays; the delimiter is auto-detected.", "description": "A correct CSV parser is more than a split on commas (quoted fields, embedded newlines and escaped quotes all bite), and doing it over a URL an agent fetches itself walks past every SSRF control.\n\nDeclared timeout: 30000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "UTF-8 CSV/TSV URL. Missing charset means UTF-8; only utf-8 and utf8 declarations are accepted (case-insensitive, optionally quoted). Unsupported or invalid declarations and NUL bytes return 415; malformed UTF-8 returns 422. A UTF-8 BOM is accepted. Encoding is checked across the whole body." }, "delimiter": { "description": "A single field delimiter character such as \",\" or a tab; omitted, it is auto-detected from the first rows among comma, tab, pipe, semicolon and the ASCII record and unit separators, and a line break, quote or BOM given here falls back to a comma.", "type": "string", "minLength": 1, "maxLength": 1 }, "header": { "default": true, "description": "Use the first nonempty record as object keys. Names are trimmed; blank names become column_. Names are made unique left to right using the next unused _2, _3 suffix, including collisions with literal suffixed names. Special names remain data keys. Short rows pad with empty strings; extra fields return 422 csv_extra_fields. With false, preserve actual row widths as string arrays.", "type": "boolean" }, "max_rows": { "default": 10000, "description": "Maximum returned nonempty data rows. One additional nonempty record sets truncated; its width is budgeted but not checked against the header. A truncated success does not validate the entire CSV structure.", "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "url" ], "additionalProperties": false, "description": "All values remain strings. Records whose parsed fields concatenate to whitespace only are skipped, including blank lines, delimiter-only and quoted-empty records. They do not establish headers, consume max_rows or alone set truncated; structural budgets still apply." }, "example": { "url": "https://grist.tools/samples/documents/garden-plots.csv", "header": true } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "delimiter": { "type": "string" }, "columns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "rows": { "type": "array", "items": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "array", "items": { "type": "string" } } ] } }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" } }, "required": [ "source_url", "delimiter", "columns", "rows", "row_count", "truncated" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/garden-plots.csv", "delimiter": ",", "columns": [ "plot", "holder", "crop", "area_m2", "notes" ], "rows": [ { "plot": "A1", "holder": "Maple Group", "crop": "tomatoes", "area_m2": "12", "notes": "Stakes needed, north side" }, { "plot": "A2", "holder": "Oak Group", "crop": "beans", "area_m2": "08", "notes": "" }, { "plot": "B1", "holder": "Willow Group", "crop": "herbs, mixed", "area_m2": "6", "notes": "Shares water with \"B2\"" }, { "plot": "B2", "holder": "Birch Group", "crop": "squash", "area_m2": "10.50", "notes": "Compost added in April" } ], "row_count": 4, "truncated": false }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/csv-to-json", "description": "Parses a CSV/TSV document into JSON rows, keyed by a header row or as arrays; the delimiter is auto-detected.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 51, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 51, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/csv-to-json/schema": { "get": { "operationId": "csv-to-json-schema", "summary": "Schema, price and examples for csv-to-json. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/dns-lookup": { "post": { "operationId": "dns-lookup", "summary": "DNS records for a domain (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA) with their TTLs.", "description": "A DNS query needs the network, so an agent cannot answer it on its own. It is what you run in a loop over a list of domains.\n\nDeclared timeout: 5000ms. Response size cap: 2097152 bytes.", "tags": [ "domain" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "description": "Fully qualified domain name to resolve, up to 253 characters; it is trimmed, lowercased and stripped of trailing dots, and IP literals, single-label names and private suffixes such as .local or .internal are refused.", "type": "string", "minLength": 1, "maxLength": 253 }, "types": { "description": "Record types to query, from a, aaaa, mx, txt, ns, cname, soa and caa in either case; duplicates collapse to one query per type, answers come back in that fixed order, and the default is all eight.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "enum": [ "a", "aaaa", "mx", "txt", "ns", "cname", "soa", "caa", "A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "CAA" ] } } }, "required": [ "domain" ], "additionalProperties": false }, "example": { "domain": "example.com", "types": [ "a", "mx" ] } } } }, "responses": { "200": { "description": "Success", "headers": {}, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "type": "string" }, "types_requested": { "type": "array", "items": { "type": "string", "enum": [ "a", "aaaa", "mx", "txt", "ns", "cname", "soa", "caa" ] } }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "a", "aaaa", "mx", "txt", "ns", "cname", "soa", "caa" ] }, "values": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "address": { "type": "string" }, "ttl": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "address", "ttl" ], "additionalProperties": false }, { "type": "object", "properties": { "exchange": { "type": "string" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "exchange", "priority" ], "additionalProperties": false }, { "type": "string" }, { "type": "object", "properties": { "nsname": { "type": "string" }, "hostmaster": { "type": "string" }, "serial": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "refresh": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "retry": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expire": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minttl": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "nsname", "hostmaster", "serial", "refresh", "retry", "expire", "minttl" ], "additionalProperties": false }, { "type": "object", "properties": { "critical": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "critical" ], "additionalProperties": { "type": "string" } } ] } }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "resolution_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "values", "truncated", "resolution_error" ], "additionalProperties": false } }, "queried_at": { "type": "string" } }, "required": [ "domain", "types_requested", "records", "queried_at" ], "additionalProperties": false }, "example": { "domain": "example.com", "types_requested": [ "a", "mx" ], "records": [ { "type": "a", "values": [ { "address": "93.184.215.14", "ttl": 3600 } ], "truncated": false, "resolution_error": null }, { "type": "mx", "values": [ { "exchange": "mail.example.com", "priority": 10 } ], "truncated": false, "resolution_error": null } ], "queried_at": "2026-08-26T18:00:00.000Z" }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/dns-lookup/schema": { "get": { "operationId": "dns-lookup-schema", "summary": "Schema, price and examples for dns-lookup. Always free.", "tags": [ "domain" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/docx-to-markdown": { "post": { "operationId": "docx-to-markdown", "summary": "Converts a Word .docx to Markdown, surfacing anything that did not translate as warnings.", "description": "A faithful docx→Markdown conversion needs a real OOXML engine plus a hardened fetch: an agent that fetches the URL itself walks past every SSRF control, and carrying mammoth per call is not something an agent does inline.\n\nDeclared timeout: 40000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the .docx, up to 2048 characters; redirects are followed, the body must be a zip, and mammoth must find a Word document in it." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/garden-handbook.docx" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "array", "items": { "type": "string" } }, "markdown": { "type": "string" } }, "required": [ "source_url", "chars", "warnings", "markdown" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/garden-handbook.docx", "chars": 341, "warnings": [], "markdown": "# Community Garden Handbook\n\nPlots are assigned for **one season** and renewed each spring.\n\n## Watering\n\n- Water early in the morning.\n- Use the rain barrels first.\n- Log each watering on the shed board.\n\n## Tools\n\nReturn every tool to the shed _before sunset_.\n\nThe seasonal calendar lives on [the garden site](https://grist.tools/)." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/docx-to-markdown", "description": "Converts a Word .docx to Markdown, surfacing anything that did not translate as warnings.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 61, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 61, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/docx-to-markdown/schema": { "get": { "operationId": "docx-to-markdown-schema", "summary": "Schema, price and examples for docx-to-markdown. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/email-validate": { "post": { "operationId": "email-validate", "summary": "Validates an email address: syntax, MX records for its domain, and whether it is a disposable or role account.", "description": "The MX check needs a resolver an agent may not have, and the disposable/role assessment is a curated dataset and rule set it would otherwise have to build and keep current.\n\nDeclared timeout: 5000ms. Response size cap: 2097152 bytes.", "tags": [ "domain" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The address to assess, up to 320 characters; it is trimmed, and a malformed address is answered with syntax_valid false rather than rejected." }, "check_mx": { "default": true, "description": "Whether to resolve MX records for the domain; when true, a domain with no MX makes valid false, and false skips every network lookup.", "type": "boolean" }, "check_disposable": { "default": true, "description": "Whether to match the domain against the bundled disposable-provider list; when true, a disposable domain makes valid false.", "type": "boolean" } }, "required": [ "email" ], "additionalProperties": false }, "example": { "email": "support@grist.tools", "check_mx": false } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string" }, "valid": { "type": "boolean" }, "syntax_valid": { "type": "boolean" }, "mx_found": { "type": "boolean" }, "mx_records": { "type": "array", "items": { "type": "object", "properties": { "exchange": { "type": "string" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "exchange", "priority" ], "additionalProperties": false } }, "is_disposable": { "type": "boolean" }, "is_role_account": { "type": "boolean" } }, "required": [ "email", "valid", "syntax_valid", "mx_found", "mx_records", "is_disposable", "is_role_account" ], "additionalProperties": false }, "example": { "email": "support@grist.tools", "valid": true, "syntax_valid": true, "mx_found": false, "mx_records": [], "is_disposable": false, "is_role_account": true }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/email-validate", "description": "Validates an email address: syntax, MX records for its domain, and whether it is a disposable or role account.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "domain" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 26, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 26, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/email-validate/schema": { "get": { "operationId": "email-validate-schema", "summary": "Schema, price and examples for email-validate. Always free.", "tags": [ "domain" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/epub-to-text": { "post": { "operationId": "epub-to-text", "summary": "Extracts an EPUB’s reading-order text and Dublin Core metadata, chapter by chapter.", "description": "Reading an EPUB means walking a zip, its container, its OPF spine and each XHTML chapter through a hardened fetch. An agent doing that inline walks past every SSRF control, and it is fiddly enough to be worth a paid endpoint.\n\nDeclared timeout: 45000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the .epub, up to 2048 characters; redirects are followed and the body must be a zip whose META-INF/container.xml points at an OPF package." }, "max_chapters": { "default": 500, "description": "How many leading XHTML/HTML spine chapters to extract, 1 to 5000; a shorter book is not an error, and a longer one is cut and reported as truncated.", "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/seed-saving.epub", "max_chapters": 500 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "metadata": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creator": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "creator", "language" ], "additionalProperties": false }, "chapter_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extracted_chapters": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "text": { "type": "string" } }, "required": [ "href", "text" ], "additionalProperties": false } }, "text": { "type": "string" } }, "required": [ "source_url", "metadata", "chapter_count", "extracted_chapters", "truncated", "chars", "chapters", "text" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/seed-saving.epub", "metadata": { "title": "A Short Guide to Seed Saving", "creator": "Grist Samples", "language": "en" }, "chapter_count": 3, "extracted_chapters": 3, "truncated": false, "chars": 441, "chapters": [ { "href": "OEBPS/ch1.xhtml", "text": "Why Save Seeds\n\nSaving seeds keeps a variety that grows well in your own soil.\n\nIt also costs nothing and makes next spring easier to plan." }, { "href": "OEBPS/ch2.xhtml", "text": "Choosing Plants\n\nPick the healthiest plants and let a few fruits ripen fully.\n\nBeans and peas are the easiest to start with.\n\nTomatoes need their seeds rinsed and dried." }, { "href": "OEBPS/ch3.xhtml", "text": "Drying and Storing\n\nDry seeds on paper for a week, away from direct sun.\n\nStore them in labelled envelopes in a cool, dark place." } ], "text": "Why Save Seeds\n\nSaving seeds keeps a variety that grows well in your own soil.\n\nIt also costs nothing and makes next spring easier to plan.\n\nChoosing Plants\n\nPick the healthiest plants and let a few fruits ripen fully.\n\nBeans and peas are the easiest to start with.\n\nTomatoes need their seeds rinsed and dried.\n\nDrying and Storing\n\nDry seeds on paper for a week, away from direct sun.\n\nStore them in labelled envelopes in a cool, dark place." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/epub-to-text", "description": "Extracts an EPUB’s reading-order text and Dublin Core metadata, chapter by chapter.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 66, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 66, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/epub-to-text/schema": { "get": { "operationId": "epub-to-text-schema", "summary": "Schema, price and examples for epub-to-text. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/favicon-extract": { "post": { "operationId": "favicon-extract", "summary": "Discovers a page's favicons and returns the best one decoded to a normalised PNG with its size.", "description": "It fans out over URLs a page author wrote and must decode several icon formats: an agent that does this itself walks past every SSRF control and becomes a request amplifier, and hand-rolling ICO/SVG decoding is not inline work.\n\nDeclared timeout: 45000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the web page whose icon tags (rel icon, shortcut, apple-touch-icon or mask-icon) are read, up to 2048 characters; /favicon.ico on its origin is added as a last candidate and icons are only fetched from the same registrable domain." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/index.html" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page_url": { "type": "string" }, "icons": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "rel": { "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "rel", "type", "sizes" ], "additionalProperties": false } }, "selected": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string" }, "source_format": { "type": "string", "enum": [ "jpeg", "png", "gif", "webp", "tiff", "avif", "heic", "svg", "bmp", "ico" ] }, "width": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "image_base64": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "source_format", "width", "height", "bytes", "image_base64" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "page_url", "icons", "selected" ], "additionalProperties": false }, "example": { "page_url": "https://grist.tools/samples/web/fieldnotes/index.html", "icons": [ { "url": "https://grist.tools/samples/web/fieldnotes/icon-32.png", "rel": "icon", "type": "image/png", "sizes": "32x32" }, { "url": "https://grist.tools/samples/web/fieldnotes/icon.svg", "rel": "icon", "type": "image/svg+xml", "sizes": null }, { "url": "https://grist.tools/favicon.ico", "rel": "icon", "type": null, "sizes": null } ], "selected": { "url": "https://grist.tools/samples/web/fieldnotes/icon-32.png", "source_format": "png", "width": 32, "height": 32, "bytes": 106, "image_base64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAACXBIWXMAAAsSAAALEgHS3X78AAAAMUlEQVRIx2PQjw2gKWIYtWDUgiFswaf3z0hCoxaMWjBqwagFoxYMTwtGq8xRC0aQBQBMN1tMlMrjbQAAAABJRU5ErkJggg==" } }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/favicon-extract", "description": "Discovers a page's favicons and returns the best one decoded to a normalised PNG with its size.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 66, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 66, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/favicon-extract/schema": { "get": { "operationId": "favicon-extract-schema", "summary": "Schema, price and examples for favicon-extract. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/feed-discover": { "post": { "operationId": "feed-discover", "summary": "Fetches a web page and returns the RSS, Atom and JSON feeds it declares in its , as absolute URLs with their type and title.", "description": "It needs the network, and the feed an agent wants is declared in the page it already has as a -- one guarded fetch and a DOM query returns it, where feeding the whole page to a model costs far more in tokens and still guesses.\n\nDeclared timeout: 8000ms. Response size cap: 5242880 bytes.", "tags": [ "feeds" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the HTML or XHTML page whose or rel=\"feed\" declarations with an RSS, Atom or JSON Feed media type are read, up to 2048 characters; up to 5 redirects are followed and no feed paths are probed." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/index.html" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string", "enum": [ "rss", "atom", "json", "unknown" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rel": { "type": "string" } }, "required": [ "url", "type", "title", "rel" ], "additionalProperties": false } }, "feeds_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "feeds_truncated": { "type": "boolean" }, "fetched_at": { "type": "string" } }, "required": [ "url", "source_url", "final_url", "http_status", "feeds", "feeds_total", "feeds_truncated", "fetched_at" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/index.html", "source_url": "https://grist.tools/samples/web/fieldnotes/index.html", "final_url": "https://grist.tools/samples/web/fieldnotes/index.html", "http_status": 200, "feeds": [ { "url": "https://grist.tools/samples/web/fieldnotes/feed.xml", "type": "rss", "title": "Field Notes (RSS)", "rel": "alternate" }, { "url": "https://grist.tools/samples/web/fieldnotes/atom.xml", "type": "atom", "title": "Field Notes (Atom)", "rel": "alternate" } ], "feeds_total": 2, "feeds_truncated": false, "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/feed-discover", "description": "Fetches a web page and returns the RSS, Atom and JSON feeds it declares in its , as absolute URLs with their type and title.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "feeds" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/feed-discover/schema": { "get": { "operationId": "feed-discover-schema", "summary": "Schema, price and examples for feed-discover. Always free.", "tags": [ "feeds" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/file-type-detect": { "post": { "operationId": "file-type-detect", "summary": "Detects a remote file's true type from its magic bytes, returning the canonical extension and media type.", "description": "Trusting a URL extension or a server content-type is exactly how an agent mislabels a payload; deciding the type from the bytes needs a signature database and a hardened fetch an agent should not run inline.\n\nDeclared timeout: 30000ms. Response size cap: 33554432 bytes.", "tags": [ "archives" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the file, up to 2048 characters; redirects are followed, the whole body (at most 32 MB) is downloaded, and the type comes from its magic bytes, ignoring the extension and content-type header." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/archives/bundle.zip" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detected": { "type": "boolean" }, "ext": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source_url", "bytes", "detected", "ext", "mime" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/archives/bundle.zip", "bytes": 639, "detected": true, "ext": "zip", "mime": "application/zip" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/file-type-detect", "description": "Detects a remote file's true type from its magic bytes, returning the canonical extension and media type.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "archives" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 51, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 51, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/file-type-detect/schema": { "get": { "operationId": "file-type-detect-schema", "summary": "Schema, price and examples for file-type-detect. Always free.", "tags": [ "archives" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/html-clean-text": { "post": { "operationId": "html-clean-text", "summary": "Fetches a web page and returns the article as clean text and markdown, with its declared metadata.", "description": "It needs the network and a real DOM: boilerplate removal, legacy charset decoding and HTML-to-markdown are three heavy libraries an agent does not carry, and feeding raw HTML to a model instead costs far more in tokens than this call costs.\n\nDeclared timeout: 12000ms. Response size cap: 1048576 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "URL of an HTML, XHTML or plain-text page to fetch, up to 2048 characters; redirects are followed, the body is capped at 1 MB, and exactly one of url or html is required.", "type": "string", "maxLength": 2048, "format": "uri" }, "html": { "description": "Inline HTML source to clean instead of fetching, up to 262,144 characters; binary content such as PDF or JSON is refused.", "type": "string", "minLength": 1, "maxLength": 262144 }, "base_url": { "description": "Base URL for resolving relative links in the html input; not allowed together with url, where the final fetched URL is the base.", "type": "string", "maxLength": 2048, "format": "uri" }, "include_links": { "default": false, "description": "Also return the links inside the extracted content, each with its text, rel and same-host flag, resolved against the fetched URL or base_url when there is one, else kept as authored.", "type": "boolean" }, "readability": { "default": true, "description": "Run Readability to keep only the main article; false, or an article Readability cannot find, converts the whole body, navigation and footer included.", "type": "boolean" }, "max_chars": { "default": 50000, "description": "Maximum length of text and markdown, 200 to 200,000 Unicode code points (default 50,000); a longer result is cut and flagged as truncated.", "type": "integer", "minimum": 200, "maximum": 200000 } }, "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/render-article.html", "include_links": true, "readability": true, "max_chars": 2000 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requested_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "final_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "charset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "http_status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "byline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "site_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang_source": { "anyOf": [ { "type": "string", "enum": [ "html_lang", "meta_content_language", "og_locale" ] }, { "type": "null" } ] }, "text": { "type": "string" }, "markdown": { "type": "string" }, "word_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "char_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "readability_applied": { "type": "boolean" }, "links": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "text": { "type": "string" }, "rel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_internal": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "href", "text", "rel", "is_internal" ], "additionalProperties": false } }, { "type": "null" } ] }, "link_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fetched_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "requested_url", "source_url", "final_url", "content_type", "charset", "http_status", "title", "byline", "excerpt", "site_name", "lang", "lang_source", "text", "markdown", "word_count", "char_count", "truncated", "readability_applied", "links", "link_count", "fetched_at" ], "additionalProperties": false }, "example": { "requested_url": "https://grist.tools/samples/web/render-article.html", "source_url": "https://grist.tools/samples/web/render-article.html", "final_url": "https://grist.tools/samples/web/render-article.html", "content_type": "text/html", "charset": "utf-8", "http_status": 200, "title": "Measuring Rainfall with a Simple Gauge", "byline": "Sample Author", "excerpt": "A short guide to reading a cylinder rain gauge at the same hour every day.", "site_name": "Grist Samples", "lang": "en", "lang_source": "html_lang", "text": "A cylinder rain gauge is a clear tube with a scale printed on the side. Rain falls through a funnel at the top and collects in the tube, where the water level shows how much fell since the last reading.\nThe most useful habit is consistency. Read the gauge at the same hour every day, ideally in the morning, so that each number covers one full day.\nPlacing the gauge\nPut the gauge in an open spot, away from walls, trees and roofs. A good rule is to keep it at least twice as far from any obstacle as the obstacle is tall.\nMount it level, so the scale reads true.\nKeep the funnel clear of leaves and insects.\nEmpty the tube right after each reading.\nReading the scale\nBend down until your eye is level with the water. The surface curves slightly where it meets the tube; read the number at the bottom of that curve.\nWrite the reading in a notebook with the date and time. A printable schedule helps when several people share the job.", "markdown": "A cylinder rain gauge is a clear tube with a scale printed on the side. Rain falls through a funnel at the top and collects in the tube, where the water level shows how much fell since the last reading.\n\nThe most useful habit is consistency. Read the gauge at the same hour every day, ideally in the morning, so that each number covers one full day.\n\n## Placing the gauge\n\nPut the gauge in an open spot, away from walls, trees and roofs. A good rule is to keep it at least twice as far from any obstacle as the obstacle is tall.\n\n- Mount it level, so the scale reads true.\n- Keep the funnel clear of leaves and insects.\n- Empty the tube right after each reading.\n\n## Reading the scale\n\nBend down until your eye is level with the water. The surface curves slightly where it meets the tube; read the number at the bottom of that curve.\n\nWrite the reading in a notebook with the date and time. A [printable schedule](https://grist.tools/samples/web/render-print.html) helps when several people share the job.", "word_count": 178, "char_count": 933, "truncated": false, "readability_applied": true, "links": [ { "href": "https://grist.tools/samples/web/render-print.html", "text": "printable schedule", "rel": null, "is_internal": true } ], "link_count": 1, "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/html-clean-text", "description": "Fetches a web page and returns the article as clean text and markdown, with its declared metadata.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 33, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 33, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/html-clean-text/schema": { "get": { "operationId": "html-clean-text-schema", "summary": "Schema, price and examples for html-clean-text. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/html-to-pdf": { "post": { "operationId": "html-to-pdf", "summary": "Renders a web page or an inline HTML string to a PDF, returned base64-encoded with its page count.", "description": "It needs a headless browser AND a hardened fetch: an agent that renders a URL itself walks the browser straight past every SSRF control, and carrying a Chromium is not something an agent does per call.\n\nDeclared timeout: 12000ms. Response size cap: 5242880 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http(s) URL of an HTML or XHTML page to fetch and render, up to 2048 characters; redirects are followed, the body is capped at 5 MB, and exactly one of url or html is required.", "type": "string", "maxLength": 2048, "format": "uri" }, "html": { "type": "string", "minLength": 1, "maxLength": 262144, "description": "Self-contained HTML. Inline PNG data images are supported; external images, stylesheets and fonts are blocked. JavaScript is disabled." }, "format": { "default": "A4", "description": "Paper size of every page, A4 by default.", "type": "string", "enum": [ "A3", "A4", "A5", "Letter", "Legal", "Tabloid" ] }, "landscape": { "default": false, "description": "Print in landscape orientation instead of portrait.", "type": "boolean" } }, "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/render-print.html", "format": "A4", "landscape": false } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "A3", "A4", "A5", "Letter", "Legal", "Tabloid" ] }, "landscape": { "type": "boolean" }, "pdf_base64": { "type": "string" }, "rendered_at": { "type": "string" } }, "required": [ "source_url", "pages", "bytes", "format", "landscape", "pdf_base64", "rendered_at" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/web/render-print.html", "pages": 1, "bytes": 38404, "format": "A4", "landscape": false, "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUK...", "rendered_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/html-to-pdf", "description": "Renders a web page or an inline HTML string to a PDF, returned base64-encoded with its page count.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 33, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 33, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/html-to-pdf/schema": { "get": { "operationId": "html-to-pdf-schema", "summary": "Schema, price and examples for html-to-pdf. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/http-headers": { "post": { "operationId": "http-headers", "summary": "Returns the response headers, final status, redirect chain and a security-header grade for a URL, without downloading the body.", "description": "It needs a hardened HTTP client -- an agent that fetches the URL itself can walk a redirect into a private address -- and the security grade is a deterministic, documented rubric it would otherwise have to build and maintain.\n\nDeclared timeout: 8000ms. Response size cap: 65536 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL to request, up to 2048 characters; up to five redirects are followed and every hop goes through the SSRF guard." }, "method": { "default": "HEAD", "description": "HTTP method for the request, HEAD by default; GET is for servers that mishandle HEAD, and its body is still never read.", "type": "string", "enum": [ "HEAD", "GET" ] } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com/", "method": "HEAD" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "redirect_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "security": { "type": "object", "properties": { "hsts": { "type": "object", "properties": { "present": { "type": "boolean" }, "max_age": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "include_subdomains": { "type": "boolean" }, "preload": { "type": "boolean" } }, "required": [ "present", "max_age", "include_subdomains", "preload" ], "additionalProperties": false }, "csp_present": { "type": "boolean" }, "x_content_type_options": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "x_frame_options": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "permissions_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_origin_opener_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_origin_resource_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hsts", "csp_present", "x_content_type_options", "x_frame_options", "referrer_policy", "permissions_policy", "cross_origin_opener_policy", "cross_origin_resource_policy" ], "additionalProperties": false }, "security_grade": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F" ] }, "missing_security_headers": { "type": "array", "items": { "type": "string", "enum": [ "strict-transport-security", "content-security-policy", "x-content-type-options", "x-frame-options", "referrer-policy", "permissions-policy", "cross-origin-opener-policy", "cross-origin-resource-policy" ] } }, "fetched_at": { "type": "string" } }, "required": [ "url", "source_url", "final_url", "redirect_count", "http_status", "headers", "security", "security_grade", "missing_security_headers", "fetched_at" ], "additionalProperties": false }, "example": { "url": "https://example.com/", "source_url": "https://example.com/", "final_url": "https://example.com/", "redirect_count": 0, "http_status": 200, "headers": { "content-security-policy": "default-src 'self'", "content-type": "text/html; charset=utf-8", "cross-origin-opener-policy": "same-origin", "cross-origin-resource-policy": "same-origin", "permissions-policy": "geolocation=()", "referrer-policy": "strict-origin-when-cross-origin", "strict-transport-security": "max-age=63072000; includeSubDomains; preload", "x-content-type-options": "nosniff", "x-frame-options": "DENY" }, "security": { "hsts": { "present": true, "max_age": 63072000, "include_subdomains": true, "preload": true }, "csp_present": true, "x_content_type_options": "nosniff", "x_frame_options": "DENY", "referrer_policy": "strict-origin-when-cross-origin", "permissions_policy": "geolocation=()", "cross_origin_opener_policy": "same-origin", "cross_origin_resource_policy": "same-origin" }, "security_grade": "A", "missing_security_headers": [], "fetched_at": "2026-08-26T18:00:00.000Z" }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/http-headers", "description": "Returns the response headers, final status, redirect chain and a security-header grade for a URL, without downloading the body.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/http-headers/schema": { "get": { "operationId": "http-headers-schema", "summary": "Schema, price and examples for http-headers. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/image-compress": { "post": { "operationId": "image-compress", "summary": "Re-encodes an image in its own format at a lower quality to shrink the file, keeping its dimensions.", "description": "Compressing safely needs a real codec and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and the output must be byte-reproducible, which an ad-hoc re-encode is not.\n\nDeclared timeout: 60000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of a JPEG, PNG, WebP or GIF image, up to 2048 characters; redirects are followed and the output keeps the source format and dimensions." }, "quality": { "default": 75, "description": "Encoder quality from 1 to 100, lower gives a smaller file; drives JPEG and WebP re-compression and PNG palette quantisation, and is ignored for GIF.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/compress-scene.jpg", "quality": 60 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "format": { "type": "string", "enum": [ "jpeg", "png", "webp", "gif" ] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "saved_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ratio": { "type": "number" }, "image_base64": { "type": "string" } }, "required": [ "source_url", "format", "width", "height", "source_bytes", "bytes", "saved_bytes", "ratio", "image_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/compress-scene.jpg", "format": "jpeg", "width": 96, "height": 64, "source_bytes": 1836, "bytes": 758, "saved_bytes": 1078, "ratio": 0.4129, "image_base64": "/9j/2wBDAA0JCgsKCA0LCgsODg0PEyAVExISEyccHhcgLikxMC4pLSwzOko+MzZG..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/image-compress", "description": "Re-encodes an image in its own format at a lower quality to shrink the file, keeping its dimensions.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/image-compress/schema": { "get": { "operationId": "image-compress-schema", "summary": "Schema, price and examples for image-compress. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/image-convert": { "post": { "operationId": "image-convert", "summary": "Transcodes an image to PNG, JPEG or WebP at a chosen quality, returned base64-encoded.", "description": "Transcoding safely needs a real codec and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and the output must be byte-reproducible, which an ad-hoc re-encode is not.\n\nDeclared timeout: 60000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the source image, up to 2048 characters; redirects are followed and the source format is detected from the bytes." }, "format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "description": "Target format to encode to, png, jpeg or webp; the pixel dimensions are kept and metadata is dropped." }, "quality": { "default": 80, "description": "Encoder quality from 1 to 100 for jpeg and webp output; ignored for png, which is always lossless.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "url", "format" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/convert-gradient.png", "format": "webp", "quality": 80 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "source_format": { "type": "string", "enum": [ "jpeg", "png", "gif", "webp", "tiff", "avif", "heic", "svg" ] }, "format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "mime_type": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "image_base64": { "type": "string" } }, "required": [ "source_url", "source_format", "format", "mime_type", "width", "height", "bytes", "image_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/convert-gradient.png", "source_format": "png", "format": "webp", "mime_type": "image/webp", "width": 32, "height": 32, "bytes": 156, "image_base64": "UklGRpQAAABXRUJQVlA4IIgAAAAQBQCdASogACAALk02m02hJCQkBABMS2AE6ZiX..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/image-convert", "description": "Transcodes an image to PNG, JPEG or WebP at a chosen quality, returned base64-encoded.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/image-convert/schema": { "get": { "operationId": "image-convert-schema", "summary": "Schema, price and examples for image-convert. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/image-metadata": { "post": { "operationId": "image-metadata", "summary": "Reads an image's EXIF/ICC/IPTC/XMP metadata and can return a copy with all metadata stripped.", "description": "Reading and stripping image metadata safely needs a real decoder and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and a strip must be byte-reproducible, which an ad-hoc re-encode is not.\n\nDeclared timeout: 30000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the image to inspect, up to 2048 characters; redirects are followed and the format is detected from the bytes." }, "strip": { "default": false, "description": "When true, also return a same-format copy re-encoded with every metadata block removed (lossy sources at quality 80); allowed for JPEG, PNG, WebP, TIFF and GIF.", "type": "boolean" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/metadata-exif.jpg", "strip": true } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "format": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "channels": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "space": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "depth": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_alpha": { "type": "boolean" }, "has_profile": { "type": "boolean" }, "orientation": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "density": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "is_progressive": { "type": "boolean" }, "metadata": { "type": "object", "properties": { "exif_bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "icc_bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "iptc_bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "xmp_bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "exif_bytes", "icc_bytes", "iptc_bytes", "xmp_bytes" ], "additionalProperties": false }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stripped": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": [ "jpeg", "png", "webp", "tiff", "gif" ] }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "image_base64": { "type": "string" } }, "required": [ "format", "bytes", "image_base64" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "source_url", "format", "width", "height", "channels", "space", "depth", "has_alpha", "has_profile", "orientation", "density", "is_progressive", "metadata", "bytes", "stripped" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/metadata-exif.jpg", "format": "jpeg", "width": 32, "height": 24, "channels": 3, "space": "srgb", "depth": "uchar", "has_alpha": false, "has_profile": true, "orientation": 6, "density": 72, "is_progressive": false, "metadata": { "exif_bytes": 186, "icc_bytes": 480, "iptc_bytes": null, "xmp_bytes": null }, "bytes": 1024, "stripped": { "format": "jpeg", "bytes": 333, "image_base64": "/9j/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsj..." } }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/image-metadata", "description": "Reads an image's EXIF/ICC/IPTC/XMP metadata and can return a copy with all metadata stripped.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 51, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 51, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/image-metadata/schema": { "get": { "operationId": "image-metadata-schema", "summary": "Schema, price and examples for image-metadata. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/image-probe": { "post": { "operationId": "image-probe", "summary": "Reports an image's format and pixel dimensions from its header, without decoding the pixels.", "description": "Reading an image header safely needs a real decoder and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an image library per call is not something an agent does inline.\n\nDeclared timeout: 20000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the image, up to 2048 characters; redirects are followed, the bytes must be jpeg, png, gif, webp, tiff, avif, heic or svg by signature, and only the header is parsed." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/tiles-64x40.png" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "format": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "channels": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "space": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_alpha": { "type": "boolean" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "source_url", "format", "width", "height", "channels", "space", "has_alpha", "bytes" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/tiles-64x40.png", "format": "png", "width": 64, "height": 40, "channels": 4, "space": "srgb", "has_alpha": true, "bytes": 10348 }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/image-probe", "description": "Reports an image's format and pixel dimensions from its header, without decoding the pixels.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 41, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 41, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/image-probe/schema": { "get": { "operationId": "image-probe-schema", "summary": "Schema, price and examples for image-probe. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/image-resize": { "post": { "operationId": "image-resize", "summary": "Resizes an image to a target width/height under a chosen fit, returned base64-encoded.", "description": "Resizing safely needs a real decoder and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and the output must be byte-reproducible, which an ad-hoc resample is not.\n\nDeclared timeout: 60000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the source image, up to 2048 characters; redirects are followed, the bytes must be jpeg, png, gif, webp, tiff, avif, heic or svg by signature, and at most 40 megapixels." }, "width": { "description": "Target width in pixels, 1 to 20000; at least one of width or height is required, and a missing side follows the aspect ratio (except under fill).", "type": "integer", "minimum": 1, "maximum": 20000 }, "height": { "description": "Target height in pixels, 1 to 20000; at least one of width or height is required, and a missing side follows the aspect ratio (except under fill).", "type": "integer", "minimum": 1, "maximum": 20000 }, "fit": { "default": "inside", "description": "How the image fills the target box, as in sharp: inside fits within keeping the ratio (default), cover crops from the centre, contain pads to the full box, fill stretches, outside covers the box without cropping.", "type": "string", "enum": [ "cover", "contain", "fill", "inside", "outside" ] }, "format": { "description": "Output format; when omitted the source format is kept if it is png, jpeg or webp, otherwise the output is PNG.", "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "quality": { "default": 80, "description": "Encoder quality from 1 to 100, default 80, used by the lossy jpeg and webp encoders and ignored for png.", "type": "integer", "minimum": 1, "maximum": 100 }, "allow_enlarge": { "default": false, "description": "When true the image may be scaled up past its native size; default false keeps each side at most its source size.", "type": "boolean" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/tiles-64x40.png", "width": 32, "fit": "inside" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "source_format": { "type": "string", "enum": [ "jpeg", "png", "gif", "webp", "tiff", "avif", "heic", "svg" ] }, "source_width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source_height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "mime_type": { "type": "string" }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill", "inside", "outside" ] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "image_base64": { "type": "string" } }, "required": [ "source_url", "source_format", "source_width", "source_height", "format", "mime_type", "fit", "width", "height", "bytes", "image_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/tiles-64x40.png", "source_format": "png", "source_width": 64, "source_height": 40, "format": "png", "mime_type": "image/png", "fit": "inside", "width": 32, "height": 20, "bytes": 779, "image_base64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAUCAYAAADskT9PAAAACXBIWXMAAAsSAAAL..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/image-resize", "description": "Resizes an image to a target width/height under a chosen fit, returned base64-encoded.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/image-resize/schema": { "get": { "operationId": "image-resize-schema", "summary": "Schema, price and examples for image-resize. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/ip-info": { "post": { "operationId": "ip-info", "summary": "Reverse DNS (PTR) and network ownership for an IP address or a domain.", "description": "A reverse lookup needs the network, and the ownership data is a versioned dataset an agent does not carry. It is what you run over a list of addresses from a log.\n\nDeclared timeout: 5000ms. Response size cap: 2097152 bytes.", "tags": [ "domain" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ip": { "description": "A public IPv4 or IPv6 address to look up; private, loopback and reserved addresses are refused. Give exactly one of ip or domain.", "type": "string", "minLength": 1 }, "domain": { "description": "A public fully qualified domain name, resolved to its first address, which is then looked up; the call is refused if the name resolves to any private address. Give exactly one of ip or domain.", "type": "string", "minLength": 1 } }, "additionalProperties": false }, "example": { "ip": "8.8.8.8" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string" }, "ip": { "type": "string" }, "ptr": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "asn": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "asn_org": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "query", "ip", "ptr", "asn", "asn_org", "country" ], "additionalProperties": false }, "example": { "query": "8.8.8.8", "ip": "8.8.8.8", "ptr": "dns.google", "asn": 15169, "asn_org": "GOOGLE", "country": "US" }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/ip-info", "description": "Reverse DNS (PTR) and network ownership for an IP address or a domain.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "domain" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 26, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 26, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/ip-info/schema": { "get": { "operationId": "ip-info-schema", "summary": "Schema, price and examples for ip-info. Always free.", "tags": [ "domain" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/json-to-csv": { "post": { "operationId": "json-to-csv", "summary": "Renders JSON objects as raw CSV with no spreadsheet formula protection; columns are inferred or given, nested values are JSON-encoded.", "description": "Correct CSV output is quoting and escaping to RFC-4180, not a join on commas, and the column set has to be reconciled across rows with different keys, fiddly enough that paying for it beats hand-rolling it per call. Headers and string values preserve formula prefixes (=, +, -, @), tabs and carriage returns without added apostrophes or trimming. CSV quoting escapes delimiters, quotes and newlines but does not neutralize spreadsheet formulas. Use spreadsheet-specific import controls for untrusted data. CRLF separates records.\n\nDeclared timeout: 30000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of a UTF-8 JSON document (a leading BOM is allowed) that is an array of objects or a single object, up to 2048 characters; redirects are followed." }, "columns": { "description": "Selects columns in exactly the supplied order; a missing key produces an empty field, except an absent __proto__ column renders {}. When omitted, visits only rows retained by max_rows, in input order, appending each unseen key once. Within each row, JavaScript enumerates canonical array-index keys (0 through 4294967294) numerically ascending, then other string keys in insertion order. Names such as 01, -1 and 4294967295 are ordinary string keys. New keys from later rows are appended, not globally sorted; textual JSON key order is not preserved for array-index keys.", "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "max_rows": { "default": 10000, "description": "Maximum rows rendered, 1 to 100000, default 10000; later rows are dropped and truncated is set, and inferred columns come only from the kept rows.", "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/garden-harvest.json" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "csv": { "type": "string" }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" } }, "required": [ "source_url", "columns", "csv", "row_count", "truncated" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/garden-harvest.json", "columns": [ "week", "crop", "kg", "plots", "note" ], "csv": "week,crop,kg,plots,note\r\n1,radish,2.5,\"[\"\"A1\"\",\"\"B2\"\"]\",\r\n1,lettuce,4,,\"first cut, outer leaves only\"\r\n2,peas,3.25,\"[\"\"A2\"\"]\",", "row_count": 3, "truncated": false }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/json-to-csv", "description": "Renders JSON objects as raw CSV with no spreadsheet formula protection; columns are inferred or given, nested values are JSON-encoded.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 51, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 51, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/json-to-csv/schema": { "get": { "operationId": "json-to-csv-schema", "summary": "Schema, price and examples for json-to-csv. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/link-extract": { "post": { "operationId": "link-extract", "summary": "Fetches a web page and returns every link on it, resolved to absolute, each tagged with its rel, a nofollow flag and whether it stays on the same site.", "description": "It needs the network and a real DOM: resolving relative and protocol-relative hrefs against a possible , classifying internal versus external, and reading rel/nofollow correctly is fiddly to get right, and feeding raw HTML to a model to do it costs far more in tokens than this call costs.\n\nDeclared timeout: 8000ms. Response size cap: 5242880 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the HTML or XHTML page to read, up to 2048 characters; up to 5 redirects are followed and links resolve against the final URL or its ." }, "internal_only": { "default": false, "description": "When true, return only links whose host equals the host of the fetched page (the final redirect hop); the totals then count only those links.", "type": "boolean" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/index.html", "internal_only": false } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "base_url": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "text": { "type": "string" }, "rel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nofollow": { "type": "boolean" }, "internal": { "type": "boolean" } }, "required": [ "href", "text", "rel", "nofollow", "internal" ], "additionalProperties": false } }, "links_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "links_returned": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "links_truncated": { "type": "boolean" }, "fetched_at": { "type": "string" } }, "required": [ "url", "source_url", "final_url", "http_status", "base_url", "links", "links_total", "links_returned", "links_truncated", "fetched_at" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/index.html", "source_url": "https://grist.tools/samples/web/fieldnotes/index.html", "final_url": "https://grist.tools/samples/web/fieldnotes/index.html", "http_status": 200, "base_url": "https://grist.tools/samples/web/fieldnotes/index.html", "links": [ { "href": "https://grist.tools/samples/web/fieldnotes/index.html", "text": "Home", "rel": null, "nofollow": false, "internal": true }, { "href": "https://grist.tools/samples/web/fieldnotes/about.html", "text": "About", "rel": null, "nofollow": false, "internal": true }, { "href": "https://grist.tools/samples/web/fieldnotes/feed.xml", "text": "Subscribe", "rel": "alternate", "nofollow": false, "internal": true }, { "href": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "text": "The first frost of the season", "rel": null, "nofollow": false, "internal": true }, { "href": "https://grist.tools/samples/web/fieldnotes/notes/rain-gauge.html", "text": "Reading a rain gauge by hand", "rel": null, "nofollow": false, "internal": true }, { "href": "https://example.org/glossary", "text": "an outside glossary", "rel": "nofollow noopener", "nofollow": true, "internal": false }, { "href": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml", "text": "Sitemap", "rel": null, "nofollow": false, "internal": true } ], "links_total": 7, "links_returned": 7, "links_truncated": false, "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/link-extract", "description": "Fetches a web page and returns every link on it, resolved to absolute, each tagged with its rel, a nofollow flag and whether it stays on the same site.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/link-extract/schema": { "get": { "operationId": "link-extract-schema", "summary": "Schema, price and examples for link-extract. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/markdown-to-pdf": { "post": { "operationId": "markdown-to-pdf", "summary": "Renders a Markdown document to a PDF, returned base64-encoded with its page count.", "description": "Turning styled Markdown into a paginated PDF needs a real layout engine AND a hardened fetch: an agent that renders a URL itself walks the browser straight past every SSRF control, and carrying a Chromium is not something an agent does per call.\n\nDeclared timeout: 12000ms. Response size cap: 2097152 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http(s) URL of a UTF-8 Markdown text file to fetch and render, up to 2048 characters; redirects are followed, the body is capped at 2 MB, and exactly one of url or markdown is required.", "type": "string", "maxLength": 2048, "format": "uri" }, "markdown": { "type": "string", "minLength": 1, "maxLength": 262144, "description": "Markdown with escaped raw HTML. PNG/JPEG/GIF/WebP data-image syntax is accepted; SVG data images and external image loading are blocked." }, "format": { "default": "A4", "description": "Paper size of every page, A4 by default.", "type": "string", "enum": [ "A3", "A4", "A5", "Letter", "Legal", "Tabloid" ] }, "landscape": { "default": false, "description": "Print in landscape orientation instead of portrait.", "type": "boolean" } }, "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/render-notes.md", "format": "A4", "landscape": false } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "A3", "A4", "A5", "Letter", "Legal", "Tabloid" ] }, "landscape": { "type": "boolean" }, "pdf_base64": { "type": "string" }, "rendered_at": { "type": "string" } }, "required": [ "source_url", "pages", "bytes", "format", "landscape", "pdf_base64", "rendered_at" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/render-notes.md", "pages": 1, "bytes": 69844, "format": "A4", "landscape": false, "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjkgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUK...", "rendered_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/markdown-to-pdf", "description": "Renders a Markdown document to a PDF, returned base64-encoded with its page count.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 33, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 33, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/markdown-to-pdf/schema": { "get": { "operationId": "markdown-to-pdf-schema", "summary": "Schema, price and examples for markdown-to-pdf. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/media-probe": { "post": { "operationId": "media-probe", "summary": "Reads a media file's container, duration, bit rate and per-stream codec/resolution without decoding it.", "description": "Probing a media file needs the ffprobe binary AND a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an ffmpeg per call is not something an agent does inline.\n\nDeclared timeout: 30000ms. Response size cap: 104857600 bytes.", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the audio or video file, up to 2048 characters, in a recognised container (MP4/MOV, Matroska/WebM, AVI, Ogg, WAV, FLAC, AIFF or MP3); ffprobe reads its container index and nothing is decoded." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/probe-clip.mov" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "container": { "type": "string", "enum": [ "mp4", "matroska", "wav", "avi", "mp3", "ogg", "flac", "aiff" ] }, "format_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bit_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "streams": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "type": { "type": "string" }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codec_long_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "frame_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sample_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "channels": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "index", "type", "codec", "codec_long_name", "width", "height", "frame_rate", "sample_rate", "channels" ], "additionalProperties": false } } }, "required": [ "source_url", "bytes", "container", "format_name", "duration_seconds", "bit_rate", "streams" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/probe-clip.mov", "bytes": 33850, "container": "mp4", "format_name": "mov,mp4,m4a,3gp,3g2,mj2", "duration_seconds": 2, "bit_rate": 135400, "streams": [ { "index": 0, "type": "video", "codec": "png", "codec_long_name": "PNG (Portable Network Graphics) image", "width": 64, "height": 36, "frame_rate": 2, "sample_rate": null, "channels": null }, { "index": 1, "type": "audio", "codec": "pcm_s16le", "codec_long_name": "PCM signed 16-bit little-endian", "width": null, "height": null, "frame_rate": null, "sample_rate": 8000, "channels": 1 } ] }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/media-probe", "description": "Reads a media file's container, duration, bit rate and per-stream codec/resolution without decoding it.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 51, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 51, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/media-probe/schema": { "get": { "operationId": "media-probe-schema", "summary": "Schema, price and examples for media-probe. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/ocr-image-to-text": { "post": { "operationId": "ocr-image-to-text", "summary": "Reads the text out of an image (scan, screenshot, photo) with Tesseract, returned with a mean confidence.", "description": "OCR needs a real engine and its language data AND a hardened fetch: an agent that pulls the image URL itself walks past every SSRF control, and carrying a WASM Tesseract plus a language model is not something an agent does per call.\n\nDeclared timeout: 45000ms. Response size cap: 10485760 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the image, up to 2048 characters and 10 MB; redirects are followed, the bytes must be PNG, JPEG, TIFF, WebP or GIF by signature, and at most 40 megapixels." }, "lang": { "default": "eng", "description": "Tesseract language model to read the text with; only languages whose data ships with the service are accepted, today eng (the default).", "type": "string", "enum": [ "eng" ] } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/ocr-scan.png", "lang": "eng" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "lang": { "type": "string", "enum": [ "eng" ] }, "image_format": { "type": "string", "enum": [ "png", "jpeg", "tiff", "webp", "gif" ] }, "text": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "source_url", "lang", "image_format", "text", "confidence" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/ocr-scan.png", "lang": "eng", "image_format": "png", "text": "SAMPLE SCAN FOR OCR\nSECOND LINE 2026\n", "confidence": 86 }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/ocr-image-to-text", "description": "Reads the text out of an image (scan, screenshot, photo) with Tesseract, returned with a mean confidence.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 66, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 66, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/ocr-image-to-text/schema": { "get": { "operationId": "ocr-image-to-text-schema", "summary": "Schema, price and examples for ocr-image-to-text. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/page-metadata": { "post": { "operationId": "page-metadata", "summary": "Fetches a page and returns its metadata -- title, description, canonical, language, hreflang, favicon, Open Graph and Twitter cards -- with every URL resolved to absolute.", "description": "It needs the network and three libraries an agent scraping many pages does not carry: an HTML parser, a legacy charset decoder, and a resolver that honours and the final redirect hop. Feeding raw HTML to a model to pull these fields costs far more in tokens than this call.\n\nDeclared timeout: 8000ms. Response size cap: 3145728 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of an HTML or XHTML page, up to 2048 characters; up to 5 redirects are followed and relative head URLs resolve against the final hop or its ." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/render-article.html" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hreflang": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "href" ], "additionalProperties": false } }, "hreflang_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hreflang_truncated": { "type": "boolean" }, "favicon": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "charset": { "type": "string" }, "opengraph": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "site_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "description", "image", "type", "site_name", "url" ], "additionalProperties": false }, "twitter": { "type": "object", "properties": { "card": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "card", "title", "description", "image" ], "additionalProperties": false }, "robots_meta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fetched_at": { "type": "string" } }, "required": [ "url", "source_url", "final_url", "http_status", "title", "description", "canonical", "lang", "hreflang", "hreflang_total", "hreflang_truncated", "favicon", "charset", "opengraph", "twitter", "robots_meta", "fetched_at" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/render-article.html", "source_url": "https://grist.tools/samples/web/render-article.html", "final_url": "https://grist.tools/samples/web/render-article.html", "http_status": 200, "title": "Measuring Rainfall with a Simple Gauge", "description": "A short guide to reading a cylinder rain gauge at the same hour every day.", "canonical": "https://grist.tools/samples/web/render-article.html", "lang": "en", "hreflang": [ { "lang": "en", "href": "https://grist.tools/samples/web/render-article.html" }, { "lang": "x-default", "href": "https://grist.tools/samples/web/render-article.html" } ], "hreflang_total": 2, "hreflang_truncated": false, "favicon": "https://grist.tools/favicon.png", "charset": "utf-8", "opengraph": { "title": "Measuring Rainfall with a Simple Gauge", "description": "Read the gauge at eye level, at the same hour, and write the number down.", "image": "https://grist.tools/og.png", "type": "article", "site_name": "Grist Samples", "url": "https://grist.tools/samples/web/render-article.html" }, "twitter": { "card": "summary_large_image", "title": "Measuring Rainfall with a Simple Gauge", "description": "Read the gauge at eye level, at the same hour, and write the number down.", "image": "https://grist.tools/og.png" }, "robots_meta": "index, follow", "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/page-metadata", "description": "Fetches a page and returns its metadata -- title, description, canonical, language, hreflang, favicon, Open Graph and Twitter cards -- with every URL resolved to absolute.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/page-metadata/schema": { "get": { "operationId": "page-metadata-schema", "summary": "Schema, price and examples for page-metadata. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/pdf-merge": { "post": { "operationId": "pdf-merge", "summary": "Concatenates 2–8 source PDFs, in order, into one PDF returned base64-encoded. Maximum output PDF size: 25 MiB before base64 encoding.", "description": "Merging PDFs needs a real PDF library and a hardened fetch over several URLs at once: an agent doing it inline walks every one past the SSRF controls, and the joined output must be byte-reproducible.\n\nDeclared timeout: 45000ms. Response size cap: 8388608 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "urls": { "minItems": 2, "maxItems": 8, "type": "array", "items": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of one source PDF, up to 2048 characters; redirects are followed and the body must start with the %PDF- signature." }, "description": "The source PDFs, 2 to 8 URLs fetched one at a time and concatenated in this order; each is read up to 8 MiB and an encrypted source is refused." } }, "required": [ "urls" ], "additionalProperties": false }, "example": { "urls": [ "https://grist.tools/samples/documents/merge-intro.pdf", "https://grist.tools/samples/documents/merge-appendix.pdf" ] } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url", "pages" ], "additionalProperties": false } }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pdf_base64": { "type": "string" } }, "required": [ "sources", "pages", "bytes", "pdf_base64" ], "additionalProperties": false }, "example": { "sources": [ { "url": "https://grist.tools/samples/documents/merge-intro.pdf", "pages": 1 }, { "url": "https://grist.tools/samples/documents/merge-appendix.pdf", "pages": 2 } ], "pages": 3, "bytes": 1474, "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjQgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUK..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/pdf-merge", "description": "Concatenates 2–8 source PDFs, in order, into one PDF returned base64-encoded. Maximum output PDF size: 25 MiB before base64 encoding.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 66, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 66, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/pdf-merge/schema": { "get": { "operationId": "pdf-merge-schema", "summary": "Schema, price and examples for pdf-merge. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/pdf-metadata": { "post": { "operationId": "pdf-metadata", "summary": "Reads a PDF's page count, document-info fields, version and encryption flag without rendering it.", "description": "Reading a PDF trailer needs a real PDF parser and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying a PDF library per call is not something an agent does inline.\n\nDeclared timeout: 25000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the PDF, up to 2048 characters; redirects are followed, the body must start with %PDF-, and an encrypted file is still described without being decrypted." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/metadata-brochure.pdf" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "encrypted": { "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creator": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "producer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creation_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modification_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source_url", "bytes", "version", "pages", "encrypted", "title", "author", "subject", "keywords", "creator", "producer", "creation_date", "modification_date" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/metadata-brochure.pdf", "bytes": 1010, "version": "1.7", "pages": 1, "encrypted": false, "title": "Sample Brochure", "author": "Grist Samples", "subject": "Public test document", "keywords": "sample metadata test", "creator": "grist.tools", "producer": "grist.tools", "creation_date": "2000-01-01T00:00:00.000Z", "modification_date": "2000-01-01T00:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/pdf-metadata", "description": "Reads a PDF's page count, document-info fields, version and encryption flag without rendering it.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 46, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 46, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/pdf-metadata/schema": { "get": { "operationId": "pdf-metadata-schema", "summary": "Schema, price and examples for pdf-metadata. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/pdf-split": { "post": { "operationId": "pdf-split", "summary": "Extracts a 1-indexed page selection (e.g. \"1,3-4\") from a PDF into one new PDF, returned base64-encoded. Maximum output PDF size: 25 MiB before base64 encoding.", "description": "Splitting a PDF needs a real PDF library and a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and the output must be byte-reproducible, which a naive save is not.\n\nDeclared timeout: 30000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the source PDF, up to 2048 characters; redirects are followed, the body must start with %PDF-, and an encrypted file is refused." }, "ranges": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Comma-separated 1-indexed pages or inclusive ranges such as \"1,3-4\", up to 512 characters; pages are emitted in the order written, repeats are kept, and a descending range or a page past the end is an error." } }, "required": [ "url", "ranges" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/split-five-pages.pdf", "ranges": "1,3-4" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "source_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pdf_base64": { "type": "string" } }, "required": [ "source_url", "source_pages", "pages", "bytes", "pdf_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/split-five-pages.pdf", "source_pages": 5, "pages": 3, "bytes": 1392, "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjQgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUK..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/pdf-split", "description": "Extracts a 1-indexed page selection (e.g. \"1,3-4\") from a PDF into one new PDF, returned base64-encoded. Maximum output PDF size: 25 MiB before base64 encoding.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 51, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 51, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/pdf-split/schema": { "get": { "operationId": "pdf-split-schema", "summary": "Schema, price and examples for pdf-split. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/pdf-to-markdown": { "post": { "operationId": "pdf-to-markdown", "summary": "Converts a PDF to Markdown, inferring headings from font size (best-effort, not layout-perfect; no OCR).", "description": "A PDF has no heading structure, only sized glyphs; recovering Markdown needs a real PDF engine plus a hardened fetch, which an agent cannot do inline without walking past the SSRF controls. Offline, best-effort text-layer extraction; no OCR. No external CMap or standard-font data is configured or fetched. PDFs with self-contained character mappings can yield text, including CJK; documents requiring unavailable predefined CMaps can return empty or partial text without an error. Embedded ToUnicode alone does not guarantee extraction when the encoding still needs an external CMap. Missing standard-font data does not necessarily prevent extraction. A successful response does not certify complete text; truncated reports only the max_pages limit.\n\nDeclared timeout: 40000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the PDF, up to 2048 characters; redirects are followed and the body must start with the %PDF- signature." }, "max_pages": { "default": 100, "description": "How many leading pages to convert, 1 to 1000; a shorter document is not an error, and a longer one is cut and reported as truncated.", "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "url" ], "additionalProperties": false, "description": "Offline, best-effort text-layer extraction; no OCR. No external CMap or standard-font data is configured or fetched. PDFs with self-contained character mappings can yield text, including CJK; documents requiring unavailable predefined CMaps can return empty or partial text without an error. Embedded ToUnicode alone does not guarantee extraction when the encoding still needs an external CMap. Missing standard-font data does not necessarily prevent extraction. A successful response does not certify complete text; truncated reports only the max_pages limit. PDF text extraction accepts at most 1000000 raw and separately 1000000 output UTF-16 code units, 10000 items per page and 100000 items across selected pages. Exceeding a limit rejects the call with 413 too_large. truncated refers only to max_pages." }, "example": { "url": "https://grist.tools/samples/documents/markdown-guide.pdf", "max_pages": 100 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extracted_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "markdown": { "type": "string" } }, "required": [ "source_url", "total_pages", "extracted_pages", "truncated", "chars", "markdown" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/markdown-guide.pdf", "total_pages": 1, "extracted_pages": 1, "truncated": false, "chars": 249, "markdown": "# Field Notes\n\n## A short guide in three parts\n\nThis sample shows how headings are inferred.\n\nLarger text becomes a heading, body text stays plain.\n\n### Second section\n\nEach line of the page becomes its own block.\n\nThe document ends after this line." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/pdf-to-markdown", "description": "Converts a PDF to Markdown, inferring headings from font size (best-effort, not layout-perfect; no OCR).", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 61, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 61, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/pdf-to-markdown/schema": { "get": { "operationId": "pdf-to-markdown-schema", "summary": "Schema, price and examples for pdf-to-markdown. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/pdf-to-text": { "post": { "operationId": "pdf-to-text", "summary": "Extracts the text layer of a PDF, page by page, in reading order (no OCR).", "description": "Pulling a PDF text layer needs a real PDF engine and a hardened fetch: an agent that fetches the URL itself walks past every SSRF control, and carrying pdfjs per call is not something an agent does inline. Offline, best-effort text-layer extraction; no OCR. No external CMap or standard-font data is configured or fetched. PDFs with self-contained character mappings can yield text, including CJK; documents requiring unavailable predefined CMaps can return empty or partial text without an error. Embedded ToUnicode alone does not guarantee extraction when the encoding still needs an external CMap. Missing standard-font data does not necessarily prevent extraction. A successful response does not certify complete text; truncated reports only the max_pages limit.\n\nDeclared timeout: 40000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the PDF, up to 2048 characters; redirects are followed and the body must start with the %PDF- signature." }, "max_pages": { "default": 100, "description": "How many leading pages to extract, 1 to 1000; a shorter document is not an error, and a longer one is cut and reported as truncated.", "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "url" ], "additionalProperties": false, "description": "Offline, best-effort text-layer extraction; no OCR. No external CMap or standard-font data is configured or fetched. PDFs with self-contained character mappings can yield text, including CJK; documents requiring unavailable predefined CMaps can return empty or partial text without an error. Embedded ToUnicode alone does not guarantee extraction when the encoding still needs an external CMap. Missing standard-font data does not necessarily prevent extraction. A successful response does not certify complete text; truncated reports only the max_pages limit. PDF text extraction accepts at most 1000000 raw and separately 1000000 output UTF-16 code units, 10000 items per page and 100000 items across selected pages. Exceeding a limit rejects the call with 413 too_large. truncated refers only to max_pages." }, "example": { "url": "https://grist.tools/samples/documents/report.pdf", "max_pages": 100 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extracted_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "source_url", "total_pages", "extracted_pages", "truncated", "chars", "text" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/report.pdf", "total_pages": 2, "extracted_pages": 2, "truncated": false, "chars": 122, "text": "Sample Report\nThis is a public test document.\nIt has two pages of plain text.\n\nPage Two\nThe second page closes the report." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/pdf-to-text", "description": "Extracts the text layer of a PDF, page by page, in reading order (no OCR).", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 61, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 61, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/pdf-to-text/schema": { "get": { "operationId": "pdf-to-text-schema", "summary": "Schema, price and examples for pdf-to-text. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/pptx-to-text": { "post": { "operationId": "pptx-to-text", "summary": "Extracts the slide text of a PowerPoint .pptx, slide by slide, in order (body text only, up to 1,000 slides).", "description": "Reading .pptx slide text needs to unpack an OOXML zip through a hardened fetch: an agent fetching the URL itself walks past every SSRF control, and the parsing is fiddly enough to be worth a paid endpoint.\n\nDeclared timeout: 40000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the .pptx, up to 2048 characters; redirects are followed and the body must be a zip holding ppt/slides/slideN.xml parts, at most 1,000 of them." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/garden-plan.pptx" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "slide_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "slides": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "number", "text" ], "additionalProperties": false } }, "text": { "type": "string" } }, "required": [ "source_url", "slide_count", "chars", "slides", "text" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/garden-plan.pptx", "slide_count": 3, "chars": 244, "slides": [ { "number": 1, "text": "Spring Planting Plan\nCommunity garden season overview" }, { "number": 2, "text": "Beds and Crops\nNorth beds: beans and peas\nSouth beds: tomatoes & peppers\nHerb spiral: basil, thyme, mint" }, { "number": 3, "text": "Next Steps\nOrder compost by March\nRepair the east fence\nSchedule the first work day" } ], "text": "Spring Planting Plan\nCommunity garden season overview\n\nBeds and Crops\nNorth beds: beans and peas\nSouth beds: tomatoes & peppers\nHerb spiral: basil, thyme, mint\n\nNext Steps\nOrder compost by March\nRepair the east fence\nSchedule the first work day" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/pptx-to-text", "description": "Extracts the slide text of a PowerPoint .pptx, slide by slide, in order (body text only, up to 1,000 slides).", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 61, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 61, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/pptx-to-text/schema": { "get": { "operationId": "pptx-to-text-schema", "summary": "Schema, price and examples for pptx-to-text. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/remote-file-hash": { "post": { "operationId": "remote-file-hash", "summary": "Computes the sha256, sha1 or md5 digest of a remote file, buffered in memory under a size cap, for checksum verification.", "description": "Verifying an artefact against a published checksum means pulling the whole file through a hardened fetch and hashing it. An agent that fetches the URL itself walks past every SSRF control and pays the bandwidth anyway.\n\nDeclared timeout: 60000ms. Response size cap: 104857600 bytes.", "tags": [ "archives" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the file, up to 2048 characters; redirects are followed and the digest is taken over the whole response body (after any HTTP content-encoding is decoded), which must be at most 100 MB." }, "algorithm": { "default": "sha256", "description": "Digest to compute over the bytes: sha256 (default), sha1 or md5, returned as lowercase hex.", "type": "string", "enum": [ "sha256", "sha1", "md5" ] } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/archives/bundle.zip", "algorithm": "sha256" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "algorithm": { "type": "string", "enum": [ "sha256", "sha1", "md5" ] }, "hash": { "type": "string" } }, "required": [ "source_url", "bytes", "algorithm", "hash" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/archives/bundle.zip", "bytes": 639, "algorithm": "sha256", "hash": "07af68ae7f049cf267c89c4c89df15fd1f59153773b308ea6bb7bb0d0585e5c3" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/remote-file-hash", "description": "Computes the sha256, sha1 or md5 digest of a remote file, buffered in memory under a size cap, for checksum verification.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "archives" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/remote-file-hash/schema": { "get": { "operationId": "remote-file-hash-schema", "summary": "Schema, price and examples for remote-file-hash. Always free.", "tags": [ "archives" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/robots-check": { "post": { "operationId": "robots-check", "summary": "Fetches robots.txt and answers whether a user agent may crawl a URL, showing the group, the winning rule and every rule that competed with it.", "description": "It needs the network, and the part an agent gets wrong on its own is precedence: RFC 9309 resolves conflicts by longest match, not first match. One fetch answers up to 50 paths.\n\nDeclared timeout: 8000ms. Response size cap: 512000 bytes.", "tags": [ "feeds" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL to check, up to 2048 characters; robots.txt is fetched from the root of its origin and the verdict is for its path and query." }, "user_agent": { "default": "*", "description": "Crawler product token or full User-Agent string, printable ASCII up to 200 characters; the text before the first slash or space picks the group, and the default is *.", "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x20-\\x7e]+$" }, "include_sitemaps": { "default": true, "description": "Whether to return the Sitemap URLs listed in robots.txt; false returns null for sitemaps and its counters.", "type": "boolean" }, "additional_paths": { "description": "Up to 50 more root-relative paths or absolute URLs on the same origin as url, each answered from the same robots.txt fetch in additional_results.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 } } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/v1/whois", "user_agent": "GPTBot", "include_sitemaps": true, "additional_paths": [ "/docs/whois", "/v1/whois/schema" ] } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "robots_url": { "type": "string" }, "robots_status": { "type": "string", "enum": [ "found", "not_found", "server_error", "unreachable", "redirect_unresolved" ] }, "robots_http_status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "user_agent": { "type": "string" }, "user_agent_token": { "type": "string" }, "allowed": { "type": "boolean" }, "decision_reason": { "type": "string", "enum": [ "rule", "default_allow", "default_disallow" ] }, "matched_rule": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allow", "disallow" ] }, "path": { "type": "string" }, "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "octet_length": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type", "path", "line", "octet_length" ], "additionalProperties": false }, { "type": "null" } ] }, "matched_group": { "anyOf": [ { "type": "object", "properties": { "user_agents": { "type": "array", "items": { "type": "string" } }, "is_wildcard": { "type": "boolean" }, "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "user_agents", "is_wildcard", "line" ], "additionalProperties": false }, { "type": "null" } ] }, "competing_rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allow", "disallow" ] }, "path": { "type": "string" }, "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "octet_length": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type", "path", "line", "octet_length" ], "additionalProperties": false } }, "competing_rules_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "competing_rules_truncated": { "type": "boolean" }, "crawl_delay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sitemaps": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sitemaps_total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sitemaps_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "groups_found": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rules_parsed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unparsed_lines": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "robots_size_bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "robots_truncated": { "type": "boolean" }, "additional_results": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "allowed": { "type": "boolean" }, "decision_reason": { "type": "string", "enum": [ "rule", "default_allow", "default_disallow" ] }, "matched_rule": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allow", "disallow" ] }, "path": { "type": "string" }, "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "octet_length": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type", "path", "line", "octet_length" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "path", "allowed", "decision_reason", "matched_rule" ], "additionalProperties": false } }, { "type": "null" } ] }, "fetched_at": { "type": "string" }, "checked_at": { "type": "string" } }, "required": [ "url", "source_url", "robots_url", "robots_status", "robots_http_status", "user_agent", "user_agent_token", "allowed", "decision_reason", "matched_rule", "matched_group", "competing_rules", "competing_rules_total", "competing_rules_truncated", "crawl_delay", "sitemaps", "sitemaps_total", "sitemaps_truncated", "groups_found", "rules_parsed", "unparsed_lines", "robots_size_bytes", "robots_truncated", "additional_results", "fetched_at", "checked_at" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/v1/whois", "source_url": "https://grist.tools/robots.txt", "robots_url": "https://grist.tools/robots.txt", "robots_status": "found", "robots_http_status": 200, "user_agent": "GPTBot", "user_agent_token": "GPTBot", "allowed": false, "decision_reason": "rule", "matched_rule": { "type": "disallow", "path": "/v1/", "line": 3, "octet_length": 4 }, "matched_group": { "user_agents": [ "*" ], "is_wildcard": true, "line": 1 }, "competing_rules": [ { "type": "disallow", "path": "/v1/", "line": 3, "octet_length": 4 }, { "type": "allow", "path": "/", "line": 2, "octet_length": 1 } ], "competing_rules_total": 2, "competing_rules_truncated": false, "crawl_delay": null, "sitemaps": [ "https://grist.tools/sitemap.xml" ], "sitemaps_total": 1, "sitemaps_truncated": false, "groups_found": 1, "rules_parsed": 3, "unparsed_lines": 0, "robots_size_bytes": 141, "robots_truncated": false, "additional_results": [ { "path": "/docs/whois", "allowed": true, "decision_reason": "rule", "matched_rule": { "type": "allow", "path": "/", "line": 2, "octet_length": 1 } }, { "path": "/v1/whois/schema", "allowed": true, "decision_reason": "rule", "matched_rule": { "type": "allow", "path": "/v1/*/schema", "line": 4, "octet_length": 12 } } ], "fetched_at": "2026-09-01T12:00:00.000Z", "checked_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/robots-check", "description": "Fetches robots.txt and answers whether a user agent may crawl a URL, showing the group, the winning rule and every rule that competed with it.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "feeds" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/robots-check/schema": { "get": { "operationId": "robots-check-schema", "summary": "Schema, price and examples for robots-check. Always free.", "tags": [ "feeds" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/rss-parse": { "post": { "operationId": "rss-parse", "summary": "Fetches an RSS, Atom or RSS 1.0 feed and returns its channel metadata and a normalised list of items -- id, title, link, summary, content, author, dates and categories -- with every date in ISO 8601 UTC.", "description": "It needs the network and normalises three feed formats that say the same things in different tags and two different date formats, behind an XXE-safe XML parser. One call replaces the three-parser, RFC-822-date, entity-decoding scraper an agent would otherwise carry.\n\nDeclared timeout: 8000ms. Response size cap: 5242880 bytes.", "tags": [ "feeds" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the RSS 2.0, Atom or RSS 1.0 (RDF) feed, up to 2048 characters; up to 5 redirects are followed and a DTD is refused." }, "limit": { "default": 50, "description": "Maximum number of items returned, 1 to 1000 (default 50), counted after the since filter; a longer feed is cut and reported as truncated.", "type": "integer", "minimum": 1, "maximum": 1000 }, "since": { "description": "ISO 8601 timestamp with Z or an offset; when set, only items whose published (or else updated) date is at or after it are kept, and undated items are dropped.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/feed.xml", "limit": 10 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "rss", "atom", "rdf" ] }, "feed": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "generator": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "link", "description", "language", "updated", "generator" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "link", "summary", "content", "author", "published", "updated", "categories" ], "additionalProperties": false } }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "fetched_at": { "type": "string" } }, "required": [ "url", "source_url", "final_url", "http_status", "format", "feed", "items", "count", "total", "truncated", "fetched_at" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/feed.xml", "source_url": "https://grist.tools/samples/web/fieldnotes/feed.xml", "final_url": "https://grist.tools/samples/web/fieldnotes/feed.xml", "http_status": 200, "format": "rss", "feed": { "title": "Field Notes", "link": "https://grist.tools/samples/web/fieldnotes/index.html", "description": "Short notes on frost, rain and wind from a small test garden.", "language": "en", "updated": "2026-08-25T06:15:00Z", "generator": "Hand-written sample" }, "items": [ { "id": "fieldnotes-rain-gauge", "title": "Reading a rain gauge by hand", "link": "https://grist.tools/samples/web/fieldnotes/notes/rain-gauge.html", "summary": "How the daily rain reading is taken & written down.", "content": "

The gauge is read once a day at eight in the morning.

", "author": "Field Notes Editors", "published": "2026-08-25T06:15:00Z", "updated": null, "categories": [ "rain", "method" ] }, { "id": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "title": "The first frost of the season", "link": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "summary": "A light ground frost on the lower beds, measured at dawn.", "content": null, "author": "Field Notes Editors", "published": "2026-08-24T06:30:00Z", "updated": null, "categories": [ "frost" ] } ], "count": 2, "total": 2, "truncated": false, "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/rss-parse", "description": "Fetches an RSS, Atom or RSS 1.0 feed and returns its channel metadata and a normalised list of items -- id, title, link, summary, content, author, dates and categories -- with every date in ISO 8601 UTC.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "feeds" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/rss-parse/schema": { "get": { "operationId": "rss-parse-schema", "summary": "Schema, price and examples for rss-parse. Always free.", "tags": [ "feeds" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/sitemap-parse": { "post": { "operationId": "sitemap-parse", "summary": "Parses a sitemap, a sitemap index or a bare origin into a flat, bounded list of URLs with lastmod, changefreq and priority.", "description": "Needs the network, follows a sitemap index across many documents and normalises four different legal sitemap formats. An agent that does it itself either writes an XML parser with the XXE and fan-out defences, or fetches an unbounded tree of documents a stranger chose.\n\nDeclared timeout: 14000ms. Response size cap: 10485760 bytes.", "tags": [ "feeds" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^[hH][tT][tT][pP][sS]?:", "description": "Absolute http(s) URL, up to 2048 characters, of a sitemap, a sitemap index or a bare origin (path / and no query); a bare origin is resolved through robots.txt Sitemap: lines or /sitemap.xml." }, "limit": { "default": 5000, "description": "Maximum number of URLs returned across every document read, 1 to 50000 (default 5000); past it the list is cut and reported as truncated.", "type": "integer", "minimum": 1, "maximum": 50000 }, "include_metadata": { "default": false, "description": "When true each URL carries its lastmod, changefreq and priority; when false (default) those three fields are null.", "type": "boolean" }, "max_sitemaps": { "default": 10, "description": "Maximum number of sitemap documents fetched, entry document included, 1 to 50 (default 10); children past it are reported as skipped with reason sitemap_limit.", "type": "integer", "minimum": 1, "maximum": 50 }, "discover_from_robots": { "default": true, "description": "Only for a bare origin: when true (default) the Sitemap: lines of /robots.txt are read first with /sitemap.xml as the fallback, when false /sitemap.xml is used directly.", "type": "boolean" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml", "limit": 100, "include_metadata": true } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requested_url": { "type": "string" }, "entry_url": { "type": "string" }, "source_url": { "type": "string" }, "discovery": { "type": "string", "enum": [ "direct", "robots_txt", "well_known_path" ] }, "kind": { "type": "string", "enum": [ "urlset", "sitemapindex", "mixed" ] }, "format": { "type": "string", "enum": [ "xml", "text", "rss", "atom" ] }, "urls": { "type": "array", "items": { "type": "object", "properties": { "loc": { "type": "string" }, "lastmod": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changefreq": { "anyOf": [ { "type": "string", "enum": [ "always", "hourly", "daily", "weekly", "monthly", "yearly", "never" ] }, { "type": "null" } ] }, "priority": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "loc", "lastmod", "changefreq", "priority" ], "additionalProperties": false } }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_seen": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "stopped_reason": { "anyOf": [ { "type": "string", "enum": [ "url_limit", "sitemap_limit", "time_budget", "depth_limit", "cross_host", "documents_skipped" ] }, { "type": "null" } ] }, "sitemap_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sitemaps_visited": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "kind": { "type": "string", "enum": [ "urlset", "sitemapindex" ] }, "url_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gzip": { "type": "boolean" }, "depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url", "kind", "url_count", "http_status", "bytes", "gzip", "depth" ], "additionalProperties": false } }, "sitemaps_skipped": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "reason": { "type": "string", "enum": [ "depth_limit", "sitemap_limit", "cross_host", "too_large", "malformed", "duplicate", "time_budget", "not_fetchable" ] } }, "required": [ "url", "reason" ], "additionalProperties": false } }, "sitemaps_skipped_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sitemaps_skipped_by_reason": { "type": "object", "properties": { "depth_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sitemap_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cross_host": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "too_large": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "malformed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "duplicate": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time_budget": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "not_fetchable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "depth_limit", "sitemap_limit", "cross_host", "too_large", "malformed", "duplicate", "time_budget", "not_fetchable" ], "additionalProperties": false }, "invalid_loc_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "invalid_lastmod_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "robots_sitemaps": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "fetched_at": { "type": "string" } }, "required": [ "requested_url", "entry_url", "source_url", "discovery", "kind", "format", "urls", "count", "total_seen", "truncated", "stopped_reason", "sitemap_count", "sitemaps_visited", "sitemaps_skipped", "sitemaps_skipped_total", "sitemaps_skipped_by_reason", "invalid_loc_count", "invalid_lastmod_count", "robots_sitemaps", "fetched_at" ], "additionalProperties": false }, "example": { "requested_url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml", "entry_url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml", "source_url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml", "discovery": "direct", "kind": "mixed", "format": "xml", "urls": [ { "loc": "https://grist.tools/samples/web/fieldnotes/index.html", "lastmod": "2026-08-25T00:00:00Z", "changefreq": "daily", "priority": 1 }, { "loc": "https://grist.tools/samples/web/fieldnotes/about.html", "lastmod": "2026-08-20T00:00:00Z", "changefreq": "yearly", "priority": 0.3 }, { "loc": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "lastmod": "2026-08-24T06:30:00Z", "changefreq": "monthly", "priority": 0.6 }, { "loc": "https://grist.tools/samples/web/fieldnotes/notes/rain-gauge.html", "lastmod": "2026-08-25T06:15:00Z", "changefreq": null, "priority": 0.6 } ], "count": 4, "total_seen": 4, "truncated": false, "stopped_reason": null, "sitemap_count": 3, "sitemaps_visited": [ { "url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml", "kind": "sitemapindex", "url_count": 0, "http_status": 200, "bytes": 407, "gzip": false, "depth": 0 }, { "url": "https://grist.tools/samples/web/fieldnotes/sitemap-pages.xml", "kind": "urlset", "url_count": 2, "http_status": 200, "bytes": 479, "gzip": false, "depth": 1 }, { "url": "https://grist.tools/samples/web/fieldnotes/sitemap-notes.xml", "kind": "urlset", "url_count": 2, "http_status": 200, "bytes": 493, "gzip": false, "depth": 1 } ], "sitemaps_skipped": [], "sitemaps_skipped_total": 0, "sitemaps_skipped_by_reason": { "depth_limit": 0, "sitemap_limit": 0, "cross_host": 0, "too_large": 0, "malformed": 0, "duplicate": 0, "time_budget": 0, "not_fetchable": 0 }, "invalid_loc_count": 0, "invalid_lastmod_count": 0, "robots_sitemaps": null, "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/sitemap-parse", "description": "Parses a sitemap, a sitemap index or a bare origin into a flat, bounded list of URLs with lastmod, changefreq and priority.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "feeds" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 35, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 35, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/sitemap-parse/schema": { "get": { "operationId": "sitemap-parse-schema", "summary": "Schema, price and examples for sitemap-parse. Always free.", "tags": [ "feeds" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/ssl-cert-info": { "post": { "operationId": "ssl-cert-info", "summary": "Fetches the TLS certificate a host presents: issuer, subject, SAN list, validity window, days to expiry and the full chain.", "description": "Reading a live certificate needs a TLS handshake against the host, which an agent may be unable to make; the days-to-expiry and chain view are what you monitor across a fleet of domains.\n\nDeclared timeout: 10000ms. Response size cap: 2097152 bytes.", "tags": [ "domain" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "description": "Public fully qualified domain name to connect to and send as SNI. Give exactly one of domain or url.", "type": "string", "minLength": 1 }, "url": { "description": "An http(s) URL whose host is probed; an explicit port in the URL overrides the port field, and the path is ignored. Give exactly one of domain or url.", "type": "string", "minLength": 1 }, "port": { "default": 443, "description": "TLS port for the handshake, one of 443, 465, 636, 990, 993, 995, 8443; defaults to 443.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false }, "example": { "domain": "example.com" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "issuer": { "type": "string" }, "subject": { "type": "string" }, "san": { "type": "array", "items": { "type": "string" } }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "days_to_expiry": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "self_signed": { "type": "boolean" }, "chain": { "type": "array", "items": { "type": "object", "properties": { "issuer": { "type": "string" }, "subject": { "type": "string" }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "issuer", "subject", "valid_from", "valid_to" ], "additionalProperties": false } }, "queried_at": { "type": "string" } }, "required": [ "host", "port", "issuer", "subject", "san", "valid_from", "valid_to", "days_to_expiry", "self_signed", "chain", "queried_at" ], "additionalProperties": false }, "example": { "host": "example.com", "port": 443, "issuer": "CN=R3, O=Let's Encrypt, C=US", "subject": "CN=example.com, O=Example Inc, C=US", "san": [ "example.com", "www.example.com" ], "valid_from": "2026-08-01T00:00:00.000Z", "valid_to": "2026-10-30T23:59:59.000Z", "days_to_expiry": 65, "self_signed": false, "chain": [ { "issuer": "CN=R3, O=Let's Encrypt, C=US", "subject": "CN=example.com, O=Example Inc, C=US", "valid_from": "2026-08-01T00:00:00.000Z", "valid_to": "2026-10-30T23:59:59.000Z" }, { "issuer": "CN=ISRG Root X1, O=Internet Security Research Group, C=US", "subject": "CN=R3, O=Let's Encrypt, C=US", "valid_from": "2020-09-04T00:00:00.000Z", "valid_to": "2025-09-15T16:00:00.000Z" } ], "queried_at": "2026-08-26T18:00:00.000Z" }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/ssl-cert-info", "description": "Fetches the TLS certificate a host presents: issuer, subject, SAN list, validity window, days to expiry and the full chain.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "domain" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 31, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 31, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/ssl-cert-info/schema": { "get": { "operationId": "ssl-cert-info-schema", "summary": "Schema, price and examples for ssl-cert-info. Always free.", "tags": [ "domain" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/structured-data-extract": { "post": { "operationId": "structured-data-extract", "summary": "Fetches a web page and returns its embedded machine-readable data -- JSON-LD, OpenGraph, microdata and meta tags -- plus a normalised merge across all four.", "description": "It needs the network and a real DOM, and the extraction is the code an agent keeps re-implementing wrong: skipping a broken JSON-LD script instead of throwing, telling og: from name= apart, and walking microdata with its parent/child nesting rule. One call replaces four brittle scrapers.\n\nDeclared timeout: 8000ms. Response size cap: 5242880 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the HTML or XHTML page to read, up to 2048 characters; up to 5 redirects are followed and relative URLs resolve against the final URL or its ." }, "types": { "description": "Which of jsonld, opengraph, microdata and meta to extract, at least one; omitted means all four, and a type not requested comes back null and is left out of the normalized merge.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "jsonld", "opengraph", "microdata", "meta" ] } } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "http_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "jsonld": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "jsonld_total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "jsonld_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "jsonld_parse_errors": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "opengraph": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "microdata": { "anyOf": [ { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "null" } ] }, "microdata_total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "microdata_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "meta": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "normalized": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "description", "image", "type", "author", "published" ], "additionalProperties": false }, "fetched_at": { "type": "string" } }, "required": [ "url", "source_url", "final_url", "http_status", "jsonld", "jsonld_total", "jsonld_truncated", "jsonld_parse_errors", "opengraph", "microdata", "microdata_total", "microdata_truncated", "meta", "normalized", "fetched_at" ], "additionalProperties": false, "$defs": { "__schema0": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/__schema0" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/__schema0" } ] } } ] } } }, "required": [ "type", "properties" ], "additionalProperties": false } } }, "example": { "url": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "source_url": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "final_url": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "http_status": 200, "jsonld": [ { "@context": "https://schema.org", "@type": "Article", "headline": "The first frost of the season", "description": "A light ground frost on the lower beds, measured at dawn.", "image": "../icon-32.png", "datePublished": "2026-08-24T06:30:00Z", "author": { "@type": "Organization", "name": "Field Notes Editors" } } ], "jsonld_total": 1, "jsonld_truncated": false, "jsonld_parse_errors": 0, "opengraph": { "og:title": "The first frost of the season", "og:type": "article", "og:url": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html", "og:image": "https://grist.tools/samples/web/fieldnotes/icon-32.png" }, "microdata": [ { "type": "https://schema.org/Place", "properties": { "name": "Lower beds", "description": "The lowest corner of the garden, where cold air settles first." } } ], "microdata_total": 1, "microdata_truncated": false, "meta": { "description": "A light ground frost on the lower beds, measured at dawn.", "author": "Field Notes Editors", "article:published_time": "2026-08-24T06:30:00Z" }, "normalized": { "title": "The first frost of the season", "description": "A light ground frost on the lower beds, measured at dawn.", "image": "https://grist.tools/samples/web/fieldnotes/icon-32.png", "type": "Article", "author": "Field Notes Editors", "published": "2026-08-24T06:30:00Z" }, "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/structured-data-extract", "description": "Fetches a web page and returns its embedded machine-readable data -- JSON-LD, OpenGraph, microdata and meta tags -- plus a normalised merge across all four.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 29, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 29, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/structured-data-extract/schema": { "get": { "operationId": "structured-data-extract-schema", "summary": "Schema, price and examples for structured-data-extract. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/subtitle-convert": { "post": { "operationId": "subtitle-convert", "summary": "Converts a subtitle track between SubRip (.srt) and WebVTT (.vtt), normalising the cues.", "description": "It fetches through a hardened guard and re-serialises the cue model rather than string-patching, so positioning settings, cue ids and NOTE blocks convert cleanly instead of corrupting the output an agent would have to repair.\n\nDeclared timeout: 15000ms. Response size cap: 5242880 bytes.", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of a SubRip or WebVTT file, at most 2048 characters; the source format is detected from the content, not the extension." }, "to": { "default": "vtt", "description": "Target format, vtt (default) or srt; cues are re-serialised, so SRT output is renumbered and VTT cue ids, settings and NOTE blocks are dropped.", "type": "string", "enum": [ "srt", "vtt" ] } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/subtitle-captions.srt", "to": "vtt" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "source_format": { "type": "string", "enum": [ "srt", "vtt" ] }, "target_format": { "type": "string", "enum": [ "srt", "vtt" ] }, "cue_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "subtitle": { "type": "string" } }, "required": [ "source_url", "source_format", "target_format", "cue_count", "subtitle" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/subtitle-captions.srt", "source_format": "srt", "target_format": "vtt", "cue_count": 3, "subtitle": "WEBVTT\n\n00:00:01.000 --> 00:00:03.500\nThe tide goes out slowly.\n\n00:00:04.000 --> 00:00:06.250\nShells line the wet sand,\none row after another.\n\n00:00:07.000 --> 00:00:09.000\nBy noon the water returns.\n" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/subtitle-convert", "description": "Converts a subtitle track between SubRip (.srt) and WebVTT (.vtt), normalising the cues.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 36, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 36, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/subtitle-convert/schema": { "get": { "operationId": "subtitle-convert-schema", "summary": "Schema, price and examples for subtitle-convert. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/subtitle-extract": { "post": { "operationId": "subtitle-extract", "summary": "Extracts a text subtitle track from a media container (MKV, MP4, WebM) as SubRip or WebVTT.", "description": "Demuxing a caption stream out of a container needs ffmpeg AND a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an ffmpeg per call is not something an agent does inline.\n\nDeclared timeout: 60000ms. Response size cap: 209715200 bytes.", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of a media container that can carry subtitles (MKV/WebM, MP4/MOV, AVI or Ogg), at most 2048 characters." }, "stream": { "default": 0, "description": "Zero-based index counted among the subtitle streams only (0 to 63, default 0); a missing stream fails with no_subtitle_stream.", "type": "integer", "minimum": 0, "maximum": 63 }, "to": { "default": "srt", "description": "Format of the returned captions, srt (default) or vtt, written by ffmpeg.", "type": "string", "enum": [ "srt", "vtt" ] } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/subtitle-movie.mkv", "stream": 0, "to": "srt" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "container": { "type": "string", "enum": [ "mp4", "matroska", "avi", "ogg" ] }, "stream_index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "srt", "vtt" ] }, "cue_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "subtitle": { "type": "string" } }, "required": [ "source_url", "bytes", "container", "stream_index", "format", "cue_count", "subtitle" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/subtitle-movie.mkv", "bytes": 1486, "container": "matroska", "stream_index": 0, "format": "srt", "cue_count": 2, "subtitle": "1\n00:00:00,500 --> 00:00:02,000\nThe kettle starts to hum.\n\n2\n00:00:02,500 --> 00:00:04,000\nSteam rises from the spout.\n\n" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/subtitle-extract", "description": "Extracts a text subtitle track from a media container (MKV, MP4, WebM) as SubRip or WebVTT.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/subtitle-extract/schema": { "get": { "operationId": "subtitle-extract-schema", "summary": "Schema, price and examples for subtitle-extract. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/svg-to-png": { "post": { "operationId": "svg-to-png", "summary": "Rasterises an SVG to a PNG at a chosen resolution, returned base64-encoded.", "description": "Rasterising an SVG safely needs a real renderer and a hardened fetch: an SVG can point at internal addresses, so an agent that renders one itself walks past every SSRF control, and the output must be byte-reproducible.\n\nDeclared timeout: 60000ms. Response size cap: 26214400 bytes.", "tags": [ "images" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the SVG, up to 2048 characters; redirects are followed and the body must look like SVG markup; external references in it are never fetched." }, "width": { "description": "Target width in pixels, 1 to 20000; when width or height is set the rendered raster is resized to fit inside that box, keeping its aspect ratio, and may be scaled up.", "type": "integer", "minimum": 1, "maximum": 20000 }, "height": { "description": "Target height in pixels, 1 to 20000; when width or height is set the rendered raster is resized to fit inside that box, keeping its aspect ratio, and may be scaled up.", "type": "integer", "minimum": 1, "maximum": 20000 }, "density": { "default": 96, "description": "Render resolution in DPI, 1 to 2400, default 96; the natural raster size scales with density / 72, so a 64-unit-wide SVG renders 85 pixels wide at 96.", "type": "integer", "minimum": 1, "maximum": 2400 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/images/svg-badge.svg", "density": 192 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "format": { "type": "string", "const": "png" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "image_base64": { "type": "string" } }, "required": [ "source_url", "format", "width", "height", "bytes", "image_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/images/svg-badge.svg", "format": "png", "width": 171, "height": 128, "bytes": 2021, "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAKsAAACACAYAAAB0g5nsAAAACXBIWXMAAB2HAAAd..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/svg-to-png", "description": "Rasterises an SVG to a PNG at a chosen resolution, returned base64-encoded.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "images" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/svg-to-png/schema": { "get": { "operationId": "svg-to-png-schema", "summary": "Schema, price and examples for svg-to-png. Always free.", "tags": [ "images" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/url-to-markdown": { "post": { "operationId": "url-to-markdown", "summary": "Fetches a web page and returns the article as clean markdown, with its title, byline and final URL.", "description": "Raw HTML is mostly navigation, scripts and markup an agent pays for in tokens and then has to strip itself; this returns only the article, as markdown with headings, lists and resolved links, fetched through an SSRF-safe client that re-checks every redirect.\n\nDeclared timeout: 12000ms. Response size cap: 1048576 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Page to fetch, http or https. Redirects are followed and every hop is checked against private and reserved addresses." }, "max_chars": { "default": 50000, "description": "Cut applied to the returned markdown, counted in Unicode code points.", "type": "integer", "minimum": 200, "maximum": 200000 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://kitchen-ledger.blog/posts/weekday-starter", "max_chars": 2000 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "byline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "site_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "markdown": { "type": "string" }, "length": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "readability_applied": { "type": "boolean" }, "url_final": { "type": "string" }, "fetched_at": { "type": "string" } }, "required": [ "title", "byline", "excerpt", "site_name", "lang", "markdown", "length", "truncated", "readability_applied", "url_final", "fetched_at" ], "additionalProperties": false }, "example": { "title": "Feeding a Sourdough Starter on a Weekday Schedule", "byline": "Marta Rinaldi", "excerpt": "A feeding routine that keeps a rye starter active on a nine-to-five schedule, with ratios and timings.", "site_name": "Kitchen Ledger", "lang": "en", "markdown": "By [Marta Rinaldi](https://kitchen-ledger.blog/authors/marta-rinaldi/)\n\nMost starter guides assume you are home all day, ready to feed every twelve hours on the dot. A starter kept on a weekday routine can stay just as lively, provided the flour, the ratio and the temperature do the work that a flexible timetable cannot.\n\n## The ratio that buys you time\n\nA stiffer, less frequently fed starter ferments more slowly. Feeding one part starter to five parts flour and five parts water stretches the peak from four hours to roughly ten at a kitchen temperature of twenty-two degrees, which is long enough to cover a working day.\n\n- Morning, before work: discard all but 10 g and feed 50 g flour and 50 g water.\n- Evening: use the starter at its peak, or refrigerate it overnight.\n- Weekend: return to two feeds a day at one to one to one if you plan to bake.\n\n## Choosing the flour\n\nWhole rye ferments faster and more predictably than white wheat, so a small share of it keeps a slow schedule from stalling. The [guide to flour protein](https://kitchen-ledger.blog/guides/flour-protein/) explains why, and the [baker's percentage tables](https://www.bakerspercentage.net/tables) help when you scale a recipe up.\n\nIf the starter smells sharply of acetone by evening, it is hungry: shorten the interval or lower the temperature rather than adding more flour at once.", "length": 1368, "truncated": false, "readability_applied": true, "url_final": "https://kitchen-ledger.blog/posts/weekday-starter", "fetched_at": "2026-09-26T09:30:00.000Z" }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/url-to-markdown", "description": "Fetches a web page and returns the article as clean markdown, with its title, byline and final URL.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 33, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_status, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 33, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/url-to-markdown/schema": { "get": { "operationId": "url-to-markdown-schema", "summary": "Schema, price and examples for url-to-markdown. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/url-unshorten": { "post": { "operationId": "url-unshorten", "summary": "Follows a shortened or tracking URL to its real destination and returns every hop it went through.", "description": "Resolving a short link needs the network, and doing it safely needs a hardened client: an agent that follows the redirects itself will happily walk into a private address or a redirect loop.\n\nDeclared timeout: 10000ms. Response size cap: 65536 bytes.", "tags": [ "fetch" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The short or tracking URL to follow, up to 2048 characters; every hop, the first included, goes through the SSRF guard." }, "max_hops": { "default": 10, "description": "Most redirects to follow, 1 to 10, default 10; a chain that has not ended by then fails as unprocessable, and a meta refresh at the limit stops with stopped_reason hop_limit.", "type": "integer", "minimum": 1, "maximum": 10 }, "method": { "default": "auto", "description": "auto sends HEAD and retries the same hop with GET on a 400, 403, 405 or 501; head and get force one method for every hop.", "type": "string", "enum": [ "auto", "head", "get" ] }, "follow_meta_refresh": { "default": false, "description": "Whether to also follow an HTML meta refresh with a delay of 30 seconds or less, found in the first 64 KiB of a 2xx HTML or untyped page; method head turns it off, and JavaScript redirects are never followed.", "type": "boolean" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/web/unshorten-start.html", "max_hops": 10, "follow_meta_refresh": true } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requested_url": { "type": "string" }, "source_url": { "type": "string" }, "final_url": { "type": "string" }, "final_status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "final_host": { "type": "string" }, "final_content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hop_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reached_final": { "type": "boolean" }, "stopped_reason": { "anyOf": [ { "type": "string", "enum": [ "hop_limit", "redirect_loop" ] }, { "type": "null" } ] }, "cross_host": { "type": "boolean" }, "hops": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "method": { "type": "string", "enum": [ "HEAD", "GET" ] }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "http_redirect", "meta_refresh", "final" ] }, "host": { "type": "string" } }, "required": [ "url", "method", "status", "location", "resolved_location", "kind", "host" ], "additionalProperties": false } }, "initial_host_is_known_shortener": { "type": "boolean" }, "shortener_list_version": { "type": "string" }, "checked_at": { "type": "string" }, "fetched_at": { "type": "string" } }, "required": [ "requested_url", "source_url", "final_url", "final_status", "final_host", "final_content_type", "hop_count", "reached_final", "stopped_reason", "cross_host", "hops", "initial_host_is_known_shortener", "shortener_list_version", "checked_at", "fetched_at" ], "additionalProperties": false }, "example": { "requested_url": "https://grist.tools/samples/web/unshorten-start.html", "source_url": "https://grist.tools/samples/web/unshorten-start.html", "final_url": "https://grist.tools/samples/web/unshorten-landing.html", "final_status": 200, "final_host": "grist.tools", "final_content_type": "text/html; charset=utf-8", "hop_count": 1, "reached_final": true, "stopped_reason": null, "cross_host": false, "hops": [ { "url": "https://grist.tools/samples/web/unshorten-start.html", "method": "GET", "status": 200, "location": "unshorten-landing.html", "resolved_location": "https://grist.tools/samples/web/unshorten-landing.html", "kind": "meta_refresh", "host": "grist.tools" }, { "url": "https://grist.tools/samples/web/unshorten-landing.html", "method": "GET", "status": 200, "location": null, "resolved_location": null, "kind": "final", "host": "grist.tools" } ], "initial_host_is_known_shortener": false, "shortener_list_version": "2026-08-26", "checked_at": "2026-09-01T12:00:00.000Z", "fetched_at": "2026-09-01T12:00:00.000Z" }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/url-unshorten", "description": "Follows a shortened or tracking URL to its real destination and returns every hop it went through.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "fetch" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 31, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 31, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/url-unshorten/schema": { "get": { "operationId": "url-unshorten-schema", "summary": "Schema, price and examples for url-unshorten. Always free.", "tags": [ "fetch" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/video-thumbnail": { "post": { "operationId": "video-thumbnail", "summary": "Grabs a single frame from a video at a chosen timestamp as a PNG or JPEG, optionally scaled to a width.", "description": "Seeking and decoding one frame needs ffmpeg AND a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an ffmpeg per call is not something an agent does inline.\n\nDeclared timeout: 60000ms. Response size cap: 209715200 bytes.", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the video, at most 2048 characters; the container (MP4/MOV, MKV/WebM, AVI or Ogg) is detected from the bytes." }, "time_seconds": { "default": 0, "description": "Timestamp of the frame to grab, in seconds from the start (0 to 86400, default 0); a time past the end fails with no_frame.", "type": "number", "minimum": 0, "maximum": 86400 }, "format": { "default": "png", "description": "Encoding of the returned frame: png (default) or jpeg.", "type": "string", "enum": [ "png", "jpeg" ] }, "width": { "description": "Output width in pixels (16 to 4096); the height keeps the aspect ratio, rounded to an even number. Native size when omitted.", "type": "integer", "minimum": 16, "maximum": 4096 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/thumbnail-clip.mp4", "time_seconds": 1, "format": "png" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "container": { "type": "string", "enum": [ "mp4", "matroska", "avi", "ogg" ] }, "time_seconds": { "type": "number" }, "format": { "type": "string", "enum": [ "png", "jpeg" ] }, "width": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "image_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "image_base64": { "type": "string" } }, "required": [ "source_url", "bytes", "container", "time_seconds", "format", "width", "height", "image_bytes", "image_base64" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/thumbnail-clip.mp4", "bytes": 2587, "container": "mp4", "time_seconds": 1, "format": "png", "width": 128, "height": 72, "image_bytes": 292, "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAIAAAABICAIAAACx52pFAAAACXBIWXMAAAABAAAA..." }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/video-thumbnail", "description": "Grabs a single frame from a video at a chosen timestamp as a PNG or JPEG, optionally scaled to a width.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 81, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 81, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/video-thumbnail/schema": { "get": { "operationId": "video-thumbnail-schema", "summary": "Schema, price and examples for video-thumbnail. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/waveform-data": { "post": { "operationId": "waveform-data", "summary": "Reduces an audio file to a fixed number of normalised waveform peaks for drawing, without shipping samples.", "description": "Decoding audio to peaks needs ffmpeg AND a hardened fetch: an agent that pulls the URL itself walks past every SSRF control, and carrying an ffmpeg per call is not something an agent does inline.\n\nDeclared timeout: 90000ms. Response size cap: 104857600 bytes.", "tags": [ "av" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of an audio or video file, up to 2048 characters, in a recognised container (MP4/MOV, Matroska/WebM, AVI, Ogg, WAV, FLAC, AIFF or MP3); its first audio stream is decoded to mono." }, "peaks": { "default": 200, "description": "Number of buckets to return, 1 to 4000, default 200; each is the largest absolute sample in an equal slice of the track, scaled to 0..1 against 16-bit full scale.", "type": "integer", "minimum": 1, "maximum": 4000 }, "sample_rate": { "default": 8000, "description": "Decode rate in Hz, one of 4000, 8000, 11025, 16000, 22050 or 44100, default 8000; it sets sample_count and how finely each bucket is scanned.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/av/waveform-beeps.wav", "peaks": 20, "sample_rate": 8000 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "container": { "type": "string", "enum": [ "mp4", "matroska", "wav", "avi", "mp3", "ogg", "flac", "aiff" ] }, "sample_rate": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sample_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number" }, "peak_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "peaks": { "type": "array", "items": { "type": "number" } } }, "required": [ "source_url", "bytes", "container", "sample_rate", "sample_count", "duration_seconds", "peak_count", "peaks" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/av/waveform-beeps.wav", "bytes": 32044, "container": "wav", "sample_rate": 8000, "sample_count": 16000, "duration_seconds": 2, "peak_count": 20, "peaks": [ 0.25, 0.25, 0.25, 0.25, 0, 0, 0, 0.5, 0.5, 0.5, 0.5, 0, 0, 0, 0.8999, 0.8999, 0.8999, 0.8999, 0, 0 ] }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/waveform-data", "description": "Reduces an audio file to a fixed number of normalised waveform peaks for drawing, without shipping samples.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "av" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "3000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 111, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.003", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 111, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.003", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/waveform-data/schema": { "get": { "operationId": "waveform-data-schema", "summary": "Schema, price and examples for waveform-data. Always free.", "tags": [ "av" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/wellknown-fetch": { "post": { "operationId": "wellknown-fetch", "summary": "Fetches and parses a domain's well-known files -- security.txt (RFC 9116), ads.txt and humans.txt -- returning typed fields, seller records and a cross-file summary in one call.", "description": "It needs the network and a hardened client: the files are named by a stranger, so a naive fetch of /ads.txt is an SSRF probe, and the value is the parse -- PGP-signed security.txt fields, ads.txt split into DIRECT/RESELLER records -- an agent would otherwise build and maintain itself.\n\nDeclared timeout: 12000ms. Response size cap: 2097152 bytes.", "tags": [ "feeds" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "description": "Fully qualified domain name whose files are fetched over https, up to 253 characters; it is trimmed, lowercased and stripped of trailing dots, and IP literals, single-label names and private suffixes are refused.", "type": "string", "minLength": 1, "maxLength": 253 }, "files": { "description": "Which files to fetch, from security.txt (read at /.well-known/security.txt), ads.txt and humans.txt (read at the root); duplicates collapse, and the default is all three.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "security.txt", "ads.txt", "humans.txt" ] } } }, "required": [ "domain" ], "additionalProperties": false }, "example": { "domain": "example.com" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "type": "string" }, "files_requested": { "type": "array", "items": { "type": "string", "enum": [ "security.txt", "ads.txt", "humans.txt" ] } }, "security_txt": { "type": "object", "properties": { "requested": { "type": "boolean" }, "present": { "type": "boolean" }, "status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "url": { "type": "string" }, "contact": { "type": "array", "items": { "type": "string" } }, "expires": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "encryption": { "type": "array", "items": { "type": "string" } }, "acknowledgments": { "type": "array", "items": { "type": "string" } }, "preferred_languages": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical": { "type": "array", "items": { "type": "string" } }, "policy": { "type": "array", "items": { "type": "string" } }, "hiring": { "type": "array", "items": { "type": "string" } }, "signed": { "type": "boolean" }, "field_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "requested", "present", "status", "url", "contact", "expires", "is_expired", "encryption", "acknowledgments", "preferred_languages", "canonical", "policy", "hiring", "signed", "field_count" ], "additionalProperties": false }, "ads_txt": { "type": "object", "properties": { "requested": { "type": "boolean" }, "present": { "type": "boolean" }, "status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "url": { "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "advertising_system": { "type": "string" }, "publisher_id": { "type": "string" }, "relationship": { "type": "string", "enum": [ "DIRECT", "RESELLER", "OTHER" ] }, "certification_authority_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "advertising_system", "publisher_id", "relationship", "certification_authority_id", "line" ], "additionalProperties": false } }, "records_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "records_truncated": { "type": "boolean" }, "direct_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reseller_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "variables_truncated": { "type": "boolean" }, "invalid_lines": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "requested", "present", "status", "url", "records", "records_total", "records_truncated", "direct_count", "reseller_count", "variables", "variables_truncated", "invalid_lines" ], "additionalProperties": false }, "humans_txt": { "type": "object", "properties": { "requested": { "type": "boolean" }, "present": { "type": "boolean" }, "status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "url": { "type": "string" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "requested", "present", "status", "url", "text", "truncated", "bytes" ], "additionalProperties": false }, "normalised": { "type": "object", "properties": { "files_present": { "type": "array", "items": { "type": "string", "enum": [ "security.txt", "ads.txt", "humans.txt" ] } }, "security_contacts": { "type": "array", "items": { "type": "string" } }, "security_expires": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "security_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "security_signed": { "type": "boolean" }, "ads_sellers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ads_direct": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ads_reseller": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "files_present", "security_contacts", "security_expires", "security_expired", "security_signed", "ads_sellers", "ads_direct", "ads_reseller" ], "additionalProperties": false }, "fetched_at": { "type": "string" } }, "required": [ "domain", "files_requested", "security_txt", "ads_txt", "humans_txt", "normalised", "fetched_at" ], "additionalProperties": false }, "example": { "domain": "example.com", "files_requested": [ "security.txt", "ads.txt", "humans.txt" ], "security_txt": { "requested": true, "present": true, "status": 200, "url": "https://example.com/.well-known/security.txt", "contact": [ "mailto:security@example.com", "https://example.com/security-contact" ], "expires": "2027-01-01T00:00:00.000Z", "is_expired": false, "encryption": [ "https://example.com/pgp-key.txt" ], "acknowledgments": [ "https://example.com/hall-of-fame" ], "preferred_languages": "en, fr", "canonical": [ "https://example.com/.well-known/security.txt" ], "policy": [ "https://example.com/security-policy" ], "hiring": [ "https://example.com/jobs" ], "signed": false, "field_count": 9 }, "ads_txt": { "requested": true, "present": true, "status": 200, "url": "https://example.com/ads.txt", "records": [ { "advertising_system": "greenadexchange.com", "publisher_id": "12345", "relationship": "DIRECT", "certification_authority_id": "d75815a79", "line": 4 }, { "advertising_system": "blueadexchange.com", "publisher_id": "xf7", "relationship": "RESELLER", "certification_authority_id": null, "line": 5 }, { "advertising_system": "silverssp.com", "publisher_id": "9675", "relationship": "DIRECT", "certification_authority_id": null, "line": 6 } ], "records_total": 3, "records_truncated": false, "direct_count": 2, "reseller_count": 1, "variables": [ { "name": "CONTACT", "value": "adops@example.com" } ], "variables_truncated": false, "invalid_lines": 0 }, "humans_txt": { "requested": true, "present": true, "status": 200, "url": "https://example.com/humans.txt", "text": "/* TEAM */\nWebmaster: Jane Doe\nSite: example.com\n\n/* THANKS */\nEveryone.\n", "truncated": false, "bytes": 73 }, "normalised": { "files_present": [ "ads.txt", "humans.txt", "security.txt" ], "security_contacts": [ "mailto:security@example.com", "https://example.com/security-contact" ], "security_expires": "2027-01-01T00:00:00.000Z", "security_expired": false, "security_signed": false, "ads_sellers": 3, "ads_direct": 2, "ads_reseller": 1 }, "fetched_at": "2026-08-26T18:00:00.000Z" }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/wellknown-fetch", "description": "Fetches and parses a domain's well-known files -- security.txt (RFC 9116), ads.txt and humans.txt -- returning typed fields, seller records and a cross-file summary in one call.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "feeds" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 33, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 33, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/wellknown-fetch/schema": { "get": { "operationId": "wellknown-fetch-schema", "summary": "Schema, price and examples for wellknown-fetch. Always free.", "tags": [ "feeds" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/whois": { "post": { "operationId": "whois", "summary": "Registration record for a domain over whois: registrar, creation/update/expiry dates, status codes and nameservers, with the raw response.", "description": "whois is a port-43 protocol an agent is unlikely to speak, behind a per-TLD server map and an IANA referral step; the parsed fields plus a confidence score are what make the raw record usable.\n\nDeclared timeout: 12000ms. Response size cap: 2097152 bytes.", "tags": [ "domain" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "description": "Public fully qualified domain name to look up, up to 253 characters; it is lowercased and stripped of trailing dots, and its TLD picks the registry whois server (built-in map, else the IANA referral).", "type": "string", "minLength": 1, "maxLength": 253 } }, "required": [ "domain" ], "additionalProperties": false }, "example": { "domain": "example.com" } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "type": "string" }, "registrar": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "array", "items": { "type": "string" } }, "nameservers": { "type": "array", "items": { "type": "string" } }, "raw": { "type": "string" }, "parsed_confidence": { "type": "number" } }, "required": [ "domain", "registrar", "created", "updated", "expires", "status", "nameservers", "raw", "parsed_confidence" ], "additionalProperties": false }, "example": { "domain": "example.com", "registrar": "Example Registrar, LLC", "created": "1995-08-14T04:00:00.000Z", "updated": "2025-08-14T07:01:44.000Z", "expires": "2026-08-13T04:00:00.000Z", "status": [ "clientTransferProhibited" ], "nameservers": [ "a.iana-servers.net", "b.iana-servers.net" ], "raw": "Domain Name: EXAMPLE.COM\nRegistrar: Example Registrar, LLC\nRegistrar WHOIS Server: whois.exampleregistrar.com\nUpdated Date: 2025-08-14T07:01:44Z\nCreation Date: 1995-08-14T04:00:00Z\nRegistry Expiry Date: 2026-08-13T04:00:00Z\nDomain Status: clientTransferProhibited https://icann.org/epp#clientTransferProhibited\nName Server: A.IANA-SERVERS.NET\nName Server: B.IANA-SERVERS.NET", "parsed_confidence": 1 }, "x-example-kind": "illustrative", "x-example-note": "This example is illustrative: it shows the exact shape the handler returns, but it was not produced by a reproducible call, because the real answer depends on live network data that changes over time." } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/whois", "description": "Registration record for a domain over whois: registrar, creation/update/expiry dates, status codes and nameservers, with the raw response.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "domain" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 33, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.002", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 33, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.002", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/whois/schema": { "get": { "operationId": "whois-schema", "summary": "Schema, price and examples for whois. Always free.", "tags": [ "domain" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } }, "/v1/xlsx-to-json": { "post": { "operationId": "xlsx-to-json", "summary": "Reads an Excel .xlsx into JSON rows, keyed by a header row or as arrays; dates become ISO strings. Archives are limited to 64 worksheets.", "description": "Parsing a real .xlsx needs a spreadsheet engine plus a hardened fetch: an agent fetching the URL itself walks past every SSRF control, and carrying exceljs per call is not something an agent does inline.\n\nDeclared timeout: 40000ms. Response size cap: 26214400 bytes.", "tags": [ "documents" ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "description": "Base64 x402 v2 payment payload. X-PAYMENT is accepted as a legacy alias. Without it the endpoint answers 402 with the requirements.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http(s) URL of the .xlsx, up to 2048 characters; redirects are followed, the body must be a zip, and exceljs must load at least one worksheet from it (at most 64)." }, "sheet": { "description": "Exact name of the one worksheet to return, 1 to 255 characters; omitted, every worksheet is returned, and a name not in the workbook is a 422 listing the available names.", "type": "string", "minLength": 1, "maxLength": 255 }, "header_row": { "default": 1, "description": "The 1-based row holding the column names, 0 to 1000, default 1; data starts on the next row, and 0 returns every row as a positional array with columns set to null.", "type": "integer", "minimum": 0, "maximum": 1000 }, "max_rows": { "default": 1000, "description": "Maximum data rows returned per worksheet, 1 to 50000, default 1000; a sheet with more rows is cut and marked truncated.", "type": "integer", "minimum": 1, "maximum": 50000 } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://grist.tools/samples/documents/garden-inventory.xlsx", "header_row": 1, "max_rows": 1000 } } } }, "responses": { "200": { "description": "Success", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 settlement receipt. The same value is also sent as X-PAYMENT-RESPONSE.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_url": { "type": "string" }, "sheet_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sheets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "columns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "rows": { "type": "array", "items": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] } }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" } }, "required": [ "name", "columns", "rows", "row_count", "truncated" ], "additionalProperties": false } } }, "required": [ "source_url", "sheet_count", "sheets" ], "additionalProperties": false }, "example": { "source_url": "https://grist.tools/samples/documents/garden-inventory.xlsx", "sheet_count": 2, "sheets": [ { "name": "Seeds", "columns": [ "Variety", "Crop", "Packets", "Sown On", "Organic" ], "rows": [ { "Variety": "Early Scarlet", "Crop": "Radish", "Packets": 4, "Sown On": "2026-03-14T00:00:00.000Z", "Organic": true }, { "Variety": "Green Arrow", "Crop": "Pea", "Packets": 6, "Sown On": "2026-03-21T00:00:00.000Z", "Organic": true }, { "Variety": "Golden Cherry", "Crop": "Tomato", "Packets": 2, "Sown On": "2026-04-11T00:00:00.000Z", "Organic": false } ], "row_count": 3, "truncated": false }, { "name": "Tools", "columns": [ "Tool", "Count", "Location" ], "rows": [ { "Tool": "Spade", "Count": 3, "Location": "Shed" }, { "Tool": "Watering can", "Count": 5, "Location": "Rain barrels" } ], "row_count": 2, "truncated": false } ] }, "x-example-kind": "real" } } }, "400": { "description": "invalid_input", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "402": { "description": "Payment required: the body carries the x402 requirements. A 402 whose error field is one of these codes refused the authorization validity window: this request was refused before any work; it does not tell whether an earlier call with the same authorization was settled. authorization_expired: The authorization validBefore is already in the past. Sign a new authorization. authorization_validity_too_long: The authorization validBefore is too far in the future to be tracked against replay. Sign again with validBefore = now + max_timeout_seconds from the payment requirements. authorization_validity_too_short: The time left before validBefore does not cover the budget of this call (max_timeout_seconds, less a small tolerance). Sign a new authorization with validBefore = now + max_timeout_seconds from the payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64 JSON of the same x402 v2 requirements carried by the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "x402Version": { "type": "number", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "description", "mimeType", "serviceName", "tags" ], "additionalProperties": false }, "accepts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "additionalProperties": false } } }, "required": [ "x402Version", "resource", "accepts" ], "additionalProperties": false }, "example": { "x402Version": 2, "resource": { "url": "https://grist.tools/v1/xlsx-to-json", "description": "Reads an Excel .xlsx into JSON rows, keyed by a header row or as arrays; dates become ISO strings. Archives are limited to 64 worksheets.", "mimeType": "application/json", "serviceName": "grist.tools", "tags": [ "documents" ] }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C", "maxTimeoutSeconds": 61, "extra": { "name": "USD Coin", "version": "2" } } ] } } } }, "403": { "description": "blocked_target", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "413": { "description": "too_large. too_large: The request body is over 262144 bytes; details.limit_bytes carries the cap. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "415": { "description": "unsupported_content_type. unsupported_content_type: The request content-type is not application/json. Refused before payment, nothing is charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "422": { "description": "unprocessable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "424": { "description": "unreachable_target, upstream_timeout", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } }, "503": { "description": "concurrency_limit, registry_at_capacity, upstream_unavailable. We could not serve the call right now. Retryable: wait the number of seconds in the retry-after header, then repeat the call. concurrency_limit and registry_at_capacity mean we were at capacity: the call did not run. You can send the same payment again if its validBefore is still far enough away to cover another call. If it is not, the retry gets a 402 authorization_validity_too_short: sign a new payment. upstream_unavailable means our internal service failed or did not answer in time: the call may already have run and the payment may have been settled. A retry with the same payment can get a 402 whose error field says why. authorization_validity_too_short: too little time is left before validBefore to cover another call. This check comes before the replay check, so it does not tell whether the first payment was settled. replay_consumed (the payment was used and may have been settled) or replay_exhausted (too many attempts): sign a new payment. replay_in_flight: the first call is still running, so wait and do not pay again. invalid_exact_evm_nonce_already_used: the transfer is already on-chain, so this payment cannot move again. Sign a new payment. An authorization can be settled only once, since its nonce is single-use. To see whether it was settled, read the EIP-3009 authorizationState of its nonce on-chain. misconfigured: The service is not configured to serve calls. The call did not run and nothing is charged. It needs a fix on our side, so there is no retry delay to wait for.", "headers": { "retry-after": { "description": "Seconds to wait before repeating the call. Sent with concurrency_limit, registry_at_capacity, upstream_unavailable; not sent with misconfigured.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] }, "message": { "type": "string" }, "details": { "type": [ "object", "null" ] } } } } } } } } }, "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "price_usd": "0.005", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 61, "payTo": "0x2C5d7FAe8338e5472755a9B9cafcDEad90a8F81C" }, "x-payment-info": { "protocol": "x402", "price": { "amount": "0.005", "currency": "USD" }, "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } }, "/v1/xlsx-to-json/schema": { "get": { "operationId": "xlsx-to-json-schema", "summary": "Schema, price and examples for xlsx-to-json. Always free.", "tags": [ "documents" ], "responses": { "200": { "description": "Schema document", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "family": { "type": "string" }, "price_usd": { "type": "string" }, "free": { "type": "boolean" }, "timeout_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_timeout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "input_example": {}, "output_example": {}, "errors": { "type": "array", "items": { "type": "string", "enum": [ "invalid_input", "blocked_target", "unreachable_target", "upstream_status", "upstream_timeout", "unsupported_content_type", "too_large", "unprocessable", "internal", "rate_limited", "concurrency_limit", "registry_at_capacity", "upstream_unavailable", "not_found", "method_not_allowed", "misconfigured" ] } } }, "required": [ "name", "summary", "rationale", "family", "price_usd", "free", "timeout_ms", "max_timeout_seconds", "input_schema", "input_example", "output_example", "errors" ], "additionalProperties": false } } } } }, "x-x402": { "free": true, "price": "0" } } } } }