API docs by Redocly

Ethproofs API (0.0.1)

Download OpenAPI specification:

This document outlines the available API endpoints for Ethproofs.

Base URL

All API endpoints are relative to:

https://ethproofs.org/api/v0

Authentication

All endpoints require authentication using an API key in the request header:

Authorization: Bearer <api_key>

Blocks

Get block details

Retrieve metadata for a specific block.

path Parameters
required
integer or string
Example: 123456

The block number to retrieve

Responses

Response samples

Content type
application/json
{
  • "block_number": 12345,
  • "timestamp": "2025-01-15T12:00:00Z",
  • "gas_used": 15000000,
  • "transaction_count": 250,
  • "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  • "created_at": "2025-01-15T12:00:00Z"
}

Clusters

Update a cluster

Update cluster metadata and/or create a new cluster version. Changing zkvm_version_id or vk_path creates a new cluster version.

Authorizations:
apikey
path Parameters
id
required
integer
Example: 1

Cluster ID (index)

Request Body schema: application/json
required
name
string <= 50 characters

Human-readable name. Main display name in the UI

num_gpus
integer > 0

Number of GPUs in the cluster. Determines if cluster is multi-GPU (>1) or single-GPU (1).

hardware_description
string <= 200 characters

Free-form text description of the cluster's hardware for display in the UI

is_active
boolean

Whether the cluster is active and can receive proofs

zkvm_version_id
integer > 0

ID of the zkVM version. Changing this creates a new cluster version. Visit ZKVMs to view all available zkVMs and their IDs.

vk_path
string

Verification key path for the cluster version

Responses

Request samples

Content type
application/json
{
  • "name": "ZKnight-01",
  • "num_gpus": 8,
  • "hardware_description": "8x NVIDIA H100 80GB GPUs, AMD EPYC 9654 96-Core Processor",
  • "is_active": true,
  • "zkvm_version_id": 1,
  • "vk_path": "/path/to/vk"
}

Response samples

Content type
application/json
{
  • "success": true
}

Create a cluster

Authorizations:
apikey
Request Body schema: application/json
required
name
required
string <= 50 characters

Human-readable name. Main display name in the UI

zkvm_version_id
required
integer > 0

ID of the zkVM version. Visit ZKVMs to view all available zkVMs and their IDs.

num_gpus
integer > 0
Default: 1

Number of GPUs in the cluster. Determines if cluster is multi-GPU (>1) or single-GPU (1).

hardware_description
string <= 200 characters

Free-form text description of the cluster's hardware for display in the UI

deployment_type
string
Default: "cloud-hosted"
Enum: "cloud-hosted" "on-prem"

Deployment type of the cluster. Determines infrastructure configuration.

Responses

Request samples

Content type
application/json
{
  • "name": "ZKnight-01",
  • "zkvm_version_id": 1,
  • "num_gpus": 8,
  • "hardware_description": "8x NVIDIA H100 80GB GPUs, AMD EPYC 9654 96-Core Processor",
  • "deployment_type": "cloud-hosted"
}

Response samples

Content type
application/json
{
  • "id": 0
}

List clusters

Authorizations:
apikey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Proofs

Download proof

Download a single proved proof by its proof ID.

Authorizations:
apikey
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique proof ID (UUID)

Responses

Download proofs

Download all proved proofs for a specific block as a ZIP file.

path Parameters
block
required
string^0x[a-fA-F0-9]{64}$
Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

The block hash (0x-prefixed 64 hex characters)

Responses

List proofs

Retrieve a filtered and paginated list of proofs.

Authorizations:
apikey
query Parameters
integer or string
Example: block=123456

Filter by block number or block hash (0x-prefixed 64 hex characters)

clusters
string
Example: clusters=550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001

Filter by comma-separated cluster UUIDs (e.g., uuid1,uuid2,uuid3)

limit
integer [ 1 .. 1000 ]
Default: 100

Number of proofs to return (default: 100, max: 1000)

offset
integer >= 0
Default: 0

Number of proofs to skip for pagination (default: 0)

Responses

Response samples

Content type
application/json
{
  • "proofs": [
    ],
  • "total_count": 0,
  • "limit": 0,
  • "offset": 0
}

Queued proof

The prover indicates they'll prove a block, but they haven't started proving yet.

Authorizations:
apikey
Request Body schema: application/json
required
block_number
required
number >= 0
cluster_id
required
number

Responses

Request samples

Content type
application/json
{
  • "block_number": 123456,
  • "cluster_id": 1
}

Response samples

Content type
application/json
{
  • "proof_id": 0
}

Proving proof

The prover indicates they've started proving a block.

Authorizations:
apikey
Request Body schema: application/json
required
block_number
required
number >= 0
cluster_id
required
number

Responses

Request samples

Content type
application/json
{
  • "block_number": 123456,
  • "cluster_id": 1
}

Response samples

Content type
application/json
{
  • "proof_id": 0
}

Proved proof

The prover indicates they've completed proving a block.

Authorizations:
apikey
Request Body schema: application/json
required
block_number
required
number >= 0
cluster_id
required
number
proving_time
required
number > 0

Time in milliseconds taken to generate the proof including witness generation. It excludes time taken for data fetching and any latency to submit the proof.

proving_cycles
integer > 0

Number of cycles taken to generate the proof.

proof
required
string

Proof in base64 format

verifier_id
string

vkey/image-id

Responses

Request samples

Content type
application/json
{
  • "block_number": 123456,
  • "cluster_id": 1,
  • "proving_time": 1000,
  • "proving_cycles": 10000,
  • "proof": "YmluYXJ5X3Byb29mX2RhdGE=",
  • "verifier_id": "..."
}

Response samples

Content type
application/json
{
  • "proof_id": 0
}

CSP benchmarks

Upload CSP benchmarks

Upload a CSP benchmarks JSON file to storage.

Authorizations:
apikey
Request Body schema: multipart/form-data
required
file
required
string <binary>

The JSON file containing CSP benchmarks data

filename
required
string

The filename to use for storage (without .json extension)

Responses

Response samples

Content type
application/json
{
  • "message": "CSP benchmarks uploaded successfully",
  • "path": "collected-benchmarks-2024-01.json"
}