Documentation
API Reference
Proof API
Generate, retrieve, and verify ZK-STARK proofs via the Minerva REST API.
The Proof API is the core of Minerva. It accepts circuit inputs, runs the Winterfell STARK prover, and returns a portable cryptographic proof that anyone can verify.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/proofs/generate | Generate a new ZK-STARK proof |
| GET | /api/v1/proofs | List all proofs for your account |
| GET | /api/v1/proofs/:id | Get a specific proof by ID |
| POST | /api/v1/proofs/:id/verify | Verify a proof by ID |
| POST | /api/v1/proofs/verify | Verify a raw proof blob (no auth required) |
| DELETE | /api/v1/proofs/:id | Delete a proof |
Generate a Proof
http
POST /api/v1/proofs/generate HTTP/1.1
Host: api.zkesg.com
Authorization: Bearer <your-api-key>
Content-Type: application/json
{
"template": "carbon-emissions",
"public_inputs": {
"threshold_tonnes": 10000
},
"private_inputs": {
"actual_emissions_tonnes": 7342
},
"webhook_url": "https://your-app.com/minerva/webhook"
}| Field | Type | Required | Description |
|---|---|---|---|
| template | string | Yes* | Template slug (e.g. carbon-emissions). Use this OR circuit. |
| circuit | object | Yes* | Custom circuit definition. Use this OR template. |
| public_inputs | object | Yes | Key-value map of public inputs (visible in proof) |
| private_inputs | object | Yes | Key-value map of private inputs (never leave server) |
| webhook_url | string | No | URL to notify when proof completes (async mode) |
Synchronous response (proof completes within timeout):
json
{
"id": "proof_01HX4KQZR9BNT5E2FPMCDVWJ3",
"status": "completed",
"template": "carbon-emissions",
"public_inputs": { "threshold_tonnes": 10000 },
"proof_blob": "WINTERFELL_PROOF_AAAAEAAAABAAAAAgA...",
"duration_ms": 1842,
"created_at": "2026-03-16T12:00:00Z"
}Async response (proof is queued, webhook will fire on completion):
json
{
"id": "proof_01HX4KQZR9BNT5E2FPMCDVWJ3",
"status": "pending",
"template": "carbon-emissions",
"created_at": "2026-03-16T12:00:00Z"
}List Proofs
bash
curl https://api.zkesg.com/api/v1/proofs \
-H "Authorization: Bearer $MINERVA_API_KEY"json
{
"proofs": [
{
"id": "proof_01HX4KQZR9BNT5E2FPMCDVWJ3",
"status": "completed",
"template": "carbon-emissions",
"duration_ms": 1842,
"created_at": "2026-03-16T12:00:00Z"
}
],
"total": 1,
"page": 1,
"per_page": 20
}Verify a Proof
Verification is public — no authentication required. Anyone with the proof blob and public inputs can verify independently.
http
POST /api/v1/proofs/verify HTTP/1.1
Host: api.zkesg.com
Content-Type: application/json
{
"proof_blob": "WINTERFELL_PROOF_AAAAEAAAABAAAAAgA...",
"template": "carbon-emissions",
"public_inputs": { "threshold_tonnes": 10000 }
}json
{
"valid": true,
"template": "carbon-emissions",
"public_inputs": { "threshold_tonnes": 10000 },
"verified_at": "2026-03-16T15:00:00Z"
}Proof Status Values
| Status | Meaning |
|---|---|
| pending | Proof generation queued or in progress |
| completed | Proof generated successfully, ready to verify |
| failed | Proof generation failed (constraint error, invalid inputs, or timeout) |
| expired | Proof was removed after the retention window |
Error Reference
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_inputs | Input values do not satisfy circuit constraints |
| 400 | unknown_template | Template slug does not exist |
| 401 | unauthorized | Missing or invalid authentication |
| 404 | proof_not_found | Proof ID does not exist in your account |
| 422 | constraint_error | Circuit constraint evaluation failed (report this) |
| 429 | rate_limit_exceeded | Too many proof requests — back off and retry |
| 500 | prover_error | Internal STARK prover error — retry or contact support |