Skip to main content

API Reference

Complete reference for Tokligence Gateway API endpoints.

Base URL​

http://localhost:8081

Authentication​

All requests require an API key (unless TOKLIGENCE_AUTH_DISABLED=true):

curl http://localhost:8081/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

OpenAI-Compatible Endpoints​

Chat Completions​

POST /v1/chat/completions

Request:

{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": true,
  "tools": [...]
}

Response:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

Responses API​

POST /v1/responses

Used by Codex CLI v0.55.0+ with session management and tool calling.

Request:

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [{"role": "user", "content": "Hello"}],
  "stream": true
}

Models​

GET /v1/models

Lists available models from configured providers.

Embeddings​

POST /v1/embeddings
{
  "model": "text-embedding-ada-002",
  "input": "Hello world"
}

Anthropic Native Endpoints​

Messages​

POST /anthropic/v1/messages

Native Anthropic protocol with correct SSE envelopes. Compatible with Claude Code.

Request:

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "Hello"}]
}

Headers:

anthropic-version: 2023-06-01
Content-Type: application/json

Count Tokens​

POST /anthropic/v1/messages/count_tokens

Estimate token count before sending a request.

Gemini Native Endpoints​

Generate Content​

POST /v1beta/models/{model}:generateContent

Stream Generate Content​

POST /v1beta/models/{model}:streamGenerateContent

Count Tokens​

POST /v1beta/models/{model}:countTokens

List Models​

GET /v1beta/models

OpenAI-Compatible (on Gemini)​

POST /v1beta/openai/chat/completions

Admin Endpoints​

Health Check​

GET /health

Response:

{
  "status": "ok"
}

User Management​

GET /api/v1/admin/users
POST /api/v1/admin/users
DELETE /api/v1/admin/users/{id}

API Key Management​

GET /api/v1/admin/api-keys
POST /api/v1/admin/api-keys
DELETE /api/v1/admin/api-keys/{id}

Streaming​

All chat endpoints support SSE streaming:

curl -N http://localhost:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

SSE Events:

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"!"}}]}

data: [DONE]

Error Responses​

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": 401
  }
}

SDK Compatibility​

Use any OpenAI-compatible SDK by changing the base URL:

Python​

from openai import OpenAI

client = OpenAI(
    api_key="your-gateway-key",
    base_url="http://localhost:8081/v1"
)

Node.js​

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'your-gateway-key',
  baseURL: 'http://localhost:8081/v1',
});

LangChain​

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    api_key="your-gateway-key",
    base_url="http://localhost:8081/v1"
)