@1claw/openapi-spec 0.58.0 → 0.59.0

package/openapi.yaml

@@ -6425,6 +6425,35 @@ paths:
                                     $ref: "#/components/schemas/PlatformTemplateResponse"
 
     /v1/platform/apps/{appId}/templates/{template_id}:
+        get:
+            tags: [Platform]
+            summary: Get a bootstrap template
+            description: Returns the full template spec for a platform app. plt_ or user JWT.
+            operationId: getPlatformTemplate
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: template_id
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Template details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformTemplateResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
         patch:
             tags: [Platform]
             summary: Update a bootstrap template
@@ -6612,9 +6641,13 @@ paths:
                     content:
                         application/json:
                             schema:
-                                type: array
-                                items:
-                                    $ref: "#/components/schemas/PlatformConnectedUserResponse"
+                                type: object
+                                required: [users]
+                                properties:
+                                    users:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/PlatformConnectedUserResponse"
 
     /v1/platform/connections/{connectionId}/bootstrap:
         post:
@@ -7246,9 +7279,10 @@ paths:
             tags: [Platform]
             summary: Set per-user spend policy override
             description: |
-                Override the app-wide spend policy for a specific connected user. This
-                policy takes precedence over the app default. Remove by deleting the
-                connection-level policy.
+                Replace the per-user spend policy for a connected user (deactivates the
+                previous active row, then inserts). Requires plt_ platform auth.
+                Optional `Idempotency-Key` header must cover the full request body — reusing
+                the same key with different parameters returns 409.
             operationId: setUserSpendPolicy
             security:
                 - BearerAuth: []
@@ -7416,6 +7450,337 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/platform/connections/{connectionId}/pending-approvals/{approvalId}:
+        get:
+            tags: [Platform]
+            summary: Get a connection-scoped pending approval (with payload_hash)
+            operationId: getConnectionPendingApproval
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: approvalId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Pending approval detail including action_payload and payload_hash
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PendingApprovalResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/pending-approvals/{approvalId}/decide:
+        post:
+            tags: [Platform]
+            summary: Decide a pending approval for a connection user
+            description: |
+                Platform apps vote on behalf of the connected user after verifying intent
+                out-of-band (e.g. wallet mandate). Requires `payload_hash` matching the
+                pending row. Accepts `decision`: `approve` or `reject` (aliases `approved` /
+                `rejected`). plt_ auth only; scoped to agents on the connection.
+            operationId: decideConnectionPendingApproval
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: approvalId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ApprovePendingApprovalRequest"
+            responses:
+                "200":
+                    description: Updated pending approval
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PendingApprovalResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    description: Already voted
+
+    /v1/platform/connections/{connectionId}/approvals/{approvalId}/decide:
+        post:
+            tags: [Platform]
+            summary: Decide a mobile/agent approval for a connection user
+            description: |
+                Platform apps decide agent approval requests on behalf of the connected user.
+                Accepts `decision`: `approved` or `rejected` (aliases `approve` / `reject`).
+                plt_ auth only.
+            operationId: decideConnectionApproval
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: approvalId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [decision]
+                            properties:
+                                decision:
+                                    type: string
+                                    enum: [approved, rejected, approve, reject]
+                                reason:
+                                    type: string
+            responses:
+                "200":
+                    description: Decided approval
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ApprovalResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    description: Already decided
+
+    /v1/platform/connections/{connectionId}/signing-keys/{chain}:
+        delete:
+            tags: [Platform]
+            summary: Deactivate a signing key for a connection agent
+            description: |
+                Deactivates the signing key for an agent provisioned on the connection.
+                When multiple agents exist, pass `agent_id` query param. plt_ auth only.
+            operationId: deactivateConnectionSigningKey
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: chain
+                  required: true
+                  schema:
+                      type: string
+                - in: query
+                  name: agent_id
+                  required: false
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Key deactivated
+                "400":
+                    description: Multiple agents — agent_id required
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/runtimes:
+        post:
+            tags: [Platform]
+            summary: Create a runtime for a connection agent
+            description: |
+                Creates a Cloud Runtime in the end-user's org for an agent on this connection.
+                Use instead of `POST /v1/runtimes` with a plt_ key (which resolves to the platform org).
+                App must verify user intent out-of-band (e.g. wallet mandate) before calling.
+            operationId: createConnectionRuntime
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateConnectionRuntimeRequest"
+            responses:
+                "201":
+                    description: Runtime created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RuntimeResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/runtimes/{runtimeId}:
+        get:
+            tags: [Platform]
+            summary: Get a connection runtime (plt_ scoped)
+            description: |
+                Returns a runtime provisioned on this connection. Use instead of
+                `GET /v1/runtimes/{id}` with a plt_ key (which resolves to the platform org).
+            operationId: getConnectionRuntime
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: runtimeId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Runtime details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RuntimeResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/passkeys/enroll/begin:
+        post:
+            tags: [Platform]
+            summary: Begin passkey enrollment for a connected user
+            description: |
+                Starts WebAuthn registration for the end-user on this connection.
+                Platform apps use this instead of `POST /v1/auth/passkeys/register/begin` (user JWT only).
+            operationId: connectionPasskeyEnrollBegin
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: WebAuthn registration ceremony options
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PasskeyRegisterBeginResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/passkeys/enroll/complete:
+        post:
+            tags: [Platform]
+            summary: Complete passkey enrollment for a connected user
+            operationId: connectionPasskeyEnrollComplete
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/PasskeyRegisterCompleteRequest"
+            responses:
+                "201":
+                    description: Passkey registered
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PasskeyRegisterCompleteResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/agents/{agentId}/chat:
+        post:
+            tags: [Platform]
+            summary: Chat with a connection agent (plt_ scoped)
+            description: |
+                Send a chat message to an agent provisioned on this connection, acting as the
+                connected end-user. Use instead of `POST /v1/agents/{id}/chat` with a plt_ key.
+            operationId: connectionAgentChat
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: agentId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/SendChatMessageRequest"
+            responses:
+                "200":
+                    description: Message sent (JSON or SSE stream)
+                "402":
+                    description: Payment required (LLM billing / inference allowance)
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # --- Approvals ---
 
     /v1/approvals:
