API Quickstart: Hello World with curl

Overview

This guide walks you through authenticating with Minerva and using every available API endpoint from the command line. No SDK required — just `curl`.

Base URL

https://zkesg.com

All API routes are under `/api/`. Authentication uses a session cookie (`minerva.session`), set automatically on login.

Step 1: Login

Authenticate with your username and password. The response sets a session cookie.

curl -s -c cookies.txt -X POST https://zkesg.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

Response:

{
  "ok": true,
  "user": {
    "sub": "d8f531d6-...",
    "email": "you@example.com",
    "name": "Your Name"
  }
}

The `-c cookies.txt` flag saves the session cookie to a file. Use `-b cookies.txt` in subsequent requests to send it.

Step 2: Check Your Session

Verify your session is valid:

curl -s -b cookies.txt https://zkesg.com/api/auth/session

Response:

{
  "authenticated": true,
  "user": {
    "sub": "d8f531d6-...",
    "email": "you@example.com",
    "name": "Your Name",
    "username": "your_username"
  }
}

Step 3: Access Protected Pages

With a valid session, you can hit any protected route:

# Dashboard
curl -s -b cookies.txt -o /dev/null -w "%{http_code}" https://zkesg.com/dashboard
# → 200

# Circuits
curl -s -b cookies.txt -o /dev/null -w "%{http_code}" https://zkesg.com/circuits
# → 200

# Chat (Juno)
curl -s -b cookies.txt -o /dev/null -w "%{http_code}" https://zkesg.com/chat
# → 200

# Proofs
curl -s -b cookies.txt -o /dev/null -w "%{http_code}" https://zkesg.com/proofs
# → 200

Without a session cookie, protected routes redirect to login (HTTP 307).

Step 4: Logout

curl -s -b cookies.txt -X POST https://zkesg.com/api/auth/logout

This invalidates the session cookie.

Public Routes (No Auth Required)

These routes are accessible without authentication:

# Landing page
curl -s -o /dev/null -w "%{http_code}" https://zkesg.com/
# → 200

# Templates
curl -s -o /dev/null -w "%{http_code}" https://zkesg.com/templates
# → 200

# Guides
curl -s -o /dev/null -w "%{http_code}" https://zkesg.com/guides
# → 200

# Pricing
curl -s -o /dev/null -w "%{http_code}" https://zkesg.com/pricing
# → 200

Coming Soon: Backend API

The Minerva backend API (Rust/Axum) will expose RESTful endpoints for proof operations:

# Generate a proof (coming soon)
curl -s -b cookies.txt -X POST https://zkesg.com/api/v1/proofs/generate \
  -H "Content-Type: application/json" \
  -d '{
    "circuit": "age-verification",
    "public_inputs": {"minimum_age": 18},
    "private_inputs": {"actual_age": 25}
  }'

# Verify a proof (coming soon)
curl -s -X POST https://zkesg.com/api/v1/proofs/verify \
  -H "Content-Type: application/json" \
  -d '{
    "proof": "WINTERFELL_PROOF_AAAA...",
    "public_inputs": {"minimum_age": 18}
  }'

# Chat with Juno (coming soon)
curl -s -b cookies.txt -X POST https://zkesg.com/api/v1/juno/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Design a circuit that proves revenue exceeds 1M"}'

Session Details

Troubleshooting

Getting 307 on protected routes?

Your session expired or the cookie wasn't sent. Re-login.

Getting 401 on login?

Check your username and password. Minerva uses Keycloak — your credentials are validated against the identity provider.

Cookie not being set?

Make sure you're using `-c cookies.txt` (save) on login and `-b cookies.txt` (send) on subsequent requests.