@1claw/openapi-spec 0.42.0 → 0.43.1

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.28.0",
-    "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations, cloud runtimes,\nagent memory, and discovery.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
+    "version": "2.30.0",
+    "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec),\ncloud runtimes with interactive shell sessions, agent memory,\nand discovery.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
     }
@@ -150,6 +150,14 @@
     {
       "name": "Discovery",
       "description": "Agent directory and platform marketplace"
+    },
+    {
+      "name": "Agent Chat",
+      "description": "Chat with agents via Shroud LLM proxy"
+    },
+    {
+      "name": "Agent Channels",
+      "description": "External messaging channels (Telegram, WhatsApp, Discord)"
     }
   ],
   "paths": {
@@ -11000,6 +11008,104 @@
         }
       }
     },
+    "/v1/runtimes/{runtimeId}/shell/session": {
+      "post": {
+        "tags": [
+          "Runtimes"
+        ],
+        "summary": "Create interactive shell session",
+        "description": "Human-only. Creates a short-lived WebSocket session token for the\nruntime's PTY terminal. Requires step-up auth via `password`,\n`totp_code`, `passkey_credential`, or `reauth_token` (from\n`POST /v1/auth/reauth` with purpose `runtime_shell`).\nRuntime must have `shell_access_enabled` and be running.\nEnabling shell on a running runtime may require stop/start, or\nthe server may auto-reconcile the sidecar on connect.\n",
+        "operationId": "createShellSession",
+        "parameters": [
+          {
+            "name": "runtimeId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ShellSessionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Shell session created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ShellSessionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/runtimes/{runtimeId}/shell/passkey/begin": {
+      "post": {
+        "tags": [
+          "Runtimes"
+        ],
+        "summary": "Begin shell passkey assertion",
+        "description": "Human-only. Starts a WebAuthn assertion ceremony for shell\nstep-up auth (social/Google users without a password).\n",
+        "operationId": "beginShellPasskey",
+        "parameters": [
+          {
+            "name": "runtimeId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Passkey challenge for shell session",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/memory": {
       "get": {
         "tags": [
@@ -11444,102 +11550,673 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      },
-      "ApiKeyAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "1ck_ prefixed API key used as Bearer token"
-      }
     },
-    "parameters": {
-      "VaultId": {
-        "name": "vault_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "SecretPath": {
-        "name": "path",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string"
+    "/v1/agents/{agent_id}/chat": {
+      "post": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "Send chat message",
+        "description": "Send a message to an agent and receive a response via Shroud LLM.\nSupports SSE streaming when Accept: text/event-stream is set.\n",
+        "operationId": "sendChatMessage",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SendChatMessageRequest"
+              }
+            }
+          }
         },
-        "description": "Secret path (e.g. \"db/credentials\")"
-      },
-      "AgentId": {
-        "name": "agent_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "PolicyId": {
-        "name": "policy_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "CardId": {
-        "name": "card_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "IncludeSignedTx": {
-        "name": "include_signed_tx",
-        "in": "query",
-        "required": false,
-        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
-        "schema": {
-          "type": "boolean",
-          "default": false,
-          "example": false
+        "responses": {
+          "200": {
+            "description": "Chat response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SendChatMessageResponse"
+                }
+              },
+              "text/event-stream": {
+                "schema": {
+                  "type": "string",
+                  "description": "SSE stream of response chunks"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
         }
       }
     },
-    "responses": {
-      "BadRequest": {
-        "description": "Invalid request",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+    "/v1/agents/{agent_id}/chat/conversations": {
+      "get": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "List conversations",
+        "description": "List all chat conversations for an agent.",
+        "operationId": "listChatConversations",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Conversation list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChatConversationListResponse"
+                }
+              }
             }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
           }
         }
-      },
-      "Unauthorized": {
-        "description": "Authentication required or invalid",
-        "content": {
-          "application/json": {
+      }
+    },
+    "/v1/agents/{agent_id}/chat/conversations/{conversation_id}": {
+      "get": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "Get conversation",
+        "description": "Get a conversation with its full message history.",
+        "operationId": "getChatConversation",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Conversation detail",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConversationDetailResponse"
+                }
+              }
             }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       },
-      "Forbidden": {
-        "description": "Insufficient permissions",
+      "delete": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "Archive conversation",
+        "description": "Archive (soft-delete) a chat conversation.",
+        "operationId": "deleteChatConversation",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Conversation archived"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Register channel",
+        "description": "Register a new external messaging channel (Telegram, WhatsApp, Discord)\nfor an agent. Human-only. Returns the channel with its webhook URL.\n",
+        "operationId": "createChannel",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateChannelRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Channel created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "List channels",
+        "description": "List all messaging channels for an agent.",
+        "operationId": "listChannels",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Channel list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels/{channel_id}": {
+      "patch": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Update channel",
+        "description": "Update a channel's name, active status, or config. Human-only.",
+        "operationId": "updateChannel",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateChannelRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Channel updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Delete channel",
+        "description": "Delete a messaging channel. Human-only.",
+        "operationId": "deleteChannel",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Channel deleted"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels/{channel_id}/send": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Send outbound message",
+        "description": "Send an outbound message via a registered channel.",
+        "operationId": "sendChannelMessage",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SendChannelMessageRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Message sent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelMessageResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels/{channel_id}/messages": {
+      "get": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Channel message history",
+        "description": "List inbound and outbound messages for a channel.",
+        "operationId": "listChannelMessages",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 50
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Message list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelMessageListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/telegram/{webhook_path}": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Telegram webhook",
+        "description": "Public webhook endpoint for receiving Telegram bot updates.",
+        "operationId": "telegramWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/whatsapp/{webhook_path}": {
+      "get": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "WhatsApp webhook verification",
+        "description": "Verification endpoint for WhatsApp Cloud API webhook setup.",
+        "operationId": "whatsappWebhookVerify",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "hub.mode",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "hub.verify_token",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "hub.challenge",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Challenge response"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "WhatsApp webhook",
+        "description": "Public webhook endpoint for receiving WhatsApp Cloud API events.",
+        "operationId": "whatsappWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/discord/{webhook_path}": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Discord webhook",
+        "description": "Public webhook endpoint for receiving Discord bot interactions.",
+        "operationId": "discordWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "ApiKeyAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "1ck_ prefixed API key used as Bearer token"
+      }
+    },
+    "parameters": {
+      "VaultId": {
+        "name": "vault_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "SecretPath": {
+        "name": "path",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        },
+        "description": "Secret path (e.g. \"db/credentials\")"
+      },
+      "AgentId": {
+        "name": "agent_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "PolicyId": {
+        "name": "policy_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "CardId": {
+        "name": "card_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "IncludeSignedTx": {
+        "name": "include_signed_tx",
+        "in": "query",
+        "required": false,
+        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
+        "schema": {
+          "type": "boolean",
+          "default": false,
+          "example": false
+        }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "Invalid request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Authentication required or invalid",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "Insufficient permissions",
         "content": {
           "application/json": {
             "schema": {
@@ -19370,42 +20047,61 @@
       "CreateAutomationRequest": {
         "type": "object",
         "required": [
-          "name"
+          "name",
+          "agent_id",
+          "trigger_type",
+          "workflow_spec"
         ],
+        "description": "Create an automation. `workflow_spec` is required and must be either\na JSON array of steps or `{ \"steps\": [...] }`. Dashboard `schedule`\ntrigger_type is accepted and normalized to `cron`. For cron triggers,\n`cron_expr` is required.\n",
         "properties": {
           "name": {
             "type": "string"
           },
-          "description": {
-            "type": "string"
-          },
           "agent_id": {
             "type": "string",
             "format": "uuid"
           },
           "trigger_type": {
             "type": "string",
+            "description": "cron | event | webhook | manual (alias schedule → cron)",
             "enum": [
-              "schedule",
-              "webhook",
+              "cron",
               "event",
-              "manual"
+              "webhook",
+              "manual",
+              "schedule"
             ]
           },
-          "trigger_config": {
-            "type": "object",
-            "additionalProperties": true
+          "cron_expr": {
+            "type": "string",
+            "description": "Required when trigger_type is cron (or schedule)",
+            "example": "0 */6 * * *"
           },
-          "action_type": {
-            "type": "string"
+          "timezone": {
+            "type": "string",
+            "default": "UTC",
+            "example": "UTC"
           },
-          "action_config": {
+          "event_filter": {
             "type": "object",
-            "additionalProperties": true
+            "additionalProperties": true,
+            "nullable": true
           },
-          "is_active": {
-            "type": "boolean",
-            "default": true
+          "workflow_spec": {
+            "description": "Workflow steps. Accepts a bare array `[...]` or\n`{ \"steps\": [...] }` (dashboard / preset shape).\n",
+            "oneOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": true
+              }
+            ]
           }
         }
       },
@@ -19415,32 +20111,32 @@
           "name": {
             "type": "string"
           },
-          "description": {
-            "type": "string"
-          },
-          "agent_id": {
-            "type": "string",
-            "format": "uuid"
-          },
-          "trigger_type": {
+          "cron_expr": {
             "type": "string",
-            "enum": [
-              "schedule",
-              "webhook",
-              "event",
-              "manual"
-            ]
-          },
-          "trigger_config": {
-            "type": "object",
-            "additionalProperties": true
+            "nullable": true
           },
-          "action_type": {
+          "timezone": {
             "type": "string"
           },
-          "action_config": {
+          "event_filter": {
             "type": "object",
-            "additionalProperties": true
+            "additionalProperties": true,
+            "nullable": true
+          },
+          "workflow_spec": {
+            "oneOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": true
+              }
+            ]
           },
           "is_active": {
             "type": "boolean"
@@ -19451,8 +20147,11 @@
         "type": "object",
         "required": [
           "id",
+          "agent_id",
           "name",
           "trigger_type",
+          "timezone",
+          "workflow_spec",
           "is_active",
           "created_at",
           "updated_at"
@@ -19462,58 +20161,58 @@
             "type": "string",
             "format": "uuid"
           },
-          "name": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string",
-            "nullable": true
-          },
           "agent_id": {
             "type": "string",
-            "format": "uuid",
-            "nullable": true
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
           },
           "trigger_type": {
             "type": "string",
             "enum": [
-              "schedule",
-              "webhook",
+              "cron",
               "event",
+              "webhook",
               "manual"
             ]
           },
-          "trigger_config": {
-            "type": "object",
-            "additionalProperties": true,
-            "nullable": true
-          },
-          "action_type": {
+          "cron_expr": {
             "type": "string",
             "nullable": true
           },
-          "action_config": {
+          "timezone": {
+            "type": "string"
+          },
+          "event_filter": {
             "type": "object",
             "additionalProperties": true,
             "nullable": true
           },
+          "workflow_spec": {
+            "oneOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": true
+              }
+            ]
+          },
           "is_active": {
             "type": "boolean"
           },
-          "webhook_url": {
-            "type": "string",
-            "nullable": true
-          },
-          "schedule_expression": {
-            "type": "string",
-            "nullable": true
-          },
-          "next_run_at": {
+          "last_run_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
           },
-          "last_run_at": {
+          "next_run_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
@@ -19547,8 +20246,11 @@
         "required": [
           "id",
           "automation_id",
+          "agent_id",
           "status",
-          "started_at"
+          "started_at",
+          "tokens_used",
+          "cost_cents"
         ],
         "properties": {
           "id": {
@@ -19559,32 +20261,45 @@
             "type": "string",
             "format": "uuid"
           },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
           "status": {
             "type": "string",
             "enum": [
               "pending",
               "running",
               "completed",
-              "failed"
+              "failed",
+              "denied"
             ]
           },
+          "step_results": {
+            "nullable": true
+          },
+          "error": {
+            "type": "string",
+            "nullable": true
+          },
+          "trigger_source": {
+            "type": "string",
+            "nullable": true
+          },
           "started_at": {
             "type": "string",
             "format": "date-time"
           },
-          "completed_at": {
+          "finished_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
           },
-          "result": {
-            "type": "object",
-            "additionalProperties": true,
-            "nullable": true
+          "tokens_used": {
+            "type": "integer"
           },
-          "error": {
-            "type": "string",
-            "nullable": true
+          "cost_cents": {
+            "type": "integer"
           }
         }
       },
@@ -19651,6 +20366,17 @@
               "jwt",
               "public"
             ]
+          },
+          "shell_access_enabled": {
+            "type": "boolean",
+            "default": false
+          },
+          "shell_auth_policy": {
+            "type": "string",
+            "description": "Step-up auth policy for shell (e.g. password, passkey, totp)"
+          },
+          "shell_max_session_minutes": {
+            "type": "integer"
           }
         }
       },
@@ -19694,6 +20420,15 @@
               "jwt",
               "public"
             ]
+          },
+          "shell_access_enabled": {
+            "type": "boolean"
+          },
+          "shell_auth_policy": {
+            "type": "string"
+          },
+          "shell_max_session_minutes": {
+            "type": "integer"
           }
         }
       },
@@ -19782,6 +20517,15 @@
             ],
             "nullable": true
           },
