API reference

#Conventions

Examples use the Compose public entry point http://localhost:21108. When running Backend separately, use http://localhost:21109 instead. Business APIs use /api. Send Content-Type: application/json for JSON and multipart/form-data for uploads. The running service serves its complete schema at /openapi.json and Swagger at /docs.

In the tables, {sid}, {pid}, and {did} represent server-issued session_id, project_id, and dataset_id; {rid} is run_id and {jid} is job_id. Replace these readability abbreviations with the corresponding identifiers. This is an index of main entry points; use /openapi.json from the same deployment for complete request constraints and response schemas.

#Single-user workspace

Public /api/* requests are bound to the workspace owner selected by IGRAPH_ADMIN_USER_ID, defaulting to admin. Clients do not need X-User-ID; if an older client sends it, Backend replaces it with the fixed owner, so it cannot switch accounts. This endpoint takes no body and returns workspace state and available models. It neither authenticates users nor issues login tokens.

{
  "valid": true,
  "single_user": true,
  "user_id": "admin",
  "is_admin": true,
  "available_models": [
    "CONFIGURED_MODEL"
  ],
  "default_model": "CONFIGURED_MODEL"
}

CONFIGURED_MODEL is a placeholder; use the workspace response and GET /api/models for the actual catalog. The old POST /api/auth/validate remains only as a hidden compatibility endpoint returning the same workspace context. /api/admin/users and its account-management operations have been removed. is_admin is an internal compatibility field, not an administrator sign-in flow.

Model API keys and IGRAPH_CONTROL_SERVICE_KEY still configure provider connections and authenticate internal service calls, respectively. Project, session, dataset, and file-scope checks remain in effect. The single-user application is accessed through loopback or an SSH tunnel by default; removing the login page does not make internal services public endpoints.

#Create a session

{
  "client_session_id": "799888e3-5ae2-43ad-bec3-5b1e8e64fa25",
  "reasoning_mode": "direct",
  "planning_mode": "auto"
}

Successful responses include success, session_id, and information such as model, project_id, and active_dataset_id. Reusing a client ID may return reused: true. Send a message using chat/stream after creation.

#Session and run endpoints

Project and dataset endpoints preserve separate scopes: project data uses /api/projects/{pid}/datasets, while personal data uses /api/personal-datasets. Read project sessions and recorded training experiments from the conversations and training-runs subpaths respectively. Reading the training summary does not start training.

Workspace files, memories, and skills also have public APIs. Skill upload uses a multipart/form-data file field, accepts .md and .zip, and currently has a 2 MiB Backend limit. Candidate skill review is separate from approval of a pending tool execution.

/api/export/sft accepts format=alpaca, sharegpt, or raw, plus min_turns and require_tool_calls filters, and returns JSON containing items. It exports recorded data, not automatically quality-reviewed or training-ready samples. The current frontend has no dedicated SFT export button; distinguish this API from workspace downloads and report display.

#Upload a dataset

Dataset upload uses multipart/form-data. Supply at least one file or files field; repeat files for a multi-file upload. Multi-table CSV files can be combined with schema JSON describing relationships into one dataset, subject to upload validation. Use the matching project or personal endpoint.

curl -X POST "http://localhost:21108/api/projects/PROJECT_ID/datasets" \
  -F "files=@customers.csv" \
  -F "files=@orders.csv" \
  -F "files=@schema.json" \
  -F "name=Commerce tables"

Chat attachments use the file field on POST /api/sessions/{sid}/upload. Use the returned file_token in a later chat request; workspace_path identifies the workspace file. A browser-local path cannot replace file_token. CSV, SQL, and TXT attachments can be registered as construction sources. Upload success, source-preview success, completed construction, and loading the graph into the current session are separate states.

Read source samples at /api/projects/{pid}/datasets/{did}/construction/source-preview or /api/personal-datasets/{did}/construction/source-preview. This read-only endpoint works before construction; CSV accepts an optional delimiter. Its tables, text, limits, and warnings describe bounded table samples or text excerpts. SQL field descriptions distinguish comments, structural information, and unavailable descriptions; structural inference is not a business definition. Successful preview parsing also does not guarantee SQL-dialect compatibility with construction.

#Errors and retries

FastAPI detail can be a string, a structured object, or a validation-error array. Do not assume one universal error envelope. After a stream starts, combine terminal events, snapshots, and control state to handle failures.