@@ -8994,6 +9359,45 @@ paths:
                             schema:
                                 $ref: "#/components/schemas/AutomationPresetsResponse"
 
+    /v1/agents/{agent_id}/automations:
+        post:
+            tags: [Automations]
+            summary: Create agent automation (agent-only)
+            operationId: createAgentAutomation
+            description: |
+                Agent-scoped create for simple manual or webhook automations from chat/runtime tools.
+                Allowed step types: log, notify, memory_get, memory_put, wait (max 10).
+                Cron, swap, http, and transaction steps require human dashboard setup.
+                Requires agent JWT; agent_id in path must match the caller.
+            parameters:
+                - name: agent_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/AgentCreateAutomationRequest"
+            responses:
+                "201":
+                    description: Automation created (includes one-time webhook credentials when trigger_type is webhook)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationCreatedResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Runtimes
     # ---------------------------------------------------------------------------
@@ -12912,6 +13316,9 @@ components:
                     description: Enable Shroud LLM Proxy for this agent
                 shroud_config:
                     $ref: "#/components/schemas/ShroudConfig"
+                system_prompt:
+                    type: string
+                    description: Default system prompt for agent chat when requests do not override it.
                 execution_intents_enabled:
                     type: boolean
                     default: false
@@ -13115,6 +13522,10 @@ components:
                     description: Enable/disable Shroud LLM Proxy
                 shroud_config:
                     $ref: "#/components/schemas/ShroudConfig"
+                system_prompt:
+                    type: string
+                    nullable: true
+                    description: Default system prompt for agent chat (null clears).
                 execution_intents_enabled:
                     type: boolean
                     description: Enable/disable Execution Intents for this agent
@@ -13385,6 +13796,9 @@ components:
                     description: Whether this agent routes LLM traffic through the Shroud TEE proxy
                 shroud_config:
                     $ref: "#/components/schemas/ShroudConfig"
+                system_prompt:
+                    type: string
+                    description: Default system prompt for agent chat when requests do not override it.
                 execution_intents_enabled:
                     type: boolean
                     description: Whether Execution Intents (bindings and execute endpoint) are enabled for this agent
@@ -17641,6 +18055,12 @@ components:
                     type: string
                 entitlement_status:
                     type: string
+                provisioned_tier:
+                    type: string
+                    nullable: true
+                    description: |
+                        Billing tier granted to the end-user org when billing_model is platform_pays
+                        (from template plan at bootstrap). Null when not provisioned.
                 wallet_address:
                     type: string
                     nullable: true
@@ -17654,6 +18074,16 @@ components:
                     items:
                         type: string
                         format: uuid
+                runtime_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                automation_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
                 claimed_at:
                     type: string
                     format: date-time
@@ -17894,6 +18324,58 @@ components:
                     minimum: 0
                     description: Number of WebAuthn passkeys registered for the calling user.
 
