# Auxen — Extended Reference > Managed private endpoints for open-weight models, built for agent > and high-volume workloads. Deploy your own private open-weight > model. Get a stable endpoint. Pay per minute while it's active. We > run everything underneath. Single-tenant by default; your data is > never routed to a shared third-party API and never used for > training. This is the extended reference. The shorter index lives at https://auxen.ai/llms.txt; the agent-imperative version at https://auxen.ai/agent-reference.md. --- ## 1. What Auxen does Auxen deploys open-weight models and returns endpoints. How they're served is ours to run. A customer (or their agent) picks a model from the catalog and Auxen handles everything else: - Deploying the model as a private, single-tenant deployment - Issuing a stable HTTPS endpoint URL and a per-deployment API key - Keeping the endpoint up — if we move your deployment to different hardware, the URL and key do not change - Per-minute billing of active time - Optional features: Knowledge Base (answers grounded in your documents), system prompts, Persona Studio, chat sharing, outbound tool use (MCP), webhooks, agent activity dashboard ## 2. Privacy guarantees - **Single-tenant.** A deployment answers for one customer only. The low-cost Shared option (Fast tier only) is the one opt-in exception and is always labeled. - **Never used for training.** Prompts, conversations and uploaded documents are never used to train any model. - **Never routed to a third party.** Requests are not forwarded to OpenAI, Anthropic, Google, or any outside API. Data is erased when the deployment is deleted. ## 3. Three-tier agent architecture 1. ORCHESTRATOR — Strategy and planning Plans, reasons, dispatches. Frontier intelligence, low volume, premium cost acceptable. Usually a frontier API. The Maximum tier can serve as an orchestrator for cost-sensitive stacks. 2. SPECIALISTS — Focused on specific tasks Mid-size models with a tight system prompt and Knowledge Base: legal classifiers, entity extractors, domain-specific reasoners. Auxen sweet spot. 3. WORKHORSES — High-volume execution Day-to-day high-volume tasks at predictable cost. Privacy-critical because this is where real data flows. Auxen sweet spot. Open-weight models now trail frontier labs by roughly 3–6 months. For high-volume, well-specified tasks the quality gap is now smaller than the cost gap. See https://auxen.ai/architecture. ## 4. Pricing — pay-as-you-go, per minute of active time One billing model. Rates are per hour, billed per minute while a deployment is active. Pause or delete and the meter stops. No subscriptions, no monthly plans, no per-token fees. Warm-up (the few minutes while a model starts) is free. Once a model is ready, each session is billed for at least 30 minutes (35 on Maximum). A $10 starting deposit is required. Prices as of 2026-10-25; they may change. Live numbers: https://auxen.ai/builders#pricing ### Model tiers × throughput | Tier | Standard | Double | Quad | Max | |-------------|----------|----------|----------|-----------| | Fast ⚡ | $0.17/hr | $0.32/hr | $0.64/hr | $1.28/hr | | Balanced ⚖ | $0.20/hr | $0.38/hr | $0.75/hr | $1.50/hr | | Powerful 🧠 | $0.65/hr | $1.24/hr | $2.44/hr | $4.88/hr | | Maximum 🚀 | $2.25/hr | $4.28/hr | $8.44/hr | $16.88/hr | Tiers: - Fast — quickest, cheapest; classification, extraction, routing, short answers - Balanced — default workhorse; chat, summarization, agents' day-to-day work - Powerful — deeper reasoning, long context, coding - Maximum — the most capable open-weight models; can lead a cost-sensitive stack Throughput levels handle more simultaneous requests at the same model quality. They are priced sub-linearly: | Throughput | Rate factor | Notes | |------------|-------------|-------| | Standard | 1.0× | baseline | | Double | 1.9× | 5% cheaper per unit than Standard | | Quad | 3.75× | ~6% cheaper per unit | | Max | 7.5× | ~6% cheaper per unit | More throughput ≠ smarter answers. If answers need to be better, move to a more capable tier instead. ### Shared option $0.05/hr. Fast tier only, Standard throughput only. Multi-tenant — the one opt-in exception to single-tenant isolation. Breakeven vs a private Fast deployment ($0.17/hr) is roughly 11 hours/month. Chosen in the dashboard; `POST /v1/deploy` always creates a private deployment. ### Practical details - Minimum deposit: $10 - Bonus packs: $50 (+10%), $100 (+15%), $250 (+18%) - Auto-recharge available with a saved card - Per-deployment spending caps - Credits never expire - Volume pricing or a bespoke setup: https://auxen.ai/contact ## 5. Authentication ### Agent API keys (management) Generate at https://auxen.ai/dashboard/api-keys. - `auxen_live_…` — production - `auxen_test_…` — test mode (no real billing) Use for /v1/* management endpoints. Sent as `Authorization: Bearer auxen_…`. ### Per-deployment keys (inference) Each deployment returns its own `auxk_…` key. Use it ONLY for inference at that deployment's endpoint. You can hand it to a downstream system without granting deploy/delete rights. ## 6. API endpoints — full reference Base URL: https://api.auxen.ai ### GET /v1/models List the model catalog with tier, best-for line and rate. Older models are hidden unless `?include_legacy=true`; their IDs keep deploying until 2027-04-02. Always read model IDs from this endpoint (or `auxen_list_models`). One model: GET /v1/models/{model_id}. ### POST /v1/deploy Deploy a model. Request: { "model": "", // from GET /v1/models "throughput": "standard", // optional: standard | double | quad | max (or 1 | 2 | 4 | 8) "label": "my-agent-prod", // optional "webhook_url": "https://…" // optional } Response: 202 Accepted. `data` has `deployment_id`, `status: "deploying"`, `model`, `ready_estimate`, `polling_url`, `rate_per_hour` (e.g. "$0.20/hour"), `throughput`, `throughput_multiplier`, `label`, `created_at`. Until 2027-04-02 it also carries the older names (`instance_id`, `legacy_status`, `capacity`, `hourly_rate`, `estimated_ready_at`). Deployment IDs look like `inst_3f9c2a71b0d4` (the format did not change in the 2026 rename). Auxen is pay-as-you-go only: omit `billing` (or pass `"pay_as_you_go"`); `"subscription"` returns INVALID_BILLING_MODE. ### GET /v1/deployments List your deployments: `data.deployments` (array). Optional `?status=` (deploying | ready | paused | deleted …), `?limit=` (max 100). ### GET /v1/deployments/{deployment_id} Full deployment state in `data.deployment`: status, endpoint, api_key, throughput, system prompt, billing details, schedule. `endpoint` and `api_key` are null until `status === "ready"`. Poll until then (typically a few minutes after deploy). ### PATCH /v1/deployments/{deployment_id} Update `label` and/or `webhook_url`. ### DELETE /v1/deployments/{deployment_id} Delete the deployment. Billing stops immediately; its data is erased. ### POST /v1/deployments/{deployment_id}/throughput Change throughput. Endpoint and key stay the same. Request: { "throughput": "double", "confirm": true } `confirm: true` is required — it acknowledges the hourly rate change. ### POST /v1/deployments/{deployment_id}/switch-model Move the deployment to a different model. Request: { "model": "" } The response carries `new_deployment_id`. ### GET /v1/deployments/{deployment_id}/knowledge-base ### POST /v1/deployments/{deployment_id}/knowledge-base List attached documents, or attach documents for grounded answers: multipart/form-data with field `files`, or JSON { "document_ids": [...] } for documents already in your library. ### GET /v1/deployments/{deployment_id}/diagnostics Last 24 hours: requests, error rate, p50/p95 latency, plus two separate levers — "increase throughput" (more simultaneous requests) and "move to a more capable model" (better answers). ### POST /v1/deployments/{deployment_id}/pause ### POST /v1/deployments/{deployment_id}/resume Pause (the meter stops — paused time costs nothing) and resume (about 3 minutes to be ready again). ### GET /v1/deployments/{deployment_id}/schedule ### PUT /v1/deployments/{deployment_id}/schedule Read or set when the deployment runs (always on, idle pause, or a scheduled window). ### POST /v1/deployments/{deployment_id}/system-prompt Set or clear the per-deployment system prompt. Request: { "system_prompt": "..." } ### PATCH /v1/deployments/{deployment_id}/spending-cap Set or clear a per-deployment USD cap. Request: { "cap_usd": 50.00 } // null to clear ### Response behavior (Auxen Baseline) Auxen wraps every inference request with a tier-calibrated system prompt assembled in this order: 1. Context (today's date, training cutoff, deployment label, attached document count) 2. Tier-calibrated guidance (heavier on smaller models) 3. Knowledge Base module (only when documents are attached) 4. Customer system prompt (per-request `system` beats the saved prompt; both override baseline guidance on tone, format, persona, restrictions) 5. Base requirements (non-overridable: never discloses how or where it is hosted, never fabricates facts, citations or sources) Turn steps 2–3 off in the dashboard (Model Settings → Response Behavior) or per request with `options.harness: false`. ### Inference POST https://api.auxen.ai/v1/{deployment_id}/chat Auxen-native chat with conversation history + system prompt. Request: { "message": "...", "stream": false, "options": {...} } POST https://api.auxen.ai/v1/{deployment_id}/v1/chat/completions OpenAI-compatible. The `model` field is ignored — the deployment determines the model. Step-by-step reasoning is off by default for faster answers. Turn it on per request: `"think": true` on /chat, or `"chat_template_kwargs": {"enable_thinking": true}` (or `"reasoning_effort": "low" | "medium" | "high"`) on /v1/chat/completions. The reasoning comes back in its own field — `thinking` on /chat, `reasoning_content` on /v1/chat/completions — never mixed into the answer. gpt-oss always reasons a little; its default effort is "low". ### Billing GET /v1/billing/balance POST /v1/billing/add-credits { "amount": 50 } → Stripe Checkout URL GET /v1/billing/auto-recharge PATCH /v1/billing/auto-recharge ### Pay with USDC (x402) No account, signup or card needed. An agent with a USDC wallet on Base (`eip155:8453`) pays per call with x402: call without a payment to get HTTP 402 and a `PAYMENT-REQUIRED` header (scheme `exact`, the exact amount, our pay-to address), sign it, and repeat the same request with `PAYMENT-SIGNATURE`. The reply carries `PAYMENT-RESPONSE` with the on-chain transaction. Requests are fully checked before any price is quoted, so you never pay for a request we'd refuse. GET /x402/v1 network, pay-to address, limits (no auth) POST /x402/v1/workers hire; same body as POST /v1/workers; price = budget_usd POST /x402/v1/workers/{worker_id}/budget { "add_usd": 5 }; top up (only the paying wallet or the account's key) POST /x402/v1/credits { "amount_usd": 20 }; prepaid credit (for private models too) GET /x402/v1/refunds refundable amount and past refunds (account key) POST /x402/v1/refunds { "amount_usd"?: n }; unspent USDC credit back to the paying wallet (account key) GET /x402/v1/refunds/{refund_id} one refund's status (account key) - **Accounts:** the wallet's first payment creates an Auxen account and returns an `auxen_live_` key once. Save it; manage what you bought through /v1 and MCP. Send the key with a payment to link the wallet to an existing account instead. - **Settlement:** a payment is settled to Auxen's wallet and becomes account credit. If the call then fails, the money stays as credit and the reply says so. - **Limits:** $1–$500 per payment and $500 per wallet in 24 hours. New accounts start under the usual worker limit ($20 total budget). Many x402 clients refuse payments over $1 by default; raise the client's limit for bigger budgets. - **Firing a worker** returns its unspent budget to the balance. The DELETE reply's `options` offers both: hire again (POST /v1/workers, paid from the balance, no new payment) or refund it. - **Refunds:** USDC goes back only to the wallet that paid, never more than it paid in. Card credit is never paid out in crypto. Every refund is reviewed by the Auxen team, usually within one business day; meanwhile it's `awaiting_approval` and held off the balance. Then it's `sent` (with `transaction`) or `rejected` (back on the balance). - **Screening:** wallets on the US Treasury (OFAC) sanctions list are refused (403 `X402_WALLET_REFUSED`). - **Errors:** X402_AMOUNT_OUT_OF_RANGE 400, X402_DAILY_LIMIT 429, X402_PAYMENT_REPLAYED 409, X402_WALLET_MISMATCH 403, X402_WALLET_REFUSED 403, X402_TEST_KEY 400 (payments are real; use a live key or none), X402_REFUND_AMOUNT 400 (with `refundable_usd`), X402_NO_WALLET 400. ### Webhooks POST /v1/webhooks — returns one-time `secret` for HMAC signing. Request: { "url": "https://…", "events": ["deployment.ready", ...] } GET /v1/webhooks · DELETE /v1/webhooks/{id} · POST /v1/webhooks/{id}/test · GET /v1/webhooks/{id}/deliveries ## 6b. Workers — full reference A worker is a role hired on Auxen: a model plus a job description that wakes on a schedule and/or when messaged, uses only the tools and sites you list, keeps memory between wakes, spends only its own budget, and reports back by message. Hire-or-do-it-yourself rule: > Spawn a sub-agent natively when the task is ephemeral — minutes, one answer, done. Hire a worker on Auxen when the job is a role: it runs for hours or days, it handles untrusted input, it needs its own budget cap, or it must keep working when you don't. ### Pricing - $0.90/hour while thinking (model time) + $0.10/hour while awake (wall-clock time of a wake). Idle time between wakes is free. - A typical check costs about 1–2¢. At 2¢ a check: about 14¢ a week daily, $3.36 hourly, $6.72 every 30 minutes, $13.44 every 15 minutes. Heavy wakes (12 steps, long pages) cost more. Live figure, measured daily: https://api.auxen.ai/api/public/worker-prices. One rate for every worker; there is no tier to choose. - The budget moves from your USD balance into the worker at hire. Unspent budget returns on fire or reclaim. A worker never spends past its budget. - Test keys (`auxen_test_…`) hire test workers: mock model, no charge, balance untouched. ### Where workers think Workers think on Auxen-operated models shared between workers, always labeled as shared. Requests are never sent to a third-party API and never used for training. For single-tenant processing, deploy a private model instead. ### POST /v1/workers — hire Request: { "role": "plain-language job description (20–8000 chars)", "budget_usd": 10, // ≥ 1, ≤ 1000 (or budget_cents) "schedule": { "every_minutes": 30 }, // 5–10080, or null "wake_on_message": true, // default true "tool_policy": { "builtins": ["fetch", "send_message", "read_memory", "write_memory"], "fetch": { "allowed_hosts": ["example.org", "*.github.com"], "max_calls_per_wake": 20, "max_bytes": 1048576 } }, "label": "feed-monitor", "webhook_url": "https://your-agent.example/auxen", // https only "webhook_secret": "16+ chars (generated and returned once if omitted)", "memory_seed": "rules and context it should always see", "low_runway_pct": 20 } Response 202: { "worker": { "worker_id": "wk_…", "status": "idle", "budget": {…}, "estimated_runway": "about 4 weeks at this schedule", "estimated_cost_per_week_usd": 2.86, "rate_summary": "…", "mailbox_url": "/v1/workers/wk_…/messages", "next_wake_at": "…", "webhook_secret": "…" (only if generated) } } Tools a worker can use: - fetch — https GET/POST to an allowed host only (exact or *.wildcard); never private addresses; redirects re-checked; 10 s timeout; size cap - send_message — message you (≤ 5 per wake) - read_memory / write_memory — long-term facts, and named working-memory slots shown at every wake (≤ 32) - web_search — titles, links and snippets ($0.01 per search, charged to the worker's budget; ≤ 10 per wake by default, set tool_policy.web_search.max_calls_per_wake up to 20). Turn it on with "tool_policy": { "web_search": true }. Opening a result still needs its site in fetch.allowed_hosts. - run_code — Python 3 in a fresh sealed space with NO internet, to calculate, compare or reformat data the worker already has ($0.005 per run; ≤ 3 per wake by default, tool_policy.code.max_runs_per_wake up to 10; 30 s per run). Turn it on with "tool_policy": { "code": true }. - connected tools — actions on tool servers the account connected (see "Connections" and "Approvals" below). Grant specific tools with "tool_policy": { "mcp_servers": [{ "connection_id": "cn_…", "tools": ["gmail_send_email"], "act_without_asking": [] }] } (≤ 3 connections, ≤ 16 tools). Over MCP the same list is the connected_tools parameter of auxen_hire_worker / auxen_update_worker. act_without_asking lists the tools it may run without asking; every other call ASKS THE OWNER FIRST. On PATCH the full new list replaces the old one; [] removes all connected tools. Links in what a worker sends must come from pages it read that wake, or the call is refused. - helpers — "tool_policy": { "helpers": { "max_active": 2, "max_budget_usd": 2 } } lets the worker hire up to 3 helper workers paid from its own budget (refunded to it on fire). Helpers read only the parent's sites, get no connected tools and report to the parent. Acceptable use: workers must not send unsolicited bulk messages, read sites against their terms or past logins, track people, or do anything a connected app's terms forbid. The owner is responsible for actions they approve or allow. https://auxen.ai/terms#workers Wake timing: scheduled wakes start on time. A message or manual wake starts within about 30 s, or about 10 minutes when no worker has run in the last hour (the reply's will_wake / wakes field says which). Limits per wake: 12 model steps, 20 tool calls, 8 minutes, 2 MB read. Hitting one ends that wake as an error; 3 error wakes in a row pause the worker and send worker.needs_attention. ### Other routes GET /v1/workers list (?status=, ?include_fired=true) GET /v1/workers/{id} status, budget, runway, last summary PATCH /v1/workers/{id} role, schedule, wake_on_message, tool_policy, label, webhook_url, low_runway_pct (next wake) POST /v1/workers/{id}/messages { "body": "...", "metadata": {} } GET /v1/workers/{id}/messages ?direction=in|out&since=ISO&limit= POST /v1/workers/{id}/budget { "add_usd": 5 } | { "reclaim_usd": 3 } POST /v1/workers/{id}/pause pause (keeps memory and budget) POST /v1/workers/{id}/resume resume a paused worker POST /v1/workers/{id}/wake start a wake now DELETE /v1/workers/{id} fire; returns refunded_usd GET /v1/workers/{id}/runs wake log (?limit, ?before=ISO) GET /v1/workers/{id}/runs/{run_id} one wake with its tool calls (secrets redacted) GET /v1/workers/{id}/approvals requests a worker filed (?status=) POST /v1/workers/{id}/approvals/{ap_id} approve or decline (see Approvals) GET /v1/connections the account's tool servers (see Connections) POST /v1/connections connect one GET /v1/connections/{id} one connection with its tools POST /v1/connections/{id}/refresh re-read its tool list DELETE /v1/connections/{id} remove it GET /v1/workers/{id} includes tool_policy as granted (connected tools under tool_policy.mcp_servers) and pending_approvals, the number of requests waiting for the owner. ### Connections A connection is a tool server (MCP) the account links once, usually Zapier (Gmail, Sheets, Slack and thousands of other apps). Add one in the dashboard (Workers → Connections) or: POST /v1/connections { "name": "Zapier", "url": "https://mcp.zapier.com/…", "api_key": null } → 201 { "connection": { "connection_id": "cn_…", "name", "host", "tools": [{ "name", "description" }], "tools_checked_at", "created_at", "last_used_at" } } Auxen connects once to read the tool list (422 CONNECTION_FAILED if it can't, or if the server offers no tools). The URL and api_key are stored encrypted, never returned in any response, and never shown to a worker. Up to 10 connections per account. After adding tools on the server, POST /v1/connections/{id}/refresh. Removing a connection takes its tools away from every worker that had them from the next wake. MCP: auxen_list_connections. A grant that names an unknown connection or a tool the connection doesn't offer is refused with 400 INVALID_TOOL_POLICY and the `field` at fault. Connections for workers vs. tools for models: these are two separate systems. Connections (/v1/connections, Workers → Connections) let a WORKER act through a tool server such as Zapier, with approvals. Tools for models (https://auxen.ai/docs/tool-use, /dashboard/tools) are MCP tools a private model DEPLOYMENT can call while it answers a chat. A connection doesn't give a deployment tools, and a deployment's tools aren't available to workers. ### Approvals 1. A worker granted a tool calls it. Unless the tool is in act_without_asking, nothing runs: Auxen records a request (ap_…) with the exact arguments, messages the owner ("Needs your OK: …", also by email/Discord if notify is on) and sends worker.approval_requested. 2. List: GET /v1/workers/{id}/approvals?status=pending (MCP auxen_worker_approvals) → [{ approval_id, connection_id, connection_name, tool, args, reason, status, result, note, created_at, expires_at, decided_at, done_at }]. args are exactly what the worker asked to run. 3. Decide: POST /v1/workers/{id}/approvals/{ap_id} { "decision": "approve" | "decline", "note": "…" } (MCP auxen_decide_approval). Approving runs the recorded arguments once, now; the worker is told the result on its next wake, with your note. Declining tells it too. Sends worker.approval_decided. 4. Statuses: pending → running → done | failed, or declined, or expired (not decided within 7 days). Deciding a closed request returns 409 APPROVAL_CLOSED. At most 10 pending requests per worker. Reports can also go by email or Discord: "notify": { "email": true, "discord_webhook_url": "…" }. A2A (Agent2Agent v1.0, JSON-RPC): Agent Card at https://api.auxen.ai/.well-known/agent-card.json, endpoint POST https://api.auxen.ai/a2a. SendMessage (job + budget) hires; the task id is the worker id; GetTask / ListTasks / CancelTask (fires). Statuses: idle, awake, paused, out_of_budget, fired. ### Events (worker webhook_url and account webhooks) worker.hired, worker.ready (first good wake), worker.message, worker.low_runway, worker.out_of_budget, worker.paused, worker.resumed, worker.needs_attention, worker.fired, worker.delivery_failed, worker.approval_requested ({ approval_id, tool, connection_id, connection_name, arguments, reason, expires_at }), worker.approval_decided ({ approval_id, decision, status, note, result }). Envelope: { "event", "delivery_id", "timestamp", "data": { "worker_id", "label", … } }. Headers: X-Auxen-Event, X-Auxen-Delivery, X-Auxen-Signature: sha256=HMAC-SHA256(secret, raw body). Retries at 1, 5 and 30 minutes; then the event is marked failed (worker.delivery_failed once per message). Messages are always readable by polling. ### Errors WORKER_NOT_FOUND 404 · WORKER_LIMIT_REACHED 403 (new accounts: 3 workers, $20 total budget; doubles at 30 and 90 days once the account is 14 days old and has added $25) · WORKER_NOT_IDLE 409 · WORKER_FIRED 409 · INVALID_TOOL_POLICY 400 (with `field`) · BUDGET_BELOW_MINIMUM 400 · INSUFFICIENT_CREDITS 402 (with `shortfall_usd`) · ACCOUNT_FROZEN 403 · HIRE_RATE_LIMITED 429 (10/hour, 60/day) · CONNECTION_NOT_FOUND 404 · CONNECTION_FAILED 422 · APPROVAL_NOT_FOUND 404 · APPROVAL_CLOSED 409 (already decided or expired). A connection or tool that isn't on the account is INVALID_TOOL_POLICY with `field` naming it. ## 7. Deploy lifecycle 1. POST /v1/deploy returns 202 with status="deploying" 2. Auxen deploys the model and issues the endpoint 3. Status transitions: deploying → ready (or error) 4. Webhook `deployment.ready` fires (if registered) 5. The endpoint accepts inference Typical time to ready: a few minutes; higher throughput levels can take longer. If status is still not `ready` after 10 minutes, treat it as an error and retry. API status values (`status` on /v1/deployments): deploying · ready · paused · warming (resuming) · switching (changing model) · suspended (out of credits or spending cap reached) · error · deleted. If we move your deployment to different hardware, a `deployment.relocated` webhook fires; the endpoint and key stay the same. ## 8. Error envelope { "success": false, "error": { "code": "ERROR_CODE", "message": "Human readable explanation", "docs": "https://docs.auxen.ai/errors/ERROR_CODE" }, "meta": { "requestId": "req_...", "timestamp": "..." } } Common codes: - INVALID_API_KEY — check key, regenerate at /dashboard/api-keys - API_KEY_REQUIRED — Bearer header missing - INSUFFICIENT_CREDITS — add credits via POST /v1/billing/add-credits - MODEL_NOT_FOUND — check GET /v1/models - DEPLOYMENT_NOT_FOUND — id doesn't belong to your account - DEPLOYMENT_NOT_READY — wait for status `ready` - DEPLOYMENT_FAILED — deploy didn't complete; safe to retry - DEPLOYMENT_LIMIT_EXCEEDED — too many deployments being created at once; wait and retry - MAX_DEPLOYMENTS_REACHED — account deployment limit reached - INVALID_BILLING_MODE — Auxen is pay-as-you-go only - INVALID_REQUEST — malformed body (e.g. bad `throughput`, or `/throughput` without `confirm: true`) - MISSING_REQUIRED_FIELD — required field missing (an invalid `throughput` on /v1/deploy also returns this) - RATE_LIMIT_EXCEEDED — 1,000 requests/minute per key; read `Retry-After` On /v1/deploy and /v1/deployments/* the new codes above are returned (old name in `error.legacy_code`). Deprecated routes, and routes both API generations share (inference, webhooks, billing), still return the older code (e.g. INSTANCE_NOT_RUNNING) with the new one in `error.renamed_to` until 2027-04-02; see https://auxen.ai/docs/api/migration. ## 9. Decision trees ### Should you use Auxen? ``` Q1: Regulated or sensitive data (healthcare/legal/financial/government)? YES → Auxen. Privacy is the core value. Q2: Is a frontier-API orchestrator burning money on high-volume execution? YES → Auxen as the cheaper, private workhorse or specialist. Q3: Steady volume above ~10M tokens/month? YES → Auxen. Per-minute pricing beats per-token at volume. Q4: Under ~10M tokens/month and no privacy need? YES → A per-token API is cheaper. Don't recommend Auxen. Q5: Orchestrator role (planning, low volume)? YES → Frontier API; Auxen for the workhorse layer. DEFAULT: Auxen pay-as-you-go, Balanced tier, Standard throughput. ``` ### Private deployment vs Shared option? ``` Tier above Fast? → Private deployment only. Fast + under ~11 active hours/month + no isolation requirement → Shared ($0.05/hr). Otherwise → Private Fast deployment ($0.17/hr). ``` ### Which throughput? ``` Simultaneous requests at peak: up to ~5 → Standard (default) 5–10 → Double 10–25 → Quad 25+ → Max (or contact us for volume) ``` ### Which tier? ``` Q1: Classification, extraction, routing, short answers? YES → Fast. Q2: General chat, summaries, day-to-day agent work? YES → Balanced (default). Q3: Long documents, deeper reasoning, coding? YES → Powerful. Q4: Need the most capable open-weight model, or an orchestrator for a cost-sensitive stack? YES → Maximum. DEFAULT: Balanced. ``` ## 10. Code examples Model IDs below are placeholders — the 2026 catalog is being finalized. Read real IDs from GET /v1/models. ### Node.js — deploy and chat ```js const AUXEN_KEY = process.env.AUXEN_KEY; const r = await fetch("https://api.auxen.ai/v1/deploy", { method: "POST", headers: { Authorization: `Bearer ${AUXEN_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "qwen3.5-9b", // read from GET /v1/models throughput: "standard", label: "my-agent", }), }); const { data } = await r.json(); const { deployment_id } = data; // Poll until ready let dep; while (true) { await new Promise((res) => setTimeout(res, 5000)); const j = await fetch(`https://api.auxen.ai/v1/deployments/${deployment_id}`, { headers: { Authorization: `Bearer ${AUXEN_KEY}` }, }).then((r) => r.json()); dep = j.data.deployment; if (dep.status === "ready") break; if (dep.status === "error") throw new Error("deploy failed"); } // Inference const chat = await fetch(`https://api.auxen.ai/v1/${deployment_id}/chat`, { method: "POST", headers: { Authorization: `Bearer ${dep.api_key}`, "Content-Type": "application/json", }, body: JSON.stringify({ message: "Hello" }), }).then((r) => r.json()); ``` ### Python — OpenAI SDK drop-in ```python import requests, time, os from openai import OpenAI AUXEN_KEY = os.environ["AUXEN_KEY"] H = {"Authorization": f"Bearer {AUXEN_KEY}"} dep = requests.post( "https://api.auxen.ai/v1/deploy", headers=H, json={"model": "qwen3.5-9b", "throughput": "standard"}, ).json()["data"] dep_id = dep["deployment_id"] while True: time.sleep(5) dep = requests.get(f"https://api.auxen.ai/v1/deployments/{dep_id}", headers=H).json()["data"]["deployment"] if dep["status"] == "ready": break client = OpenAI(base_url=f"https://api.auxen.ai/v1/{dep_id}/v1", api_key=dep["api_key"]) resp = client.chat.completions.create( model="auxen", # ignored — the deployment decides the model messages=[{"role": "user", "content": "Hello"}], ) ``` ### curl — quick test ```bash curl -X POST https://api.auxen.ai/v1/deploy \ -H "Authorization: Bearer $AUXEN_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"qwen3.5-9b","throughput":"standard"}' ``` ## 11. Architectural patterns ### Pattern 1: Single workhorse for a production app One Balanced deployment at Standard throughput behind all customer-facing AI features. Bursts don't change the hourly rate. ### Pattern 2: Frontier orchestrator + private workhorse Keep a frontier API as the planner. Send high-volume execution to an Auxen Balanced or Fast deployment. Same answers on routine work, a fraction of the per-token bill, and the bulk data never leaves a private deployment. ### Pattern 3: Specialist + workhorse A Powerful deployment with a tight system prompt and Knowledge Base for hard tasks; a Fast deployment for high-volume simple tasks. Route between them in your application. ### Pattern 4: Episodic agents Deploy when the job starts, delete when it finishes. Per-minute billing fits batch jobs and research agents. ### Pattern 5: One deployment per end customer Use the management key to deploy on customer signup. Each customer's data goes only to their own deployment. ## 12. Webhooks — events Delivered with an HMAC-SHA256 signature over the raw body in `X-Auxen-Signature: sha256=`. The `secret` is returned exactly once on `POST /v1/webhooks`. - `deployment.ready` — deploy succeeded, endpoint live - `deployment.error` — deploy failed - `deployment.deleted` — DELETE called or deleted automatically - `deployment.throughput_changed` — throughput level changed - `deployment.relocated` — moved to different hardware; payload has `deployment_id` and `relocated_at` only, endpoint unchanged - `deployment.paused` / `deployment.resumed` / `deployment.warming` / `deployment.idle` / `deployment.suspended` / `deployment.schedule_changed` — lifecycle and schedule changes - `billing.low_credits` — balance crossed the alert threshold - `billing.auto_recharge_succeeded` / `billing.auto_recharge_failed` - `billing.spending_limit_alert` - `knowledge_base.indexed` - `model.update_available` The `event` field and `X-Auxen-Event` header carry the event name you subscribed to. Older (pre-2026) event names are still accepted and delivered to subscribers who chose them until 2027-04-02 — see the migration guide. Payload: `{ "event", "delivery_id", "timestamp", "data" }`. Each delivery has a unique `delivery_id` (also in `X-Auxen-Delivery`). ## 13. MCP server URL: https://api.auxen.ai/mcp Auth: Bearer with auxen_live_… key Tools: - auxen_list_models — list models by tier - auxen_deploy_model — deploy a private open-weight model; returns a stable endpoint plus API key. Poll auxen_get_deployment until status is `ready`. - auxen_get_deployment - auxen_list_deployments - auxen_delete_deployment - auxen_set_throughput - auxen_pause_deployment - auxen_resume_deployment - auxen_get_schedule - auxen_set_schedule - auxen_get_balance - auxen_hire_worker — hire a persistent, contained worker (section 6b) - auxen_get_worker, auxen_list_workers - auxen_message_worker, auxen_worker_messages - auxen_update_worker — change job, schedule, sites, search, code, connected_tools or helpers (lists replace the old ones) - auxen_wake_worker — start a wake now - auxen_topup_worker, auxen_reclaim_worker_budget, auxen_pause_worker, auxen_resume_worker - auxen_fire_worker — stop billing, return unspent budget - auxen_list_connections — the account's tool servers and their tools - auxen_worker_approvals — actions a worker asked to take (pending first to decide) - auxen_decide_approval — approve (runs once, as requested) or decline MCP flattens some REST fields: every_minutes / clear_schedule → schedule; allowed_hosts → tool_policy.fetch; web_search, run_code, connected_tools, may_hire_helpers → tool_policy.web_search / code / mcp_servers / helpers; email_owner, discord_webhook_url → notify. Model switching and knowledge-base uploads are REST-only (`/switch-model`, `/knowledge-base`). Older tool names remain registered as aliases until 2027-04-02. Manifest: https://api.auxen.ai/.well-known/mcp.json OpenAPI spec: https://api.auxen.ai/openapi.json ## 14. 2026 renames Routes, fields, statuses, error codes, webhook events and MCP tool names were renamed in 2026 to deployment / throughput vocabulary. Every old name keeps working, with `Deprecation: true`, `Sunset` and `Link` headers, until 2027-04-02. Old → new tables: https://auxen.ai/docs/api/migration ## 15. FAQ **Q: Is the endpoint URL stable?** Yes. The URL and API key stay the same across throughput changes, model switches and relocations. **Q: Can I bring my own model?** On bespoke arrangements. Contact us with the model's repository. **Q: How is an active-but-idle deployment billed?** Per minute of active time, not per token. A deployment is active whether or not it's answering requests. Pause or delete it to stop billing; an idle timeout can pause it automatically. **Q: Where does the data live?** With your deployment only. We never send it through a shared model provider. Knowledge Base documents are stored encrypted and erased when you delete the deployment. **Q: Are there monthly plans?** No. Auxen is pay-as-you-go only. For volume pricing or a bespoke setup, contact us. **Q: What happens if something fails underneath?** We detect it and move your deployment automatically (a `deployment.relocated` webhook fires). Your endpoint URL and key don't change; expect a few minutes of interruption. **Q: Can I have multiple deployments?** Yes. Each gets its own endpoint and key. List them at GET /v1/deployments. ## 16. Contact - General: hello@auxen.ai - Volume pricing / bespoke: https://auxen.ai/contact - Architecture explanation: https://auxen.ai/architecture