@1claw/openapi-spec 0.43.0 → 0.43.2

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.29.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.31.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,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
     }
@@ -10400,11 +10400,11 @@
         },
         "responses": {
           "201": {
-            "description": "Automation created",
+            "description": "Automation created (includes one-time webhook credentials when trigger_type is webhook)",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AutomationResponse"
+                  "$ref": "#/components/schemas/AutomationCreatedResponse"
                 }
               }
             }
@@ -10648,6 +10648,183 @@
         }
       }
     },
+    "/v1/automations/assist/draft": {
+      "post": {
+        "tags": [
+          "Automations"
+        ],
+        "summary": "Draft automation from natural language",
+        "operationId": "assistDraftAutomation",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "message"
+                ],
+                "properties": {
+                  "message": {
+                    "type": "string"
+                  },
+                  "agent_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "timezone": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Reviewable automation draft",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AssistDraftResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/automations/assist/session": {
+      "post": {
+        "tags": [
+          "Automations"
+        ],
+        "summary": "Mint short-lived Assist session token",
+        "operationId": "assistAutomationSession",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "runtime_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Assist session token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AssistSessionResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/automations/webhook/{automationId}/{token}": {
+      "post": {
+        "tags": [
+          "Automations"
+        ],
+        "summary": "Public webhook trigger",
+        "operationId": "webhookTriggerAutomation",
+        "security": [],
+        "parameters": [
+          {
+            "name": "automationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "token",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "description": "whk_ prefixed webhook token (SHA-256 verified server-side)"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Automation run queued",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AutomationRunResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/automations/{automationId}/rotate-webhook-token": {
+      "post": {
+        "tags": [
+          "Automations"
+        ],
+        "summary": "Rotate webhook token",
+        "operationId": "rotateAutomationWebhookToken",
+        "parameters": [
+          {
+            "name": "automationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "New one-time webhook URL and token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WebhookTokenRotatedResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/runtimes": {
       "post": {
         "tags": [
@@ -10917,21 +11094,13 @@
             }
           },
           {
-            "name": "since",
-            "in": "query",
-            "schema": {
-              "type": "string",
-              "format": "date-time"
-            },
-            "description": "Only return logs after this timestamp"
-          },
-          {
-            "name": "limit",
+            "name": "tail",
             "in": "query",
             "schema": {
               "type": "integer",
               "default": 100
-            }
+            },
+            "description": "Number of recent log lines to return"
           }
         ],
         "responses": {
@@ -10941,11 +11110,17 @@
               "application/json": {
                 "schema": {
                   "type": "object",
+                  "required": [
+                    "entries"
+                  ],
                   "properties": {
-                    "lines": {
+                    "entries": {
                       "type": "array",
                       "items": {
                         "type": "object",
+                        "required": [
+                          "message"
+                        ],
                         "properties": {
                           "timestamp": {
                             "type": "string",
@@ -11008,6 +11183,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": [
@@ -19949,42 +20222,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
+              }
+            ]
           }
         }
       },
@@ -19994,32 +20286,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"
@@ -20030,8 +20322,11 @@
         "type": "object",
         "required": [
           "id",
+          "agent_id",
           "name",
           "trigger_type",
+          "timezone",
+          "workflow_spec",
           "is_active",
           "created_at",
           "updated_at"
@@ -20041,58 +20336,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
@@ -20107,6 +20402,92 @@
           }
         }
       },
+      "AutomationCreatedResponse": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/AutomationResponse"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "webhook_url": {
+                "type": "string",
+                "description": "Full POST URL including token (one-time on create)"
+              },
+              "webhook_token": {
+                "type": "string",
+                "description": "whk_ token segment (one-time on create)"
+              }
+            }
+          }
+        ]
+      },
+      "WebhookTokenRotatedResponse": {
+        "type": "object",
+        "required": [
+          "webhook_url",
+          "webhook_token"
+        ],
+        "properties": {
+          "webhook_url": {
+            "type": "string"
+          },
+          "webhook_token": {
+            "type": "string"
+          }
+        }
+      },
+      "AssistDraftResponse": {
+        "type": "object",
+        "required": [
+          "draft",
+          "reply"
+        ],
+        "properties": {
+          "draft": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "reply": {
+            "type": "string"
+          }
+        }
+      },
+      "AssistSessionResponse": {
+        "type": "object",
+        "required": [
+          "access_token",
+          "expires_in",
+          "scopes",
+          "cli_hint"
+        ],
+        "properties": {
+          "access_token": {
+            "type": "string"
+          },
+          "expires_in": {
+            "type": "integer"
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "runtime_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "runtime_status": {
+            "type": "string",
+            "nullable": true
+          },
+          "cli_hint": {
+            "type": "string"
+          }
+        }
+      },
       "AutomationListResponse": {
         "type": "object",
         "required": [
@@ -20126,8 +20507,11 @@
         "required": [
           "id",
           "automation_id",
+          "agent_id",
           "status",
-          "started_at"
+          "started_at",
+          "tokens_used",
+          "cost_cents"
         ],
         "properties": {
           "id": {
@@ -20138,32 +20522,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"
           }
         }
       },
@@ -20230,6 +20627,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"
           }
         }
       },
@@ -20273,6 +20681,15 @@
               "jwt",
               "public"
             ]
+          },
+          "shell_access_enabled": {
+            "type": "boolean"
+          },
+          "shell_auth_policy": {
+            "type": "string"
+          },
+          "shell_max_session_minutes": {
+            "type": "integer"
           }
         }
       },
@@ -20361,6 +20778,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
@@ -20408,6 +20834,56 @@
           }
         }
       },
+      "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"
+          },
+          "ws_url": {
+            "type": "string",
+            "description": "WebSocket URL for the PTY terminal"
+          },
+          "expires_in": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "runtime_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "max_session_minutes": {
+            "type": "integer"
+          }
+        }
+      },
       "MemoryEntry": {
         "type": "object",
         "required": [