REST API

thalabus REST API — v1

Overview

The thalabus REST API exposes four groups of endpoints that together cover the full lifecycle of an AI-powered session: platform management and health (/v1/api), custom agent plan authoring (/v1/agent), real-time diagnostic log retrieval (/v1/logs), and session lifecycle and conversation management (/v1/sessions).

Base URL: https://{host}/v1

The API is built with ASP.NET Core and follows conventional REST design. All request and response bodies use JSON. Dates are formatted as yyyy-MM-dd HH:mm:ss.ffffff (UTC) unless noted otherwise.

Architecture concepts

Sessions

A session is the central unit of work in thalabus. When a user opens the chatbot interface, a session is created for them. Each session:

Sessions can be created programmatically via POST /v1/sessions/session and destroyed via DELETE /v1/sessions/session/{id}.

Plans and Goals

A Plan is the structured execution blueprint for a session. It models the work to be done as a tree of Goals. The root goal is the high-level intent; its child subgoals break the work into steps that agents execute in sequence or in parallel (when there are no declared dependencies).

Plans are sent from the Python AI backend to the .NET web layer via POST /v1/sessions/session/{id}/plan, and can be polled by clients using GET /v1/sessions/session/{id}/plan.

LLM configurations

Configurations define which language models are assigned to which agent roles, and at what settings (temperature, max tokens, etc.). A deployment can have multiple named configurations (e.g. "default", "advanced", "fast"). Users can switch the active configuration per session without restarting anything.

Custom plans (PlanFragments)

A PlanFragment is a reusable, named execution template that can be injected into a session. When flagged as isCustomPlan = true it is user-authored and managed via /v1/agent/customPlans. Built-in plan fragments are defined in the server's LLM settings file and are not editable through this API.

Authentication

Most endpoints require an ?token={token} query parameter passed in the query string.

Token type Scope Description
Platform token Global Full access to all endpoints. Retrieved via GET /v1/api/platformtoken using the backdoor token. Treat this token like a root password — keep it secret.
Session token Per-session Scoped to a single session. Returned in the api_token field of the session creation response. Accepted by all session-scoped endpoints. A platform token also satisfies any session-token check.

Token validation is performed by ApplicationService.ValidateGlobalApiToken(token) for platform tokens and by session.ValidateToken(token) for session tokens.

Common error responses:

Status Meaning
400 Bad Request Required parameter missing (usually token or prompt)
401 Unauthorized Token provided but invalid
404 Not Found Resource (session, plan, configuration) not found
500 Internal Server Error Unhandled exception — the response body contains { "error": 500, "message": "...", "exception": "..." }

Data models

The following objects appear in request and response bodies throughout the API. They are documented here to avoid repetition.

SessionCreateResponse

Returned by POST /v1/sessions/session. Contains everything the caller needs to start working with the new session.

Field Type Description
id string The session identifier (e.g. "luca-s-1"). Used in all subsequent session-scoped requests.
user_id string Username of the session owner.
title string Human-readable title auto-assigned to the session.
endpoint_base string Full URL to this session including the session token, e.g. https://host/v1/sessions/session/luca-s-1?token=<token>. Paste into a client to immediately start interacting.
api_token string Session-scoped API token. Store this — all further calls to session endpoints require it.
active_llm_configuration_name string Name of the LLM configuration currently active for this session.
plan Plan The initial (usually empty) execution plan. See the Plan object below.

Plan

A Plan is the structured execution blueprint for a session. It organises the work as a tree of Goal nodes. The Python AI backend sends plans to the .NET layer; clients read them via polling.

