@1claw/openapi-spec 0.43.0 → 0.43.2

package/openapi.yaml

@@ -2,12 +2,13 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.29.0
+    version: 2.31.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
-        sharing, billing, and audit logging. Automations, cloud runtimes,
-        agent memory, and discovery.
+        sharing, billing, and audit logging. Automations (workflow_spec,
+        webhook tokens, event triggers, Assist), cloud runtimes with
+        interactive shell sessions, agent memory, and discovery.
 
         All endpoints require JWT Bearer authentication unless marked with
         `security: []`.
@@ -6627,11 +6628,11 @@ paths:
                             $ref: "#/components/schemas/CreateAutomationRequest"
             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"
                 "400":
                     $ref: "#/components/responses/BadRequest"
                 "401":
@@ -6780,6 +6781,117 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /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"
+
     # ---------------------------------------------------------------------------
     # Runtimes
     # ---------------------------------------------------------------------------
@@ -6952,17 +7064,12 @@ paths:
                   schema:
                       type: string
                       format: uuid
-                - 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:
                 "200":
                     description: Runtime logs
@@ -6970,11 +7077,13 @@ paths:
                         application/json:
                             schema:
                                 type: object
+                                required: [entries]
                                 properties:
-                                    lines:
+                                    entries:
                                         type: array
                                         items:
                                             type: object
+                                            required: [message]
                                             properties:
                                                 timestamp:
                                                     type: string
@@ -7009,6 +7118,78 @@ paths:
                 "401":
                     $ref: "#/components/responses/Unauthorized"
 
+    /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
+                runtime's PTY terminal. Requires step-up auth via `password`,
+                `totp_code`, `passkey_credential`, or `reauth_token` (from
+                `POST /v1/auth/reauth` with purpose `runtime_shell`).
+                Runtime must have `shell_access_enabled` and be running.
+                Enabling shell on a running runtime may require stop/start, or
+                the server may auto-reconcile the sidecar on connect.
+            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
+                step-up auth (social/Google users without a password).
+            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"
+
     # ---------------------------------------------------------------------------
     # Agent Memory
     # ---------------------------------------------------------------------------
@@ -13124,97 +13305,110 @@ components:
 
         CreateAutomationRequest:
             type: object
-            required: [name]
+            required: [name, agent_id, trigger_type, workflow_spec]
+            description: |
+                Create an automation. `workflow_spec` is required and must be either
+                a JSON array of steps or `{ "steps": [...] }`. Dashboard `schedule`
+                trigger_type is accepted and normalized to `cron`. For cron triggers,
+                `cron_expr` is required.
             properties:
                 name:
                     type: string
-                description:
-                    type: string
                 agent_id:
                     type: string
                     format: uuid
                 trigger_type:
                     type: string
-                    enum: [schedule, webhook, event, manual]
-                trigger_config:
-                    type: object
-                    additionalProperties: true
-                action_type:
+                    description: cron | event | webhook | manual (alias schedule → cron)
+                    enum: [cron, event, webhook, manual, schedule]
+                cron_expr:
+                    type: string
+                    description: Required when trigger_type is cron (or schedule)
+                    example: "0 */6 * * *"
+                timezone:
                     type: string
-                action_config:
+                    default: UTC
+                    example: UTC
+                event_filter:
                     type: object
                     additionalProperties: true
-                is_active:
-                    type: boolean
-                    default: true
+                    nullable: true
+                workflow_spec:
+                    description: |
+                        Workflow steps. Accepts a bare array `[...]` or
+                        `{ "steps": [...] }` (dashboard / preset shape).
+                    oneOf:
+                        - type: array
+                          items:
+                              type: object
+                              additionalProperties: true
+                        - type: object
+                          additionalProperties: true
 
         UpdateAutomationRequest:
             type: object
             properties:
                 name:
                     type: string
-                description:
+                cron_expr:
                     type: string
-                agent_id:
-                    type: string
-                    format: uuid
-                trigger_type:
-                    type: string
-                    enum: [schedule, webhook, event, manual]
-                trigger_config:
-                    type: object
-                    additionalProperties: true
-                action_type:
+                    nullable: true
+                timezone:
                     type: string
-                action_config:
+                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
 
         AutomationResponse:
             type: object
-            required: [id, name, trigger_type, is_active, created_at, updated_at]
+            required: [id, agent_id, name, trigger_type, timezone, workflow_spec, is_active, created_at, updated_at]
             properties:
                 id:
                     type: string
                     format: uuid
-                name:
-                    type: string
-                description:
-                    type: string
-                    nullable: true
                 agent_id:
                     type: string
                     format: uuid
-                    nullable: true
+                name:
+                    type: string
                 trigger_type:
                     type: string
-                    enum: [schedule, webhook, event, manual]
-                trigger_config:
-                    type: object
-                    additionalProperties: true
-                    nullable: true
-                action_type:
+                    enum: [cron, event, webhook, manual]
+                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
@@ -13225,6 +13419,59 @@ components:
                     type: string
                     format: date-time
 
+        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: [automations]
@@ -13236,7 +13483,7 @@ components:
 
         AutomationRunResponse:
             type: object
-            required: [id, automation_id, status, started_at]
+            required: [id, automation_id, agent_id, status, started_at, tokens_used, cost_cents]
             properties:
                 id:
                     type: string
@@ -13244,23 +13491,31 @@ components:
                 automation_id:
                     type: string
                     format: uuid
+                agent_id:
+                    type: string
+                    format: uuid
                 status:
                     type: string
-                    enum: [pending, running, completed, failed]
+                    enum: [pending, running, completed, 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
-                error:
-                    type: string
-                    nullable: true
+                tokens_used:
+                    type: integer
+                cost_cents:
+                    type: integer
 
         AutomationRunListResponse:
             type: object
@@ -13304,6 +13559,14 @@ components:
                 inbound_auth:
                     type: string
                     enum: [api_key, 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
 
         UpdateRuntimeRequest:
             type: object
@@ -13331,6 +13594,12 @@ components:
                 inbound_auth:
                     type: string
                     enum: [api_key, jwt, public]
+                shell_access_enabled:
+                    type: boolean
+                shell_auth_policy:
+                    type: string
+                shell_max_session_minutes:
+                    type: integer
 
         RuntimeResponse:
             type: object
@@ -13383,6 +13652,12 @@ components:
                     type: string
                     enum: [api_key, jwt, public]
                     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
@@ -13414,6 +13689,41 @@ components:
                     type: string
                     nullable: true
 
+        ShellSessionRequest:
+            type: object
+            description: |
+                Step-up credentials for an interactive shell session.
+                Provide one of password, totp_code, passkey_credential, or reauth_token.
+            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
+
         # --- Agent Memory ---
 
         MemoryEntry:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1claw/openapi-spec",
-  "version": "0.43.0",
+  "version": "0.43.2",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
   "license": "MIT",
   "repository": {