Models (Schemas)

`AgentNodeAdminDetail`

Type: object

Description: Full node detail for admin view — includes invite_token and skill config.

Property	Type	Description
`node_id*`	`string`
`display_name*`	`string`
`description`	`anyOf`
`skill_config`	`object`
`capabilities`	`object`
`invite_token`	`anyOf`
`is_active`	`boolean`
`last_status*`	`string`
`last_seen_at`	`anyOf`
`created_at*`	`string`
`registered_by*`	`string`
`group_access`	`array`
`stats`	`Ref: AgentNodeStats`

`AgentNodeCreate`

Type: object

Description: Payload for admin creating a new node registration.

Property	Type	Description
`node_id*`	`string`	Stable identifier used in the node's config YAML, e.g. 'dev-macbook-m3'
`display_name*`	`string`	Human-readable name shown in the UI
`description`	`anyOf`
`skill_config`	`Ref: NodeSkillConfig`

`AgentNodeStats`

Type: object

Description: Live performance stats reported via heartbeat.

Property	Type	Description
`active_worker_count`	`integer`
`cpu_usage_percent`	`number`
`memory_usage_percent`	`number`
`cpu_count`	`integer`
`memory_used_gb`	`number`
`memory_total_gb`	`number`
`running`	`array`
`cpu_usage_per_core`	`array`
`cpu_freq_mhz`	`number`
`memory_available_gb`	`number`
`load_avg`	`array`

`AgentNodeUpdate`

Type: object

Description: Payload for admin updating node configuration.

Property	Type	Description
`display_name`	`anyOf`
`description`	`anyOf`
`skill_config`	`anyOf`
`is_active`	`anyOf`

`AgentNodeUserView`

Type: object

Description: Node as seen by a user — no invite_token, no admin config details.

Property	Type	Description
`node_id*`	`string`
`display_name*`	`string`
`description`	`anyOf`
`capabilities`	`object`
`available_skills`	`array`
`last_status*`	`string`
`last_seen_at`	`anyOf`
`stats`	`Ref: AgentNodeStats`

`AppConfigUpdate`

Type: object

Property	Type	Description
`allow_password_login`	`anyOf`

`Body_fs_upload_nodes__node_id__fs_upload_post`

Type: object

Property	Type	Description
`file*`	`string`

`Body_import_user_config_yaml_users_me_config_import_post`

Type: object

Property	Type	Description
`file*`	`string`

`Body_transcribe_audio_to_text_stt_transcribe_post`

Type: object

Property	Type	Description
`audio_file*`	`string`

`Body_upload_message_audio_sessions_messages__message_id__audio_post`

Type: object

Property	Type	Description
`file*`	`string`

`ChatRequest`

Type: object

Description: Defines the shape of a request to the /chat endpoint.

Property	Type	Description
`prompt*`	`string`
`provider_name`	`string`
`load_faiss_retriever`	`anyOf`	Whether to use the FAISS DB retriever for the chat.

`ConfigResponse`

Type: object

Description: Schema for returning user preferences alongside effective settings.

Property	Type	Description
`preferences*`	`Ref: UserPreferences`
`effective`	`object`

`DirectoryListing`

Type: object

Property	Type	Description
`node_id*`	`string`
`path*`	`string`
`files*`	`array`

`DocumentCreate`

Type: object

Property	Type	Description
`title*`	`string`
`text*`	`string`
`source_url`	`anyOf`
`author`	`anyOf`
`user_id`	`string`

`DocumentDeleteResponse`

Type: object

Property	Type	Description
`message*`	`string`
`document_id*`	`integer`

`DocumentInfo`

Type: object

Property	Type	Description
`id*`	`integer`
`title*`	`string`
`source_url`	`anyOf`
`status*`	`string`
`created_at*`	`string`

`DocumentListResponse`

Type: object

Property	Type	Description
`documents*`	`array`

`DocumentResponse`

Type: object

Property	Type	Description
`message*`	`string`

`FileDeleteRequest`

Type: object

Property	Type	Description
`path*`	`string`
`session_id`	`anyOf`

`FileNodeInfo`

Type: object

Property	Type	Description
`path*`	`string`
`name*`	`string`
`is_dir*`	`boolean`
`size`	`integer`
`hash`	`anyOf`
`is_synced`	`boolean`

`FileWriteRequest`

Type: object

Property	Type	Description
`path*`	`string`
`content`	`string`
`is_dir`	`boolean`
`session_id`	`anyOf`

`GroupCreate`

Type: object

Property	Type	Description
`name*`	`string`
`description`	`anyOf`
`policy`	`object`

`GroupInfo`

Type: object

Property	Type	Description
`name*`	`string`
`description`	`anyOf`
`policy`	`object`
`id*`	`string`
`created_at`	`anyOf`

