API Reference

Arc sits between your application and AI providers (OpenAI, Anthropic, etc.). You make the same API calls you already make — Arc handles routing, logging, caching, and fallback silently in the middle.

Two changes to your existing code:

- base_url = "https://api.openai.com/v1"
+ base_url = "https://api-arc.cornerstone.sh/v1"

- api_key = "sk-..."
+ api_key = "arc_live_..."

Everything else stays the same. Arc is fully OpenAI-API-compatible — the same request format, the same response format, streaming included.

Get your Arc key from the dashboard, add your provider API key, then make your first request:

curl https://api-arc.cornerstone.sh/v1/chat/completions \
  -H "Authorization: Bearer arc_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

The response is identical to OpenAI's. Arc logs the request in the background — token counts, cost, latency, provider — without adding meaningful latency.

Arc uses Bearer token authentication. Pass your Arc key in the Authorization header on every request.

Authorization: Bearer arc_live_<your-key>

Arc authenticates you, then uses your workspace's stored provider key to forward the request upstream. Your OpenAI or Anthropic key never leaves Arc's servers.

Routes let you tag requests so Arc can apply per-route configuration: a default model, a system prompt, caching rules, and fallback behaviour. Tag a request by passing the X-Arc-Route header.

curl https://api-arc.cornerstone.sh/v1/chat/completions \
  -H "Authorization: Bearer arc_live_<your-key>" \
  -H "X-Arc-Route: customer-support" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "I need help with my order." }] }'

If a route has a primary model configured, you can omit the model field entirely — Arc injects it automatically.

// No "model" field needed if your route has one configured
{
  "messages": [{ "role": "user", "content": "Summarise this document..." }]
}

Requests without X-Arc-Route are logged as Direct — they still work, they just don't inherit any route-level configuration.

Each route can have a system prompt configured in the dashboard. When set, Arc prepends it as a system message at the start of your messages array — before anything your application sends.

// Route "joke" has system prompt: "Make a joke about the following topic."
// Your application only needs to send the topic:

POST /v1/chat/completions
X-Arc-Route: joke

{ "messages": [{ "role": "user", "content": "software engineers" }] }

// Arc sends to provider:
// [
//   { "role": "system", "content": "Make a joke about the following topic." },
//   { "role": "user",   "content": "software engineers" }
// ]

To skip injection for a specific request — for example when your application is already providing its own system prompt — add the opt-out header:

X-Arc-No-Inject: 1

Arc can maintain per-user conversation memory across requests. Memory is stored in a pool — a configurable bucket attached to a route in the dashboard. Each pool tracks a rolling window of recent turns plus a compressed summary generated automatically when the window fills.

To enable memory, attach a pool to a route in the dashboard, then pass a client identifier on each request. Arc handles injection automatically — no changes to your messages array needed.

X-Arc-Client-ID: user_12345

Alternatively, pass the client ID in the OpenAI user field of the request body. The header takes precedence if both are present.

{
  "model": "gpt-4o",
  "user": "user_12345",
  "messages": [{ "role": "user", "content": "What did we discuss last time?" }]
}

Arc prepends the memory context (summary + recent turns) into the messages array before forwarding to the provider. The assembled messages are never stored — only the metadata and the rolling window.

Arc supports two caching modes, configured per-route in the dashboard:

Cache hits are logged in the dashboard. The cache_hit field appears in request logs and analytics, so you can measure hit rate per route. Message bodies are never stored in the cache — only embeddings and responses.

Routes can enforce a request rate limit. When a limit is exceeded, Arc either rejects the request or passes it through with a warning header — configurable per route.

When the action is reject, Arc returns a 429 with standard rate limit headers:

HTTP/1.1 429 Too Many Requests
Retry-After: <unix-timestamp>
X-Arc-Rate-Limit-Remaining: 0
X-Arc-Rate-Limit-Reset: <unix-timestamp>

{ "detail": "Rate limit exceeded" }

When the action is warn, the request is forwarded normally and the response includes:

X-Arc-Rate-Limit-Warning: true

Smart Tier routes each request to a different model based on how complex the request is — automatically, without any changes to your application. A lightweight complexity score (0–1) is computed from the messages on every request in under a millisecond.

A typical tier configuration looks like this:

[
  { "label": "simple",   "complexityMax": 0.35, "model": "gpt-4o-mini" },
  { "label": "standard", "complexityMax": 0.75, "model": "gpt-4o"      },
  { "label": "complex",  "complexityMax": 1.00, "model": "gpt-4o"      }
]

Arc selects the first tier where the request's complexity score falls at or below complexityMax. A short, simple question routes to gpt-4o-mini; a multi-step technical request routes to gpt-4o. The model field in the response reflects whichever model was used.

Smart Tier is configured per-route in the dashboard Config tab. It can also be enabled automatically via Auto-Tune — Arc shadows candidate models in the background, evaluates response quality with an AI judge, and surfaces a one-click suggestion when savings exceed 20% with quality above 85/100.

Arc logs the country of origin for each request. By default it reads the country of the server making the API call (your backend). To log the end user's country instead, forward their IP address in the standard X-Forwarded-For header.

X-Forwarded-For: <end-user-ip>

Arc performs an async geo-lookup on that IP and stores the country code — it does not add latency to your request. The lookup happens in the background after the response is returned to you.

// Node.js / Express example
const userIp = req.headers['x-forwarded-for']?.split(',')[0] ?? req.socket.remoteAddress

await fetch('https://api-arc.cornerstone.sh/v1/chat/completions', {
  headers: {
    'Authorization': `Bearer ${process.env.ARC_KEY}`,
    'X-Arc-Route': 'customer-support',
    'X-Forwarded-For': userIp,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ messages }),
})