AI Gateway API

Overview

Embedding an AI provider key inside a mobile app makes it publicly extractable — keys shipped in binaries are routinely harvested and abused. The gateway removes the key from the client entirely: the app sends a task name and a message, and the gateway holds the provider key encrypted server-side, enforces a per-app task allowlist, applies rate limits, and streams the model's answer back.

• Task allowlist — a client can only name a task. The model, output cap, streaming/JSON permission, temperature ceiling, and safety settings are decided server-side per task. Capabilities outside the allowlist (e.g. image generation, arbitrary model selection) do not exist on this API surface.
• Two auth modes per app — public for mobile clients (app id only; nothing secret ships in the binary) and token for server-to-server callers (a revocable bearer token kept in server secrets).
• Operator controls — keys, tasks, tokens, rate limits, and a per-app kill switch are managed at runtime in a private portal; no client release is needed to rotate a key or pause traffic.

Authentication

Every request carries X-App-Id. Whether a bearer token is also required depends on the app's operator-configured auth mode:

POST /v1/invoke

The single proxy endpoint. Send a task name and a message; receive the model's answer as JSON or as a Server-Sent-Events stream.

Request headers

# public mode
X-App-Id: your-app-id
Content-Type: application/json

# token mode
X-App-Id: your-app-id
Authorization: Bearer amp_your-app-id_XXXXXXXX
Content-Type: application/json

Request body

Example request

{
  "task": "chat",
  "message": "Summarize this in one sentence: …",
  "history": [
    { "role": "user",  "text": "…" },
    { "role": "agent", "text": "…" }
  ],
  "generationConfig": { "temperature": 0.3, "maxOutputTokens": 1024 },
  "stream": false,
  "clientId": "6f1c9c1e-anon-install-uuid"
}

Response — single-shot

{
  "text": "…the model's answer…",
  "usage": { "promptTokens": 132, "outputTokens": 456 }
}

Streaming

With "stream": true (on tasks that allow it) the response is text/event-stream. Each frame is a JSON object:

data: {"token":"The "}
data: {"token":"answer "}
data: {"token":"continues…"}
data: {"done":true}

# on a mid-stream failure the gateway emits one error frame, then closes:
data: {"error":"upstream_error"}

Concatenate token values in order; treat done as end-of-message; surface error frames through your app's normal degraded-state handling.

GET /v1/health

Unauthenticated liveness probe.

{ "ok": true, "service": "almaqdisi-ai-gateway", "ts": "2026-07-18T12:00:00.000Z" }

Errors

Every non-2xx response uses one standardized envelope. Branch on code, never on message:

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry later." } }

Rate limits

Two fixed windows are checked on every request, and both must pass:

• Per client — each task has a per-minute allowance, bucketed by clientId (or IP when absent). Send a stable anonymous clientId so one heavy user cannot exhaust the shared IP bucket.
• Per app — a global per-minute ceiling across all of an app's clients.

A 429 response includes a Retry-After header (seconds). Back off and retry after that interval.

Code examples

Mobile app — public mode (zero build-time credentials)

const res = await fetch('https://api.almaqdisiproductions.com/v1/invoke', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Id': 'your-app-id', // the only identity the build carries
  },
  body: JSON.stringify({ task: 'chat', message, history, stream: true }),
});

Server-to-server — token mode

const res = await fetch(`${process.env.AI_GATEWAY_URL}/v1/invoke`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.AI_GATEWAY_APP_TOKEN}`,
    'X-App-Id': 'your-app-id',
  },
  body: JSON.stringify({ task: 'ragAnswer', message: combinedPrompt }),
});
const { text } = await res.json();