REST API Reference

Programmatic access to Volspan GPU compute.

Base URL

https://api.volspan.dev

Authentication

All requests require a Bearer token in the Authorization header. Use your API key (format: vc_live_...).

Authorization: Bearer vc_live_your_key_here

Rate limits

60 requests per minute per API key. Exceeding this returns 429 Too Many Requests with a Retry-After header.

POST /v1/runs

Submit a GPU run.

curl -X POST https://api.volspan.dev/v1/runs \
  -H "Authorization: Bearer vc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import torch; print(torch.cuda.get_device_name(0))",
    "gpu": "A100",
    "timeout": 300
  }'

Response

{
  "id": "run_abc123",
  "status": "queued",
  "gpu": "A100",
  "created_at": "2025-01-15T10:30:00Z"
}

GET /v1/runs/{id}

Get run status and results.

curl https://api.volspan.dev/v1/runs/run_abc123 \
  -H "Authorization: Bearer vc_live_your_key"

Response

{
  "id": "run_abc123",
  "status": "completed",
  "gpu": "A100",
  "stdout": "NVIDIA A100-SXM4-80GB",
  "stderr": "",
  "duration_ms": 2340,
  "cost_cents": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:02Z"
}

GET /v1/runs

List runs. Supports pagination and filtering.

curl "https://api.volspan.dev/v1/runs?limit=10&status=completed" \
  -H "Authorization: Bearer vc_live_your_key"

Response

{
  "runs": [...],
  "total": 42,
  "has_more": true,
  "cursor": "cur_xyz789"
}

GET /v1/vault/balance

Check current vault balance.

curl https://api.volspan.dev/v1/vault/balance \
  -H "Authorization: Bearer vc_live_your_key"

Response

{
  "balance_cents": 4850,
  "reserved_cents": 150,
  "available_cents": 4700
}

Need help? Reach out at [email protected]