API reference

Introduction

The Lumen API is organised around three resources: runs (a model call, with optional tools and retrieval), collections (indexed documents) and keys. Requests and responses are JSON. All timestamps are RFC 3339 in UTC.

Authentication

Authenticate with a bearer token in the Authorization header. Keys are scoped to a single workspace and carry one of three roles: read, run or admin.

Authorization: Bearer lum_live_7f4c9a2e8b1d6035
Content-Type: application/json
Lumen-Version: 2026-08-01

Key roles

Quickstart

The shortest useful call: one prompt, one model, one answer. Pick your language.

curl https://api.lumen.example.com/v1/runs \
  -H "Authorization: Bearer $LUMEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lumen-pro",
    "input": "Summarise our refund policy in two sentences.",
    "collections": ["handbook"],
    "max_output_tokens": 300
  }'

from lumen import Lumen

client = Lumen()  # reads LUMEN_API_KEY

run = client.runs.create(
    model="lumen-pro",
    input="Summarise our refund policy.",
    collections=["handbook"],
)

print(run.output_text)
print(run.usage.output_tokens, "tokens")

import { Lumen } from "@lumen/sdk";

const lumen = new Lumen();

const run = await lumen.runs.create({
  model: "lumen-pro",
  input: "Summarise our refund policy.",
  collections: ["handbook"],
});

console.log(run.outputText);
console.log(run.usage.outputTokens);

package main

import (
	"context"
	"fmt"

	"github.com/lumen/lumen-go"
)

func main() {
	c := lumen.New()

	run, err := c.Runs.Create(context.Background(), lumen.RunParams{
		Model: "lumen-pro",
		Input: "Summarise our refund policy.",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(run.OutputText)
}

Create a run

A run is one turn of an agent: optional retrieval, zero or more tool calls, and a final answer. Runs are durable — fetch one again by id for 30 days.

Body parameters

Response

{  "id": "run_9f2ab41c",  "object": "run",  "model": "lumen-pro",  "created_at": "2026-08-01T09:14:22Z",  "status": "completed",  "output_text": "Refunds are available for 30 days…",  "citations": [    { "source": "handbook.pdf", "page": 14, "score": 0.912 }  ],  "usage": {    "input_tokens": 1842,    "cached_tokens": 1408,    "output_tokens": 96,    "cost_eur": 0.00213  }}

Streaming

Set stream: true to receive Server-Sent Events. Tokens, tool calls and citations arrive on the same channel, each as a typed event.

event: run.started
data: {"id":"run_9f2ab41c","model":"lumen-pro"}

event: token
data: {"text":"Refunds "}

event: tool.call
data: {"name":"lookup_order","arguments":{"id":"A-8812"}}

event: citation
data: {"source":"handbook.pdf","page":14}

event: run.completed
data: {"finish_reason":"stop","usage":{"output_tokens":96}}

with client.runs.stream(
    model="lumen-pro",
    input=question,
    tools=[lookup_order],
) as stream:
    for event in stream:
        if event.type == "token":
            print(event.text, end="")
        elif event.type == "citation":
            sources.append(event.source)

    final = stream.get_final_run()
    print(final.usage.cost_eur)

const stream = await lumen.runs.stream({
  model: "lumen-pro",
  input: question,
  tools: [lookupOrder],
});

for await (const event of stream) {
  switch (event.type) {
    case "token":
      write(event.text);
      break;
    case "tool.call":
      ui.showToolChip(event.name);
      break;
  }
}

Tool calling

Declare tools as JSON Schema. Lumen validates arguments before they reach your handler, so a malformed call never becomes a runtime exception in your code. Independent calls run in parallel automatically.

{
  "name": "lookup_order",
  "description": "Fetch an order by its reference.",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "pattern": "^A-[0-9]{4}$" }
    },
    "required": ["id"],
    "additionalProperties": false
  },
  "timeout_ms": 4000,
  "retries": 2
}

Retrieval

Query a collection directly when you want the passages without an answer — for a search UI, an evaluation harness, or your own prompt assembly.

curl ".../v1/collections/handbook/query" \
  -H "Authorization: Bearer $LUMEN_KEY" \
  -d '{
    "query": "parental leave",
    "top_k": 5,
    "rerank": true,
    "filter": { "region": "eu", "updated_after": "2026-01-01" }
  }'

# → { "matches": [ { "text": "…", "score": 0.91, "page": 14 } ] }

Errors

Errors use standard HTTP status codes with a stable machine-readable code. Match on code, never on message — the prose changes, the code does not.

{
  "error": {
    "code": "invalid_request",
    "message": "temperature must be between 0 and 2",
    "param": "temperature",
    "request_id": "req_c81f0a44"
  }
}

Always log request_id. It is the fastest way for us to find your call in support.

Versioning

The API is dated, not numbered. Pin a version with the Lumen-Version header; without it you get the version your workspace was created on, frozen. Breaking changes ship under a new date and old dates stay live for 18 months.