API

AI Gateway API: one endpoint for chat, batch and embeddings

One OpenAI-shaped endpoint for chat, batch and embeddings, with failover, budgets and your choice of model provider.

What it does

The AI Gateway gives your code one place to ask a model for help. You send a chat request in the familiar OpenAI shape. Takelan picks a provider and model, runs the call and returns the answer.
You can tell the gateway what matters most for a call: cost, latency or quality. If a provider fails with a temporary error, the gateway can try another one. Streaming (server-sent events) is supported.
Start with the Takelan platform default model. Or bring your own provider: OpenAI, Anthropic, Azure AI, a self-hosted Ollama, any OpenAI-style HTTP endpoint, or an on-premises pool of your own devices. Your provider keys are held in Takelan Secrets and are never returned by the API.
Set a tenant budget to cap cost, tokens and request rate. A refused request tells you it is a budget refusal (HTTP 402 or 429), so your code can tell that apart from a model outage.
For long jobs, use async mode. Register a signed webhook, send the request with the subscription id, get a 202 and a request id back, and receive the result at your URL. You can also poll for it or ask for a redelivery.
Routing policy has two modes. "mixed" lets the gateway use any of your providers. "on_prem_only" sends AI only to your own on-premises pool and returns an error if none is available. It never falls back to a cloud provider. Note: the Assistant and Knowledge "ask" path does not follow this policy.
Be aware that prompts and results are stored with the request record, along with token counts and cost, so you can read your history. Do not send data you cannot store.

See how it works

One request, routed by policy

The gateway picks a provider by your hint, can fail over on a temporary error, and refuses past a budget. In on_prem_only mode calls stay on your own pool. The Assistant and Knowledge ask path does not follow this policy.

Long jobs: a signed webhook delivers the result

In async mode the gateway answers 202 with a request id straight away. The result arrives at your URL as a signed webhook; you can also poll or ask for a redelivery.

Example use cases

Add a summarise button to your app

Call chat completions with a short system prompt and the text. Set the priority hint to cost for a quick, cheap answer. No model account of your own is needed to start.

Keep AI inside your own walls

Register an on-premises pool, switch the tenant policy to on_prem_only, and every AI call stays on your devices. If the pool is down you get an error, not a silent cloud call.

Run big jobs overnight

Send a batch or an async chat request with a webhook subscription. Your worker receives each signed result when it is ready, with retries if your endpoint is busy.

Control spend per customer

An MSP sets a budget per tenant. When a tenant hits its cap, calls stop with a clear 402, and an alert event is raised as the cap gets close.

Try it

Chat completion with a routing hint

curl -X POST https://app.takelan.com/api/v1/ai/chat/completions \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "Answer in one short paragraph."},
      {"role": "user", "content": "Why do backups need a restore test?"}
    ],
    "hints": {"priority": "cost"},
    "idempotency_key": "restore-test-001"
  }'

Idempotency keys are remembered for 24 hours, so a retry will not run the call twice.

Async result by signed webhook

# 1. Register a webhook subscription (HTTPS URL required)
curl -X POST https://app.takelan.com/api/v1/ai/webhook-subscriptions \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "nightly-summaries", "url": "https://example.com/hooks/ai",
       "events": ["chat.completed", "chat.failed"]}'

# 2. Send the request with the subscription id. You get HTTP 202 and a request id.
curl -X POST https://app.takelan.com/api/v1/ai/chat/completions \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Summarise the attached log."}],
       "webhook_subscription_id": "<subscription-id>"}'

Each delivery is signed with HMAC-SHA256 in the X-Signature-256 header, and carries X-Request-Id and X-Webhook-Attempt headers. You cannot combine stream=true with a webhook subscription.

Pin AI to your own devices

curl -X PUT https://app.takelan.com/api/v1/ai/tenant-policy \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"routing_policy": "on_prem_only"}'

Endpoints

