@1claw/openapi-spec 0.57.0 → 0.58.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.57.0",
+    "version": "0.58.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"
@@ -9648,8 +9648,15 @@
           }
         ],
         "responses": {
-          "204": {
-            "description": "Deleted"
+          "200": {
+            "description": "Soft-deleted; slug released for reuse within the org",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlatformAppDeleteResponse"
+                }
+              }
+            }
           },
           "403": {
             "description": "Only human users can delete platform apps"
@@ -9657,6 +9664,71 @@
         }
       }
     },
+    "/v1/platform/apps/{appId}/transfer-ownership": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Transfer platform app to another organization",
+        "description": "Moves the platform app record to another organization. Requires org\nowner/admin in the source org and step-up auth (`X-Auth-Confirm`,\npurpose `platform.app.transfer`). End-user connections and provisioned\nresources remain in their original organizations.\n",
+        "operationId": "transferPlatformAppOwnership",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "header",
+            "name": "X-Auth-Confirm",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TransferPlatformAppOwnershipRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Ownership transferred",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TransferPlatformAppOwnershipResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/platform/apps/{appId}/rotate-key": {
       "post": {
         "tags": [
@@ -11085,6 +11157,53 @@
       }
     },
     "/v1/platform/apps/{appId}/spend-policies/{policyId}": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Get a spend policy by ID",
+        "operationId": "getSpendPolicy",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "policyId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Spend policy",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SpendPolicyResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
       "delete": {
         "tags": [
           "Platform"
@@ -11127,6 +11246,57 @@
       }
     },
     "/v1/platform/connections/{connectionId}/spend-policy": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Get effective spend policy for a connection",
+        "description": "Returns the effective spend policy for the connected user, resolving\nper-user overrides before app-level defaults. Requires plt_ platform auth.\n",
+        "operationId": "getConnectionSpendPolicy",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "connectionId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Effective spend policy (or null)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "policy": {
+                      "oneOf": [
+                        {
+                          "$ref": "#/components/schemas/SpendPolicyResponse"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
       "put": {
         "tags": [
           "Platform"
@@ -11148,6 +11318,15 @@
               "type": "string",
               "format": "uuid"
             }
+          },
+          {
+            "in": "header",
+            "name": "Idempotency-Key",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional replay protection; same key + body returns cached response (409 on body mismatch)."
           }
         ],
         "requestBody": {
@@ -11162,7 +11341,17 @@
         },
         "responses": {
           "200": {
-            "description": "Spend policy set",
+            "description": "Spend policy set (or idempotent replay)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SpendPolicyResponse"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "Spend policy created",
             "content": {
               "application/json": {
                 "schema": {
@@ -11176,6 +11365,201 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "Idempotency-Key reused with different body"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connectionId}/approvals": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "List approvals for a platform connection",
+        "description": "Returns approvals assigned to the connection's user, filtered to agents\nprovisioned on the connection. Requires plt_ platform auth.\n",
+        "operationId": "listConnectionApprovals",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "connectionId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "risk_tier",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 50
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Connection-scoped approvals",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApprovalListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connectionId}/approvals/{approvalId}": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Get a connection-scoped approval",
+        "operationId": "getConnectionApproval",
+        "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": "Approval detail",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApprovalResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connectionId}/pending-approvals": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "List pending consensus approvals for a connection",
+        "description": "Returns pending approvals for agents provisioned on the connection,\nincluding `action_payload` and `payload_hash` for consensus UX.\nRequires plt_ platform auth.\n",
+        "operationId": "listConnectionPendingApprovals",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "connectionId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "default": "pending"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 50
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Pending approvals list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PendingApprovalListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       }
@@ -14199,7 +14583,7 @@
           "Runtimes"
         ],
         "summary": "Chat with a running runtime agent",
-        "description": "Human-only. Proxies to the runtime container's OpenAI-compatible\n`POST /v1/chat/completions` (hermes / openclaw / openclaude chat bridge).\nStarts the runtime if stopped. Streams SSE when `Accept: text/event-stream`\nor `stream: true`. Conversation history is ephemeral (pass `messages`).\nRequires a public URL (shell access, Shroud sidecar, or HTTP hosting).\n",
+        "description": "Human-only. Proxies to the runtime container's OpenAI-compatible\n`POST /v1/chat/completions` (hermes / openclaw / openclaude / opencode chat bridge).\nStarts the runtime if stopped. Streams SSE when `Accept: text/event-stream`\nor `stream: true`. Conversation history is ephemeral (pass `messages`).\nRequires a public URL (shell access, Shroud sidecar, or HTTP hosting).\n",
         "operationId": "runtimeChat",
         "parameters": [
           {
@@ -24898,6 +25282,69 @@
           }
         }
       },
+      "PlatformAppDeleteResponse": {
+        "type": "object",
+        "required": [
+          "deleted",
+          "soft_delete",
+          "slug_released",
+          "former_slug"
+        ],
+        "properties": {
+          "deleted": {
+            "type": "boolean"
+          },
+          "soft_delete": {
+            "type": "boolean"
+          },
+          "slug_released": {
+            "type": "boolean"
+          },
+          "former_slug": {
+            "type": "string"
+          }
+        }
+      },
+      "TransferPlatformAppOwnershipRequest": {
+        "type": "object",
+        "properties": {
+          "target_org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "target_user_email": {
+            "type": "string",
+            "format": "email"
+          }
+        },
+        "description": "Provide `target_org_id` or `target_user_email` (owner/admin in destination org)."
+      },
+      "TransferPlatformAppOwnershipResponse": {
+        "type": "object",
+        "required": [
+          "app_id",
+          "former_org_id",
+          "new_org_id",
+          "message"
+        ],
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "former_org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "new_org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      },
       "PlatformAppResponse": {
         "type": "object",
         "properties": {
@@ -25944,6 +26391,24 @@
           }
         }
       },
