# API reference

Backend HTTP interfaces for the default workspace, projects, sessions, datasets, construction, files, memory, and skills. Examples target a running iGraph service; the documentation site itself does not execute API calls.

## 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

**GET** `/api/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.

```json
{
  "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

**POST** `/api/sessions`

| Field | Type / default | Meaning |
| --- | --- | --- |
| client_session_id | UUID string \| null | Optional client idempotency UUID, up to 64 characters; invalid UUIDs return 400. |
| model | string \| null | Optional model ID; choose an available, enabled model with a complete connection configuration. |
| project_id | string \| null | Project ownership; null for a non-project session. |
| active_dataset_id | string \| null | Optional active dataset; it must fall within the workspace and project scope accessible to the session. |
| initial_message_preview | string / "" | Up to 1,000 characters, used for session metadata such as title. |
| reasoning_mode | "direct" \| "staged" / "direct" | Reasoning mode. |
| planning_mode | "never" \| "auto" \| "always" / "auto" | Planning policy. |

```json
{
  "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

| Method | Path | Purpose |
| --- | --- | --- |
| GET / POST | /api/sessions | List / create sessions in the default workspace |
| POST | /api/sessions/{sid}/activate | Activate a session and restore available state |
| GET | /api/sessions/{sid}/messages | Read persisted messages and recoverable UI content |
| GET | /api/sessions/{sid}/info | Session metadata, active data, and run state |
| GET | /api/sessions/{sid}/context-usage | Context-usage information |
| PATCH | /api/sessions/{sid} | Update session metadata such as the title |
| PATCH | /api/sessions/{sid}/model | Switch to an available workspace model |
| PATCH | /api/sessions/{sid}/dataset | Update the session dataset binding |
| PATCH | /api/sessions/{sid}/reasoning-mode | Update reasoning mode |
| PATCH | /api/sessions/{sid}/planning-mode | Update planning mode |
| DELETE | /api/sessions/{sid} | Delete a session; active work may need to stop first |
| POST | /api/sessions/{sid}/chat/stream | Submit a message and receive SSE |
| POST | /api/sessions/{sid}/feedback/stream | Submit a tool-approval decision and continue the original run |
| POST | /api/sessions/{sid}/runs/{rid}/resume | Resume observing a run from last_event_index |
| GET | /api/sessions/{sid}/runs/{rid}/snapshot | Read a phase snapshot; inspect snapshot_complete |
| GET | /api/capabilities | Read cancellation and latest-turn editing capabilities |
| POST | /api/sessions/{sid}/runs/cancel | Stop a targeted run when run_cancel_v1 is enabled |
| GET | /api/sessions/{sid}/runs/control | Query control state by run_id or start_request_id |
| POST | /api/sessions/{sid}/jobs/{jid}/cancel | Stop a targeted job when job_cancel_v1 is enabled |
| GET | /api/sessions/{sid}/jobs/{jid}/control | Read job stop and persistence state |

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.

| Method | Path | Purpose |
| --- | --- | --- |
| GET / POST | /api/projects | List / create projects |
| GET / PATCH / DELETE | /api/projects/{pid} | Read / update / delete a project |
| GET | /api/projects/{pid}/conversations | Project sessions |
| GET | /api/projects/{pid}/training-runs | Recorded project training configuration, metrics, and model information |
| GET | /api/server-datasets | List server-provided datasets |
| POST | /api/projects/{pid}/datasets/from-server | Add an accessible server dataset to a project |
| GET / POST | /api/models/custom | List / save workspace custom-model configuration |
| DELETE | /api/models/custom/{model_id} | Delete workspace custom-model configuration |
| GET | /api/models | Read the model catalog and default model |
| PUT | /api/models/default | Set the default model |
| GET / POST | /api/model-providers | List / save model service providers |
| GET | /api/construction-models | Read available construction models |
| GET / POST | /api/construction-model-settings | Read / save the separate construction-model connection |

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.

| Method | Path | Purpose |
| --- | --- | --- |
| GET | /api/sessions/{sid}/workspace/files | List visible uploads and published outputs |
| GET | /api/sessions/{sid}/workspace/derived/{artifact_path} | Download Derived outputs after session and file-scope checks |
| GET / POST | /api/memory | Query / create memory; GET accepts scope, query, and limit |
| PATCH / DELETE | /api/memory/{memory_id} | Update / delete a memory record |
| GET | /api/memory/events | Read memory-related events |
| GET | /api/memory/usage | Read memory-usage information |
| GET / POST | /api/skills | List / create skills |
| POST | /api/skills/upload | Upload a skill file or archive |
| GET / PUT / DELETE | /api/skills/{name} | Read full content / edit / delete a skill |
| POST | /api/skills/{name}/approve | Approve a candidate skill |
| POST | /api/skills/{name}/reject | Reject a candidate skill |
| GET | /api/export/sft | Export input/output samples from existing workspace sessions |

/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.

- [Workspace operations](/en/workspace/): Find the available UI entry points and workflows.
- [Streaming protocol](/en/streaming/): Request identities, recovery cursors, cancellation state, and approval feedback.

## Upload a dataset

**POST** `/api/projects/{project_id}/datasets`

**POST** `/api/personal-datasets`

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.

| Field | Description |
| --- | --- |
| file / files | Upload one or more files; at least one is required |
| csv_schema | Optional CSV schema JSON text |
| name / description | Optional dataset name and description |
| session_id | Optional associated session, subject to ownership checks |
| set_as_default | Project upload only; defaults to false |

```bash
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

| Status | Typical meaning | Client handling |
| --- | --- | --- |
| 403 | Internal service credential or data-scope check failed | Inspect detail, internal service keys, and project / session scope; signing in again is not required |
| 404 | Resource missing or inaccessible | Verify IDs and workspace / project / session scope; removed account-management endpoints also return 404 |
| 409 | State or graph-revision conflict | Read current state before retrying a write |
| 422 | Invalid request parameters | Inspect detail and field types |
| 429 | Construction capacity exhausted: construction_capacity_exhausted | No build was started; back off before retrying. |
| 504 | Construction still running or unconfirmed: construction_running_unconfirmed | Read construction state first; do not immediately submit a duplicate build after a timeout. |

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.

> **Transport success and business success**
> HTTP 200 or a returned job_id does not prove an analysis is complete. Inspect success, construction state, terminal job status, and final results; asynchronous submission only confirms acceptance. Treat parsing failures, unsupported input, and missing final results as explicit failures.