Qredence Documentation

The Fleet RLM server serves a JSON API on http://127.0.0.1:8000 by default. Start it with fleet serve. The terminal client uses the same API.

The API has no caller authentication. Keep it on loopback. See Security.
Routes have no /api prefix. openapi.yaml in the package documents every route and response model.
Errors use the FastAPI shape {"detail": "..."} with an HTTP status code. Invalid request bodies, IDs, and paths return 422. Request bodies reject unknown fields.
Session IDs are 1 to 64 letters, digits, dots, underscores, or hyphens, and can’t contain ... Fleet creates a Session the first time you use its ID. There is no create route.

Session lock

Each Session runs one Turn at a time. A Turn holds the Session lock until its stream ends and its sandbox work has drained. These routes take the same lock: Turn, mode, model, and context changes, memory writes and deletes, Skills, workspace files, and attachments. When a Turn already holds the lock, they wait 2 seconds and then return 409. Retry when the Turn completes. History and Turn status don’t take the lock. They read from PostgreSQL, so they work during a Turn and from any server process.

Turns

Run a Turn

POST /sessions/{session_id}/turn
Content-Type: application/json

Field	Type	Description
`task`	string	Required. 1 to 100,000 characters.
`idempotency_key`	string	Optional. Up to 128 characters.
`record_replay`	boolean	Default `false`. Persist a bounded snapshot of this Turn’s inputs as a candidate GEPA example.
`timeout_seconds`	integer or null	Optional. Fleet deadline for this Turn only. Omit it or send `null` to use the configured value, which is no Fleet deadline unless the server sets one. `0` means no Fleet deadline. Any other value must be an integer from 10 to 3600. Booleans, floats, strings, and out-of-range values return `422`. See Turn deadlines.

The response is a text/event-stream of Turn events. See Stream events.

curl -N -X POST http://127.0.0.1:8000/sessions/my-session/turn \
  -H 'Content-Type: application/json' \
  -d '{"task": "Summarize files/report.csv and verify the totals with Python.", "idempotency_key": "report-review-1"}'

The stream reports exactly one outcome event: turn_complete, error, or turn_cancelled. A final done event follows it after cleanup. If the Turn stops without reporting an outcome, Fleet sends a sanitized error event.
A second Turn on a busy Session gets 409 after 2 seconds, before any stream starts.
Closing the connection before the outcome event cancels the Turn. Closing it after the outcome keeps the completed Turn and its warm root Sandbox. Either way, Fleet keeps the Session locked until the sandbox work has drained, so two Turns never overlap in one sandbox.
Fleet records the Turn intent before it runs. If you resend a completed Turn with the same idempotency_key, Fleet replays the stored outcome instead of running it again. A failed or uncertain earlier attempt is not replayed. Reusing a key for a different task returns an error event.
record_replay can retain sensitive workspace content. Use it only for data approved for that purpose.

Get a Turn’s status

GET /sessions/{session_id}/turns/{turn_id}

Returns turn_id, status, result, and updated_at from PostgreSQL, or 404 when the Turn is unknown. Use it to recover an outcome after a dropped stream. It doesn’t replay the Turn. result.provenance_state tells you whether the stored outcome records which sandbox snapshot it ran on:

Value	Meaning
`recorded`	All six snapshot fields are present: `snapshot_name`, `snapshot_id`, `snapshot_cpu`, `snapshot_mem`, `snapshot_disk`, and `snapshot_definition_digest`.
`unresolved`	The Turn recorded its deadline policy but not every snapshot field.
`pre-provenance`	The Turn was stored before Fleet recorded provenance.

Get history

GET /sessions/{session_id}/history

Returns session_id and the stored turns. Fleet reads history from PostgreSQL without starting the Session’s sandbox.

Sessions

Method and path	Description
`GET /sessions`	List the 100 most recently updated Sessions with `session_id`, `updated_at`, and `turn_count`.
`DELETE /sessions/{session_id}`	Stop the Session’s sandbox, release its lease, and drop its runtime from the server process. History is kept, and the next request rebuilds the runtime. Returns `404` when the process holds no runtime for the Session and `409` while a Turn runs.
`GET /sessions/{session_id}/config`	Get the Session’s `mode`, `models` (`root`, `sub`), selected `context`, resolved `configuration`, and `limits` (`lm_calls`, `depth`, `children`, `active_children`, `timeout_seconds`).
`GET /sessions/{session_id}/mode`	Get the execution mode.
`PUT /sessions/{session_id}/mode`	Set the execution mode. Body: `{ "mode": "<mode>" }`, where the mode is `direct`, `flex`, `rlm`, or `hybrid`.
`PUT /sessions/{session_id}/model`	Bind a model to a role. Body: `{ "role": "<role>", "model": "<provider>/<model>" }`, where the role is `root` (default) or `sub`. The model is any DSPy route without whitespace, up to 300 characters. Fleet doesn’t check it against a model listing, and the role keeps its configured endpoint and key.
`GET /models`	List models from a role’s OpenAI-compatible endpoint. Query: `role` (`root`, `sub`, `reflection`, or `judge`; default `root`). Fleet reads the endpoint’s `/models` list only when that role has an explicit `api_base`, and returns an empty list otherwise. `scope` is deprecated and ignored.

Mode, model, and context selections persist and survive a server restart. Model discovery is optional. You can always set a model route manually.

Context

Select a workspace file as the Session’s dataset context.

Method and path	Description
`PUT /sessions/{session_id}/context`	Body: `{ "path": string, "description": string? }`. Returns `path`, `size_bytes`, and `sha256`.
`DELETE /sessions/{session_id}/context`	Clear the selection.

Workspace files

