API & SDKs

The core exposes two APIs on the same port, both under /v1/:

• Runtime API · for your applications

  ---

  Provider-native gateways under /v1/proxy-apps/<app-id>/…. Point the official OpenAI or Google SDK at them, authenticate with an ax_… key, change nothing else.

  Proxy apps & gateways · SDK examples

• Management API · for the console and automation

  ---

  Users, roles, providers, models, proxy apps, API keys, statistics and traces. JSON, bearer tokens, role-based permissions. Everything the web console does goes through it.

  Authentication · Endpoints

Concepts

flowchart LR
    P[Provider<br/>OpenAI · Azure OpenAI · Google AI Studio · Vertex AI] --> M[Models<br/>name · prices · scopes]
    M -->|allow-list + default| A[Proxy app<br/>status · budget · policies]
    A --> K[API keys<br/>ax_… · scoped to one app]
    K --> C[Your application]

Concept	What it is
Provider	An account at an LLM vendor with its credentials, stored encrypted. Types: openai, azure-openai, google-aistudio, google-enterprise (Vertex AI).
Model	A deployed model of a provider, with input/output prices per million tokens used to compute cost. Can be global or scoped to specific apps.
Proxy app	The unit your applications talk to. Has an allow-list of models, a default model, a budget and a policy document (cache, firewall, DLP). States: draft → ready → inactive.
API key	ax_ + 40 hex. Belongs to one proxy app. Optional expiry.
Gateway	A path under the proxy app that speaks one vendor's protocol: /openai, /gemini, /vertex.

Response conventions (management API)

{ "status": true, "data": { … }, "total": 42 }
{ "status": false, "error": { "code": "VALIDATION_ERROR", "message": "…", "details": [ { "field": "name", "message": "Required" } ] } }

code	HTTP
VALIDATION_ERROR	400
UNAUTHORIZED	401
FORBIDDEN	403
NOT_FOUND	404
CONFLICT, LAST_SUPER_ADMIN	409
INTERNAL_ERROR	500

Malformed JSON is 400 Malformed JSON body; a body over 10 MB is 400 Request body is too large; an unknown route is 404 Route not found. Database constraint violations map to 409 Duplicate value for: <column>, 409 Record is referenced by other records or 404 Related record not found.

Errors on the runtime API are different: they are returned in the provider's own error format so SDKs can parse them. See Proxy apps & gateways.