Unified API (OpenAI compat)

Truememory AI Gateway offers an OpenAI-compatible /v1/chat/completions endpoint, enabling integration with multiple AI providers using a single URL. This is a drop-in replacement for OpenAI, Cloudflare AI Gateway, or LiteLLM — change the base URL and it works.

Authentication

All requests require a Bearer token in the Authorization header. See Ways to authenticate for how to get one.

Endpoint URL

POST /v1/chat/completions

Switch providers by changing the model parameter. For example: anthropic/claude-sonnet-4-5, openai/gpt-5.1, vertexai/gemini-2.5-flash.

Parameters

Custom Prompt Mode

If you want to replace the agent’s built-in prompt with your own instructions, send a system or developer message in the messages array.

When Truememory sees one of those roles, your message replaces the agent’s base instructions for that request:

• your system or developer message becomes the top-level instruction instead of the agent’s built-in prompt
• Truememory still injects persistent memory context so the model knows what it remembers about the user
• Truememory still injects the active persona (if any)
• thread history and turn recording still work normally
• client-defined tools in the tools parameter still work

This is useful when you want full prompt control for a specific request while keeping Truememory’s memory and conversation features.

Example: caller-owned prompt

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "openai/gpt-5.1",
    "messages": [
      {"role": "developer", "content": "You are a concise support assistant. Answer in 3 bullet points max."},
      {"role": "user", "content": "How do I rotate an API key?"}
    ]
  }'

Examples

A minimal request — memory and the active persona are injected automatically, nothing extra to send:

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "What did I say I was working on?"}]
  }'

With "stream": true, tokens arrive as SSE chunks in the standard OpenAI shape — content lives in choices[0].delta.content, and the stream ends with a finish_reason chunk followed by data: [DONE]:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711234567,"model":"anthropic/claude-sonnet-4-5","choices":[{"index":0,"delta":{"content":"Hel"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711234567,"model":"anthropic/claude-sonnet-4-5","choices":[{"index":0,"delta":{"content":"lo!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711234567,"model":"anthropic/claude-sonnet-4-5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Use the interactive picker below for per-language variants (OpenAI SDKs, Vercel AI SDK, cURL) and image inputs:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "$TOKEN",
  baseURL: "https://your-tie-host/v1",
});

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4-5",
  messages: [{ role: "user", content: "What is the capital of France?" }],
});

console.log(response.choices[0].message.content);

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711234567,
  "model": "anthropic/claude-sonnet-4-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0
  },
  "metadata": null
}

If metadata was included in the request, it is echoed back here.

Understanding the usage object

Every time you call the AI, it counts the pieces of text (called tokens) that go in and out. You pay your provider for these tokens, so the usage object is how you know what just got spent.

Think of it like a taxi meter: prompt_tokens is how far you rode in, completion_tokens is how far the AI drove back, and total_tokens is the full fare.

Features

Request-level capabilities — each has its own page under Features:

• Prompt caching — reuse a stable prompt prefix at up to 10x lower cost
• Vision (image input) — send images via content parts
• Tool calling — client-defined functions the model can call
• Custom metadata — key-value pairs persisted with the thread
• Message compression — summarise long histories to save tokens
• Skill instructions — additive caller-composed skill prompts

Threads

Pass a thread_id to maintain conversation state across requests. Truememory uses it to persist the message history so the LLM has context from previous turns.

• If omitted, Truememory auto-generates a UUID for the thread. Each request starts a new conversation.
• If provided, Truememory resumes the conversation from where it left off. Use any string (e.g. a UUID you generate client-side).

See Threads for the full API reference (list, rename, delete, history).

Streaming Usage

When streaming (stream: true), token usage is available by setting stream_options.include_usage to true.

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

When enabled, Truememory emits a final SSE chunk after the finish_reason chunk with an empty choices array and the accumulated usage:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711234567,"model":"anthropic/claude-sonnet-4-5","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21,"cache_read_tokens":0,"cache_creation_tokens":0}}

data: [DONE]

The final usage chunk includes the same fields as the non-streaming response, including cache_read_tokens and cache_creation_tokens. Numbers are accumulated across every internal step (tool calls, memory lookups, etc.) so you get one clean bill for the whole request. See Understanding the usage object for what each field means.

If stream_options is omitted or include_usage is false, no usage chunk is emitted.

Agent Selection

By default, requests use the chatbot agent. To use a different agent, pass the X-Agent-Id header:

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "X-Agent-Id: research-assistant" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"model": "anthropic/claude-sonnet-4-5", "messages": [...]}'

If the request includes a system or developer message, that message replaces the agent’s built-in prompt for that request. Memory and personas are still injected.

Per-App Thread Isolation

To scope threads to a specific application, pass the X-App-Id header. Threads sent with an app ID are isolated — they won’t appear in other apps’ thread lists, and can only be resumed, renamed, or deleted with the same X-App-Id.

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "X-App-Id: vibrantly" \
  -H "X-Agent-Id: chatbot" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"model": "anthropic/claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hello"}], "thread_id": "my-thread"}'

When X-App-Id is omitted, threads are unscoped and visible to all apps. See Threads — Per-App Thread Isolation for details.

For the full agent registry (memory scope and safety behavior per agent), see Agents — the single source of truth. Query GET /info to see the agents on your instance.

Supported Providers

• Anthropic
• OpenAI
• Google Vertex AI
• Z.ai (GLM) — e.g. zai/glm-4.6, zai/glm-4.7, zai/glm-5.2

Query GET /info to see which models are currently available on your instance.