+          "shell_access_enabled": {
+            "type": "boolean"
+          },
+          "shell_auth_policy": {
+            "type": "string"
+          },
+          "shell_max_session_minutes": {
+            "type": "integer"
+          },
           "monthly_hours_used": {
             "type": "number",
             "nullable": true
@@ -19817,15 +20561,65 @@
           "slug"
         ],
         "properties": {
-          "available": {
-            "type": "boolean"
-          },
-          "slug": {
+          "available": {
+            "type": "boolean"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "ShellSessionRequest": {
+        "type": "object",
+        "description": "Step-up credentials for an interactive shell session.\nProvide one of password, totp_code, passkey_credential, or reauth_token.\n",
+        "properties": {
+          "password": {
+            "type": "string"
+          },
+          "totp_code": {
+            "type": "string"
+          },
+          "passkey_credential": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "reauth_token": {
+            "type": "string",
+            "description": "Single-use `rat_` token from POST /v1/auth/reauth (purpose runtime_shell)"
+          }
+        }
+      },
+      "ShellSessionResponse": {
+        "type": "object",
+        "required": [
+          "session_token",
+          "ws_url",
+          "expires_in",
+          "runtime_id",
+          "max_session_minutes"
+        ],
+        "properties": {
+          "session_token": {
             "type": "string"
           },
-          "reason": {
+          "ws_url": {
             "type": "string",
-            "nullable": true
+            "description": "WebSocket URL for the PTY terminal"
+          },
+          "expires_in": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "runtime_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "max_session_minutes": {
+            "type": "integer"
           }
         }
       },
@@ -20089,6 +20883,307 @@
             }
           }
         }
