curl Reference

This guide shows curl commands for every major Zeq endpoint. Perfect for testing, debugging, and shell scripts.

Setup

Store Your Token

export ZEQ_TOKEN="your_bearer_token_here"
export ZEQ_API="https://zeq.dev/api"

Or hardcode it in commands (less secure):

ZEQ_TOKEN="your_token_here"

Compute Endpoint

Execute a single computation step:

curl -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "state": {
      "x": 1.0,
      "y": 2.0,
      "z": 0.5
    },
    "time_quantum": 1
  }'

Pretty-print JSON

Pipe to jq:

curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}' | jq '.'

Extract Result Only

curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}' | jq '.data.result'

Complex State

curl -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "state": {
      "position": {
        "x": 1.5,
        "y": 2.3,
        "z": 0.7
      },
      "velocity": {
        "x": 0.1,
        "y": -0.2,
        "z": 0.05
      },
      "mass": 5.0
    },
    "time_quantum": 10
  }'

Verify Endpoint

Verify a computation proof:

curl -X POST "$ZEQ_API/zeq/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "proof": "zeqproof_abc123...",
    "expected_state": {
      "x": 1.5,
      "y": 2.8
    }
  }'

Full Verification Flow

# 1. Compute
RESULT=$(curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}')

# 2. Extract proof and result
PROOF=$(echo "$RESULT" | jq -r '.data.proof')
STATE=$(echo "$RESULT" | jq '.data.result')

# 3. Verify
curl -s -X POST "$ZEQ_API/zeq/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d "{
    \"proof\": \"$PROOF\",
    \"expected_state\": $STATE
  }" | jq '.data.valid'

Pulse Endpoint

Get the current Zeq time pulse:

curl -X GET "$ZEQ_API/zeq/pulse" \
  -H "Authorization: Bearer $ZEQ_TOKEN"

Check Synchronization Status

curl -s -X GET "$ZEQ_API/zeq/pulse" \
  -H "Authorization: Bearer $ZEQ_TOKEN" | jq '.data | {
    quantum: .current_quantum,
    synced: .synchronized,
    drift_ns: .drift_ns
  }'

Monitor Drift Over Time

for i in {1..10}; do
  DRIFT=$(curl -s -X GET "$ZEQ_API/zeq/pulse" \
    -H "Authorization: Bearer $ZEQ_TOKEN" | jq '.data.drift_ns')
  echo "Sample $i: Drift = $DRIFT ns"
  sleep 1
done

Operators Endpoint

List all available operators:

curl -X GET "$ZEQ_API/zeq/operators" \
  -H "Authorization: Bearer $ZEQ_TOKEN"

Filter by Category

curl -s -X GET "$ZEQ_API/zeq/operators?category=physics" \
  -H "Authorization: Bearer $ZEQ_TOKEN" | jq '.data.operators'

Count Operators

curl -s -X GET "$ZEQ_API/zeq/operators" \
  -H "Authorization: Bearer $ZEQ_TOKEN" | jq '.data.operators | length'

List Operator Names

curl -s -X GET "$ZEQ_API/zeq/operators" \
  -H "Authorization: Bearer $ZEQ_TOKEN" | jq '.data.operators[] | .name'

Timebridge Endpoint

Convert Unix timestamp to Zeqond:

curl -X POST "$ZEQ_API/zeq/timebridge" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "timestamp": 1704067200,
    "timezone": "UTC"
  }'

Current Time Conversion

NOW=$(date +%s)
curl -s -X POST "$ZEQ_API/zeq/timebridge" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d "{
    \"timestamp\": $NOW,
    \"timezone\": \"America/New_York\"
  }" | jq '.data.zeqond'

Batch Time Conversions

# Convert last 24 hours to Zeqonds
for offset in {0..24}; do
  TIMESTAMP=$(($(date +%s) - (offset * 3600)))
  ZEQOND=$(curl -s -X POST "$ZEQ_API/zeq/timebridge" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ZEQ_TOKEN" \
    -d "{\"timestamp\": $TIMESTAMP}" | jq '.data.zeqond')

  echo "Hour -$offset: $ZEQOND"
done

Lattice Endpoint (Batch)

Submit multiple computations:

curl -X POST "$ZEQ_API/zeq/lattice" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "requests": [
      {"state": {"x": 1.0}, "time_quantum": 1},
      {"state": {"x": 2.0}, "time_quantum": 1},
      {"state": {"x": 3.0}, "time_quantum": 1}
    ]
  }'

Process Batch Results

curl -s -X POST "$ZEQ_API/zeq/lattice" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "requests": [
      {"state": {"x": 1.0}, "time_quantum": 1},
      {"state": {"x": 2.0}, "time_quantum": 1}
    ]
  }' | jq '.data.results[] | {result: .result, proof: .proof}'

