# REST API The Colibri Stateless server provides a comprehensive REST API for generating and verifying cryptographic proofs for blockchain data. This API enables lightweight, stateless verification of Ethereum and Layer-2 blockchain operations. ## Overview The API consists of the following main categories: * **Proof Generation** - Create cryptographic proofs for blockchain data * **Proof Verification** - Verify proofs and execute JSON-RPC requests * **Beacon Chain API** - Light client sync endpoints for Ethereum consensus layer * **Health & Monitoring** - Server health checks and Prometheus metrics * **Configuration** - Server configuration management (requires WEB\_UI\_ENABLED) ## OpenAPI Specification The complete API is documented using OpenAPI 3.1.0 specification. You can access the specification in the following ways: ### Live Server Endpoint If you have a running Colibri server instance, the OpenAPI specification is available at: ``` http://localhost:8090/openapi.yaml ``` Replace `localhost:8090` with your server's host and port. ### Static Specification The specification is also available in the source repository at: ``` src/server/openapi.yaml ``` ## Interactive API Documentation The OpenAPI specification below provides interactive documentation for all available endpoints. **Note**: First, add the OpenAPI specification to GitBook via the OpenAPI panel or CLI, then replace `colibri-api` below with your spec name. ### Endpoints ## Verify and Execute JSON-RPC Request > \*\*Primary Use Case: Local RPC Provider Replacement\*\*\ > \ > This endpoint is designed to serve as a \*\*complete, trustless replacement for traditional RPC providers\*\*. When running the Colibri server locally (using the \[installer packages]\()), you can configure this endpoint as your RPC provider in wallets like MetaMask, enabling fully verified, trustless access to the blockchain without relying on third-party infrastructure.\ > \ > \*\*How It Works:\*\*\ > \ > The endpoint processes JSON-RPC requests through the following flow:\ > 1\. \*\*Proof Generation\*\*: Creates or fetches cryptographic proofs for the request (locally or from configured prover nodes)\ > 2\. \*\*Verification\*\*: Verifies the proof against the current sync committee state\ > 3\. \*\*Response\*\*: Returns the verified JSON-RPC response in standard format\ > \ > \*\*Supported Methods:\*\*\ > \ > This endpoint supports \*\*all\*\* Ethereum JSON-RPC methods, including:\ > \- Methods with proofs (see \[Supported RPC Methods]\( > \- Local methods without proofs (\`eth\_chainId\`, \`web3\_clientVersion\`, etc.)\ > \- Filter methods (\`eth\_newFilter\`, \`eth\_getFilterChanges\`, etc.)\ > \- Subscription methods (\`eth\_subscribe\`, \`eth\_unsubscribe\`)\ > \ > \*\*Local Setup Example:\*\*\ > \ > \`\`\`bash\ > \# Install and run locally (macOS/Linux/Windows)\ > \# See: > \ > \# Configure in MetaMask:\ > \# Network Name: Colibri Verified Ethereum\ > \# RPC URL: > \# Chain ID: 1 (or your configured chain)\ > \`\`\`\ > \ > The \`/config\` and \`/config.html\` endpoints complement this use case by providing an easy-to-use configuration interface for non-developers, allowing them to adjust settings like RPC nodes, beacon nodes, and caching without editing configuration files.
````json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Verifier","description":"Endpoints for verifying proofs and executing JSON-RPC calls"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/rpc":{"post":{"tags":["Verifier"],"summary":"Verify and Execute JSON-RPC Request","description":"**Primary Use Case: Local RPC Provider Replacement**\n\nThis endpoint is designed to serve as a **complete, trustless replacement for traditional RPC providers**. When running the Colibri server locally (using the [installer packages](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer)), you can configure this endpoint as your RPC provider in wallets like MetaMask, enabling fully verified, trustless access to the blockchain without relying on third-party infrastructure.\n\n**How It Works:**\n\nThe endpoint processes JSON-RPC requests through the following flow:\n1. **Proof Generation**: Creates or fetches cryptographic proofs for the request (locally or from configured prover nodes)\n2. **Verification**: Verifies the proof against the current sync committee state\n3. **Response**: Returns the verified JSON-RPC response in standard format\n\n**Supported Methods:**\n\nThis endpoint supports **all** Ethereum JSON-RPC methods, including:\n- Methods with proofs (see [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods))\n- Local methods without proofs (`eth_chainId`, `web3_clientVersion`, etc.)\n- Filter methods (`eth_newFilter`, `eth_getFilterChanges`, etc.)\n- Subscription methods (`eth_subscribe`, `eth_unsubscribe`)\n\n**Local Setup Example:**\n\n```bash\n# Install and run locally (macOS/Linux/Windows)\n# See: https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer\n\n# Configure in MetaMask:\n# Network Name: Colibri Verified Ethereum\n# RPC URL: http://localhost:8090/rpc\n# Chain ID: 1 (or your configured chain)\n```\n\nThe `/config` and `/config.html` endpoints complement this use case by providing an easy-to-use configuration interface for non-developers, allowing them to adjust settings like RPC nodes, beacon nodes, and caching without editing configuration files.\n","operationId":"verifyAndExecute","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"Request verified and executed successfully","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcResponse"},{"$ref":"#/components/schemas/JsonRpcErrorResponse"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}},"JsonRpcResponse":{"type":"object","required":["jsonrpc","result","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"result":{"description":"Method result (type varies by method)"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}},"JsonRpcErrorResponse":{"type":"object","required":["jsonrpc","error","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"JSON-RPC error code"},"message":{"type":"string","description":"Error message"},"data":{"description":"Additional error data (optional)"}}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}} ```` ## Generate Proof > Generates a cryptographic proof for a JSON-RPC request.\ > \ > This endpoint accepts standard JSON-RPC requests with additional optional properties:\ > \- \`c4\`: Hex-encoded state of the requested client for proof decisions\ > \- \`include\_code\`: Include bytecode in eth\_call proofs\ > \ > The response is an SSZ-encoded \`C4Request\` container defined in the \[Ethereum Main Proof Request specification]\( > \ > \*\*Supported Methods with Proofs:\*\*\ > \ > This endpoint only accepts RPC methods that have an associated ProofType. The ProofType determines the structure used in the \`C4Request.proof\` union.\ > \ > For the complete list of supported methods and their proof types, see the \[Supported RPC Methods]\() documentation.\ > \ > \*\*Common Methods:\*\*\ > \- \`eth\_call\` → EthCallProof\ > \- \`eth\_getBalance\` → EthAccountProof\ > \- \`eth\_getStorageAt\` → EthAccountProof\ > \- \`eth\_getCode\` → EthAccountProof\ > \- \`eth\_getProof\` → EthAccountProof\ > \- \`eth\_getTransactionByHash\` → EthTransactionProof\ > \- \`eth\_getTransactionReceipt\` → EthReceiptProof\ > \- \`eth\_getLogs\` → List\[EthLogsBlock]\ > \- \`eth\_getBlockByNumber\` → EthBlockProof\ > \- \`eth\_getBlockByHash\` → EthBlockProof\ > \- \`eth\_blockNumber\` → EthBlockNumberProof\ > \- \`colibri\_simulateTransaction\` → EthCallProof\ > \ > \*\*Note:\*\* Methods without a ProofType (like \`eth\_chainId\`, \`web3\_clientVersion\`) are not supported by this endpoint. Use the \`/rpc\` endpoint instead, which handles all methods.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Prover","description":"Endpoints for generating cryptographic proofs"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/proof":{"post":{"tags":["Prover"],"summary":"Generate Proof","description":"Generates a cryptographic proof for a JSON-RPC request.\n\nThis endpoint accepts standard JSON-RPC requests with additional optional properties:\n- `c4`: Hex-encoded state of the requested client for proof decisions\n- `include_code`: Include bytecode in eth_call proofs\n\nThe response is an SSZ-encoded `C4Request` container defined in the [Ethereum Main Proof Request specification](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request).\n\n**Supported Methods with Proofs:**\n\nThis endpoint only accepts RPC methods that have an associated ProofType. The ProofType determines the structure used in the `C4Request.proof` union.\n\nFor the complete list of supported methods and their proof types, see the [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods) documentation.\n\n**Common Methods:**\n- `eth_call` → EthCallProof\n- `eth_getBalance` → EthAccountProof\n- `eth_getStorageAt` → EthAccountProof\n- `eth_getCode` → EthAccountProof\n- `eth_getProof` → EthAccountProof\n- `eth_getTransactionByHash` → EthTransactionProof\n- `eth_getTransactionReceipt` → EthReceiptProof\n- `eth_getLogs` → List[EthLogsBlock]\n- `eth_getBlockByNumber` → EthBlockProof\n- `eth_getBlockByHash` → EthBlockProof\n- `eth_blockNumber` → EthBlockNumberProof\n- `colibri_simulateTransaction` → EthCallProof\n\n**Note:** Methods without a ProofType (like `eth_chainId`, `web3_clientVersion`) are not supported by this endpoint. Use the `/rpc` endpoint instead, which handles all methods.\n","operationId":"generateProof","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofRequest"}}}},"responses":{"200":{"description":"Proof generated successfully","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","description":"SSZ-encoded C4Request container. See the [C4Request specification](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request) for detailed structure.\n\nThe container includes:\n- `version`: 4-byte version (domain, major, minor, patch)\n- `data`: Union of different proof data types\n- `proof`: Union of different proof types\n- `sync_data`: Optional light client updates\n"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ProofRequest":{"allOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"object","properties":{"c4":{"type":"string","format":"hex","description":"Hex-encoded state of the requested client. Allows the prover to make\ndecisions about required header proofs (e.g., for historic blocks).\n"},"include_code":{"type":"boolean","description":"If true, eth_call proofs will include the required contract bytecode\nin the proof, enabling stateless verification.\n","default":false}}}]},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}} ``` ## Get Configuration Web UI > Serves the web-based configuration interface for managing server settings.\ > \ > \*\*Use Case: Local RPC Provider Setup\*\*\ > \ > This endpoint is specifically designed for users running Colibri locally as a trustless RPC provider (see \`/rpc\` endpoint). The Web UI provides an accessible way for non-developers to configure the server without editing configuration files directly.\ > \ > \*\*Configuration Options:\*\*\ > \- RPC node endpoints (upstream Ethereum nodes)\ > \- Beacon node endpoints (for light client sync)\ > \- Memcached settings (for proof caching)\ > \- Network settings (host, port, chain ID)\ > \- Prover settings (local vs. remote proof generation)\ > \ > \*\*Security Note:\*\* This endpoint is disabled by default for security reasons. Enable it with \`WEB\_UI\_ENABLED=1\` environment variable or the \`-u\` command-line flag. \*\*Only enable on trusted networks\*\* (typically localhost for local RPC provider setup).
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/config.html":{"get":{"tags":["Configuration"],"summary":"Get Configuration Web UI","description":"Serves the web-based configuration interface for managing server settings.\n\n**Use Case: Local RPC Provider Setup**\n\nThis endpoint is specifically designed for users running Colibri locally as a trustless RPC provider (see `/rpc` endpoint). The Web UI provides an accessible way for non-developers to configure the server without editing configuration files directly.\n\n**Configuration Options:**\n- RPC node endpoints (upstream Ethereum nodes)\n- Beacon node endpoints (for light client sync)\n- Memcached settings (for proof caching)\n- Network settings (host, port, chain ID)\n- Prover settings (local vs. remote proof generation)\n\n**Security Note:** This endpoint is disabled by default for security reasons. Enable it with `WEB_UI_ENABLED=1` environment variable or the `-u` command-line flag. **Only enable on trusted networks** (typically localhost for local RPC provider setup).\n","operationId":"getConfigUI","responses":{"200":{"description":"Configuration UI HTML page","content":{"text/html":{"schema":{"type":"string","description":"HTML page with interactive configuration editor"}}}},"403":{"description":"Web UI is disabled","content":{"text/html":{"schema":{"type":"string","description":"HTML error page explaining how to enable the Web UI"}}}}}}}}} ``` ## Get Server Configuration > Returns the current server configuration as JSON.\ > \ > This endpoint is used by the configuration Web UI (\`/config.html\`) to display and manage settings. It's part of the local RPC provider setup workflow, allowing programmatic access to server configuration for management tools.\ > \ > \*\*Security Note:\*\* This endpoint is disabled by default. Enable it with \`WEB\_UI\_ENABLED=1\` environment variable or the \`-u\` command-line flag. Only enable on trusted networks.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/config":{"get":{"tags":["Configuration"],"summary":"Get Server Configuration","description":"Returns the current server configuration as JSON.\n\nThis endpoint is used by the configuration Web UI (`/config.html`) to display and manage settings. It's part of the local RPC provider setup workflow, allowing programmatic access to server configuration for management tools.\n\n**Security Note:** This endpoint is disabled by default. Enable it with `WEB_UI_ENABLED=1` environment variable or the `-u` command-line flag. Only enable on trusted networks.\n","operationId":"getConfig","responses":{"200":{"description":"Current server configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigResponse"}}}},"403":{"description":"Web UI is disabled","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ConfigResponse":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","items":{"$ref":"#/components/schemas/ConfigParameter"}}}},"ConfigParameter":{"type":"object","required":["name","env","description","type"],"properties":{"name":{"type":"string","description":"Parameter name"},"env":{"type":"string","description":"Environment variable name"},"description":{"type":"string","description":"Human-readable parameter description"},"type":{"type":"string","enum":["int","string","key"],"description":"Parameter type"},"value":{"description":"Current parameter value (not included for 'key' type)"},"min":{"type":"integer","description":"Minimum value (for 'int' type)"},"max":{"type":"integer","description":"Maximum value (for 'int' type)"}}}}}} ``` ## Update Server Configuration > Updates the server configuration and triggers an automatic restart.\ > \ > \*\*How It Works:\*\*\ > \ > 1\. \*\*Validation\*\*: The server validates all parameter values against their definitions (type, range, etc.)\ > 2\. \*\*Save\*\*: Valid parameters are written to the configuration file\ > 3\. \*\*Restart\*\*: The server executes \`exit(0)\`, relying on the service manager (systemd, launchd, docker-compose) to restart it with the new configuration\ > \ > \*\*Requirements:\*\*\ > \ > \- Server must be started with a config file: \`-f \\` or \`--config \\`\ > \- \`WEB\_UI\_ENABLED=1\` must be set (enabled by default with \[installer packages]\( > \- Service manager (systemd/launchd/docker-compose) must be configured to restart on exit\ > \ > \*\*Restrictions:\*\*\ > \ > \- \*\*Sensitive parameters\*\* (type: \`key\`) cannot be updated via this endpoint for security reasons\ > \- \*\*Integer parameters\*\* must be within their defined min/max range\ > \- Changes take effect after server restart (typically 1-2 seconds)\ > \ > \*\*Use Case:\*\*\ > \ > This endpoint is specifically designed for the local RPC provider setup, allowing non-technical users to adjust settings like RPC endpoints, beacon nodes, or caching options through the Web UI without manually editing configuration files.\ > \ > \*\*Security Note:\*\* This endpoint is disabled by default. Only enable on trusted networks (typically localhost for local installations).
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/config":{"post":{"tags":["Configuration"],"summary":"Update Server Configuration","description":"Updates the server configuration and triggers an automatic restart.\n\n**How It Works:**\n\n1. **Validation**: The server validates all parameter values against their definitions (type, range, etc.)\n2. **Save**: Valid parameters are written to the configuration file\n3. **Restart**: The server executes `exit(0)`, relying on the service manager (systemd, launchd, docker-compose) to restart it with the new configuration\n\n**Requirements:**\n\n- Server must be started with a config file: `-f ` or `--config `\n- `WEB_UI_ENABLED=1` must be set (enabled by default with [installer packages](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer))\n- Service manager (systemd/launchd/docker-compose) must be configured to restart on exit\n\n**Restrictions:**\n\n- **Sensitive parameters** (type: `key`) cannot be updated via this endpoint for security reasons\n- **Integer parameters** must be within their defined min/max range\n- Changes take effect after server restart (typically 1-2 seconds)\n\n**Use Case:**\n\nThis endpoint is specifically designed for the local RPC provider setup, allowing non-technical users to adjust settings like RPC endpoints, beacon nodes, or caching options through the Web UI without manually editing configuration files.\n\n**Security Note:** This endpoint is disabled by default. Only enable on trusted networks (typically localhost for local installations).\n","operationId":"updateConfig","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateRequest"}}}},"responses":{"200":{"description":"Configuration updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateResponse"}}}},"400":{"description":"Validation error or invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Web UI is disabled","content":{"text/html":{"schema":{"type":"string","description":"HTML error page explaining how to enable the Web UI"}}}},"500":{"description":"Failed to save configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ConfigUpdateRequest":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","description":"Array of parameters to update","items":{"type":"object","required":["env","value"],"properties":{"env":{"type":"string","description":"Environment variable name (must match a valid parameter)"},"value":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"New value for the parameter (type depends on parameter definition)"}}}}}},"ConfigUpdateResponse":{"type":"object","required":["success","restart_required","message","updated_count"],"properties":{"success":{"type":"boolean","description":"Whether the configuration was successfully updated"},"restart_required":{"type":"boolean","description":"Whether a server restart is required (always true for successful updates)"},"message":{"type":"string","description":"Human-readable status message"},"updated_count":{"type":"integer","description":"Number of parameters that were successfully updated"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}} ``` ## Health Check > Returns the server health status and operational statistics.\ > \ > Use this endpoint for monitoring and health checks in production deployments.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Health","description":"Health checks and monitoring"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Returns the server health status and operational statistics.\n\nUse this endpoint for monitoring and health checks in production deployments.\n","operationId":"healthCheck","responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"500":{"description":"Server is unhealthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","required":["status","stats"],"properties":{"status":{"type":"string","enum":["ok","error"],"description":"Overall health status"},"stats":{"type":"object","required":["total_requests","total_errors","last_sync_event","last_request_time","open_requests"],"properties":{"total_requests":{"type":"integer","description":"Total number of requests processed since server start"},"total_errors":{"type":"integer","description":"Total number of errors encountered"},"last_sync_event":{"type":"integer","description":"Timestamp of last sync committee event"},"last_request_time":{"type":"integer","description":"Unix timestamp of last request"},"open_requests":{"type":"integer","description":"Number of currently active requests"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}} ``` ## Prometheus Metrics > Returns Prometheus-compatible metrics for monitoring server performance and operations.\ > \ > Configure your Prometheus instance to scrape this endpoint for comprehensive\ > monitoring of proof generation, verification, and RPC operations.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Health","description":"Health checks and monitoring"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/metrics":{"get":{"tags":["Health"],"summary":"Prometheus Metrics","description":"Returns Prometheus-compatible metrics for monitoring server performance and operations.\n\nConfigure your Prometheus instance to scrape this endpoint for comprehensive\nmonitoring of proof generation, verification, and RPC operations.\n","operationId":"getMetrics","responses":{"200":{"description":"Prometheus metrics","content":{"text/plain":{"schema":{"type":"string","description":"Prometheus text-based exposition format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}} ``` ## Get Beacon Block Header > Retrieves the beacon block header for a given block identifier.\ > \ > This endpoint is part of the Ethereum Beacon Chain API and is used for\ > light client sync operations. Requests are proxied to configured beacon nodes.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Beacon","description":"Ethereum Beacon Chain light client endpoints"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/eth/v1/beacon/headers/{block_id}":{"get":{"tags":["Beacon"],"summary":"Get Beacon Block Header","description":"Retrieves the beacon block header for a given block identifier.\n\nThis endpoint is part of the Ethereum Beacon Chain API and is used for\nlight client sync operations. Requests are proxied to configured beacon nodes.\n","operationId":"getBlockHeader","parameters":[{"name":"block_id","in":"path","required":true,"schema":{"type":"string"},"description":"Block identifier. Can be one of:\n- `head` - Canonical head in node's view\n- `genesis` - Genesis block\n- `finalized` - Latest finalized block\n- `` - Specific slot number\n- `` - Hex-encoded block root with 0x prefix\n"}],"responses":{"200":{"description":"Block header retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["execution_optimistic","finalized","data"],"properties":{"execution_optimistic":{"type":"boolean","description":"True if the response references an unverified execution payload"},"finalized":{"type":"boolean","description":"True if the response references the finalized history"},"data":{"type":"object","required":["root","canonical","header"],"properties":{"root":{"type":"string","format":"hex","pattern":"^0x[a-fA-F0-9]{64}$"},"canonical":{"type":"boolean"},"header":{"type":"object","description":"SignedBeaconBlockHeader object"}}}}}}}},"400":{"$ref":"#/components/responses/BeaconBadRequest"},"404":{"$ref":"#/components/responses/BeaconNotFound"},"500":{"$ref":"#/components/responses/BeaconError"}}}}},"components":{"responses":{"BeaconBadRequest":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconNotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}}},"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}} ``` ## Get Light Client Bootstrap > Requests the LightClientBootstrap structure for a given post-Altair beacon block root.\ > \ > This is used to initialize light clients with the current sync committee.\ > See the \[Ethereum Consensus Specs]\( > for details.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Beacon","description":"Ethereum Beacon Chain light client endpoints"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/eth/v1/beacon/light_client/bootstrap/{block_root}":{"get":{"tags":["Beacon"],"summary":"Get Light Client Bootstrap","description":"Requests the LightClientBootstrap structure for a given post-Altair beacon block root.\n\nThis is used to initialize light clients with the current sync committee.\nSee the [Ethereum Consensus Specs](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/altair/light-client/sync-protocol.md#lightclientbootstrap)\nfor details.\n","operationId":"getLightClientBootstrap","parameters":[{"name":"block_root","in":"path","required":true,"schema":{"type":"string","format":"hex","pattern":"^0x[a-fA-F0-9]{64}$"},"description":"Hex-encoded block root with 0x prefix"}],"responses":{"200":{"description":"Light client bootstrap data","headers":{"Eth-Consensus-Version":{"required":true,"schema":{"type":"string","enum":["phase0","altair","bellatrix","capella","deneb","electra","fulu"]},"description":"The active consensus version"}},"content":{"application/json":{"schema":{"type":"object","required":["version","data"],"properties":{"version":{"type":"string","enum":["phase0","altair","bellatrix","capella","deneb","electra","fulu"]},"data":{"type":"object","description":"LightClientBootstrap structure"}}}}}},"400":{"$ref":"#/components/responses/BeaconBadRequest"},"404":{"$ref":"#/components/responses/BeaconNotFound"},"500":{"$ref":"#/components/responses/BeaconError"}}}}},"components":{"responses":{"BeaconBadRequest":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconNotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}}},"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}} ``` ## Get Light Client Updates > Requests LightClientUpdate instances in the sync committee period range\ > \[start\_period, start\_period + count), leading up to the current head.\ > \ > Used for light client sync to track sync committee changes across periods.\ > See the \[Ethereum Consensus Specs]\( > for details.
```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Beacon","description":"Ethereum Beacon Chain light client endpoints"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/eth/v1/beacon/light_client/updates":{"get":{"tags":["Beacon"],"summary":"Get Light Client Updates","description":"Requests LightClientUpdate instances in the sync committee period range\n[start_period, start_period + count), leading up to the current head.\n\nUsed for light client sync to track sync committee changes across periods.\nSee the [Ethereum Consensus Specs](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/altair/light-client/sync-protocol.md#lightclientupdate)\nfor details.\n","operationId":"getLightClientUpdatesByRange","parameters":[{"name":"start_period","in":"query","required":true,"schema":{"type":"string"},"description":"Starting sync committee period"},{"name":"count","in":"query","required":true,"schema":{"type":"string"},"description":"Number of periods to request"}],"responses":{"200":{"description":"Array of light client updates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["version","data"],"properties":{"version":{"type":"string","enum":["phase0","altair","bellatrix","capella","deneb","electra","fulu"]},"data":{"type":"object","description":"LightClientUpdate structure"}}}}}}},"400":{"$ref":"#/components/responses/BeaconBadRequest"},"500":{"$ref":"#/components/responses/BeaconError"}}}}},"components":{"responses":{"BeaconBadRequest":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}}},"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}} ``` ## Get OpenAPI Specification > Returns this OpenAPI specification document in YAML format ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/openapi.yaml":{"get":{"tags":["Configuration"],"summary":"Get OpenAPI Specification","description":"Returns this OpenAPI specification document in YAML format","operationId":"getOpenApiSpec","responses":{"200":{"description":"OpenAPI specification","content":{"text/yaml":{"schema":{"type":"string"}}}}}}}}} ``` ### Schemas ## The ProofRequest object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ProofRequest":{"allOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"object","properties":{"c4":{"type":"string","format":"hex","description":"Hex-encoded state of the requested client. Allows the prover to make\ndecisions about required header proofs (e.g., for historic blocks).\n"},"include_code":{"type":"boolean","description":"If true, eth_call proofs will include the required contract bytecode\nin the proof, enabling stateless verification.\n","default":false}}}]},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}}}}} ``` ## The JsonRpcRequest object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}}}}} ``` ## The JsonRpcResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"JsonRpcResponse":{"type":"object","required":["jsonrpc","result","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"result":{"description":"Method result (type varies by method)"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}}}}} ``` ## The JsonRpcErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"JsonRpcErrorResponse":{"type":"object","required":["jsonrpc","error","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"JSON-RPC error code"},"message":{"type":"string","description":"Error message"},"data":{"description":"Additional error data (optional)"}}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}} ``` ## The HealthResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"HealthResponse":{"type":"object","required":["status","stats"],"properties":{"status":{"type":"string","enum":["ok","error"],"description":"Overall health status"},"stats":{"type":"object","required":["total_requests","total_errors","last_sync_event","last_request_time","open_requests"],"properties":{"total_requests":{"type":"integer","description":"Total number of requests processed since server start"},"total_errors":{"type":"integer","description":"Total number of errors encountered"},"last_sync_event":{"type":"integer","description":"Timestamp of last sync committee event"},"last_request_time":{"type":"integer","description":"Unix timestamp of last request"},"open_requests":{"type":"integer","description":"Number of currently active requests"}}}}}}}} ``` ## The ConfigResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigResponse":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","items":{"$ref":"#/components/schemas/ConfigParameter"}}}},"ConfigParameter":{"type":"object","required":["name","env","description","type"],"properties":{"name":{"type":"string","description":"Parameter name"},"env":{"type":"string","description":"Environment variable name"},"description":{"type":"string","description":"Human-readable parameter description"},"type":{"type":"string","enum":["int","string","key"],"description":"Parameter type"},"value":{"description":"Current parameter value (not included for 'key' type)"},"min":{"type":"integer","description":"Minimum value (for 'int' type)"},"max":{"type":"integer","description":"Maximum value (for 'int' type)"}}}}}} ``` ## The ConfigParameter object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigParameter":{"type":"object","required":["name","env","description","type"],"properties":{"name":{"type":"string","description":"Parameter name"},"env":{"type":"string","description":"Environment variable name"},"description":{"type":"string","description":"Human-readable parameter description"},"type":{"type":"string","enum":["int","string","key"],"description":"Parameter type"},"value":{"description":"Current parameter value (not included for 'key' type)"},"min":{"type":"integer","description":"Minimum value (for 'int' type)"},"max":{"type":"integer","description":"Maximum value (for 'int' type)"}}}}}} ``` ## The ConfigUpdateRequest object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigUpdateRequest":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","description":"Array of parameters to update","items":{"type":"object","required":["env","value"],"properties":{"env":{"type":"string","description":"Environment variable name (must match a valid parameter)"},"value":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"New value for the parameter (type depends on parameter definition)"}}}}}}}}} ``` ## The ConfigUpdateResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigUpdateResponse":{"type":"object","required":["success","restart_required","message","updated_count"],"properties":{"success":{"type":"boolean","description":"Whether the configuration was successfully updated"},"restart_required":{"type":"boolean","description":"Whether a server restart is required (always true for successful updates)"},"message":{"type":"string","description":"Human-readable status message"},"updated_count":{"type":"integer","description":"Number of parameters that were successfully updated"}}}}}} ``` ## The BeaconErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}} ``` ## Quick Start Examples ### Generate a Proof Generate a cryptographic proof for an `eth_getBalance` request: ```bash curl -X POST http://localhost:8090/proof \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"], "id": 1 }' \ --output proof.ssz ``` The response is an SSZ-encoded `C4Request` container. For details on the proof format, see the [Ethereum Main Proof Request](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request) specification. ### Verify and Execute a Request Execute a JSON-RPC request with automatic proof verification: ```bash curl -X POST http://localhost:8090/rpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"], "id": 1 }' ``` Response: ```json { "jsonrpc": "2.0", "result": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000", "id": 1 } ``` ### Execute a Smart Contract Call with Proof Generate a proof for an `eth_call` request with bytecode included: ```bash curl -X POST http://localhost:8090/proof \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_call", "params": [{ "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "data": "0x06fdde03" }, "latest"], "id": 1, "include_code": true }' \ --output call_proof.ssz ``` The `include_code` property ensures that the contract bytecode is included in the proof, enabling fully stateless verification. ### Update Configuration Update server configuration programmatically (requires `WEB_UI_ENABLED=1` and a config file): ```bash curl -X POST http://localhost:8090/config \ -H "Content-Type: application/json" \ -d '{ "parameters": [ {"env": "PORT", "value": 8091}, {"env": "RPC_NODES", "value": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"} ] }' ``` Response: ```json { "success": true, "restart_required": true, "message": "Configuration saved. Restart server to apply changes.", "updated_count": 2 } ``` **Note:** After a successful configuration update, the server automatically restarts (via `exit(0)`), relying on the service manager (systemd/launchd/docker-compose) to restart it with the new settings. This is automatically configured by the [installer packages](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer). ### Health Check Check the server's operational status: ```bash curl http://localhost:8090/health ``` Response: ```json { "status": "ok", "stats": { "total_requests": 1523, "total_errors": 12, "last_sync_event": 125705, "last_request_time": 1698234567, "open_requests": 3 } } ``` ### Prometheus Metrics Retrieve metrics for monitoring: ```bash curl http://localhost:8090/metrics ``` ## Advanced Features ### Client State Parameter For historic block proofs, you can provide the client's state to optimize proof generation: ```json { "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "0x100000"], "id": 1, "c4": "0x1234567890abcdef..." } ``` The `c4` parameter is a hex-encoded representation of the client's current sync committee state, allowing the prover to determine which header proofs are necessary. ### Supported JSON-RPC Methods The following Ethereum JSON-RPC methods are supported with proof generation: **Account & Storage:** * `eth_getBalance` * `eth_getCode` * `eth_getStorageAt` * `eth_getProof` **Transactions:** * `eth_getTransactionByHash` * `eth_getTransactionReceipt` * `eth_getTransactionCount` **Blocks:** * `eth_getBlockByNumber` * `eth_getBlockByHash` * `eth_blockNumber` **Contract Calls:** * `eth_call` **Events & Logs:** * `eth_getLogs` **Colibri-Specific:** * `colibri_simulateTransaction` - Simulate transaction execution with proof For a complete list of supported methods, see the [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods) documentation. ## Beacon Chain API The server also provides light client endpoints from the Ethereum Beacon Chain API for sync committee updates: * `GET /eth/v1/beacon/headers/{block_id}` - Retrieve beacon block headers * `GET /eth/v1/beacon/light_client/bootstrap/{block_root}` - Initialize light client * `GET /eth/v1/beacon/light_client/updates` - Sync committee period updates These endpoints are used internally by the verifier to maintain the current sync committee state and are also available for external light client implementations. ## Error Handling ### HTTP Status Codes * **200 OK** - Request successful * **400 Bad Request** - Invalid request format or parameters * **403 Forbidden** - Web UI disabled (for `/config` and `/config.html`) * **404 Not Found** - Endpoint or resource not found * **500 Internal Server Error** - Server error during processing ### Error Response Format Error responses use the following JSON format: ```json { "error": "Error message describing what went wrong" } ``` For JSON-RPC errors, the standard JSON-RPC error format is used: ```json { "jsonrpc": "2.0", "error": { "code": -32000, "message": "execution reverted" }, "id": 1 } ``` ## Rate Limiting & Performance The server is designed for high-performance proof generation and verification. Key performance characteristics: * **Concurrent Requests**: Multiple requests can be processed in parallel * **Proof Generation**: Typically 100-500ms depending on proof complexity * **Proof Verification**: Typically 50-200ms depending on proof size * **Light Client Sync**: Sync committee updates every \~27 hours For production deployments, consider: * Using memcached for caching frequently requested proofs (configure via `MEMCACHED_HOST` and `MEMCACHED_PORT`) * Monitoring via Prometheus metrics at `/metrics` * Load balancing across multiple RPC nodes (configure via `RPC_NODES`) ## Security Considerations ### Web UI Access The configuration endpoints (`/config` and `/config.html`) are **disabled by default** for security reasons. Only enable them on trusted networks using: ```bash # Environment variable export WEB_UI_ENABLED=1 # Command line flag ./colibri-server -u ``` ### Network Binding By default, the server binds to `127.0.0.1` (localhost only). To expose the server to other machines: ```bash export HOST=0.0.0.0 export PORT=8090 ``` **Warning**: Only expose the server to untrusted networks if you have proper security measures in place (firewall, authentication proxy, etc.). ## Additional Resources * [Full Specification Documentation](https://corpus-core.gitbook.io/specification-colibri-stateless/) * [Ethereum Main Proof Request Format](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request) * [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods) * [Building & Installation Guide](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/building) * [GitHub Repository](https://github.com/corpus-core/colibri-stateless) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/apis/rest-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.