Developer API

Your APIRaven account, as an API

Your whole APIRaven account from any script or service — balance and usage, the full IPv6 proxy lifecycle, and the AI model catalog — authenticated with the API key you already have.

Try it liveEndpoint referenceAPI Keys

Three steps, zero setup

If you have ever called one of the data APIs, you already know how to use the Developer API.

1

Use an existing key

The Developer API authenticates with the same sl_… API keys you already use for the data APIs — no new credential to create.

2

Send a Bearer request

Any HTTP client works. One header: Authorization: Bearer sl_…. Base URL: https://api.apiraven.com.

3

Free to call

Calling the API is free. Product operations (creating proxies, adding bandwidth) charge your balance at exactly the dashboard prices.

bash
curl -H "Authorization: Bearer sl_your_key" \
  https://api.apiraven.com/api/overview

Everything your account can do, from code

25 endpoints across your account, your IPv6 proxy fleet, and the AI gateway — free to call, one Bearer key.

Account & billing

Live balance in cents or USD, lifetime spend, top-up history with invoice numbers, per-key limits, and your recent request log.

IPv6 proxies

Provision, top up, rotate, whitelist, test, and delete proxies — plus live bandwidth stats and the buyable region catalog.

AI gateway

The full model catalog with per-1M-token pricing, your AI usage and cost summaries, and paginated request logs with payloads.

Free & self-service

Every endpoint is free to call and runs on the API key you already have. Writes charge your balance at the same prices as the dashboard.

Free — never metered
Read-only by design
Same key, same auth

Try it live

Runs against your own account with your default API key. Log in first — nothing here touches anyone else's data.

Endpoints

  • Account

  • IPv6 Proxies

  • AI Gateway

API Status

Ping the Developer API and confirm the calling key is valid. Returns the authenticated user id and the key's id, name, and prefix.

GEThttps://api.apiraven.com/api/status

Checking your session…

Endpoint reference

All endpoints live on https://api.apiraven.com behind a Bearer API key. Every response is JSON.

Account11 endpoints

GET/api/status— API Status

Ping the Developer API and confirm the calling key is valid. Returns the authenticated user id and the key's id, name, and prefix.

{
  "ok": true,
  "service": "api.apiraven.com/developer-api",
  "authenticated": {
    "userId": "8f14e45f-...",
    "key": {
      "id": "b6d81c92-...",
      "name": "Production",
      "prefix": "sl_1a2b3c",
      "isDefault": true
    }
  },
  "timestamp": "2026-10-11T12:00:00.000Z"
}
GET/api/overview— Account Overview

Everything at a glance: profile, balance, key count, and usage totals for today, this month, and all time, plus the current billing period.

{
  "profile": {
    "email": "you@example.com",
    "name": "Ada Lovelace",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "memberSince": "2025-04-18T09:12:44.000Z"
  },
  "balance": { "cents": 1250, "usd": "12.50", "currency": "USD" },
  "keys": {
    "total": 3,
    "calling": { "id": "b6d8...", "name": "Production", "prefix": "sl_1a2b3c", "isDefault": true }
  },
  "usage": {
    "today": { "requests": 412, "errors": 3, "spentCents": 18 },
    "thisMonth": { "requests": 8210, "errors": 41, "spentCents": 372 },
    "lifetime": { "requests": 154203, "errors": 1204, "spentCents": 8914 },
    "billingPeriod": { "period": "2026-10", "requests": 8210, "billedCents": 372, "billedUsd": "3.72" }
  },
  "topupsThisMonth": { "count": 1, "totalCents": 1000, "totalUsd": "10.00" }
}
GET/api/profile— Profile

Basic account profile: email, name, and member-since date.

{
  "email": "you@example.com",
  "name": "Ada Lovelace",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "memberSince": "2025-04-18T09:12:44.000Z"
}
GET/api/balance— Balance

Current account balance in cents and USD, lifetime requests and spend, top-ups this month, and the most recent top-up.

