@1claw/openapi-spec 0.43.4 → 0.44.1

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.32.0
+    version: 2.33.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -94,6 +94,8 @@ tags:
       description: Chat with agents via Shroud LLM proxy
     - name: Agent Channels
       description: External messaging channels (Telegram, WhatsApp, Discord)
+    - name: OAuth Connect
+      description: OAuth connected accounts for agents (provider registry, connect flows, app credentials)
 
 # =============================================================================
 # PATHS
@@ -5028,6 +5030,78 @@ paths:
                                 items:
                                     $ref: "#/components/schemas/PlatformTemplateResponse"
 
+    /v1/platform/apps/{appId}/templates/{template_id}:
+        patch:
+            tags: [Platform]
+            summary: Update a bootstrap template
+            description: Update an existing template's name, description, spec, or active status.
+            operationId: updatePlatformTemplate
+            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
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                name:
+                                    type: string
+                                description:
+                                    type: string
+                                    nullable: true
+                                spec:
+                                    type: object
+                                    additionalProperties: true
+                                is_active:
+                                    type: boolean
+            responses:
+                "200":
+                    description: Template updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformTemplateResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        delete:
+            tags: [Platform]
+            summary: Delete a bootstrap template
+            operationId: deletePlatformTemplate
+            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:
+                "204":
+                    description: Template deleted
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/platform/users/upsert:
         post:
             tags: [Platform]
@@ -5218,6 +5292,53 @@ paths:
                                             $ref: "#/components/schemas/ConnectedAppResponse"
 
     /v1/platform/connected-apps/{connectionId}:
+        patch:
+            tags: [Platform]
+            summary: Update connection delegation
+            description: Toggle delegation and update delegation scopes for a connected platform app. User-only.
+            operationId: updateConnectionDelegation
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                delegation_enabled:
+                                    type: boolean
+                                delegation_scopes:
+                                    type: array
+                                    items:
+                                        type: string
+                                    description: "Scopes: vaults:read, vaults:write, agents:read, agents:write, secrets:read, secrets:write, automations:*, runtimes:*"
+            responses:
+                "200":
+                    description: Delegation settings updated
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    connection_id:
+                                        type: string
+                                        format: uuid
+                                    delegation_enabled:
+                                        type: boolean
+                                    delegation_scopes:
+                                        type: array
+                                        items:
+                                            type: string
+                "404":
+                    $ref: "#/components/responses/NotFound"
         delete:
             tags: [Platform]
             summary: Disconnect a platform app
@@ -5237,6 +5358,53 @@ paths:
                 "404":
                     description: Connection not found
 
+    /v1/platform/connections/{connectionId}/delegation-log:
+        get:
+            tags: [Platform]
+            summary: Delegation audit log
+            description: List delegated actions performed by a platform app on behalf of this user.
+            operationId: getDelegationLog
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Delegation log entries
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    entries:
+                                        type: array
+                                        items:
+                                            type: object
+                                            properties:
+                                                action:
+                                                    type: string
+                                                scope:
+                                                    type: string
+                                                resource_type:
+                                                    type: string
+                                                resource_id:
+                                                    type: string
+                                                    format: uuid
+                                                timestamp:
+                                                    type: string
+                                                    format: date-time
+                                                details:
+                                                    type: object
+                                                    additionalProperties: true
+                                                    nullable: true
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/platform/connections/{connectionId}/grant:
         post:
             tags: [Platform]
@@ -6781,6 +6949,37 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/automations/{automationId}/runs/{runId}:
+        get:
+            tags: [Automations]
+            summary: Get automation run
+            operationId: getAutomationRun
+            description: Get details of a single automation run including step results and context.
+            parameters:
+                - name: automationId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: runId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Automation run detail
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationRunResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/automations/assist/draft:
         post:
             tags: [Automations]
@@ -7829,6 +8028,53 @@ paths:
                 "401":
                     $ref: "#/components/responses/Unauthorized"
 
+    /v1/agents/{agent_id}/channels/{channel_id}/test:
+        post:
+            tags: [Agent Channels]
+            summary: Test channel connectivity
+            description: Send a test message through the channel to verify connectivity and credentials.
+            operationId: testChannel
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: channel_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                external_chat_id:
+                                    type: string
+                                    description: Optional chat ID to send the test message to
+                                content:
+                                    type: string
+                                    description: Optional custom test message content
+            responses:
+                "200":
+                    description: Test result
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    success:
+                                        type: boolean
+                                    message:
+                                        type: string
+                                        nullable: true
+                                    error:
+                                        type: string
+                                        nullable: true
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Channel Webhooks (Public)
     # ---------------------------------------------------------------------------
@@ -7929,6 +8175,200 @@ paths:
                 "200":
                     description: Webhook processed
 