Field Type Description
plan_guid string Unique identifier for this plan.
plan_name string Short name describing the plan's purpose. Required when sending a plan via POST /v1/sessions/session/{id}/plan.
plan_description string Human-readable description.
plan_domain string Thematic domain (e.g. "legal", "medical"). Used to contextualise agent behaviour.
plan_focus string A focal point or constraint that narrows the agent's scope within the domain.
plan_flavour string Optional key selecting a named flavour (behaviour variant) from the LLM settings.
plan_active_reasoning AgentReasoningEnum Reasoning mode at plan level: FAST (0), DETAILED (1), BALANCED (2).
plan_default_language string BCP-47 language code for the plan (e.g. "en", "fr", "de").
plan_language_in_use string Language currently active in the running session.
plan_dossier_id string Optional identifier of a dossier (case file) attached to this plan.
plan_document_ids string[] List of document IDs referenced by this plan.
plan_document_template_ids string[] Document template IDs pre-loaded into the session.
plan_loaded_documents string[] IDs of documents currently loaded in memory for this session.
plan_reasoning_document_id string ID of a special document that drives extended chain-of-thought reasoning.
plan_datasets Dataset[] Structured datasets made available to agents during execution.
plan_ontology_id string ID of the ontology to use for knowledge-graph queries.
plan_community_ids string[] Knowledge-graph community identifiers restricting the graph search space.
plan_goal Goal Root goal of the execution tree. All agent work flows from this node.
plan_revision integer Monotonically increasing counter. Clients can pass their last-known revision to GET /v1/sessions/session/{id}/plan to receive a 304 Not Modified when nothing has changed.
plan_total_completion_tokens integer Running total of completion tokens consumed by this plan.
plan_maximum_tokens integer Hard cap on total tokens for this plan.
plan_token_limit integer Soft warning threshold on token usage.

Goal

A Goal is a single node in the plan tree. Goals can be nested to any depth via goal_subgoals. Each goal maps to one agent invocation (or a grouping of subgoals with no direct agent action).

Field Type Description
goal_id int[] Positional index within the plan tree, e.g. [1, 2] for the second child of the first root goal.
goal_guid string Stable UUID for this goal node. Used as the key in plan-status responses.
goal_parent integer Index of the parent goal, or null for the root.
goal_title string Short descriptive label shown in the UI.
goal_description string Longer explanation of what this goal is meant to achieve.
goal_prompt string The exact instruction sent to the LLM agent responsible for this goal.
goal_target string How this goal is executed. Values: "Agent" (an AI agent acts), "Contextualizer" (enriches context for children), "Consolidator" (merges children outputs), "Only subgoals" (container node, no direct action), "No Operation", "Debug".
goal_target_agent_name string Name of the specific agent assigned when goal_target = "Agent".
goal_status string Runtime status: "Not Started", "In Progress", "Children in Progress", "Completed", "Failed", "Run Every Time".
goal_async_status GoalAsyncStatus Async execution state: SYNC, ASYNC_REQUESTED, ASYNC_IN_PROGRESS, ASYNC_COMPLETE, ASYNC_FAILED, ASYNC_ABORTED.
goal_subgoals Goal[] Ordered list of child goals. Execution follows dependency order.
goal_dependent_upon string Comma-separated list of sibling goal GUIDs that must complete before this goal can start.
goal_recommended_plan string ID of a PlanFragment to use as a template for this goal's sub-execution.
goal_recommended_tools string[] Agent tools (skills/functions) that are encouraged for this goal.
goal_summary string Plain-text summary produced by the agent after completing this goal.
goal_summary_pretty string Formatted (Markdown or HTML) version of the summary for display.
goal_html_summary string Final HTML output, if the goal produces a rich-text result.
goal_internal_thought string Internal chain-of-thought reasoning produced by the agent (visible in logs at level LLM_OUT).
goal_validation GoalValidation Validation state: NOT_VALIDATED (0), VALIDATED_OK (1), VALIDATED_ISSUES (2).
goal_error boolean true if this goal ended in an error state.
goal_error_message string Human-readable error description when goal_error = true.
goal_completion_reason string Reason recorded when the goal was marked complete or failed.
goal_attributes object Arbitrary key/value metadata attached by the AI or the caller.
goal_last_update_datetime string Timestamp of the last change to this goal node, format yyyy-MM-dd HH:mm:ss.ffffff.
goal_images string[] IDs of images attached to this goal's output.
goal_documents string[] IDs of documents produced or referenced by this goal.
goal_datasets Dataset[] Datasets scoped to this individual goal.
goal_rag_fragments IRagFragment[] Retrieved RAG (Retrieval-Augmented Generation) fragments used as context for this goal.
goal_is_partial boolean true if the goal result is provisional and further updates are expected.

PlanFragmentConfiguration

A PlanFragment is a reusable named template that describes how an agent or a group of agents should behave for a particular type of task. When customplan = true it is user-created and fully managed via /v1/agent/customPlans. Built-in fragments (system-defined) have customplan = false and are read-only from the API perspective.

