DevAI Gateway API

# 1. Sign in → Dashboard → Your keys → "Add your first provider key"
#    (OpenAI, Anthropic, Gemini, Groq, OpenRouter or Mistral; stored encrypted)
# 2. Same page → "New key" → copy your dvai_ key (shown once)
# 3. Call the gateway; it routes only over the keys you added:
curl https://devai-gateway.onrender.com/v1/chat/completions \
  -H "Authorization: Bearer $DEVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "auto", "messages": [{ "role": "user", "content": "hi" }] }'

# Check your keys without spending tokens (Clerk session token, as the dashboard does):
#   POST /user/pool/health           → every key
#   POST /user/pool/keys/:id/test    → one key

{
  "error": {
    "type": "no_provider_keys",
    "message": "no_provider_keys: add your own provider key in the dashboard (Your keys → Add a key), then retry. DevAI never uses shared keys for your requests.",
    "request_id": "req_3f9c2a1b7d4e8f60"
  }
}

Authorization: Bearer dvai_your_key

curl https://devai-gateway.onrender.com/v1/chat/completions \
  -H "Authorization: Bearer $DEVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Explain binary search in one line." }
    ],
    "temperature": 0.3,
    "max_tokens": 200
  }'

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1792310400,
  "model": "llama-3.1-8b-instant",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Binary search halves a sorted range each step..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 22, "total_tokens": 36 },
  "devai": {
    "mode": "single",
    "provider": "Groq",
    "model": "llama-3.1-8b-instant",
    "fallbacks": 0,
    "key": "gsk_…DyMg",
    "key_fallbacks": 1,
    "latency_ms": 912,
    "candidates": [
      { "provider": "Groq", "provider_type": "groq", "model": "llama-3.1-8b-instant",
        "status": "error", "latency_ms": 120, "key": "gsk_…k3Qa", "error": "429 rate limited" },
      { "provider": "Groq", "provider_type": "groq", "model": "llama-3.1-8b-instant",
        "status": "success", "latency_ms": 780, "key": "gsk_…DyMg", "selected": true,
        "usage": { "prompt_tokens": 14, "completion_tokens": 22, "total_tokens": 36 } }
    ]
  }
}

curl -N https://devai-gateway.onrender.com/v1/chat/completions \
  -H "Authorization: Bearer $DEVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [{ "role": "user", "content": "Write a haiku about failover" }]
  }'

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1792310400,"model":"llama-3.1-8b-instant","choices":[{"index":0,"delta":{"role":"assistant","content":"Keys"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1792310400,"model":"llama-3.1-8b-instant","choices":[{"index":0,"delta":{"content":" rotate quietly"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1792310400,"model":"llama-3.1-8b-instant","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1792310400,"model":"llama-3.1-8b-instant","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":17,"total_tokens":26}}

data: [DONE]

# Race every provider; first valid answer wins
curl https://devai-gateway.onrender.com/v1/chat/completions \
  -H "Authorization: Bearer $DEVAI_KEY" \
  -H "Content-Type: application/json" \
  -H "x-devai-mode: fastest" \
  -d '{ "model": "auto",
        "messages": [{ "role": "user", "content": "Summarise RAFT in 2 lines" }] }'

# Ask two providers, let a judge pick the best answer
curl https://devai-gateway.onrender.com/v1/chat/completions \
  -H "Authorization: Bearer $DEVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Is 2^61-1 prime? Explain briefly." }],
    "devai": {
      "mode": "best",
      "providers": ["openai:gpt-4o-mini", "groq:llama-3.1-8b-instant"],
      "judge": "openai:gpt-4o-mini",
      "timeoutMs": 20000
    }
  }'

{
  "model": "auto",
  "messages": [{ "role": "user", "content": "hi" }],
  "devai": { "keyStrategy": "round_robin" }
}

# or as a header (body wins if both are set):
x-devai-key-strategy: least_used

curl https://devai-gateway.onrender.com/v1/models -H "Authorization: Bearer $DEVAI_KEY"

# {
#   "object": "list",
#   "data": [
#     { "id": "gpt-4o-mini", "object": "model", "created": 1792310400, "owned_by": "OpenAI" },
#     { "id": "llama-3.1-8b-instant", "object": "model", "created": 1792310400, "owned_by": "Groq" }
#   ]
# }
# Only models of the providers YOUR key routes over; empty until you add a provider key.

curl "https://devai-gateway.onrender.com/v1/usage?period=week" -H "Authorization: Bearer $DEVAI_KEY"

# {
#   "requestCount": 42, "inputTokens": 5120, "outputTokens": 8730, "totalTokens": 13850,
#   "avgLatencyMs": 840, "cacheHitRate": 12, "period": "week"
# }

curl https://devai-gateway.onrender.com/v1/health

# {
#   "status": "healthy",            // healthy | degraded | unhealthy (gateway, database, Redis)
#   "gateway": "healthy",
#   "database": "healthy",
#   "redis": "healthy",
#   "byok": true,
#   "providers": [],                // shared providers only, if any; never affects status
#   "providers_checked_at": null,
#   "uptime": 5321.4,
#   "timestamp": "2026-10-18T08:00:00.000Z"
# }

{
  "error": {
    "type": "all_providers_failed",
    "message": "All 1 provider attempt(s) failed",
    "request_id": "req_3f9c2a1b7d4e8f60",
    "retry_after": 30,
    "attempts": [
      { "provider": "Groq", "provider_type": "groq", "model": "llama-3.1-8b-instant",
        "status": "skipped", "latency_ms": 0, "key": "gsk_…DyMg", "error": "rate limited (cooling down)" }
    ]
  }
}

# With the gateway's ADMIN_API_KEY (server-side only, never in a browser)
curl https://devai-gateway.onrender.com/admin/me -H "Authorization: Bearer $DEVAI_ADMIN_KEY"
# { "data": { "method": "admin_key" } }

# With a Clerk session token of an allowlisted user (what the dashboard sends)
# { "data": { "method": "clerk", "userId": "user_…", "email": "you@example.com" } }

# Create a project, then an app key for it
curl -X POST https://devai-gateway.onrender.com/admin/projects \
  -H "Authorization: Bearer $DEVAI_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "My app", "description": "Chat feature" }'

curl -X POST https://devai-gateway.onrender.com/admin/api-keys/project/PROJECT_ID \
  -H "Authorization: Bearer $DEVAI_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "production" }'
# → data.key is the full dvai_ key. It is returned only once.