+    # ---------------------------------------------------------------------------
+    # OAuth Connect
+    # ---------------------------------------------------------------------------
+
+    /v1/oauth/providers:
+        get:
+            tags: [OAuth Connect]
+            summary: List OAuth providers
+            description: |
+                Returns the list of supported OAuth providers with their metadata,
+                available scopes, and authorization URLs. No authentication required.
+            operationId: listOAuthProviders
+            security: []
+            responses:
+                "200":
+                    description: Provider list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthProviderListResponse"
+
+    /v1/agents/{agent_id}/oauth/connect:
+        post:
+            tags: [OAuth Connect]
+            summary: Initiate OAuth connection
+            description: |
+                Start an OAuth authorization flow for the specified agent and provider.
+                Returns the authorization URL to redirect the user to. Human-only.
+            operationId: connectOAuth
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ConnectOAuthRequest"
+            responses:
+                "200":
+                    description: Authorization URL generated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ConnectOAuthResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/oauth/connections:
+        get:
+            tags: [OAuth Connect]
+            summary: List OAuth connections
+            description: List all active OAuth connections for the specified agent.
+            operationId: listOAuthConnections
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Connection list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthConnectionListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/oauth/disconnect/{binding_id}:
+        post:
+            tags: [OAuth Connect]
+            summary: Disconnect OAuth connection
+            description: |
+                Disconnect an OAuth connection by revoking tokens and removing the binding.
+                Human-only.
+            operationId: disconnectOAuth
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: binding_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Connection disconnected
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/oauth/app-credentials:
+        post:
+            tags: [OAuth Connect]
+            summary: Save OAuth app credentials
+            description: |
+                Store custom OAuth app credentials (client ID/secret) for a provider.
+                Allows the agent to use a BYOA (Bring Your Own App) OAuth application
+                instead of 1Claw's shared credentials. Human-only.
+            operationId: saveOAuthAppCredentials
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/SaveOAuthAppCredentialsRequest"
+            responses:
+                "201":
+                    description: Credentials saved
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthAppCredentialResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        get:
+            tags: [OAuth Connect]
+            summary: List OAuth app credentials
+            description: |
+                List stored OAuth app credentials for the agent. Client secrets
+                are never returned in the response.
+            operationId: listOAuthAppCredentials
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Credential list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthAppCredentialListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/oauth/app-credentials/{provider_slug}:
+        delete:
+            tags: [OAuth Connect]
+            summary: Delete OAuth app credentials
+            description: |
+                Remove stored OAuth app credentials for a specific provider. Human-only.
+            operationId: deleteOAuthAppCredentials
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: provider_slug
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                  description: Provider identifier (e.g. "github", "google", "slack")
+            responses:
+                "204":
+                    description: Credentials deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/oauth/callback:
+        get:
+            tags: [OAuth Connect]
+            summary: OAuth callback
+            description: |
+                Public callback URL that OAuth providers redirect to after user authorization.
+                Exchanges the authorization code for tokens and redirects to the dashboard.
+            operationId: oauthConnectCallback
+            security: []
+            parameters:
+                - name: code
+                  in: query
+                  schema:
+                      type: string
+                  description: Authorization code from the OAuth provider
+                - name: state
+                  in: query
+                  schema:
+                      type: string
+                  description: Opaque state parameter for CSRF protection and session binding
+                - name: error
+                  in: query
+                  schema:
+                      type: string
+                  description: Error code if the authorization was denied or failed
+            responses:
+                "302":
+                    description: Redirect to dashboard with success or error status
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -12484,6 +12924,10 @@ components:
                             type: string
                             nullable: true
                             description: One-time agent API key (ocv_ prefix). Store securely — not retrievable later.
+                        agent_evm_address:
+                            type: string
+                            nullable: true
+                            description: EOA address when provision_eoa is true in the template
                         signing_keys:
                             type: array
                             description: Provisioned signing key details (chain, address, public key)
@@ -12498,6 +12942,18 @@ components:
                                         type: string
                                     address:
                                         type: string
+                        runtime_ids:
+                            type: array
+                            items:
+                                type: string
+                                format: uuid
+                            description: IDs of runtimes provisioned by the template
+                        automation_ids:
+                            type: array
+                            items:
+                                type: string
+                                format: uuid
+                            description: IDs of automations provisioned by the template
 
         ConnectedAppResponse:
             type: object
@@ -13510,6 +13966,22 @@ components:
                     type: string
                     format: date-time
                     nullable: true