{
  "balance": { "cents": 1250, "usd": "12.50", "currency": "USD" },
  "lifetime": { "requests": 154203, "spentCents": 8914, "spentUsd": "89.14" },
  "topupsThisMonth": { "count": 1, "totalCents": 1000, "totalUsd": "10.00" },
  "lastTopup": {
    "amountCents": 1000,
    "amountUsd": "10.00",
    "status": "completed",
    "completedAt": "2026-10-03T15:20:01.000Z",
    "createdAt": "2026-10-03T15:19:44.000Z"
  }
}
GET/api/topups— Top-up History

Recent balance top-ups with amount, provider, payment method, status, and invoice number.

Query parameters

  • limit — Number of top-ups to return (1–100, default 20).
{
  "count": 2,
  "topups": [
    {
      "invoiceNumber": "INV-2026-000142",
      "amountCents": 1000,
      "amountUsd": "10.00",
      "provider": "stripe",
      "paymentMethod": "card",
      "status": "completed",
      "completedAt": "2026-10-03T15:20:01.000Z",
      "createdAt": "2026-10-03T15:19:44.000Z"
    }
  ]
}
GET/api/keys— List API Keys

Every key on the account: name, prefix, status, limits, expiry, and last-used time. Secrets are never returned — only the display prefix.

{
  "count": 3,
  "keys": [
    {
      "id": "b6d81c92-...",
      "name": "Production",
      "prefix": "sl_1a2b3c",
      "status": "active",
      "isDefault": true,
      "limit": {
        "interval": "monthly",
        "creditLimitCents": 500,
        "creditLimitUsd": "5.00",
        "windowStartedAt": "2026-10-01T00:00:00.000Z",
        "spentCents": 372,
        "spentUsd": "3.72"
      },
      "expiresAt": null,
      "lastUsedAt": "2026-10-11T11:58:02.000Z",
      "createdAt": "2025-04-18T09:15:00.000Z",
      "isCallingKey": true
    }
  ]
}
GET/api/keys/:id— Key Detail

Full detail for one key on your account, including its usage today, in the current limit window, and lifetime.

{
  "id": "b6d81c92-...",
  "name": "Production",
  "prefix": "sl_1a2b3c",
  "status": "active",
  "isDefault": true,
  "limit": { "interval": "monthly", "creditLimitCents": 500, "creditLimitUsd": "5.00", "spentCents": 372, "spentUsd": "3.72" },
  "usage": {
    "today": { "requests": 412, "errors": 3, "spentCents": 18 },
    "window": { "requests": 8210, "errors": 41, "spentCents": 372 },
    "lifetime": { "requests": 154203, "errors": 1204, "spentCents": 8914 }
  },
  "expiresAt": null,
  "lastUsedAt": "2026-10-11T11:58:02.000Z",
  "createdAt": "2025-04-18T09:15:00.000Z",
  "isCallingKey": true
}
GET/api/limits— Limits

The calling key's credit limit, interval, spend and remaining budget for the current window, plus the account balance.

{
  "key": { "id": "b6d8...", "name": "Production", "prefix": "sl_1a2b3c", "expiresAt": null },
  "creditLimit": {
    "interval": "monthly",
    "creditLimitCents": 500,
    "creditLimitUsd": "5.00",
    "windowStartedAt": "2026-10-01T00:00:00.000Z",
    "spentCents": 372,
    "spentUsd": "3.72",
    "remainingCents": 128
  },
  "accountBalance": { "cents": 1250, "usd": "12.50", "currency": "USD" }
}
GET/api/usage— Usage Report

Requests, errors, and spend for today, this month, the current limit window, and lifetime — with per-API and per-key breakdowns for this month.

