Chat completions

AiQL exposes OpenAI-compatible POST /v1/chat/completions and GET /v1/models endpoints. Point an OpenAI SDK, LiteLLM, or any other OpenAI client at https://api.aiql.io/v1 and the request runs as a workspace query. The last user message is the prompt. AiQL runs the same agent chat as POST /queries. Tool use stays internal; the client only sees assistant text.

Prerequisites

An AiQL API key in the AIQL_API_KEY environment variable
A workspace ID with a finished ingestion (see Run a full ingestion)
The official OpenAI client for your language

Authenticate

Send the API key as a Bearer token. Completions also need the workspace in AiQL-Workspace. OpenAI clients pass that as a default header.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.aiql.io/v1",
    api_key=os.environ["AIQL_API_KEY"],
    default_headers={"AiQL-Workspace": "YOUR_WORKSPACE_ID"},
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.aiql.io/v1",
  apiKey: process.env.AIQL_API_KEY,
  defaultHeaders: { "AiQL-Workspace": "YOUR_WORKSPACE_ID" },
});

curl https://api.aiql.io/v1/chat/completions \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json"

Models

GET /v1/models lists the interaction modes. Use ask, reason, or build. Any other model id still runs the chat in ask mode, so examples that send gpt-4o work.

models = client.models.list()
print([model.id for model in models.data])

const models = await client.models.list();
console.log(models.data.map((model) => model.id));

curl https://api.aiql.io/v1/models \
  -H "Authorization: Bearer $AIQL_API_KEY"

Create a completion

Pass messages the way you would for OpenAI. The last user message becomes the query. Earlier turns are given to the agent as conversation history.

completion = client.chat.completions.create(
    model="ask",
    messages=[
        {
            "role": "user",
            "content": "list every invoice over $1,000 from last quarter",
        }
    ],
)
print(completion.choices[0].message.content)

const completion = await client.chat.completions.create({
  model: "ask",
  messages: [
    {
      role: "user",
      content: "list every invoice over $1,000 from last quarter",
    },
  ],
});
console.log(completion.choices[0].message.content);

curl -X POST https://api.aiql.io/v1/chat/completions \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"ask","messages":[{"role":"user","content":"list every invoice over $1,000 from last quarter"}]}'

The JSON response matches OpenAI’s chat.completion object. id is chatcmpl-<query_id>, so you can fetch the same turn later with GET /queries/{id}.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "ask",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "There are 12 invoices over $1,000 from last quarter."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

JSON mode waits until the query finishes. temperature, tools, and similar OpenAI fields are accepted and ignored. Only n=1 is supported.

Stream tokens

Set stream: true to receive OpenAI SSE chunks (chat.completion.chunk) as the agent writes text. The stream ends with data: [DONE].

stream = client.chat.completions.create(
    model="ask",
    messages=[
        {
            "role": "user",
            "content": "list every invoice over $1,000 from last quarter",
        }
    ],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "ask",
  messages: [
    {
      role: "user",
      content: "list every invoice over $1,000 from last quarter",
    },
  ],
  stream: true,
});
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

curl -X POST https://api.aiql.io/v1/chat/completions \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"ask","stream":true,"messages":[{"role":"user","content":"list every invoice over $1,000 from last quarter"}]}'

Tools

Pipeline

Workspace

Embedding

Prerequisites

Authenticate

Models

Create a completion

Stream tokens

​Prerequisites

​Authenticate

​Models

​Create a completion

​Stream tokens

Prerequisites

Authenticate

Models

Create a completion

Stream tokens