+      "ApprovalListResponse": {
+        "type": "object",
+        "required": [
+          "approvals",
+          "total"
+        ],
+        "properties": {
+          "approvals": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ApprovalResponse"
+            }
+          },
+          "total": {
+            "type": "integer"
+          }
+        }
+      },
       "ApprovalStatusResponse": {
         "type": "object",
         "required": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 0.57.0
+    version: 0.58.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -6216,11 +6216,59 @@ paths:
                       type: string
                       format: uuid
             responses:
-                "204":
-                    description: Deleted
+                "200":
+                    description: Soft-deleted; slug released for reuse within the org
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformAppDeleteResponse"
                 "403":
                     description: Only human users can delete platform apps
 
+    /v1/platform/apps/{appId}/transfer-ownership:
+        post:
+            tags: [Platform]
+            summary: Transfer platform app to another organization
+            description: |
+                Moves the platform app record to another organization. Requires org
+                owner/admin in the source org and step-up auth (`X-Auth-Confirm`,
+                purpose `platform.app.transfer`). End-user connections and provisioned
+                resources remain in their original organizations.
+            operationId: transferPlatformAppOwnership
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: header
+                  name: X-Auth-Confirm
+                  required: true
+                  schema:
+                      type: string
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/TransferPlatformAppOwnershipRequest"
+            responses:
+                "200":
+                    description: Ownership transferred
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TransferPlatformAppOwnershipResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/platform/apps/{appId}/rotate-key:
         post:
             tags: [Platform]
@@ -7110,6 +7158,34 @@ paths:
                                             $ref: "#/components/schemas/SpendPolicyResponse"
 
     /v1/platform/apps/{appId}/spend-policies/{policyId}:
+        get:
+            tags: [Platform]
+            summary: Get a spend policy by ID
+            operationId: getSpendPolicy
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: policyId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Spend policy
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SpendPolicyResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
         delete:
             tags: [Platform]
             summary: Delete a spend policy
@@ -7136,6 +7212,36 @@ paths:
                     $ref: "#/components/responses/NotFound"
 
     /v1/platform/connections/{connectionId}/spend-policy:
+        get:
+            tags: [Platform]
+            summary: Get effective spend policy for a connection
+            description: |
+                Returns the effective spend policy for the connected user, resolving
+                per-user overrides before app-level defaults. Requires plt_ platform auth.
+            operationId: getConnectionSpendPolicy
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Effective spend policy (or null)
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    policy:
+                                        oneOf:
+                                            - $ref: "#/components/schemas/SpendPolicyResponse"
+                                            - type: "null"
+                "404":
+                    $ref: "#/components/responses/NotFound"
         put:
             tags: [Platform]
             summary: Set per-user spend policy override
@@ -7153,6 +7259,12 @@ paths:
                   schema:
                       type: string
                       format: uuid
+                - in: header
+                  name: Idempotency-Key
+                  required: false
+                  schema:
+                      type: string
+                  description: Optional replay protection; same key + body returns cached response (409 on body mismatch).
             requestBody:
                 required: true
                 content:
@@ -7161,16 +7273,149 @@ paths:
                             $ref: "#/components/schemas/CreateSpendPolicyRequest"
             responses:
                 "200":
-                    description: Spend policy set
+                    description: Spend policy set (or idempotent replay)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SpendPolicyResponse"
+                "201":
+                    description: Spend policy created
                     content:
                         application/json:
                             schema:
                                 $ref: "#/components/schemas/SpendPolicyResponse"
+                "409":
+                    description: Idempotency-Key reused with different body
                 "400":
                     $ref: "#/components/responses/BadRequest"
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/approvals:
+        get:
+            tags: [Platform]
+            summary: List approvals for a platform connection
+            description: |
+                Returns approvals assigned to the connection's user, filtered to agents
+                provisioned on the connection. Requires plt_ platform auth.
+            operationId: listConnectionApprovals
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: status
+                  in: query
+                  required: false
+                  schema:
+                      type: string
+                - name: risk_tier
+                  in: query
+                  required: false
+                  schema:
+                      type: integer
+                - name: limit
+                  in: query
+                  required: false
+                  schema:
+                      type: integer
+                      default: 50
+                - name: offset
+                  in: query
+                  required: false
+                  schema:
+                      type: integer
+                      default: 0
+            responses:
+                "200":
+                    description: Connection-scoped approvals
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ApprovalListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/approvals/{approvalId}:
+        get:
+            tags: [Platform]
+            summary: Get a connection-scoped approval
+            operationId: getConnectionApproval
+            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: Approval detail
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ApprovalResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/pending-approvals:
+        get:
+            tags: [Platform]
+            summary: List pending consensus approvals for a connection
+            description: |
+                Returns pending approvals for agents provisioned on the connection,
+                including `action_payload` and `payload_hash` for consensus UX.
+                Requires plt_ platform auth.
+            operationId: listConnectionPendingApprovals
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: status
+                  in: query
+                  schema:
+                      type: string
+                      default: pending
+                - name: limit
+                  in: query
+                  schema:
+                      type: integer
+                      default: 50
+                - name: offset
+                  in: query
+                  schema:
+                      type: integer
+                      default: 0
+            responses:
+                "200":
+                    description: Pending approvals list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PendingApprovalListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # --- Approvals ---
 
     /v1/approvals:
@@ -9053,7 +9298,7 @@ paths:
             summary: Chat with a running runtime agent
             description: |
                 Human-only. Proxies to the runtime container's OpenAI-compatible
-                `POST /v1/chat/completions` (hermes / openclaw / openclaude chat bridge).
+                `POST /v1/chat/completions` (hermes / openclaw / openclaude / opencode chat bridge).
                 Starts the runtime if stopped. Streams SSE when `Accept: text/event-stream`
                 or `stream: true`. Conversation history is ephemeral (pass `messages`).
                 Requires a public URL (shell access, Shroud sidecar, or HTTP hosting).
@@ -16353,6 +16598,46 @@ components:
                     nullable: true
                     description: Optional expiration time for the platform API key. Set to null to clear.
 
+        PlatformAppDeleteResponse:
+            type: object
+            required: [deleted, soft_delete, slug_released, former_slug]
+            properties:
+                deleted:
+                    type: boolean
+                soft_delete:
+                    type: boolean
+                slug_released:
+                    type: boolean
+                former_slug:
+                    type: string
+
+        TransferPlatformAppOwnershipRequest:
+            type: object
+            properties:
+                target_org_id:
+                    type: string
+                    format: uuid
+                target_user_email:
+                    type: string
+                    format: email
+            description: Provide `target_org_id` or `target_user_email` (owner/admin in destination org).
+
+        TransferPlatformAppOwnershipResponse:
+            type: object
+            required: [app_id, former_org_id, new_org_id, message]
+            properties:
+                app_id:
+                    type: string
+                    format: uuid
+                former_org_id:
+                    type: string
+                    format: uuid
+                new_org_id:
+                    type: string
+                    format: uuid
+                message:
+                    type: string
+
         PlatformAppResponse:
             type: object
             properties:
@@ -17080,6 +17365,17 @@ components:
                     type: string
                     format: date-time
 
+        ApprovalListResponse:
+            type: object
+            required: [approvals, total]
+            properties:
+                approvals:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/ApprovalResponse"
+                total:
+                    type: integer
+
         ApprovalStatusResponse:
             type: object
             required: [status]

package/package.json

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