API documentation

Aven is API-first: everything you can do in the dashboard, you can script. Drive the GPU catalog, your wallet, instances, invoices and receipts over a plain REST API.

Authentication

Authenticate every request (except the public catalog) with your API key as a Bearer token. Create and revoke keys in dashboard → settings, or via the account endpoints. Keys are shown once at creation — store them securely and never commit them to source control.

curl https://api.aven.cloud/v1/wallet \
  -H "Authorization: Bearer $AVEN_API_KEY"

Conventions

• Money is always an exact decimal string in USD (e.g. "12.50") — never a floating-point number. Parse it with a decimal type.
• Timestamps are ISO 8601 in UTC (e.g. 2026-07-10T02:23:15Z).
• Idempotency — send an Idempotency-Key header on POST /v1/wallet/topups so a retried request is never charged twice.
• Pagination — list endpoints that page return next_cursor and has_more; pass the cursor back as ?cursor=.

Errors

Errors use the standard application/problem+json format (RFC 7807). The HTTP status is authoritative; detail is a human-readable message.

{
  "type": "https://aven.cloud/problems/insufficient-funds",
  "title": "Insufficient funds",
  "status": 402,
  "detail": "Wallet balance is below the amount required to start this instance."
}

Common statuses: 401 invalid/expired key · 402 insufficient wallet balance · 404 not found · 409 conflict (e.g. capacity) · 422 validation · 429 rate limited.

Quickstart

# 1. List the live GPU catalog (public, no key needed)
curl https://api.aven.cloud/v1/catalog

# 2. Check your wallet balance
curl https://api.aven.cloud/v1/wallet -H "Authorization: Bearer $AVEN_API_KEY"

# 3. Order a single H100
curl -X POST https://api.aven.cloud/v1/instances \
  -H "Authorization: Bearer $AVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gpu_type":"H100_SXM5","gpu_count":1,"interruptible":false}'

# 4. Release it when done — you pay only for the seconds used
curl -X DELETE https://api.aven.cloud/v1/instances/<id> \
  -H "Authorization: Bearer $AVEN_API_KEY"

Catalog

Live GPU availability and pricing. Public — no authentication required. Filter with query parameters such as gpu_type, region, interruptible, max_usd_per_hour, min_gpu_count, min_gpu_memory_gb.

Instances

Order, inspect, pause and release GPU instances. Metering is per second against your prepaid wallet. Stop/start is available on instance types that support it (see supports_stop).

Wallet & top-ups

A prepaid balance in USD. Top up by card, save a card for automatic reloads, and read your transaction and usage history.

Invoices & receipts

A downloadable PDF receipt for every top-up, and an itemized monthly usage invoice for each month you consume GPU time.

Account & keys

Manage your profile, API keys and SSH keys. Add SSH keys so ordered instances trust you on first boot.