{
  "today": { "requests": 412, "errors": 3, "spentCents": 18 },
  "thisMonth": { "requests": 8210, "errors": 41, "spentCents": 372 },
  "window": { "interval": "monthly", "startedAt": "2026-10-01T00:00:00.000Z", "requests": 8210, "errors": 41, "spentCents": 372 },
  "lifetime": { "requests": 154203, "errors": 1204, "spentCents": 8914 },
  "perApi": [
    { "apiId": "c1a2...", "apiName": "BIN Lookup", "apiSlug": "bin", "requests": 4120, "errors": 12, "spentCents": 186, "spentUsd": "1.86", "avgLatencyMs": 92 }
  ],
  "perKey": [
    { "apiKeyId": "b6d8...", "apiKeyName": "Production", "requests": 7980, "spentCents": 361, "spentUsd": "3.61", "isCallingKey": true }
  ]
}
GET/api/usage/daily— Daily Usage Series

A zero-filled day-by-day usage series for charts. Default 30 days, up to 90.

Query parameters

  • days — Number of days to return (1–90, default 30).
{
  "days": 3,
  "since": "2026-10-09T00:00:00.000Z",
  "series": [
    { "day": "2026-10-09", "requests": 388, "errors": 2, "spentCents": 17, "spentUsd": "0.17", "avgLatencyMs": 88 },
    { "day": "2026-10-10", "requests": 451, "errors": 9, "spentCents": 21, "spentUsd": "0.21", "avgLatencyMs": 91 },
    { "day": "2026-10-11", "requests": 412, "errors": 3, "spentCents": 18, "spentUsd": "0.18", "avgLatencyMs": 90 }
  ]
}
GET/api/activity— Activity Feed

Your most recent API requests: time, method, path, API, status code, latency, cost, and the key that made each call.

Query parameters

  • limit — Number of entries to return (1–100, default 25).
{
  "count": 1,
  "activity": [
    {
      "id": "e91af...",
      "time": "2026-10-11T11:58:02.000Z",
      "method": "GET",
      "path": "/v1/bin/lookup/4111111111111111",
      "apiName": "BIN Lookup",
      "apiSlug": "bin",
      "statusCode": 200,
      "ok": true,
      "latencyMs": 94,
      "costUsd": "0.000045",
      "errorCode": null,
      "apiKeyId": "b6d8...",
      "apiKeyName": "Production",
      "isCallingKey": true
    }
  ]
}

IPv6 Proxies11 endpoints

GET/api/ipv6-proxies— List My Proxies

Your proxy fleet from the database: username, host, port, mode, pinned IPv6, bandwidth cap, region, and billing state (balance + first-top-up minimum). No live server calls — pair with the live endpoint for usage stats.

{
  "proxies": [
    {
      "id": "468834a1-...",
      "assignmentId": 5,
      "username": "user-81afb882-mv7i4fsm",
      "displayName": "United States1",
      "host": "45.76.75.77",
      "port": 9281,
      "mode": "rotate",
      "pinnedIpv6": null,
      "stickyTtlSeconds": null,
      "bandwidthLimitMb": 2048,
      "bandwidthUsedMb": null,
      "dataAllocatedGb": 2,
      "region": { "id": 1, "name": "United States", "countryCode": "US", "flagEmoji": "🇺🇸" },
      "createdAt": "2026-10-14T02:39:26.000Z"
    }
  ],
  "billing": { "balanceCents": 499, "balanceUsd": "4.99", "hasFundedBefore": false, "minFirstTopupCents": 500 }
}
GET/api/ipv6-proxies/packages— List Proxy Packages

Buyable providers and regions with pricing — the region ids you pass to the create endpoint. Includes supported modes, the sticky-TTL cap, the dedicated-IP account cap, and sample order costs computed from the live pricing formula.

{
  "modes": ["rotate", "sticky", "static"],
  "stickyMaxTtlSeconds": 86400,
  "maxDedicatedPerAccount": 5,
  "providers": [
    {
      "id": 1,
      "name": "Vultr",
      "slug": "vultr",
      "proxyHost": "45.76.75.77",
      "proxyPort": 9281,
      "regions": [
        {
          "id": 1,
          "name": "United States",
          "slug": "usa",
          "countryCode": "US",
          "flagEmoji": "🇺🇸",
          "pricePerTbUsd": 6,
          "serverPricePerMonthUsd": 5,
          "serverCapacityTb": 20,
          "serverCostPerTbUsd": 4,
          "poolPrefix": "2001:19f0:6000:95e8::/48",
          "poolSize": 1200000,
          "sampleCostCents": { "1gb": 1, "10gb": 6, "100gb": 62, "1024gb": 638 }
        }
      ]
    }
  ]
}
POST/api/ipv6-proxies— Create / Provision Proxy