These routes operate on the Session’s workspace. Paths are relative to the workspace root. Files are limited to 25 MB.

Method and path	Description
`GET /sessions/{session_id}/files`	List workspace paths. Returns `files` and the `artifacts` subset under `artifacts/`.
`GET /sessions/{session_id}/workspace/tree`	Same as `/files`.
`GET /sessions/{session_id}/workspace/stat/{rel_path}`	Get `size_bytes` and `sha256`.
`GET /sessions/{session_id}/workspace/files/{rel_path}`	Download the file.
`PUT /sessions/{session_id}/workspace/files/{rel_path}`	Write the file. Body: exactly one of `content` (UTF-8 text) or `content_base64`. Either can be empty to write an empty file. Sending both, neither, or invalid base64 returns `422`. Returns `413` above 25 MB.
`DELETE /sessions/{session_id}/workspace/files/{rel_path}`	Delete the file.
`POST /sessions/{session_id}/attach`	Upload a multipart `file` field to `files/<name>`. Returns `mounted_path` and `rel_path`.

curl -X POST http://127.0.0.1:8000/sessions/my-session/attach -F 'file=@report.csv'

Uploads are limited to the smaller of storage.max_upload_bytes and 25 MB. Larger uploads return 413. Unavailable or invalid file paths return 404.

Memory

Method and path	Description
`GET /sessions/{session_id}/memory`	List up to 20 memories that match the optional full-text query `q`.
`PUT /sessions/{session_id}/memory/{memory_id}`	Save a memory. Body: `content` (1 to 10,000 characters), `kind` (`observation`, `preference`, `hypothesis`, or `procedure`), `sources` (path-to-digest map), `reviewed` (default `false`).
`DELETE /sessions/{session_id}/memory/{memory_id}`	Delete a memory.

Skills

These routes take an optional session_id query parameter. It defaults to default.

Method and path	Description
`GET /skills`	Sync local Skills to the Session’s workspace and return the catalog as `catalog_xml`.
`POST /skills/pull`	Export the Session’s workspace Skills to the local Skills directory. Returns `exported`.
`POST /skills/push`	Push local Skills to the Session’s workspace. Returns the `pushed` count.

See Skills.

Experiments

These routes run and review GEPA optimization for a Session on the server. Fleet runs the optimizer in a separate worker process and stores each run’s lifecycle in PostgreSQL. The server runs one optimization at a time, so a start request while another run is active returns 409 instead of queueing.

Method and path	Description
`GET /sessions/{session_id}/experiments`	List the Session’s runs as `experiments`, with `active_run_id` and `accepting` (whether the server admits new runs).
`POST /sessions/{session_id}/experiments`	Start a run. Returns `202` with the new run in `experiment`.
`GET /sessions/{session_id}/experiments/{run_id}`	Get one run in `experiment` and its saved candidate `comparison`, or `null`.
`POST /sessions/{session_id}/experiments/{run_id}/cancel`	Request a cooperative stop of a `running` run. Returns `202`. The run reaches its final status after the worker cleans up.
`POST /sessions/{session_id}/experiments/{run_id}/review`	Approve or reject the run’s candidate. Body: `{ "decision": "approved" \| "rejected", "request_id": string }`. Returns `202`.

The start body accepts the same search options as fleet optimize:

Field	Type	Description
`request_id`	string	Required. 1 to 128 letters, digits, underscores, or hyphens. Resending the same ID with the same options returns the existing run. Reusing it with different options returns `409`.
`gepa_budget`	string	`light` (default), `medium`, or `heavy`.
`max_metric_calls`	integer	GEPA search metric-call budget, at least 1. Replaces `gepa_budget`. Sending both returns `422`.
`threads`	integer	Default `4`, from 1 to 32.
`reflection_minibatch_size`	integer	Default `3`, at least 1.
`max_candidate_proposals`	integer	Optional. Stop after this many candidate proposals, at least 1.
`validation_ratio`	number	Default `0.35`, from 0.1 to 0.5.
`trace_search`	boolean	Default `false`. Also trace search rollouts in MLflow.

Each run has run_id, session_id, status, and, when known, stage, options, candidate_version, gate, dataset_sizes, progress, failure, mlflow_run_id, decision, and timestamps. status is running or approving while the run is active, and completed, failed, cancelled, interrupted, approved, or rejected once it ends. A passing candidate stays inactive until you approve it. Approval works only on a completed run. Fleet rechecks the candidate’s evidence before it serves the candidate from the Session’s next Turn. Rejection records the decision without installing anything. These routes return 404 for an unknown run, 409 when the request conflicts with the run’s status or another active operation, 422 for an invalid body or run ID, and 503 when experiment storage or the worker is unavailable.

Health

Method and path	Description
`GET /health`	Returns `status: "ok"`, the package `version`, and the `mlflow` destination with `mode`, `tracking_uri`, experiment names, `experiment_id`, and `ready`.

Routes return 503 while Session storage or the Session runtime is unavailable. This includes a server that has reached runtime.max_active_sessions or a Session owned by another server process.

Fleet-RLM

Fleet Prime Agent

Fleet Pi

GEPA Omni

Qredence Skills

Fleet Reasoner

Qredence Plugins

HTTP API

Session lock

Turns

Run a Turn

Get a Turn’s status

Get history

Sessions

Context

Workspace files

Memory

Skills

Experiments

Health

​Session lock

​Turns

​Run a Turn

​Get a Turn’s status

​Get history

​Sessions

​Context

​Workspace files

​Memory

​Skills

​Experiments

​Health

Session lock

Turns

Run a Turn

Get a Turn’s status

Get history

Sessions

Context

Workspace files

Memory

Skills

Experiments

Health