`GroupUpdate`

Type: object

Property	Type	Description
`name`	`anyOf`
`description`	`anyOf`
`policy`	`anyOf`

`HTTPValidationError`

Type: object

Property	Type	Description
`detail`	`array`

`LocalLoginRequest`

Type: object

Property	Type	Description
`email*`	`string`
`password*`	`string`

`Message`

Type: object

Description: Defines the shape of a single message within a session's history.

Property	Type	Description
`id*`	`integer`
`sender*`	`string`
`content*`	`string`
`reasoning_content`	`anyOf`
`created_at*`	`string`
`audio_url`	`anyOf`
`has_audio`	`boolean`

`MessageHistoryResponse`

Type: object

Description: Defines the response for retrieving a session's chat history.

Property	Type	Description
`session_id*`	`integer`
`messages*`	`array`

`ModelInfoResponse`

Type: object

Property	Type	Description
`model_name*`	`string`
`max_tokens`	`anyOf`
`max_input_tokens`	`anyOf`

`NodeAccessGrant`

Type: object

Description: Admin grants a group access to a node.

Property	Type	Description
`group_id*`	`string`
`access_level`	`string`	'view', 'use', or 'admin'

`NodeAccessResponse`

Type: object

Property	Type	Description
`id*`	`integer`
`node_id*`	`string`
`group_id*`	`string`
`access_level*`	`string`
`granted_at*`	`string`

`NodeAttachRequest`

Type: object

Description: Attach one or more nodes to a session.

Property	Type	Description
`node_ids*`	`array`
`config`	`anyOf`

`NodeConfigYamlResponse`

Type: object

Description: The generated config YAML content an admin downloads to set up a node.

Property	Type	Description
`node_id*`	`string`
`config_yaml*`	`string`

`NodeDataSourceConfig`

Type: object

Description: How a node should seed its workspace for a session.

Property	Type	Description
`source`	`string`	'empty'	'server'	'node_local'
`path`	`anyOf`

`NodeDispatchRequest`

Type: object

Description: Dispatch a shell action to a specific node.

Property	Type	Description
`task_id`	`anyOf`
`command`	`string`
`session_id`	`anyOf`
`timeout_ms`	`integer`

`NodeDispatchResponse`

Type: object

Property	Type	Description
`task_id*`	`string`
`status*`	`string`
`reason`	`anyOf`

`NodeSkillConfig`

Type: object

Description: Admin-controlled skill configuration for a node.

Property	Type	Description
`status`	`anyOf`
`shell`	`Ref: SkillConfig`
`sync`	`Ref: SkillConfig`

`NodeSyncStatusEntry`

Type: object

Description: Per-node sync status within a session.

Property	Type	Description
`node_id*`	`string`
`status*`	`string`
`last_sync`	`anyOf`
`error`	`anyOf`

`NodeWorkspaceConfig`

Type: object

Description: How a node should seed its workspace for a session.

Property	Type	Description
`source`	`string`
`path`	`anyOf`
`source_node_id`	`anyOf`
`read_only_node_ids`	`array`

`OIDCConfigUpdate`

Type: object

Property	Type	Description
`enabled`	`anyOf`
`client_id`	`anyOf`
`client_secret`	`anyOf`
`server_url`	`anyOf`
`redirect_uri`	`anyOf`
`allow_oidc_login`	`anyOf`

`PasswordUpdateRequest`

Type: object

Property	Type	Description
`current_password*`	`string`
`new_password*`	`string`

`STTResponse`

Type: object

Description: Defines the shape of a successful response from the /stt endpoint.

Property	Type	Description
`transcript*`	`string`

`SandboxConfig`

Type: object

Description: Granular command execution policy for the shell skill.

Property	Type	Description
`mode`	`string`
`allowed_commands`	`array`
`denied_commands`	`array`
`sensitive_commands`	`array`

`Session`

Type: object

Description: Defines the shape of a session object returned by the API.

Property	Type	Description
`id*`	`integer`
`user_id*`	`string`
`title`	`anyOf`
`provider_name`	`anyOf`
`stt_provider_name`	`anyOf`
`tts_provider_name`	`anyOf`
`feature_name*`	`string`
`created_at*`	`string`
`sync_workspace_id`	`anyOf`
`attached_node_ids`	`anyOf`
`node_sync_status`	`anyOf`
`sync_config`	`anyOf`

`SessionCreate`

Type: object

Description: Defines the shape for starting a new conversation session.

Property	Type	Description
`user_id*`	`string`
`provider_name`	`string`
`stt_provider_name`	`anyOf`
`tts_provider_name`	`anyOf`
`feature_name`	`anyOf`

`SessionNodeStatusResponse`

Type: object

