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://staging--ethproofs.netlify.app/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

Create a cluster

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

Human-readable name. Main display name in the UI

description
string <= 200 characters

Description of the cluster

zkvm_version_id
required
integer > 0

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

hardware
string <= 200 characters
Deprecated

Technical specifications. Use configuration.cluster_machine field instead.

cycle_type
string <= 50 characters

Type of cycle

proof_type
string <= 50 characters

Proof system used to generate proofs. (e.g., Groth16 or PlonK)

required
Array of objects

Cluster configuration

Responses

Request samples

Content type
application/json
{
  • "nickname": "ZKnight-01",
  • "description": "Primary RISC-V prover",
  • "zkvm_version_id": 1,
  • "hardware": "RISC-V Prover",
  • "cycle_type": "SP1",
  • "proof_type": "Groth16",
  • "configuration": [
    ]
}

Response samples

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

List clusters

Authorizations:
apikey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Single machine

Create a single machine

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

Human-readable name. Main display name in the UI

description
string <= 200 characters

Description of the cluster

zkvm_version_id
required
integer > 0

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

hardware
string <= 200 characters
Deprecated

Technical specifications. Use configuration.cluster_machine field instead.

cycle_type
string <= 50 characters

Type of cycle

proof_type
string <= 50 characters

Proof system used to generate proofs. (e.g., Groth16 or PlonK)

required
object

Physical hardware specifications of the machine

cloud_instance_name
required
string

The instance_name value of the cloud instance. Visit Cloud Instances to view all available instances and their exact names.

Responses

Request samples

Content type
application/json
{
  • "nickname": "ZKnight-01",
  • "description": "Primary RISC-V prover",
  • "zkvm_version_id": 1,
  • "hardware": "RISC-V Prover",
  • "cycle_type": "SP1",
  • "proof_type": "Groth16",
  • "machine": {
    },
  • "cloud_instance_name": "c5.xlarge"
}

Response samples

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

Proofs

Download proof

Download a single proved proof by its proof ID.

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.

query Parameters
integer or string
Example: block=123456

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

team
string

Filter by team slug

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
}

Cloud instances

List cloud instances

Returns a list of available cloud instances across different providers. Filter results by provider using the query parameter. See Cloud Instances for a visual table view and more details.

query Parameters
provider
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Verification keys

Upload verification key

Upload a verification key binary file to storage.

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

The verification key binary file to upload

filename
required
string

The filename to use for storage (e.g., 'team-vk.bin')

Responses

Response samples

Content type
application/json
{
  • "message": "Verification key uploaded successfully",
  • "path": "team-vk.bin"
}

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"
}