Guides

Practical guides for working with Argus.

Authentication

Argus uses virtual keys for all API authentication. Virtual keys are prefixed with nxvk_.

Obtaining a Key

Keys are provisioned by your Argus administrator and appear in the My Access section of the portal. Keys are shown in full only once at creation time — copy them immediately.

Using Your Key

Pass your virtual key as a Bearer token in the Authorization header:

bash

curl https://nexus.cirruslabs.technology/v1/chat/completions \
  -H "Authorization: Bearer nxvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Key Types

Type	Access	Use Case
llm	Chat completions, embeddings, models	Standard API usage
mcp	MCP gateway tool calls	Agent tool execution
all	Both LLM and MCP endpoints	Full access

Rate Limits

Rate limits are configured per virtual key. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Limit	Scope	Description
RPM	Per key	Requests per minute
TPD	Per key	Tokens per day
Spend Cap	Per key	USD spend limit (daily, monthly, or total)

Check your current limits and usage in the My Access section of the portal or via the GET /api/v1/portal/usage/me/limits endpoint.

Error Handling

Argus returns errors in a consistent format:

json

{
  "error": {
    "message": "Rate limit of 60 RPM exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

HTTP Status	Code	Meaning
400	bad_request	Invalid request format or parameters
401	unauthorized	Missing or invalid virtual key
403	forbidden	Key doesn't have access to this endpoint
402	spend_cap_exceeded	Spend cap exceeded (`team_spend_cap_exceeded` for a team cap)
429	rate_limit_exceeded	Rate limit exceeded (`team_rate_limit_exceeded` / `org_rate_limit_exceeded` for aggregate limits)
500	internal_error	Gateway internal error
502	bad_gateway	Upstream provider returned an error

Auto Model Routing

Argus selects a model per request rather than requiring the client to name one. A request submitting model: "auto" is scored by a complexity classifier and dispatched to the corresponding tier in the requested provider family: the fastest and least expensive model for trivial prompts, a more capable model as complexity rises.

Basic usage

bash

curl https://nexus.cirruslabs.technology/v1/chat/completions \
  -H "Authorization: Bearer nxvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "model_family": "anthropic",
    "messages": [{"role": "user", "content": "Summarize this doc..."}]
  }'

The model_family field

Resolution order for which provider ladder to pick from:

Explicit model_family on the request body — always wins.
API-surface default — POST /v1/messages defaults to anthropic; POST /v1/chat/completions has no default.
Per-VK default (configured by your Argus admin on the virtual key).
HTTP 400 with auto_family_required if none of the above are set.

Families available by default are anthropic, openai, and google-gemini. Any other family returns 400 auto_no_tiers until an administrator configures a tier ladder for it. Confirm with your Argus administrator which families are configured for your organization.

Response headers

Every auto-routed response carries these headers so you can audit the selection without pulling the request log:

Header	Meaning
x-argus-auto-model	Concrete model id that was picked (e.g. `claude-sonnet-4-6`).
x-argus-auto-tier	Tier ordinal (0 = cheapest, higher = more capable).
x-argus-auto-signals	Comma-separated classifier signals that fired (`long_prompt`, `tool_use`, `code_or_math`, `reasoning_high`, ...).
x-argus-auto-heuristic-tier	What the heuristic alone would have picked (delta to `x-argus-auto-tier` reveals the effect of LLM-assist / cost clamps).
x-argus-auto-llm-assist	`cache-hit`, `cache-miss`, `not-ambiguous`, or `disabled`.
x-argus-auto-downshift-reason	Present only when the soft cost governor forced a lower tier (`cost-threshold`).

Model self-identification is unreliable. When asked "what version are you?", Claude and OpenAI models often name older versions they were trained to expect — trust the x-argus-auto-model header, not the model's own claim.