Medical Imaging: MRI Reconstruction

curl -X POST "$ZEQ_API/medical/mri" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "scan_id": "scan_12345",
    "k_space_data": {
      "dimensions": [256, 256],
      "data": "base64_encoded_k_space"
    },
    "enhancement_level": 2
  }'

Game Physics: Rigid Body Simulation

curl -X POST "$ZEQ_API/physics/rigidbody" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "bodies": [
      {
        "id": "ball",
        "position": [0, 0, 0],
        "velocity": [5, 0, 0],
        "mass": 1.0
      }
    ],
    "time_step": 0.016,
    "steps": 60
  }'

Emergency Systems: 911 Dispatch

curl -X POST "$ZEQ_API/emergency/dispatch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "call_id": "911_call_xyz",
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "incident_type": "medical",
    "priority": "high"
  }'

Hardware Design: Timing Analysis

curl -X POST "$ZEQ_API/chip/timing" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{
    "netlist": "netlist_file_id",
    "clock_frequency": 3000000000,
    "process_node": 5,
    "analyze_critical_path": true
  }'

Error Responses

400 Bad Request

curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"invalid": "payload"}' | jq '.error'

# Output:
# {
#   "code": "INVALID_REQUEST",
#   "message": "Missing required field: state"
# }

401 Unauthorized

curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer invalid_token" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}' | jq '.error'

# Output:
# {
#   "code": "UNAUTHORIZED",
#   "message": "Invalid or expired token"
# }

429 Rate Limited

curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}' | jq '{
    error: .error,
    reset_at: .error.details.reset_at
  }'

Response Headers

Check rate limit headers:

curl -i -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}' | grep "X-RateLimit"

# Output:
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1234567890

Advanced Patterns

Retry on Rate Limit

#!/bin/bash

MAX_RETRIES=3
BACKOFF=1

for attempt in $(seq 1 $MAX_RETRIES); do
  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$ZEQ_API/zeq/compute" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ZEQ_TOKEN" \
    -d '{"state": {"x": 1.0}, "time_quantum": 1}')

  HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
  BODY=$(echo "$RESPONSE" | head -n-1)

  if [ "$HTTP_CODE" -eq 200 ]; then
    echo "$BODY" | jq '.'
    exit 0
  elif [ "$HTTP_CODE" -eq 429 ] && [ $attempt -lt $MAX_RETRIES ]; then
    echo "Rate limited. Retrying in ${BACKOFF}s..."
    sleep $BACKOFF
    BACKOFF=$((BACKOFF * 2))
  else
    echo "Error: $BODY"
    exit 1
  fi
done

Parallel Requests

#!/bin/bash

# Submit 10 computations in parallel
for i in {1..10}; do
  (
    curl -s -X POST "$ZEQ_API/zeq/compute" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ZEQ_TOKEN" \
      -d "{\"state\": {\"x\": $i.0}, \"time_quantum\": 1}" | jq ".data.result"
  ) &
done

wait

Save Response to File

curl -s -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d '{"state": {"x": 1.0}, "time_quantum": 1}' > response.json

jq '.data' response.json

Load Request from File

curl -X POST "$ZEQ_API/zeq/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_TOKEN" \
  -d @request.json

Where request.json contains:

{
  "state": {"x": 1.0},
  "time_quantum": 1
}

Tips & Tricks

Use -s flag to suppress progress bar
Use -i flag to see response headers
Use -v flag for debugging
Pipe to jq for pretty-printing
Export variables to avoid repeating token
Use -w "%{http_code}" to capture HTTP status
Use -d @file.json to load request body from file
Use -H multiple times for multiple headers

Next Steps

tip

curl is perfect for one-off testing. For repeated use, switch to a helper SDK for your language.

Setup​

Store Your Token​

Compute Endpoint​

Pretty-print JSON​

Extract Result Only​

Complex State​

Verify Endpoint​

Full Verification Flow​

Pulse Endpoint​

Check Synchronization Status​

Monitor Drift Over Time​

Operators Endpoint​

Filter by Category​

Count Operators​

List Operator Names​

Timebridge Endpoint​

Current Time Conversion​

Batch Time Conversions​

Lattice Endpoint (Batch)​

Process Batch Results​

Medical Imaging: MRI Reconstruction​

Game Physics: Rigid Body Simulation​

Emergency Systems: 911 Dispatch​

Hardware Design: Timing Analysis​

Error Responses​

400 Bad Request​

401 Unauthorized​

429 Rate Limited​

Response Headers​

Advanced Patterns​

Retry on Rate Limit​

Parallel Requests​

Save Response to File​

Load Request from File​

Tips & Tricks​

Next Steps​