Endpoint reference
Generated from olxcore/src/api/schema.json, the same schema the gateway validates requests against. Base URL http://127.0.0.1:8780.
Unknown fields in a turn body are rejected, not ignored. Errors are listed under Auth.
GET /v1/status scope: any
Gateway and core state as this token sees it.
Response: StatusResult
| field | type | required | meaning |
|---|---|---|---|
api | "v1" | yes | |
app | string | yes | |
scopes | array | yes | |
core | object | yes | |
turns_running | integer |
GET /v1/models scope: models
Installed local models by display name, OpenAI list format. `resident` says which are loaded right now.
Response: ModelList
| field | type | required | meaning |
|---|---|---|---|
object | "list" | yes | |
data | array | yes |
POST /v1/chat/completions scope: models
OpenAI-compatible completion on a local model (stream true|false, tools passthrough, sampling). The model's own answer only: olix tools do not run here.
Body
| field | type | required | meaning |
|---|---|---|---|
model | string (max 128 chars) | ||
messages | array | yes | |
stream | boolean | ||
tools | array | ||
tool_choice | any | ||
temperature | number (0..2) | ||
top_p | number (0..1) | ||
top_k | number (0..1000) | ||
presence_penalty | number (-2..2) | ||
max_tokens | integer (1..131072) | ||
max_completion_tokens | integer (1..131072) |
POST /v1/turns scope: chat
Run one olix turn. With stream true (default) the response is Server-Sent Events: one event per core event, ending at task_complete. With stream false it waits and returns the final task_complete plus the events.
Body
| field | type | required | meaning |
|---|---|---|---|
type | "input" | ||
text | string (max 100000 chars) | yes | What to ask olix. |
session_id | string | Continue one of this app's sessions. A turn already running in it steers instead. | |
cwd | string (max 4096 chars) | Project folder. Must be inside a folder the owner granted this token (--allow-dir); the default is this app's own workspace folder. | |
model | string (max 128 chars) | A display name (blink 1.1, flux) or id (olx-1). Default is the owner's chat model. | |
effort | low | medium | high | xhigh | max | Reasoning effort. Values the owner's build does not know are refused by the core. | |
stream | boolean | HTTP only. true (default) answers with Server-Sent Events; false waits for the whole turn. | |
request_id | string (max 128 chars) |
Streams the turn's events: see Events.
POST /v1/turns/{id}/interrupt scope: chat
Stop a running turn of this app.
Response: Interrupted
| field | type | required | meaning |
|---|---|---|---|
interrupted | boolean | yes | |
found | boolean | yes | |
request_id | string |
POST /v1/turns/{id}/answer scope: chat
Answer an open question of the turn. Deny only: an approve is refused with approval_not_allowed.
Body
| field | type | required | meaning |
|---|---|---|---|
question_id | string (max 200 chars) | yes | |
decision | "deny" | yes | |
reason | string (max 500 chars) |
Response: Answered
| field | type | required | meaning |
|---|---|---|---|
answered | boolean | yes | |
decision | "deny" | yes | |
question_id | string |
GET /v1/sessions scope: chat
This app's own sessions.
Response: SessionList
GET /v1/sessions/{id} scope: chat
The saved transcript of one of this app's sessions.
Response: Transcript
| field | type | required | meaning |
|---|---|---|---|
session_id | string | yes | |
title | string | ||
pinned | boolean | ||
messages | array | yes | |
truncated | boolean | yes |
GET /v1/sessions/{id}/changes scope: chat
Files this app's session changed (workspace_changes). Add ?path=relative/file for one file's diff.
Response: Changes
| field | type | required | meaning |
|---|---|---|---|
ok | true | yes | |
files | array | ||
file | object |
GET /v1/settings/schema scope: any
The field list of olix's settings (read-only; the API cannot change a setting).
Response: SettingsSchema
| field | type | required | meaning |
|---|---|---|---|
fields | array | yes |
GET /v1/history scope: history.read
The owner's saved sessions across projects, newest first. ?limit=N (max 500).
Response: SessionList
GET /v1/history/{id} scope: history.read
The saved transcript of any session.
Response: Transcript
| field | type | required | meaning |
|---|---|---|---|
session_id | string | yes | |
title | string | ||
pinned | boolean | ||
messages | array | yes | |
truncated | boolean | yes |
GET /v1/history/search?q=TEXT&cwd=DIR scope: history.read
Search saved sessions of one project folder.
Response: SessionList
Examples
curl -s http://127.0.0.1:8780/v1/sessions \
-H "Authorization: Bearer $OLIX_API_TOKEN" | jq '.[0] | {id, turns}'{
"id": "20261106132214-54f2e5",
"turns": 1
}