+      },
+      "SendChatMessageRequest": {
+        "type": "object",
+        "required": [
+          "message"
+        ],
+        "properties": {
+          "message": {
+            "type": "string"
+          },
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "mode": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "system_prompt": {
+            "type": "string"
+          }
+        }
+      },
+      "ChatMessageResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "role": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "tool_calls": {},
+          "tool_results": {},
+          "tokens_prompt": {
+            "type": "integer"
+          },
+          "tokens_completion": {
+            "type": "integer"
+          },
+          "model": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChatConversationResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "title": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChatConversationListResponse": {
+        "type": "object",
+        "properties": {
+          "conversations": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChatConversationResponse"
+            }
+          }
+        }
+      },
+      "ConversationDetailResponse": {
+        "type": "object",
+        "properties": {
+          "conversation": {
+            "$ref": "#/components/schemas/ChatConversationResponse"
+          },
+          "messages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChatMessageResponse"
+            }
+          }
+        }
+      },
+      "SendChatMessageResponse": {
+        "type": "object",
+        "properties": {
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "message": {
+            "$ref": "#/components/schemas/ChatMessageResponse"
+          }
+        }
+      },
+      "CreateChannelRequest": {
+        "type": "object",
+        "required": [
+          "channel_type",
+          "config"
+        ],
+        "properties": {
+          "channel_type": {
+            "type": "string",
+            "enum": [
+              "telegram",
+              "whatsapp",
+              "discord"
+            ]
+          },
+          "channel_name": {
+            "type": "string"
+          },
+          "config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Platform-specific config.\nTelegram: { bot_token }.\nWhatsApp: { phone_number_id, access_token, verify_token }.\nDiscord: { bot_token, application_id }.\n"
+          }
+        }
+      },
+      "UpdateChannelRequest": {
+        "type": "object",
+        "properties": {
+          "channel_name": {
+            "type": "string"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ChannelResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "channel_type": {
+            "type": "string",
+            "enum": [
+              "telegram",
+              "whatsapp",
+              "discord"
+            ]
+          },
+          "channel_name": {
+            "type": "string"
+          },
+          "webhook_path": {
+            "type": "string"
+          },
+          "webhook_url": {
+            "type": "string"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChannelListResponse": {
+        "type": "object",
+        "properties": {
+          "channels": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChannelResponse"
+            }
+          }
+        }
+      },
+      "SendChannelMessageRequest": {
+        "type": "object",
+        "required": [
+          "external_chat_id",
+          "content"
+        ],
+        "properties": {
+          "external_chat_id": {
+            "type": "string",
+            "description": "External platform chat/user ID"
+          },
+          "content": {
+            "type": "string"
+          },
+          "reply_to": {
+            "type": "string",
+            "description": "External message ID to reply to"
+          }
+        }
+      },
+      "ChannelMessageResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "channel_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound"
+            ]
+          },
+          "external_chat_id": {
+            "type": "string"
+          },
+          "external_message_id": {
+            "type": "string"
+          },
+          "sender_name": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "media_url": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChannelMessageListResponse": {
+        "type": "object",
+        "properties": {
+          "messages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChannelMessageResponse"
+            }
+          }
+        }
       }
     }
   }