POST /api/v1/ai/chat/completions OpenAI-shaped chat. Sync, streaming (SSE) or async by webhook subscription.
GET /api/v1/ai/chat/completions/{request_id} Poll the status and result of an async chat request.
POST /api/v1/ai/chat/completions/{request_id}/redeliver-webhook Ask for a signed webhook delivery to be sent again.
POST /api/v1/ai/inference Single prompt in, text out. Immediate or queued.
POST /api/v1/ai/batch Submit up to 100 inference requests in one call.
GET /api/v1/ai/status/{request_id} Check one inference request.
DELETE /api/v1/ai/cancel/{request_id} Cancel a queued request.
GET /api/v1/ai/history List your past requests, with filters and pages.
GET /api/v1/ai/stats Usage statistics for your tenant.
GET /api/v1/ai/models List the models you can use right now.
POST /api/v1/ai/embeddings Create vectors. Use a provider-prefixed model such as ollama:, openai: or agent_pool:. Vectors are cached per tenant.
POST /api/v1/ai/embeddings/search Similarity search over your stored embeddings.
POST /api/v1/ai/providers Register your own provider. Keys are stored in Takelan Secrets.
GET /api/v1/ai/providers List your providers.
PATCH /api/v1/ai/providers/{provider_id} Change a provider.
DELETE /api/v1/ai/providers/{provider_id} Remove a provider.
GET /api/v1/ai/tenant-policy Read the routing policy: mixed or on_prem_only.
PUT /api/v1/ai/tenant-policy Set the routing policy.
GET /api/v1/ai/tenant-budget Read cost, token and rate ceilings. A null ceiling means uncapped; 0 means every request is refused.
PUT /api/v1/ai/tenant-budget Set the ceilings.
GET /api/v1/ai/tenant-budget/usage See current usage against the budget.
GET /api/v1/ai/tenant-budget/events Budget alert events as the cap gets close or is reached.
POST /api/v1/ai/webhook-subscriptions Create a signed webhook subscription for async results.
GET /api/v1/ai/webhook-subscriptions List webhook subscriptions.
POST /api/v1/ai/webhook-subscriptions/{subscription_id}/rotate-secret Rotate the signing secret.
GET /api/v1/ai/agent/config Read the on-premises agent setup (OpenAI, Anthropic, Azure, Ollama or compatible).
PUT /api/v1/ai/agent/config Set the agent setup. Call with pipeline "agent" to use it.

MCP

The Utils MCP server at https://app.takelan.com/mcp/utils exposes these routes as tools. Reads are on by default. Anything that spends AI credit counts as a write, so it needs the tenant writes switch and a key that is not read-only. Webhook secret routes are treated as sensitive and are hidden. About MCP

Common questions

Is there an OpenAI-compatible chat API I can call with one key?

Yes. POST /api/v1/ai/chat/completions takes OpenAI-shaped messages and is routed by Takelan to the platform default model or to a provider you registered. You authenticate with the same Takelan API key or token you use for the other APIs.

Can I bring my own OpenAI, Anthropic or Azure key?

Yes. Register a provider for OpenAI, Anthropic, Azure AI, Ollama, or any OpenAI-style or Anthropic-style endpoint. The key is stored in Takelan Secrets and is never returned by the API. Calls then go to the provider you chose.

Can I keep AI on my own servers?

Yes. Register an on-premises pool of your own devices and set the tenant routing policy to on_prem_only. Requests only go to that pool, and you get an error if none is available. The Assistant and knowledge "ask" path do not follow this policy.

Are my prompts stored?

Yes. The request record keeps the prompt, the result, token counts and cost so you can read your history. There is no retention setting, so do not send data you cannot have stored.

How do I stop AI costs running away?

Set a tenant budget with cost, token and request-rate ceilings. Calls past a ceiling are refused with HTTP 402 or 429 and a clear budget error, and alert events are recorded as you approach the cap.

How do async results and webhooks work?

Create a webhook subscription with an HTTPS URL, then send a chat request with its id. You get HTTP 202 and a request id. The result is posted to your URL, signed with HMAC-SHA256, with retries and backoff. You can also poll the request id or ask for a redelivery.

Which models can I use?

Call GET /api/v1/ai/models to see what is available to your tenant. The platform default runs on Takelan-operated model hosts. Models from your own providers appear once you register them.

Is there an SDK?

No Utils or AI SDK exists yet. Use plain HTTP with curl or any HTTP client. The OpenAI-shaped body makes it easy to adapt existing code.

All API families | Takelan AI | Pricing