+                last_run_status:
+                    type: string
+                    nullable: true
+                    description: Status of the most recent run (enriched list field)
+                total_runs:
+                    type: integer
+                    nullable: true
+                    description: Total runs in the last 30 days (enriched list field)
+                success_rate:
+                    type: number
+                    nullable: true
+                    description: Success rate percentage (enriched list field)
+                agent_name:
+                    type: string
+                    nullable: true
+                    description: Resolved agent display name (enriched list field)
                 created_at:
                     type: string
                     format: date-time
@@ -13594,7 +14066,7 @@ components:
                     format: uuid
                 status:
                     type: string
-                    enum: [pending, running, completed, failed, denied, cancelled, awaiting_approval]
+                    enum: [running, success, failed, timed_out, cancelled, awaiting_approval]
                 step_results:
                     nullable: true
                 error:
@@ -13603,6 +14075,11 @@ components:
                 trigger_source:
                     type: string
                     nullable: true
+                context:
+                    type: object
+                    additionalProperties: true
+                    nullable: true
+                    description: JSONB context passed between workflow steps
                 started_at:
                     type: string
                     format: date-time
@@ -14194,6 +14671,14 @@ components:
                     type: string
                 is_active:
                     type: boolean
+                config:
+                    type: object
+                    additionalProperties: true
+                    nullable: true
+                    description: |
+                        Channel-specific configuration JSON. May include:
+                        - sender_allowlist (array of strings): restrict which external senders can trigger the agent
+                        - auto_respond_enabled (boolean): whether the agent auto-responds to inbound messages
                 created_at:
                     type: string
                     format: date-time
@@ -14255,3 +14740,164 @@ components:
                     type: array
                     items:
                         $ref: "#/components/schemas/ChannelMessageResponse"
+
+        # ── OAuth Connect ──────────────────────────────────────────────
+
+        OAuthProviderScope:
+            type: object
+            properties:
+                scope:
+                    type: string
+                label:
+                    type: string
+                description:
+                    type: string
+                default:
+                    type: boolean
+
+        OAuthProvider:
+            type: object
+            properties:
+                slug:
+                    type: string
+                    description: Unique provider identifier (e.g. "github", "google", "slack")
+                display_name:
+                    type: string
+                icon_url:
+                    type: string
+                    format: uri
+                authorization_url:
+                    type: string
+                    format: uri
+                token_url:
+                    type: string
+                    format: uri
+                scopes_available:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/OAuthProviderScope"
+                default_scopes:
+                    type: array
+                    items:
+                        type: string
+                extra_auth_params:
+                    type: object
+                    additionalProperties:
+                        type: string
+                    nullable: true
+                requires_app_credentials:
+                    type: boolean
+                    description: Whether custom app credentials are required (vs. shared 1Claw app)
+                documentation_url:
+                    type: string
+                    format: uri
+                    nullable: true
+
+        OAuthProviderListResponse:
+            type: object
+            properties:
+                providers:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/OAuthProvider"
+
+        ConnectOAuthRequest:
+            type: object
+            required: [provider_slug]
+            properties:
+                provider_slug:
+                    type: string
+                    description: Provider to connect (e.g. "github", "google", "slack")
+                scopes:
+                    type: array
+                    items:
+                        type: string
+                    description: Override default scopes for this connection
+                redirect_after:
+                    type: string
+                    description: URL to redirect to after the OAuth flow completes
+
+        ConnectOAuthResponse:
+            type: object
+            properties:
+                authorization_url:
+                    type: string
+                    format: uri
+                    description: Redirect the user to this URL to authorize the connection
+
+        OAuthConnectionResponse:
+            type: object
+            properties:
+                binding_id:
+                    type: string
+                    format: uuid
+                provider_slug:
+                    type: string
+                provider_name:
+                    type: string
+                scopes:
+                    type: array
+                    items:
+                        type: string
+                status:
+                    type: string
+                    enum: [active, expired, revoked]
+                needs_reauth:
+                    type: boolean
+                created_at:
+                    type: string
+                    format: date-time
+
+        OAuthConnectionListResponse:
+            type: object
+            properties:
+                connections:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/OAuthConnectionResponse"
+
+        SaveOAuthAppCredentialsRequest:
+            type: object
+            required: [provider_slug, client_id, client_secret]
+            properties:
+                provider_slug:
+                    type: string
+                    description: Provider this credential is for
+                client_id:
+                    type: string
+                client_secret:
+                    type: string
+                    description: Write-only; never returned in responses
+                redirect_uri:
+                    type: string
+                    format: uri
+                    description: Custom redirect URI override
+
+        OAuthAppCredentialResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                provider_slug:
+                    type: string
+                client_id:
+                    type: string
+                redirect_uri:
+                    type: string
+                    format: uri
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        OAuthAppCredentialListResponse:
+            type: object
+            properties:
+                credentials:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/OAuthAppCredentialResponse"