Description: Response showing all attached nodes and their sync state.

Property	Type	Description
`session_id*`	`integer`
`sync_workspace_id`	`anyOf`
`nodes`	`array`
`sync_config`	`anyOf`

`SessionTokenUsageResponse`

Type: object

Description: Defines the response for retrieving a session's token usage.

Property	Type	Description
`token_count*`	`integer`
`token_limit*`	`integer`
`percentage*`	`number`

`SessionUpdate`

Type: object

Property	Type	Description
`title`	`anyOf`
`provider_name`	`anyOf`
`stt_provider_name`	`anyOf`
`tts_provider_name`	`anyOf`

`SkillConfig`

Type: object

Description: Per-skill enable/disable with optional config.

Property	Type	Description
`enabled`	`boolean`
`cwd_jail`	`anyOf`
`max_file_size_mb`	`anyOf`
`sandbox`	`anyOf`

`SkillCreate`

Type: object

Property	Type	Description
`name*`	`string`
`description`	`anyOf`
`skill_type`	`string`
`config`	`object`
`system_prompt`	`anyOf`
`is_enabled`	`boolean`
`features`	`array`
`is_system`	`boolean`
`extra_metadata`	`object`
`preview_markdown`	`anyOf`

`SkillResponse`

Type: object

Property	Type	Description
`name*`	`string`
`description`	`anyOf`
`skill_type`	`string`
`config`	`object`
`system_prompt`	`anyOf`
`is_enabled`	`boolean`
`features`	`array`
`is_system`	`boolean`
`extra_metadata`	`object`
`preview_markdown`	`anyOf`
`id*`	`integer`
`owner_id*`	`string`
`created_at*`	`string`

`SkillUpdate`

Type: object

Property	Type	Description
`name`	`anyOf`
`description`	`anyOf`
`skill_type`	`anyOf`
`config`	`anyOf`
`system_prompt`	`anyOf`
`is_enabled`	`anyOf`
`features`	`anyOf`
`is_system`	`anyOf`
`extra_metadata`	`anyOf`
`preview_markdown`	`anyOf`

`SpeechRequest`

Type: object

Property	Type	Description
`text*`	`string`

`SwarmConfigUpdate`

Type: object

Property	Type	Description
`external_endpoint`	`anyOf`

`SystemStatus`

Type: object

Description: Schema for overall system status, including TLS and OIDC state.

Property	Type	Description
`status*`	`string`
`oidc_enabled*`	`boolean`
`tls_enabled*`	`boolean`
`external_endpoint`	`anyOf`
`version*`	`string`

`UserGroupUpdate`

Type: object

Property	Type	Description
`group_id*`	`string`

`UserNodePreferences`

Type: object

Description: Stored in User.preferences['nodes'].

Property	Type	Description
`default_node_ids`	`array`	Node IDs auto-attached when starting a new session
`data_source`	`Ref: NodeDataSourceConfig`

`UserPreferences`

Type: object

Description: Schema for user-specific LLM, TTS, STT preferences.

Property	Type	Description
`llm`	`object`
`tts`	`object`
`stt`	`object`
`statuses`	`anyOf`

`UserProfile`

Type: object

Property	Type	Description
`id*`	`string`
`email*`	`string`
`username`	`anyOf`
`full_name`	`anyOf`
`role`	`string`
`group_id`	`anyOf`
`group_name`	`anyOf`
`avatar_url`	`anyOf`
`created_at*`	`string`
`last_login_at`	`anyOf`

`UserProfileUpdate`

Type: object

Property	Type	Description
`username`	`anyOf`
`full_name`	`anyOf`
`avatar_url`	`anyOf`

`UserRoleUpdate`

Type: object

Property	Type	Description
`role*`	`string`

`UserStatus`

Type: object

Description: Schema for the response when checking a user's status.

Property	Type	Description
`id*`	`string`	The internal user ID.
`email`	`anyOf`	The user's email address.
`is_logged_in`	`boolean`	Indicates if the user is currently authenticated.
`is_anonymous`	`boolean`	Indicates if the user is an anonymous user.
`oidc_configured`	`boolean`	Whether OIDC SSO is enabled on the server.
`allow_password_login`	`boolean`	Whether local password login is supported by the server.

`ValidationError`

Type: object

Property	Type	Description
`loc*`	`array`
`msg*`	`string`
`type*`	`string`
`input`	``
`ctx`	`object`

`VerifyProviderRequest`

Type: object

Property	Type	Description
`provider_name*`	`string`
`provider_type`	`anyOf`
`api_key`	`anyOf`
`model`	`anyOf`
`voice`	`anyOf`

`VerifyProviderResponse`

Type: object

Property	Type	Description
`success*`	`boolean`
`message*`	`string`