Field Type Required Description
id string yes Unique identifier for this fragment. If omitted on creation, a UUID is generated automatically.
customplan boolean no true for user-authored fragments, false (or absent) for system-defined ones. Set automatically by the API — do not include on POST.
name string yes Human-readable name shown in the UI plan-fragment picker.
description string no Explanation of when and why to use this fragment.
blacklisted boolean no When true, this fragment is excluded from the automatic plan selector. Useful to temporarily disable a fragment without deleting it.
template_agents PlanFragmentAgent[] no Ordered list of agents that constitute this fragment's workflow. When the fragment is activated in a session the agents are invoked in the declared order, respecting dependencies.

Minimal creation example:

{
              "name": "Summarise legal brief",
              "description": "Extracts key facts and produces a structured summary of a legal document.",
              "template_agents": [
                { "name": "DocumentReader", "purpose": "Extract raw text from the uploaded document" },
                { "name": "LegalSummariser", "purpose": "Produce a structured legal summary", "dependencies": [0] }
              ]
            }

PlanFragmentAgent

Each entry in template_agents defines one agent step within a fragment.

Field Type Description
name string Agent name (must match a key in the agents section of the LLM settings file).
purpose string Natural-language description of what this agent does in this context. Used as documentation and potentially injected into the agent's system prompt.
prompt string Optional prompt override. When set, this replaces the agent's default system prompt for this fragment step.
override_recommended_tools string[] List of tool names to restrict this agent to. Overrides the agent's default tool list.
silent_summary boolean When true, the agent produces its summary internally but does not surface it to the user in the conversation thread.
repeat_on_error boolean When true, the agent automatically retries this step if it encounters an error.
dependencies int[] Zero-based indices of earlier agents in template_agents that must complete before this agent runs. Enables parallel execution of independent agents.

InputMessage

The body of PUT /v1/sessions/session/{id}/prompt. Carries a user prompt and optional control overrides that take effect only for that single turn.

Field Type Required Description
prompt string yes The user's natural-language input to the session.
role string no Message role, default "user". Change to "system" to inject a system-level instruction.
recommended_plan string no ID of a PlanFragment to activate for this turn. The session will prefer this fragment when building its execution plan.
recommended_tools string[] no List of tool names to suggest to the agent for this turn.
active_reasoning AgentReasoning no Reasoning mode override for this turn only. See AgentReasoning below.
active_flavour string no Flavour key to activate for this turn (must exist in the LLM settings flavours map).
rag_settings AgentRagSetting no Overrides which retrieval sources are enabled for this turn. See AgentRagSetting below.
language string no BCP-47 language code forcing a language change for this turn.
json_output object no If provided, instructs the agent to produce a JSON response matching this schema.
structured_output object no Alternative structured-output specification (provider-specific format).
images document[] no Images to attach to this prompt for multimodal models.
documents document[] no Documents to attach to this prompt.

AgentReasoning

Controls how deeply the LLM reasons before producing its answer. Applied per-session, per-turn, or at plan level.

Value Description
"minimal" Fastest mode. The model answers directly with minimal internal reasoning.
"fast" Light reasoning pass before answering. Good balance of speed and quality for simple tasks.
"simple" Standard reasoning mode. Default for most configurations.
"complex" Extended chain-of-thought reasoning. Slower but significantly more thorough. Recommended for complex legal, medical, or analytical tasks.

AgentRagSetting

Controls which retrieval-augmented generation (RAG) sources are active. Each flag can be toggled independently.

Field Type Default Description
internet boolean true Enable/disable live internet search. When enabled, agents can retrieve up-to-date information from the web.
dossier boolean false Enable/disable retrieval from the session's attached dossier (case file). Only relevant when a dossier has been loaded.
documents boolean true Enable/disable retrieval from the documents uploaded to the session or the knowledge base.
knowledge_graph boolean true Enable/disable retrieval from the Neo4j knowledge graph. When enabled, agents can traverse entity relationships and semantic communities.

SessionLlmConfiguration

Returned by GET /v1/api/platform/config/llm and GET /v1/api/platform/config/llm/{sessionId}.

Field Type Description
llmconfiguration LlmSettings The full LLM settings object loaded from the server's configuration file. Contains model definitions, agent mappings, plan fragments, workflows, and more.
activeconfiguration string Name of the configuration currently active (globally or for the specified session).
flavour string Active flavour key, or null if none is set.
reasoning string Active reasoning mode as a lowercase string (e.g. "simple"), or null if using the default.
ragsettings AgentRagSetting Active RAG source toggles for the session, or null if using defaults.

API Controller

Base path: /v1/api

The API controller provides platform-level operations: health check, version info, token management, configuration reload, and cache management. These endpoints are intended for administrative use and automated deployment scripts.

GET /v1/api/ping

Health check. Returns 200 OK with an empty body if the server is running and able to accept requests. Use this from load balancers, container health probes, or monitoring systems.

Auth: none

Response 200: empty body.

GET /v1/api/version

Returns the server build version. Useful for confirming which deployment is active or for version-gating client behaviour.

Auth: none

Response 200:

{
              "version": "1.2.3",
              "build": "2026-05-01"
            }

GET /v1/api/platformtoken

Returns the platform API token for the currently running server. The caller must already possess the backdoor token (a separate lower-privilege secret used only for this one endpoint). This design avoids storing the full platform token on every client.

Auth: query ?token={backdoor_token}

Parameter Type Description
token string The backdoor token (must match the server-side secret).

Response 200: plain string — the platform API token.
Response 401: invalid backdoor token.

POST /v1/api/utils/error

Injects an error message into the global session message queue. Used internally by Python agents to surface errors as user-visible notifications in the chatbot UI without crashing the agent process.

Auth: none (internal use — should not be exposed to untrusted clients)

Request body (JSON):

{
              "message": "Something went wrong while processing your request.",
              "session_id": "luca-s-1",
              "exception": "Optional stack trace or exception detail string"
            }

The message is displayed in the chatbot as a temporary error banner (ContainerMessageType.SkillError) and expires after 2 minutes.

Response 200: message enqueued.
Response 400: message field missing from the request body.

POST /v1/api/platform/config/reload

Reloads the LLM settings from the configuration file on disk and broadcasts the new settings to all currently active sessions. Use this after editing the server's LLM configuration file to apply changes without restarting the service.

Auth: none (call from a trusted network context — should not be exposed publicly)

Response 200: configuration reloaded and broadcast successfully.
Response 500: configuration file could not be parsed or loaded.

GET /v1/api/platform/config/llm

Returns the global (server-wide) LLM configuration. Exposes the full LlmSettings object plus the currently active global configuration name.

Auth: query ?token={platform_token}

Parameter Type Description
token string Platform API token

Response 200: SessionLlmConfiguration with session-specific fields (flavour, reasoning, ragsettings) set to null.

Response 400: token not provided.
Response 401: invalid token.

GET /v1/api/platform/config/llm/{sessionId}

Returns the LLM configuration as seen by a specific session — including the session-level overrides for active configuration, flavour, reasoning mode, and RAG settings.

Use sessionId = "global" (case-insensitive) to retrieve the global configuration, identical to the no-sessionId variant.

Auth: query ?token={platform_token}

Parameter Where Description
sessionId path Session identifier, or "global" for the server-wide defaults.
token query Platform API token

Response 200: SessionLlmConfiguration populated with session-specific overrides.
Response 404: session not found.

POST /v1/api/platform/cache/clear

Clears the global in-memory document cache and reloads user data from the database. Call this after bulk document imports, user updates, or whenever stale cache entries are suspected.

Auth: query ?token={platform_token}

Parameter Type Description
token string Platform API token

Response 200:

{ "message": "Cache cleared successfully" }

Response 401: invalid token.

Agent Controller

Base path: /v1/agent

The agent controller manages custom plan fragments — user-authored execution templates that can be referenced in session plans. All operations are serialised server-side (one write at a time) to prevent concurrent modification of the shared LLM settings file.

A custom plan fragment is a PlanFragmentConfiguration object with customplan = true. It is stored in the LLM settings plan_fragments dictionary and immediately broadcast to all active sessions after each write operation (create, update, delete).

Auth (all endpoints): query ?token={token}&username={username}

The token may be a platform token (full access) or any valid session token belonging to the specified username. The username parameter is only required when using a session token — it is used to look up the user's sessions and find one with a matching token.

GET /v1/agent/customPlans

Lists all custom plan fragments (i.e. those with customplan = true), ordered alphabetically by name.

Parameter Type Description
token query Platform or session token
username query Required when using a session token

Response 200:

{
              "customPlans": [
                {
                  "id": "plan-abc",
                  "name": "Summarise legal brief",
                  "customplan": true,
                  "description": "Extracts key facts from a legal document.",
                  "blacklisted": false,
                  "template_agents": [ ... ]
                }
              ]
            }

GET /v1/agent/customPlans/{id}

Returns a single custom plan fragment by its id.

Parameter Where Description
id path Plan fragment identifier
token query Platform or session token
username query Required when using a session token

Response 200: the full PlanFragmentConfiguration object.
Response 404: no custom plan with that id exists (built-in plans are not returned by this endpoint).

POST /v1/agent/customPlans

Creates a new custom plan fragment. If id is omitted or empty in the request body, the server generates a UUID automatically.

The new fragment is immediately persisted to disk and broadcast to all active sessions.

Parameter Where Description
token query Platform or session token
username query Required when using a session token

Request body (JSON): a PlanFragmentConfiguration object. Do not include customplan — the API sets it to true automatically.

{
              "name": "My Custom Workflow",
              "description": "Does X, then Y, then Z.",
              "template_agents": [
                { "name": "AgentA", "purpose": "Step X" },
                { "name": "AgentB", "purpose": "Step Y", "dependencies": [0] },
                { "name": "AgentC", "purpose": "Step Z", "dependencies": [1] }
              ]
            }

Response 201: the created PlanFragmentConfiguration including its generated id. The Location header contains the URL to retrieve it.
Response 409 Conflict: a plan with the same id already exists.

PUT /v1/agent/customPlans/{id}

Updates an existing custom plan fragment. All fields in the request body replace the stored values. If the body includes an id that differs from the path parameter, the plan is renamed (the old key is removed and the new key is added atomically).

The updated fragment is immediately persisted and broadcast to all active sessions.

Parameter Where Description
id path Current plan fragment identifier
token query Platform or session token
username query Required when using a session token

Request body (JSON): updated PlanFragmentConfiguration. The id field in the body is optional — if provided and different from the path {id}, a rename is performed.

Response 200: the updated PlanFragmentConfiguration.
Response 404: plan not found.
Response 409 Conflict: rename requested but target id is already taken.

DELETE /v1/agent/customPlans/{id}

Permanently deletes a custom plan fragment. The deletion is persisted immediately and broadcast to all active sessions (sessions that had this fragment active will lose it on the next plan refresh).

Parameter Where Description
id path Plan fragment identifier
token query Platform or session token
username query Required when using a session token

Response 204 No Content: deleted successfully.
Response 404: plan not found (built-in plans cannot be deleted via this endpoint).

Logs Controller

Base path: /v1/logs

The logs controller gives callers read access to the real-time stdout of any running session or background job. Every log entry recorded by the Python AI process is streamed to the .NET container and becomes visible here.

This is the primary tool for debugging agent behaviour without access to the server's file system. You can observe the exact prompts sent to the LLM (LLM_IN), the raw model responses (LLM_OUT), tool calls (FUNCTION), and plan transitions (PLAN).

GET /v1/logs/{sessionId}

GET /v1/logs/{sessionId}/{goalId}

Returns log entries for a session or job, optionally filtered to a specific goal subtree and/or a minimum log level.

Auth: query ?token={session_token} (session token or platform token both accepted)

Parameter Where Required Description
sessionId path yes Session identifier (e.g. luca-s-1) or background job identifier. The controller checks sessions first, then background jobs.
goalId path no Dot-separated goal index (e.g. 1.2). When provided, only log entries whose GoalId starts with this prefix are returned. Use this to zoom into the output of a single goal node.
token query yes Session or platform API token. Note: for jobs, only the platform token is accepted (jobs have no per-session token).
level query no Minimum log level. Only entries at this level or higher (more severe) are returned.

Log levels (ascending severity — specifying a level returns that level and all higher ones):

Level Description
INFO Verbose informational messages from the Python process. Includes module loading, cache lookups, and routine state changes. Very noisy — use only for deep debugging.
LLM_IN The full prompt payload sent to the language model. Includes system prompt, conversation history, tool definitions, and the user turn.
LLM_OUT The raw model response, including any tool-call JSON and the chain-of-thought <think> block when extended reasoning is active.
FUNCTION Records of tool (skill/function) invocations: the function name, input arguments, and return value.
PLAN Plan update events — when the AI creates, modifies, or advances through a plan.
WARNING Non-fatal anomalies — missing optional data, fallback behaviours triggered, retries.
ERROR Errors that disrupted a goal but did not terminate the session.
FATAL Critical errors that caused the session or agent to terminate.

Recommended default: level=LLM_IN — this returns LLM inputs/outputs, function calls, plan events, warnings, errors, and fatals, while omitting the high-volume INFO noise.

Response 200:

[
              {
                "Timestamp": "2026-05-29 10:30:00.123",
                "GoalId": "1.2",
                "LogLevel": "LLM_IN",
                "Agent": "LegalSummariser",
                "Module": "agents.legal",
                "Class": "LegalSummariserAgent",
                "Function": "run",
                "LineNumber": 87,
                "Message": "System: You are a legal expert...\nUser: Summarise this document...",
                "Reasoning": null
              },
              {
                "Timestamp": "2026-05-29 10:30:04.501",
                "GoalId": "1.2",
                "LogLevel": "LLM_OUT",
                "Agent": "LegalSummariser",
                "Module": "agents.legal",
                "Class": "LegalSummariserAgent",
                "Function": "run",
                "LineNumber": 91,
                "Message": "The document concerns a 2019 asylum case...",
                "Reasoning": "<think>The document is a legal decision from the Swiss SEM...</think>"
              }
            ]

Response 400: token not provided, or level value is not a valid PythonLogCategory name.
Response 401: invalid token.
Response 404: session or job not found.

Sessions Controller

Base path: /v1/sessions

The sessions controller is the primary integration point for external clients. It manages the full session lifecycle (create, delete), exposes conversation messages, plans, and prompt submission, and allows switching the active LLM configuration at runtime.

POST /v1/sessions/session

Creates a new session for a user and returns everything needed to interact with it. The server allocates the session, generates an API token for it, and starts the underlying AI program instance.

Sessions are resource-intensive — each one runs an in-memory Python AI process. Create them deliberately and always delete them when done.

Auth: query ?token={platform_token}

Parameter Type Required Description
userId string yes Username of the session owner. The user must already exist in the system.
token string yes Platform API token
sessionId string no Desired session identifier. Must be unique across all active sessions. If omitted, the server generates one automatically.

Response 201: SessionCreateResponse. The Location header points to the session resource URL.

Response 401: invalid platform token.
Response 404: user not found — ensure userId matches an existing user's username.
Response 503 Service Unavailable: the server has begun a shutdown sequence and cannot accept new sessions.

DELETE /v1/sessions/session/{sessionId}

Stops a session's AI program and removes it from the server. This frees the memory and compute resources associated with the session. The session's conversation history is not persisted after deletion.

Auth: query ?token={session_token}

Parameter Where Description
sessionId path Session identifier
token query Session API token (or platform token)

Response 204 No Content: session stopped and removed.
Response 401: invalid token.
Response 404: session not found.

GET /v1/sessions/configurations

Returns the list of all named LLM configurations available on this server. Configurations are defined in the LLM settings file and control which language models are assigned to which agent roles, as well as their inference parameters (temperature, top-p, max tokens, etc.).

Use this endpoint to populate a configuration picker in your UI, or to verify which configurations are available before calling PUT /v1/sessions/session/{id}/configuration/{name}.

Auth: none

Response 200:

[
              {
                "name": "default",
                "description": "Balanced configuration using GPT-4o for reasoning agents and GPT-4o-mini for routine tasks."
              },
              {
                "name": "advanced",
                "description": "All agents use GPT-4o with extended context. Slower but more thorough."
              },
              {
                "name": "fast",
                "description": "All agents use GPT-4o-mini. Fast and cost-efficient for simple tasks."
              }
            ]

GET /v1/sessions/session/{sessionId}/configuration

Returns the name of the LLM configuration currently active for a session. Use this to display the active configuration in your UI or to check the state before switching.

Auth: query ?token={session_token}

Parameter Where Description
sessionId path Session identifier
token query Session API token

Response 200:

{ "activeConfiguration": "default" }

Response 404: session not found.

PUT /v1/sessions/session/{sessionId}/configuration/{configName}

Switches the active LLM configuration for a session. The change takes effect immediately for the next agent invocation within that session. The session does not need to be restarted.

If the session is currently processing a prompt, the configuration change will apply to the next turn.

Auth: query ?token={session_token}

Parameter Where Description
sessionId path Session identifier
configName path Configuration name — must match a value from GET /v1/sessions/configurations
token query Session API token

Response 200:

{ "message": "Active configuration set successfully" }

Or, if the requested configuration is already active:

{ "message": "Active configuration already set" }

Response 404: session or configuration name not found.

GET /v1/sessions/session/{sessionId}

Returns the full session object, including current state, active configuration, plan reference, and user information. Primarily useful for debugging or administrative inspection.

Auth: query ?token={session_token}

Response 200: serialised session object (large — includes full plan and runtime state).
Response 404: session not found.

GET /v1/sessions/session/{sessionId}/messages

Returns the conversation history for a session — the sequence of user prompts and agent responses.

Auth: query ?token={session_token}

Parameter Type Default Description
list string true When truthy ("true" or "1"), returns a list of structured message objects. When falsy, returns an array of raw strings (prompt text and function-call JSON).
json string false When truthy, returns raw JSON strings for function-call entries instead of parsed objects.
pretty string false When truthy, pretty-prints JSON output with indentation.

Response 200: array of message objects (with list=true) or strings (with list=false).

GET /v1/sessions/session/{sessionId}/plan

Returns the current execution plan for a session. Clients should poll this endpoint periodically to track plan progress. The plan_revision field provides a cheap way to detect changes — pass your last-known revision and receive a 304 when nothing has changed, avoiding unnecessary payload transfer.

Auth: query ?token={session_token}

Parameter Type Description
revision integer The last revision number the client has seen. If the server's current revision equals this value, 304 Not Modified is returned immediately without a body.

Response 200: the full Plan object (potentially large — includes the complete goal tree with all summaries and results).
Response 304 Not Modified: plan has not changed since the requested revision. No body.
Response 404: session not found.

POST /v1/sessions/session/{sessionId}/plan

Sends a new execution plan to a session. This is called by the Python AI backend after computing the plan, not by end-user clients. The plan replaces the session's current plan atomically.

Auth: query ?token={platform_token}

Request body: JSON-serialised Plan object. Maximum body size: 256 MB (plans with large RAG fragments can be substantial). The plan_name field is required.

Response 200: a dictionary mapping each goal's plan_guid to its goal_last_update_datetime, allowing the caller to confirm which goals were affected:

{
              "goal-guid-1234": "2026-05-29 10:30:00.000000",
              "goal-guid-5678": null
            }

Response 400: invalid JSON, or plan_name is missing.
Response 404: session not found.

GET /v1/sessions/session/{sessionId}/planstatus

A lightweight alternative to GET .../plan when only change-detection is needed. Returns the last-update timestamp for each goal in the current plan without returning the full goal content. Use this to detect which goals have changed since the last full plan fetch.

Auth: query ?token={platform_token}

Response 200:

{
              "goal-guid-1234": "2026-05-29 10:30:00.000000",
              "goal-guid-5678": "2026-05-29 10:30:04.501000",
              "goal-guid-9999": null
            }

A null value means the goal has never been updated since the plan was set.

GET /v1/sessions/session/{sessionId}/awaitinginput

Checks whether the session is paused and waiting for a user prompt before proceeding. Use this to implement a polling loop that knows when to prompt the user for the next input.

When timeoutsec > 0, the request blocks server-side (long-poll) until the session becomes ready for input or the timeout expires. This avoids rapid polling at the cost of holding an HTTP connection open.

Auth: query ?token={session_token}

Parameter Type Description
timeoutsec integer If > 0, long-polls for up to this many seconds waiting for the session to reach an input-ready state. When the timeout expires without the session becoming ready, awaitingInput: false is returned. Maximum recommended value: 30.

Response 200:

{ "awaitingInput": true }

or

{ "awaitingInput": false }

Response 404: session not found.

PUT /v1/sessions/session/{sessionId}/prompt

Submits a user prompt to a session. This is the core interaction endpoint. The session receives the prompt, the AI program processes it, the plan is updated, and new messages are appended to the conversation history.

The call returns 200 as soon as the prompt is enqueued — it does not wait for the agent to finish processing. Use GET .../awaitinginput to know when the agent is ready for the next input, and GET .../messages or GET .../plan to read the result.

Auth: query ?token={session_token}

Request body (JSON): InputMessage object.

{
              "prompt": "What are the key risks identified in the uploaded document?",
              "active_reasoning": "complex",
              "rag_settings": {
                "internet": false,
                "dossier": true,
                "documents": true,
                "knowledge_graph": true
              }
            }

Response 200: prompt accepted and enqueued.
Response 400: prompt field is empty, or token not provided.
Response 401: invalid token.
Response 404: session not found.

Last updated: May 2026