Documentation

Everything you need to integrate AI-Gate into your application. The API is OpenAI-compatible — swap the base URL and start using it immediately.

Authentication

All requests require an API key passed in the Authorization header as a Bearer token.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8000/v1/chat/completions

You can request an API key from the landing page. Once submitted, an admin reviews the request and provisions the key. You will receive an email when the key is ready.

Chat Completions

The chat completions endpoint provides an OpenAI-compatible interface for sending messages and receiving AI-generated responses.

Endpoint

POST http://localhost:8000/v1/chat/completions

Request Format

{
  "messages": [
    {"role": "user", "content": "Hello, how are you?"}
  ],
  "stream": true
}

Response Format

Default

Streaming is the default behavior. Responses are sent as application/x-ndjson over SSE.

data: {"message": {"role": "assistant", "content": "Hello"}, "done": false}

data: {"message": {"role": "assistant", "content": "!"}, "done": false}

data: {"message": {"role": "assistant", "content": ""}, "done": true}

Opt-in

Set stream: false to receive the full response as a single JSON object.

{
  "choices": [
    {
      "message": {"role": "assistant", "content": "Hello!"}
    }
  ],
  "usage": {"prompt_tokens": 15, "completion_tokens": 8, "total_tokens": 23}
}

Embeddings

The embeddings endpoint generates vector embeddings for input text. The model is determined automatically by the platform based on the embedding model synced via the admin dashboard.

Endpoint

POST http://localhost:8000/v1/embeddings

Request Format

{
  "input": "This is the text to embed"
}

Pass an array of strings in input to embed multiple texts in a single request.

Response Format

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0142, 0.0083, ...]
    }
  ],
  "model": "default-embedding-model"
}

Usage with RAG

Process your documents through your own embedding step, store the vectors in your vector database, then use AI-Gate for chat completion calls that retrieve and reason over your context.

Limits

The following limits apply to all API requests to protect the gateway and ensure fair usage:

Request body size:          3 MB max
Chat messages per request:  128 max
Message content length:     8192 characters max
Embedding inputs per call:  100 max
Embedding input length:     8192 characters max
Rate limit:                 60 requests per 60 minutes per API key

Requests exceeding any limit will receive an appropriate error response (413 for oversized bodies, 422 for invalid input, 429 for rate limiting).

Quick Start

import httpx

response = httpx.post(
    "http://localhost:8000/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "messages": [
            {"role": "user", "content": "Explain RAG in simple terms."}
        ],
        "stream": False,
    },
    timeout=60.0,
)
print(response.json())

// Using Fetch API (built-in)
const response = await fetch("http://localhost:8000/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [
      { role: "user", content: "Explain RAG in simple terms." }
    ],
    stream: false,
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

// --- OR using Axios ---
// import axios from "axios";
// const response = await axios.post(
//   "http://localhost:8000/v1/chat/completions",
//   {
//     messages: [
//       { role: "user", content: "Explain RAG in simple terms." }
//     ],
//     stream: false,
//   },
//   {
//     headers: {
//       Authorization: "Bearer YOUR_API_KEY",
//       "Content-Type": "application/json",
//     },
//   }
// );
// console.log(response.data.choices[0].message.content);

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "time"
)

func main() {
  payload := map[string]interface{}{
    "messages": []map[string]string{
      {"role": "user", "content": "Explain RAG in simple terms."},
    },
    "stream": false,
  }

  reqBody, _ := json.Marshal(payload)

  client := &http.Client{Timeout: 60 * time.Second}
  req, _ := http.NewRequest("POST", "http://localhost:8000/v1/chat/completions", bytes.NewBuffer(reqBody))
  req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")

  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  fmt.Println(result["choices"].([]interface{})[0].(map[string]interface{})["message"].(map[string]interface{})["content"])
}

require "net/http"
require "json"

uri = URI.parse("http://localhost:8000/v1/chat/completions")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  messages: [
    { role: "user", content: "Explain RAG in simple terms." }
  ],
  stream: false
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts JSON.parse(response.body)["choices"][0]["message"]["content"]

use reqwest::Client;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box> {
  let client = Client::new();

  let mut messages = Vec::new();
  let mut msg = HashMap::new();
  msg.insert("role", "user");
  msg.insert("content", "Explain RAG in simple terms.");
  messages.push(msg);

  let mut body = HashMap::new();
  body.insert("messages", messages);
  body.insert("stream", false);

  let res = client
    .post("http://localhost:8000/v1/chat/completions")
    .bearer_auth("YOUR_API_KEY")
    .json(&body)
    .send()
    .await?;

  let json: serde_json::Value = res.json().await?;
  println!("{}", json["choices"][0]["message"]["content"]);

  Ok(())
}

#include <curl/curl.h>
#include <string>
#include <iostream>

int main() {
  CURL *curl = curl_easy_init();
  if (curl) {
    std::string url = "http://localhost:8000/v1/chat/completions";
    std::string jsonBody = R"({
      "messages": [{"role": "user", "content": "Explain RAG in simple terms."}],
      "stream": false
    })";

    struct curl_slist *headers = NULL;
    headers = curl_slist_append(headers, "Content-Type: application/json");

    std::string authHeader = "Authorization: Bearer YOUR_API_KEY";
    headers = curl_slist_append(headers, authHeader.c_str());

    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonBody.c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

    CURLcode res = curl_easy_perform(curl);
    if (res != CURLE_OK) {
      std::cerr << curl_easy_strerror(res) << std::endl;
    }

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
  }
  return 0;
}

<?php

$ch = curl_init("http://localhost:8000/v1/chat/completions");

$data = [
  "messages" => [
    ["role" => "user", "content" => "Explain RAG in simple terms."]
  ],
  "stream" => false,
];

curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($data),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_TIMEOUT => 60,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result["choices"][0]["message"]["content"];

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.time.Duration;

HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(60))
  .build();

String json = """
  {
    "messages": [
      {"role": "user", "content": "Explain RAG in simple terms."}
    ],
    "stream": false
  }
""";

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("http://localhost:8000/v1/chat/completions"))
  .header("Authorization", "Bearer YOUR_API_KEY")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(json))
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain RAG in simple terms."}
    ],
    "stream": false
  }'