+        PasskeyRegisterBeginResponse:
+            type: object
+            properties:
+                challenge:
+                    type: string
+                rp_id:
+                    type: string
+                rp_name:
+                    type: string
+                user_id:
+                    type: string
+                user_name:
+                    type: string
+                user_display_name:
+                    type: string
+                attestation:
+                    type: string
+                authenticator_selection:
+                    type: object
+                pub_key_cred_params:
+                    type: array
+                    items:
+                        type: object
+
+        PasskeyRegisterCompleteRequest:
+            type: object
+            required: [credential_id, attestation_object, client_data_json]
+            properties:
+                credential_id:
+                    type: string
+                attestation_object:
+                    type: string
+                client_data_json:
+                    type: string
+                transports:
+                    type: array
+                    items:
+                        type: string
+                name:
+                    type: string
+
+        PasskeyRegisterCompleteResponse:
+            type: object
+            properties:
+                passkey_id:
+                    type: string
+                    format: uuid
+                credential_id:
+                    type: string
+                name:
+                    type: string
+
         PasskeyTxAssertBeginRequest:
             type: object
             required: [tx_digest]
@@ -18502,6 +18984,33 @@ components:
                         - type: object
                           additionalProperties: true
 
+        AgentCreateAutomationRequest:
+            type: object
+            required: [name, workflow_spec]
+            description: |
+                Agent-scoped automation create. Defaults to manual trigger.
+                workflow_spec must use only agent-allowed step types (log, notify, memory_get, memory_put, wait).
+            properties:
+                name:
+                    type: string
+                    maxLength: 128
+                trigger_type:
+                    type: string
+                    enum: [manual, webhook]
+                    default: manual
+                workflow_spec:
+                    oneOf:
+                        - type: array
+                          items:
+                              type: object
+                              additionalProperties: true
+                        - type: object
+                          additionalProperties: true
+                auto_trigger:
+                    type: boolean
+                    default: false
+                    description: When true (manual trigger only), start a run immediately after creation
+
         UpdateAutomationRequest:
             type: object
             properties:
@@ -18585,6 +19094,10 @@ components:
                     type: string
                     nullable: true
                     description: Resolved agent display name (enriched list field)
+                created_by_type:
+                    type: string
+                    enum: [user, agent]
+                    description: Whether the automation was created by a human or agent (chat-native create)
                 created_at:
                     type: string
                     format: date-time
@@ -18730,6 +19243,35 @@ components:
 
         # --- Runtimes ---
 
+        CreateConnectionRuntimeRequest:
+            type: object
+            required: [name]
+            properties:
+                name:
+                    type: string
+                agent_id:
+                    type: string
+                    format: uuid
+                    description: Required when multiple agents on the connection; defaults to sole agent
+                template:
+                    type: string
+                preset:
+                    type: string
+                    default: medium
+                env_public:
+                    type: object
+                    additionalProperties: true
+                idle_timeout_secs:
+                    type: integer
+                expose_http:
+                    type: boolean
+                slug:
+                    type: string
+                inbound_auth:
+                    type: string
+                startup_command:
+                    type: string
+
         CreateRuntimeRequest:
             type: object
             required: [name, agent_id]
@@ -19182,10 +19724,10 @@ components:
 
         SendChatMessageRequest:
             type: object
-            required: [message]
             properties:
                 message:
                     type: string
+                    description: User message text. Optional when `messages` includes a user turn.
                 conversation_id:
                     type: string
                     format: uuid
@@ -19197,6 +19739,28 @@ components:
                     type: string
                 system_prompt:
                     type: string
+                    description: Stored on new conversations when `conversation_id` is omitted.
+                system:
+                    type: string
+                    description: Per-request system prompt alias (same precedence as `system_prompt_override`).
+                system_prompt_override:
+                    type: string
+                    description: Per-request override; highest precedence except inline `messages` system role.
+                messages:
+                    type: array
+                    description: Optional OpenAI-shaped history. When set, used for LLM context instead of DB history.
+                    items:
+                        type: object
+                        required: [role, content]
+                        properties:
+                            role:
+                                type: string
+                            content:
+                                type: string
+                llm_api_key_vault_id:
+                    type: string
+                llm_api_key_path:
+                    type: string
 
         ChatMessageResponse:
             type: object
@@ -20628,7 +21192,7 @@ components:
             properties:
                 decision:
                     type: string
-                    enum: [approve, reject]
+                    enum: [approve, reject, approved, rejected]
                 payload_hash:
                     type: string
                 reason: