API reference.
Protocol spec.

ACE uses two credentials that do two different jobs. Conflating them is the most common integration error.

Provider key resolution.

Pass-through header on this request → your tenant's stored vendor key → reject. Pass-through keys are used for that one call and never persisted or logged (zero-knowledge mode), so there is nothing to onboard if you always send one.

Key prefixes.

Two prefixes count as an ACE key: ace_dev_ (what the dashboard mints, and what every key you hold looks like) and ace_tok_ (env-seeded deployment keys). A credential starting with neither is treated as a provider key, leaving the request with no ACE identity — which is a 401.

Vendor-shaped surfaces.

The vendor-shaped surfaces accept the ACE dev key on the header their SDK already sends, which is what makes the drop-in one line: /anthropic/v1/messages reads x-api-key, /azure/openai/… (chat completions and /azure/openai/v1/responses alike) reads api-key, and /v1/responses reads Authorization: Bearer exactly as /v1/chat/completions does. An ACE key prefix there is your ACE identity; any other value is treated as a pass-through provider key.

Precedence.

An Authorization: Bearer header you set yourself always wins. Sending both is the normal pass-through shape — bearer carries your ACE identity, x-api-key / api-key carries the provider credential. A synthesized value only ever fills a gap; nothing overwrites a header you set.

ACE acts as an intelligent proxy gateway. Requests authenticate using your ACE Developer Key, while upstream provider credentials can be passed dynamically via headers (Zero-Trust Mode) or attached server-side via the Cloud Provider Vault.

The response body is byte-shape unmodified — a standard OpenAI chat.completion object — so existing SDKs parse it with zero changes. Everything ACE-specific rides on headers.

The x-ace-warnings codes:

The skill latency ceiling. Every heavy stage on the request path — pii_ner, semantic_cache (the embed and the vector-store query), prompt_compaction, llm_router and the injection guard's learned stage — runs under a wall-clock ceiling measured by the request itself: 250 ms for a stage the key runs in prod, 50 ms for one it runs in shadow. A stage that has not answered by then is shed: the request is served without it, the response says so on the header that stage already reports through, and the trace stage carries reason, waited_ms and ceiling_ms. It is a bound on one request's wait, not a quota. Nothing accumulates across calls, there is nothing to reset, and the next request is judged on its own clock.

GET /api/v1/settings reports the effective ceilings under skill_ceiling (per skill, acting and shadow, with the worker pool that runs them); GET /healthz reports the pool as it stands — what is queued, what is running and for how long, and everything shed so far by reason. A gateway shedding at ceiling_exceeded with nothing queued and a job running for minutes has a wedged worker; one shedding at loop_stalled has a held loop; neither is load, and neither is your key.

This header set is frozen legacy: nothing in it is going away without notice, and nothing new is being added. A flat string cannot carry what a shadow skill measured, and on a streamed request x-ace-cost-usd is written before the first token exists — an estimate reported as fact. Both are why /v1/execute exists; new skills report on its trace.

Every vendor-shaped surface — /v1/chat/completions, /v1/responses, /anthropic/v1/messages, /azure/openai/…, /gemini/v1beta/…, /bedrock/converse — is a compatibility shim over the same engine, and each one makes the same promises.

Request.

The body you send is the body the provider receives, byte for byte except inside the text spans a lever rewrote. Thinking configuration and signed thinking blocks, `cache_control` breakpoints, images, documents, tool definitions, tool results, Gemini `thoughtSignature` parts and Bedrock `reasoningContent` all travel as you wrote them. Nothing on this path is parked, projected into another vendor's schema, or silently dropped — and the levers that would invalidate a signature or a cache prefix stand down when one is present.

Response.

The provider's answer comes back as the provider sent it, buffered or streamed. On Anthropic that is the full event vocabulary — `thinking_delta`, `signature_delta`, `redacted_thinking`, `ping`, a mid-stream `error`, the cache counters on `message_start` and the vendor's own `msg_` id. On Gemini it is every `thought` part and `thoughtSignature`, `thoughtsTokenCount`, `cachedContentTokenCount`, `groundingMetadata` and `responseId`. On Bedrock it is the signed `reasoningContent`, the cache counters and `metrics`. Usage is metered from a copy of the stream, so accounting can never alter it. A response the vendor produced also carries the vendor's own rate-limit headers verbatim — `anthropic-ratelimit-*`, `x-ratelimit-*`, `retry-after` and its request id — buffered or streamed; see Response Headers.

Attachments.

Images, PDFs and audio reach the provider, whichever provider that is. On a provider surface the part arrives by construction, because the body is relayed as written. When ACE translates — an OpenAI-shaped /v1/chat/completions or /v1/execute request served by Anthropic, Gemini, Vertex or Bedrock — every attachment is rewritten into the destination's schema: `image_url` becomes an Anthropic `image`, a Gemini `inlineData` or a Converse `image`; a `file` part (a PDF, base64 or `file_url`) becomes an Anthropic `document`, a Gemini `inlineData` or a Converse `document`; `input_audio` becomes a Gemini `inlineData`. What the destination cannot receive — audio to Anthropic or Bedrock, a URL image to Bedrock (Converse takes bytes, and ACE does not fetch URLs for you), a document type the provider does not read, an OpenAI `file_id` sent anywhere but OpenAI — is a 400 naming the part and the provider, raised before anything goes upstream. An attachment is never dropped silently. The one place one legitimately leaves a request is trajectory compaction, which replaces whole earlier turns with a summary; the current and retained turns keep theirs.

No cross-provider failover.

A request written in one vendor's format is only ever served by that vendor's channel. It never fails forward to another provider, even when your vault holds keys for two channels that serve the same model — an Anthropic Messages body is never posted to Bedrock Converse on an Anthropic 503.

The Responses API.

The OpenAI Responses API is a surface of its own: `POST /v1/responses`, and for Azure `/azure/openai/v1/responses`, `/azure/openai/responses?api-version=…` and `/openai/v1/responses` (the Azure SDKs have used all three). It is what an OpenAI or Azure client posts for GPT-5 — `client.responses.create(...)`, or the AI SDK's `@ai-sdk/openai` / `@ai-sdk/azure` providers, which default to it — and chat completions cannot carry it: the body is item-based, `reasoning.summary` has no chat equivalent, and `store: false` + `include: ["reasoning.encrypted_content"]` is how a Zero-Data-Retention org keeps reasoning continuity across turns. The `input[]` items (`reasoning` items with `encrypted_content`, `function_call` / `function_call_output`, `input_image` and `input_file` data URLs), `tools`, `tool_choice`, `reasoning`, `store`, `include`, `max_output_tokens` and `stream` go upstream as sent; the Responses object comes back verbatim, and `stream: true` relays the provider's own `response.*` event stream. A Responses body can only be served by OpenAI or Azure. Pinned to any other provider (`x-ace-provider: anthropic`, say) it is refused with a 400 naming the reason, in OpenAI's error envelope — never rewritten into chat completions you did not write. A request the semantic cache or an in-fleet model answers is projected into a Responses object (`output[]` of `message` and `function_call` items) so the SDK still parses it; those paths never produce a `reasoning` item.

Anthropic count_tokens.

`POST /anthropic/v1/messages/count_tokens` (and `/v1/messages/count_tokens`) relays the body to Anthropic with the credential the call carries — the zero-trust header, a non-ACE `x-api-key`, or your stored Anthropic key — and returns the vendor's count, status included, so a vendor 400 naming a bad block reaches you as such. With no Anthropic credential anywhere the local estimate answers, which cannot count an image, a PDF or a tool schema the way the model's tokenizer does. Echo is decided first: a key in echo mode, or a request sending `x-ace-mode: echo`, is never relayed whatever credential it carries — the estimate answers with `x-ace-served-by: echo` and `x-ace-warnings: echo_fallback`, so a placeholder key sent while testing cannot reach the vendor.

The one exception.

POST /v1/messages is the exception, and it is not the recommended proxy: it exists for parity testing, not production traffic. Being a relay, it preserves however you presented your credential and never rewrites it — and it forwards the body unmodified, so no ACE lever runs on it. Production Anthropic traffic belongs on /anthropic/v1/messages, which accepts the same SDK, carries thinking, tools, images and cache_control as sent, returns Anthropic's own answer, and gets the full lever set.

Each skill runs in one of three modes per developer key, set on the Optimization Skills page. Onboard in shadow first, promote once the numbers justify it.

Errors share one envelope:

{"error": {"message": "...", "type": "invalid_developer_key", "code": 401}}

/v1/execute refuses differently. A validation failure is {"detail": {"error": "...", "field": "input.messages"}} and a locked-skill override is {"detail": {"error": "skill_locked", "locked": [...]}}. Both still carry x-ace-error (request_error and skill_locked respectively).

Guardrail detection values. A guardrail_violation carries a detected field naming what fired — instruction_override, role_reassignment, secret_exfiltration, system_prompt_probe from the always-on regex stage, and learned_injection from the optional classifier. The four regex values come from the always-on stage. `learned_injection` comes from the optional classifier and only appears on a deployment that has moved it out of its default shadow mode (ACE_GUARDRAILS_MODEL_MODE=enforce). In shadow — the default — the classifier never produces a 400 and never alters the response.

ACE never blocks traffic on its own accounting. No spend threshold, quota or internal limit turns a request into an error. Whenever ACE cannot compute — a metering ceiling, a telemetry blip, a skill that fails to evaluate — it degrades to direct passthrough: relayed straight to your provider, pipeline bypassed, normal 200, upstream body untouched. Errors originate at the edge (auth) or upstream (provider), never from the optimization layer.