# Models (Schemas)

## `AgentConfigUpdate`

**Type:** `object`

**Description:** Day 2 Agent Configuration edits

| Property | Type | Description |
|----------|------|-------------|
| `name` | `anyOf` |  |
| `system_prompt` | `anyOf` |  |
| `max_loop_iterations` | `anyOf` |  |
| `mesh_node_id*` | `string` |  |
| `provider_name` | `anyOf` |  |
| `allowed_skill_ids` | `anyOf` |  |
| `restrict_skills` | `anyOf` |  |
| `is_locked` | `anyOf` |  |
| `auto_clear_history` | `anyOf` |  |

## `AgentInstanceCreate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `template_id*` | `string` |  |
| `session_id` | `anyOf` |  |
| `mesh_node_id` | `anyOf` |  |
| `status` | `string` |  |
| `current_workspace_jail` | `anyOf` |  |

## `AgentInstanceResponse`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `template_id*` | `string` |  |
| `session_id` | `anyOf` |  |
| `mesh_node_id` | `anyOf` |  |
| `status` | `string` |  |
| `current_workspace_jail` | `anyOf` |  |
| `id*` | `string` |  |
| `last_heartbeat` | `anyOf` |  |
| `template` | `anyOf` |  |
| `session` | `anyOf` |  |
| `total_runs` | `anyOf` |  |
| `successful_runs` | `anyOf` |  |
| `total_tokens_accumulated` | `anyOf` |  |
| `total_input_tokens` | `anyOf` |  |
| `total_output_tokens` | `anyOf` |  |
| `total_running_time_seconds` | `anyOf` |  |
| `tool_call_counts` | `anyOf` |  |
| `last_reasoning` | `anyOf` |  |
| `last_error` | `anyOf` |  |

## `AgentInstanceStatusUpdate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `status*` | `string` |  |

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

## `AgentTemplateCreate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `name*` | `string` |  |
| `description` | `anyOf` |  |
| `system_prompt_path` | `anyOf` |  |
| `max_loop_iterations` | `integer` |  |

## `AgentTemplateResponse`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `name*` | `string` |  |
| `description` | `anyOf` |  |
| `system_prompt_path` | `anyOf` |  |
| `max_loop_iterations` | `integer` |  |
| `id*` | `string` |  |
| `system_prompt_content` | `anyOf` |  |

## `AgentTriggerCreate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `trigger_type*` | `string` |  |
| `cron_expression` | `anyOf` |  |
| `interval_seconds` | `anyOf` |  |
| `default_prompt` | `anyOf` |  |

## `AgentTriggerResponse`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `instance_id*` | `string` |  |
| `trigger_type*` | `string` |  |
| `cron_expression` | `anyOf` |  |
| `interval_seconds` | `anyOf` |  |
| `default_prompt` | `anyOf` |  |
| `webhook_secret` | `anyOf` |  |
| `webhook_mapping_schema` | `anyOf` |  |
| `id*` | `string` |  |

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

## `DeployAgentRequest`

**Type:** `object`

**Description:** One-click deployment: creates template + session + instance atomically.

| Property | Type | Description |
|----------|------|-------------|
| `name*` | `string` |  |
| `description` | `anyOf` |  |
| `system_prompt` | `anyOf` |  |
| `mesh_node_id*` | `string` |  |
| `max_loop_iterations` | `integer` |  |
| `initial_prompt` | `anyOf` |  |
| `provider_name` | `anyOf` |  |
| `trigger_type` | `anyOf` |  |
| `cron_expression` | `anyOf` |  |
| `interval_seconds` | `anyOf` |  |
| `default_prompt` | `anyOf` |  |

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

## `FileCopyRequest`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `old_path*` | `string` |  |
| `new_path*` | `string` |  |
| `session_id` | `anyOf` |  |

## `FileDeleteRequest`

**Type:** `object`

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

## `FileMoveRequest`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `old_path*` | `string` |  |
| `new_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` |  |

## `FileStatResponse`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `path*` | `string` |  |
| `name*` | `string` |  |
| `size*` | `integer` |  |
| `is_dir*` | `boolean` |  |
| `is_file*` | `boolean` |  |
| `is_link*` | `boolean` |  |
| `mtime*` | `number` |  |
| `exists` | `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` |  |
| `source_node_id` | `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` |  |
| `restrict_skills` | `boolean` |  |
| `allowed_skill_names` | `anyOf` |  |
| `system_prompt_override` | `anyOf` |  |
| `is_locked` | `boolean` |  |
| `auto_clear_history` | `boolean` |  |

## `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` |  |
| `restrict_skills` | `anyOf` |  |
| `allowed_skill_ids` | `anyOf` |  |
| `allowed_skill_names` | `anyOf` |  |
| `system_prompt_override` | `anyOf` |  |
| `is_locked` | `anyOf` |  |
| `auto_clear_history` | `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` |  |
| `is_enabled` | `boolean` |  |
| `features` | `array` |  |
| `is_system` | `boolean` |  |
| `extra_metadata` | `object` |  |

## `SkillFileUpdate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `content*` | `string` |  |

## `SkillUpdate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `name` | `anyOf` |  |
| `description` | `anyOf` |  |
| `skill_type` | `anyOf` |  |
| `is_enabled` | `anyOf` |  |
| `features` | `anyOf` |  |
| `is_system` | `anyOf` |  |
| `extra_metadata` | `anyOf` |  |

## `SpeechRequest`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `text*` | `string` |  |

## `SwarmConfigUpdate`

**Type:** `object`

| Property | Type | Description |
|----------|------|-------------|
| `external_endpoint` | `anyOf` |  |
| `grpc_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` |  |

