HTTP endpoints (v1)¶
skeino exposes four route groups — health/info, assistants, threads,
and runs — plus configurable CORS. The application is generated by
create_app, and FastAPI serves interactive OpenAPI docs at
/docs and the raw schema at /openapi.json.
Conventions
- All successful responses return 200. Invalid request bodies return
422; unknown thread/assistant ids return 404; a busy thread under a
non-
enqueuestrategy returns 409. - Path ids (
thread_id,run_id) are UUIDs. - The request bodies and response models below are defined in the
Python API reference under
skeino.schemas.*.
Health & info¶
| Method | Path | Response | Notes |
|---|---|---|---|
GET |
/api/health |
HealthResponse |
Liveness check: {status, version}. |
GET |
/info |
ServerInfoModel |
Server identity for SDK clients: {status, name, version}. |
GET |
/api/initial-message |
InitialMessageResponse |
Welcome message (welcome_message setting): {message, version}. |
Assistants¶
Prefix: /assistants
| Method | Path | Request | Response | Notes |
|---|---|---|---|---|
POST |
/assistants/search |
AssistantSearchRequest |
list[AssistantModel] |
List/search assistants (paginated, filterable). |
GET |
/assistants/{assistant_id} |
— | AssistantModel |
Assistant metadata. |
GET |
/assistants/{assistant_id}/schemas |
— | GraphSchemaModel |
Input/output/state/config/context JSON schemas. |
GET |
/assistants/{assistant_id}/graph |
— | dict |
Node/edge structure. Query: xray: bool = false. |
GET |
/assistants/{assistant_id}/subgraphs |
— | dict |
Subgraph schemas. Query: recurse: bool = false. |
See Assistants for how ids resolve to your graph.
Threads¶
Prefix: /threads
| Method | Path | Request | Response | Notes |
|---|---|---|---|---|
POST |
/threads |
ThreadCreateRequest |
ThreadModel |
Create a thread (optional id, metadata, if_exists, ttl, seed supersteps). |
POST |
/threads/search |
ThreadSearchRequest |
list[ThreadModel] |
Search by ids/metadata/values/status; paginated. |
GET |
/threads/{thread_id} |
— | ThreadModel |
Metadata plus latest values. |
PATCH |
/threads/{thread_id} |
ThreadPatchRequest |
ThreadModel |
Update thread metadata. |
DELETE |
/threads/{thread_id} |
— | 204 |
Delete the thread, its runs, and its checkpoints. |
POST |
/threads/{thread_id}/copy |
— | ThreadModel |
Fork into a new thread seeded with the source's latest state (shallow; metadata stamped forked_from). |
GET |
/threads/{thread_id}/state |
— | ThreadStateModel |
Latest checkpoint state. Query: subgraphs: bool = false. |
POST |
/threads/{thread_id}/state |
ThreadStateUpdateRequest |
CheckpointConfigModel |
Write/patch state (human-in-the-loop edit); returns the new checkpoint. |
GET |
/threads/{thread_id}/state/{checkpoint_id} |
— | ThreadStateModel |
State at a specific checkpoint (time travel). |
POST |
/threads/{thread_id}/state/checkpoint |
CheckpointConfigModel |
ThreadStateModel |
State at a checkpoint selected by a full config body. |
GET |
/threads/{thread_id}/history |
— | list[ThreadStateModel] |
Checkpoint history. Query: limit (1–1000, default 10), before. |
POST |
/threads/{thread_id}/history |
ThreadStateSearchRequest |
list[ThreadStateModel] |
History via POST (richer filters). |
See Threads & runs for the lifecycle and status values.
Runs¶
Prefix: /threads/{thread_id}
| Method | Path | Request | Response | Notes |
|---|---|---|---|---|
POST |
/threads/{thread_id}/runs |
RunCreateRequest |
RunModel |
Execute to completion. Headers: Location, X-Tokens-Used. |
POST |
/threads/{thread_id}/runs/stream |
RunCreateRequest |
SSE stream | Stream events (text/event-stream). See Streaming. |
GET |
/threads/{thread_id}/runs |
— | list[RunModel] |
List runs. Query: limit, offset, status. |
GET |
/threads/{thread_id}/runs/{run_id} |
— | RunModel |
Fetch a single run. |
Key RunCreateRequest fields¶
| Field | Type | Default | Meaning |
|---|---|---|---|
assistant_id |
str |
— | Which assistant/graph to run (required). |
input |
JsonValue |
null |
New state to merge in (messages is converted to LangChain messages). |
command |
CommandModel |
null |
Resume an interrupted graph (update/resume/goto). |
checkpoint |
CheckpointConfigModel |
null |
Resume from a specific checkpoint. |
stream_mode |
StreamMode \| list |
["values"] |
Streaming mode(s) — see Streaming. |
multitask_strategy |
enum | "enqueue" |
Behaviour when the thread is busy (enqueue/reject/rollback/interrupt). |
if_not_exists |
enum | "reject" |
"create" to auto-create a missing thread. |
config / context / metadata |
dict |
{} |
Passed through to the graph invocation. |
Provide either input or command, not both. Some LangGraph Platform
options (scheduled runs via after_seconds, webhook) are accepted by the
schema but rejected at runtime as out of scope for v1.
Status values¶
- Thread status:
idle,busy,interrupted,error. - Run status:
pending,running,success,error,timeout,interrupted.
For the exact fields of every request and response model, see the Python API reference.