Version: Current

Migrating a client to acumen

import StatusPill from ‘../../../components/StatusPill.astro’;

This guide covers everything you need to migrate your client to acumen. It consolidates guidance from multiple sources into a single reference.

Prerequisites

Before migrating, ensure you have:

An acumen instance running (see first request)
A virtual key with appropriate scopes (see authentication)
The base URL: http://127.0.0.1:4020 (loopback) or https://ai.tcp.systems (public, verified 2026-10-21)

Base URL change

acumen serves on a different base URL than most providers:

Old: https://api.openai.com/v1
New: http://127.0.0.1:4020/v1  # loopback
     or
     https://ai.tcp.systems/v1   # public, TLS terminated at edge

Key handling

acumen uses virtual keys instead of provider keys:

Old: sk-... (OpenAI) or xai-... (Anthropic)
New: vk_... (acumen virtual key)

Key management:

# Create a key (admin scope required)
curl -X POST http://127.0.0.1:4020/v1/router/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-client","scopes":["chat"],"daily_usd":10}'

# Use the key in requests
curl -X POST http://127.0.0.1:4020/v1/chat/completions \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"cheap","messages":[{"role":"user","content":"hello"}]}'

Model aliases and dialects

acumen provides public model aliases instead of vendor model IDs.

Public aliases

auto: Default routing picks based on cost and availability.
cheap: Lowest cost option, typically GPT-3.5 tier.
coding: Optimized for code generation.
reason: Strong reasoning capabilities, typically GPT-4 tier.
vision: Image-capable models.
search: Search-enhanced models.

OpenAI dialect

acumen speaks OpenAI API natively:

{
  "model": "cheap",
  "messages": [
    {"role": "user", "content": "Hello world"}
  ],
  "stream": false
}

Anthropic dialect

For Anthropic-shaped requests, use /v1/messages:

{
  "model": "cheap",
  "messages": [
    {"role": "user", "content": "Hello world"}
  ],
  "max_tokens": 1000
}

Served-Model transparency

acumen tells you which model actually answered your request via the X-Acumen-Served-Model header (added 2026-11-04):

HTTP/1.1 200 OK
X-Acumen-Served-Model: gpt-5.3-codex
Content-Type: application/json

This helps you understand routing decisions and debug cost variations.

Streaming

Streaming works similarly to OpenAI:

curl -X POST http://127.0.0.1:4020/v1/chat/completions \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"cheap","messages":[{"role":"user","content":"hello"}],"stream":true}'

The response is text/event-stream with OpenAI-formatted chunks.

Error handling and retries

acumen has specific retry behavior.

Circuit breaking

If a provider returns 429 or times out, acumen opens the circuit for that provider.
Subsequent requests retry the next available provider.
The same deployment is not retried immediately.

Retry timeouts

free or subscription seats: 30s circuit hold.
prepaid seats: 60s circuit hold.
Vendor Retry-After headers are not honored.

Common error codes

Status	`X-Acumen-Denied-By`	Meaning
401	`key`	Invalid or unknown virtual key
403	`scope`	Missing required scope
403	`model`	Model not on allowlist
429	`rate`	Rate limit exceeded
502	-	All providers failed or exhausted
503	-	No eligible provider available

Limits and plan windows

acumen enforces limits at multiple levels.

Rate limits

RPM (requests per minute) and TPM (tokens per minute) per key.
Windows reset on process restart.

Spend caps

Daily and monthly USD limits per key.
Hard stops (402) when exceeded.

Model-specific limits

Context window and max output vary by model.
See /v1/models for exact values per provider.

Failover behavior

acumen automatically fails over between providers:

Bandit routing: Routes to cheapest available provider by default.
Circuit breaking: Opens circuits for failing providers.
Seat ranking: Eligible seats ranked by catalog order and price.
No retries: Same request never retried on same deployment.

Failover indicators

X-Acumen-Served-Model shows which model actually answered.
Check /v1/router/stats for circuit states and recent decisions.
Monitor /v1/router/analytics for failover counts.

Migration checklist

Change base URL to acumen endpoint.
Replace provider keys with virtual keys.
Update model names to public aliases.
Handle X-Acumen-Served-Model header for logging.
Implement retry logic for 502 errors.
Monitor rate limits and spend caps.
Test both OpenAI and Anthropic dialects if needed.