Order and provision a new proxy in one call. The proxy server is updated BEFORE the balance is charged, so a failed provision never costs anything. Choose a region id and gigabytes from the packages endpoint; mode defaults to rotate. Static proxies require a pinnedIpv6 from the dedicated-ips endpoint.

JSON body

  • regionId — Region to provision in (from the packages endpoint).
  • dataGb — Bandwidth to allocate in GB (integer ≥ 1).
  • mode — rotate | sticky | static (default: rotate).
  • stickyTtlSeconds — Sticky mode only — TTL window, 1 to 86400.
  • pinnedIpv6 — Static mode only — a free address from dedicated-ips.
{
  "ok": true,
  "proxy": {
    "id": "468834a1-...",
    "username": "user-81afb882-mv7i4fsm",
    "password": "faf40a600a6209d8ba9fc12eb4dfb71a",
    "displayName": "United States1",
    "host": "45.76.75.77",
    "port": 9281,
    "region": "United States",
    "provider": "Vultr",
    "mode": "rotate",
    "dataGb": 1,
    "bandwidthLimitMb": 1024,
    "costCents": 1,
    "costUsd": "0.01"
  },
  "balanceCents": 499
}
GET/api/ipv6-proxies/live— Live Proxy States

Live per-proxy data from the proxy servers: bandwidth used, active connections, whitelist, sticky window, and current mode. Pass assignment ids from the list endpoint (comma-separated).

Query parameters

  • ids — Comma-separated assignment ids (max 200).
{
  "live": {
    "5": {
      "stats": { "bytesIn": 1048576, "bytesOut": 2097152, "connections": 3, "totalBytes": 3145728, "usedMb": 3 },
      "allowedIps": [],
      "mode": "rotate",
      "pinnedIpv6": null,
      "sticky": null,
      "stickyTtlSeconds": null,
      "bandwidthLimitMb": 1024
    }
  }
}
POST/api/ipv6-proxies/:username/add-bandwidth— Add Bandwidth

Top up an existing proxy's bandwidth. The new cap is pushed to the proxy server first — if the server rejects it, nothing is charged. Priced identically to a new order.

JSON body

  • dataGb — Bandwidth to add in GB (1–5120).
{
  "ok": true,
  "costCents": 6,
  "costUsd": "0.06",
  "dataGb": 10,
  "bandwidthLimitMb": 12288,
  "dataAllocatedGb": 12,
  "balanceCents": 493
}
POST/api/ipv6-proxies/:username/rotate— Rotate Credentials

Issue a new password for a proxy you own. Tries an in-place update on the proxy server first; falls back to delete + recreate if the server rejects the in-place change.

{
  "ok": true,
  "password": "5bd8794f2605a688f01afd4bb0209a68",
  "recreated": false
}
PUT/api/ipv6-proxies/:username/whitelist— IP Whitelist

Add or remove an authorized source IP. An empty list allows all IPs; a non-empty list restricts the proxy to those IPs only (max 20). The proxy server is the source of truth.

JSON body

  • action — add | remove
  • ip — A valid IPv4 or IPv6 address.
{
  "ok": true,
  "allowedIps": ["203.0.113.7"]
}
POST/api/ipv6-proxies/:username/test— Connection Test

Fetches your egress IP through the proxy itself (HTTP CONNECT + TLS to a dual-stack probe host), proving the credentials work end-to-end. Returns latency and the IPv6 address the outside world sees.

{
  "ok": true,
  "success": true,
  "egressIp": "2001:19f0:6000:95e8::1607",
  "latencyMs": 873,
  "proxyHost": "45.76.75.77",
  "proxyPort": 9281,
  "probeHost": "api64.ipify.org"
}
DELETE/api/ipv6-proxies/:username— Delete Proxy

Remove a proxy: deleted on the server, soft-deleted locally, with unused bandwidth refunded pro-rata to your account balance based on the original purchase cost.

{
  "ok": true,
  "refundCents": 42,
  "refundUsd": "0.42",
  "remainingGb": 9,
  "balanceCents": 541
}
GET/api/ipv6-proxies/purchases— Purchase History

Every bandwidth purchase and refund for your proxies, newest first: gigabytes, cost, status (active / refunded), and region.

Query parameters

  • limit — Number of entries (1–100, default 50).
{
  "count": 2,
  "purchases": [
    {
      "id": "5eebaa43-...",
      "proxyUserId": "468834a1-...",
      "dataGb": 10,
      "costCents": 6,
      "costUsd": "0.06",
      "status": "active",
      "createdAt": "2026-10-14T02:40:16.000Z",
      "region": { "name": "United States", "countryCode": "US", "flagEmoji": "🇺🇸" }
    }
  ]
}
GET/api/ipv6-proxies/dedicated-ips— Free Dedicated IPs

Free (unpinned) addresses from a region's pool for static/dedicated proxies. Use one as pinnedIpv6 when creating a static proxy.

Query parameters

  • regionId — Region id (required).
  • q — Optional substring filter.
  • limit — Page size (1–500, default 100).
  • offset — Pagination offset.
{
  "ok": true,
  "items": ["2001:19f0:6000:95e8::1000", "2001:19f0:6000:95e8::1001", "2001:19f0:6000:95e8::1002"],
  "total": 4096,
  "offset": 0,
  "limit": 3,
  "poolSize": 4096,
  "takenCount": 0
}

AI Gateway3 endpoints

GET/api/ai/models— List AI Models

The full AI gateway model catalog: kind (chat, image, video, embedding, …), vendor, context window, capabilities, and pricing in USD per 1M tokens. Filter by kind, vendor, or free-text search.

Query parameters

  • kind — Filter by modality: chat, vision, image, video, embedding, transcription, speech, rerank, audio.
  • vendor — Filter by vendor brand.
  • q — Search model name, slug, or id.
  • limit — Page size (1–500, default 100).
{
  "count": 1,
  "priceUnit": "USD per 1M tokens",
  "kinds": [{ "kind": "chat", "count": 219 }, { "kind": "image", "count": 103 }],
  "vendors": [{ "vendor": "OpenAI", "count": 99 }],
  "models": [
    {
      "slug": "gpt-oss-120b",
      "modelId": "openai/gpt-oss-120b",
      "name": "GPT-OSS 120B",
      "vendor": "OpenAI",
      "kind": "chat",
      "context": 131072,
      "maxOutput": 32768,
      "pricing": { "inputPer1MTokens": 0.15, "outputPer1MTokens": 0.6, "perImageUsd": null, "perAudioMinuteUsd": null },
      "status": "stable"
    }
  ]
}
GET/api/ai/usage— AI Usage Summary

AI gateway usage for your account: total requests, tokens, and cost (lifetime and this month), broken down per model and per API key, plus the most recent requests. Filter the recent list to one key with apiKeyId, or 'playground' for dashboard runs.

Query parameters

  • apiKeyId — Scope 'recent' to one key id, or 'playground'.
  • recentLimit — Recent entries (1–100, default 25).
{
  "totalRequests": 142,
  "totalTokens": 918273,
  "totalCostUsd": 1.27,
  "monthCostUsd": 0.41,
  "monthRequests": 38,
  "errorCount": 3,
  "byModel": [
    { "modelSlug": "gpt-oss-120b", "modelName": "GPT-OSS 120B", "requests": 88, "tokens": 512004, "costUsd": 0.72 }
  ],
  "byApiKey": [
    { "apiKeyId": "b6d8...", "name": "Production", "prefix": "sl_1a2b3c", "requests": 100, "tokens": 600000, "costUsd": 0.85 }
  ],
  "recent": [
    {
      "id": "a1b2...",
      "modelSlug": "gpt-oss-120b",
      "modelName": "GPT-OSS 120B",
      "apiKeyName": "Production",
      "modality": "chat",
      "source": "playground",
      "promptTokens": 1204,
      "completionTokens": 486,
      "totalTokens": 1690,
      "costUsd": 0.0005,
      "latencyMs": 812,
      "status": "ok",
      "createdAt": "2026-10-14T02:00:00.000Z"
    }
  ]
}
GET/api/ai/logs— AI Request Logs

Paginated AI gateway request logs with the full input and output payloads, token counts, cost, latency, and status. Filter by modality or ok/error status.

Query parameters

  • page — Page number (default 1).
  • pageSize — Entries per page (1–100, default 20).
  • modality — Filter: chat, image, embedding, …
  • status — ok | error
{
  "logs": [
    {
      "id": "a1b2...",
      "modelSlug": "gpt-oss-120b",
      "modelName": "GPT-OSS 120B",
      "modelVendor": "OpenAI",
      "modality": "chat",
      "source": "playground",
      "apiKeyId": null,
      "apiKeyName": "Playground",
      "promptTokens": 1204,
      "completionTokens": 486,
      "totalTokens": 1690,
      "costUsd": 0.0005,
      "latencyMs": 812,
      "status": "ok",
      "errorMessage": null,
      "input": { "messages": [{ "role": "user", "content": "Hello!" }] },
      "output": { "choices": [{ "message": { "content": "Hi there!" } }] },
      "createdAt": "2026-10-14T02:00:00.000Z"
    }
  ],
  "total": 142,
  "page": 1,
  "pageSize": 20
}

Frequently asked questions

What is the APIRaven Developer API?

A self-service HTTP API for everything around your APIRaven account: check your balance and usage, manage your IPv6 proxy fleet (provision, top up, rotate, whitelist, test, delete), and browse the AI gateway model catalog and your AI usage — all with the API key you already have.

Do I need a separate API key?

No. Any active API key from the API Keys page works as-is. Send it as a Bearer token exactly like a data API endpoint. Keys that are revoked, disabled, or expired are rejected with a 401.

Is the Developer API free to call?

Calling the API is free — no endpoint is metered against your credit limits. Product operations that spend resources (creating a proxy, adding bandwidth) deduct from your account balance at exactly the same prices as the dashboard.

Can I manage IPv6 proxies from the API?

Yes — the full lifecycle. List your proxies and their live bandwidth stats, browse buyable regions with pricing, provision a new proxy, add bandwidth, rotate credentials, manage the IP whitelist, run a connection test that returns your egress IP, list free dedicated IPs, review purchase history, and delete a proxy with a pro-rata refund of unused bandwidth.

Can I change a proxy's mode (rotate / sticky / static)?

Not directly. A proxy's mode is fixed at creation — to switch modes, delete the proxy (unused bandwidth is refunded) and create a new one in the mode you want.

What can I see about the AI gateway?

The full model catalog — every chat, vision, image, video, embedding, transcription and speech model with context windows and per-1M-token pricing — plus your AI usage summary (requests, tokens, cost per model and per key) and paginated request logs with full input/output payloads.

Can the Developer API create or rotate keys?

No. Key management stays in the dashboard: the Developer API can list your keys, their statuses and limits, but never create, modify, or reveal them.

What format are amounts in?

Money is returned as integer cents (balanceCents, costCents) alongside a decimal USD string (balanceUsd, costUsd) for display. Integer cents are the canonical values — compute with those.

Are there rate limits?

Yes — the same per-key window rate limit as the data APIs. If you exceed it you get a 429 with error code rate_limit_exceeded. The endpoints are lightweight, so typical monitoring intervals (every minute or faster) are fine.

Ready to automate your account?

Grab one of your existing keys and make your first call in under a minute.

Try it liveManage API keys