@1claw/openapi-spec 0.44.3 → 0.46.0

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.33.0
+    version: 2.35.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -96,6 +96,8 @@ tags:
       description: External messaging channels (Telegram, WhatsApp, Discord)
     - name: OAuth Connect
       description: OAuth connected accounts for agents (provider registry, connect flows, app credentials)
+    - name: Delegations
+      description: Agent-to-agent delegation management (human-controlled authorization)
 
 # =============================================================================
 # PATHS
@@ -2526,6 +2528,154 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    # ---------------------------------------------------------------------------
+    # Agent Delegations
+    # ---------------------------------------------------------------------------
+
+    /v1/agents/{agent_id}/delegations:
+        post:
+            tags: [Delegations]
+            summary: Create a delegation
+            description: |
+                Grant an agent (delegator) permission to delegate tasks to another agent (delegate).
+                Human-only — agents cannot create their own delegations.
+            operationId: createDelegation
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateDelegationRequest"
+            responses:
+                "201":
+                    description: Delegation created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DelegationResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "409":
+                    description: Delegation already exists for this delegator/delegate pair
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ProblemDetails"
+        get:
+            tags: [Delegations]
+            summary: List delegations for an agent
+            description: |
+                List all delegations where this agent is the delegator.
+            operationId: listDelegations
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: List of delegations
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DelegationListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/delegations/effective:
+        get:
+            tags: [Delegations]
+            summary: Get effective delegations
+            description: |
+                Get the effective delegations for an agent, including daily usage statistics.
+                Agents can call this on their own ID to discover what they are authorized to delegate to.
+            operationId: getEffectiveDelegations
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Effective delegations with usage stats
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DelegationListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/delegations/{delegation_id}:
+        get:
+            tags: [Delegations]
+            summary: Get a specific delegation
+            operationId: getDelegation
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: delegation_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Delegation details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DelegationResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        patch:
+            tags: [Delegations]
+            summary: Update a delegation
+            description: |
+                Update delegation tools, limits, mode, or active status. Human-only.
+            operationId: updateDelegation
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: delegation_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpdateDelegationRequest"
+            responses:
+                "200":
+                    description: Delegation updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DelegationResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        delete:
+            tags: [Delegations]
+            summary: Revoke a delegation
+            operationId: revokeDelegation
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: delegation_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Delegation revoked
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Unified Signing Intent
     # ---------------------------------------------------------------------------
@@ -4981,6 +5131,67 @@ paths:
                 "403":
                     description: Only human users can rotate platform keys
 
+    /v1/platform/apps/{appId}/stats:
+        get:
+            tags: [Platform]
+            summary: Get platform app statistics
+            description: Returns aggregate statistics about a platform app's connected users, bootstraps, and grants.
+            operationId: getPlatformAppStats
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: appId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: App statistics
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformAppStatsResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/apps/{appId}/rotate-webhook-secret:
+        post:
+            tags: [Platform]
+            summary: Rotate webhook secret
+            description: Generate a new webhook signing secret for the platform app. The old secret is immediately invalidated. Returns the new secret (one-time).
+            operationId: rotatePlatformWebhookSecret
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: appId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: New webhook secret generated
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [webhook_secret]
+                                properties:
+                                    webhook_secret:
+                                        type: string
+                                        description: The new webhook signing secret (shown once)
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    description: Only human users can rotate webhook secrets
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/platform/apps/{appId}/templates:
         post:
             tags: [Platform]
@@ -6310,6 +6521,79 @@ paths:
                 "401":
                     $ref: "#/components/responses/Unauthorized"
 
+    /v1/oauth/revoke:
+        post:
+            tags: [OAuth]
+            summary: Revoke an OAuth token (RFC 7009)
+            description: |
+                Revokes an access token or refresh token. The authorization server
+                invalidates the token so it can no longer be used. Follows RFC 7009.
+            operationId: revokeOAuthToken
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [token]
+                            properties:
+                                token:
+                                    type: string
+                                    description: The token to revoke (access_token or refresh_token)
+                                token_type_hint:
+                                    type: string
+                                    enum: [access_token, refresh_token]
+                                    description: Hint about the type of token being revoked
+            responses:
+                "200":
+                    description: Token revoked successfully (or was already invalid)
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    revoked:
+                                        type: boolean
+                                        example: true
+
+    /v1/oauth/consents/{app_id}:
+        delete:
+            tags: [OAuth]
+            summary: Revoke consent for a platform app
+            description: |
+                Revokes the user's previously granted OAuth consent for a specific platform app.
+                All active tokens issued to the app are invalidated and the consent record is deleted.
+            operationId: revokeOAuthConsent
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: app_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                  description: The platform app ID whose consent to revoke
+            responses:
+                "200":
+                    description: Consent revoked
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    revoked:
+                                        type: boolean
+                                        example: true
+                                    app_id:
+                                        type: string
+                                        format: uuid
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Risk Engine
     # ---------------------------------------------------------------------------
@@ -7772,9 +8056,9 @@ paths:
 
     /v1/platform/marketplace:
         get:
-            tags: [Discovery]
+            tags: [Platform, Discovery]
             summary: Public marketplace
-            description: Browse the public platform marketplace of agents and apps.
+            description: Browse the public platform marketplace of listed apps and agents. Returns approved platform apps with category, tags, pricing summaries, and screenshots.
             operationId: listMarketplace
             security: []
             parameters:
@@ -7793,13 +8077,18 @@ paths:
                   schema:
                       type: string
                   description: Search query
+                - name: category
+                  in: query
+                  schema:
+                      type: string
+                  description: Filter by app category
             responses:
                 "200":
                     description: Marketplace listing
                     content:
                         application/json:
                             schema:
-                                $ref: "#/components/schemas/DirectoryResponse"
+                                $ref: "#/components/schemas/MarketplaceResponse"
 
     # ---------------------------------------------------------------------------
     # Agent Chat
@@ -10878,6 +11167,136 @@ components:
                     items:
                         $ref: "#/components/schemas/BankrKeyLeaseResponse"
 
+        # Agent Delegations
+        CreateDelegationRequest:
+            type: object
+            required: [delegate_id]
+            properties:
+                delegate_id:
+                    type: string
+                    format: uuid
+                    description: The agent ID to delegate to.
+                allowed_tools:
+                    type: array
+                    items:
+                        type: string
+                    description: Tool names the delegate may use. Empty means all tools allowed.
+                blocked_tools:
+                    type: array
+                    items:
+                        type: string
+                    description: Tool names the delegate may NOT use.
+                max_daily_delegations:
+                    type: integer
+                    description: Maximum delegation calls per UTC day. NULL means unlimited.
+                max_depth:
+                    type: integer
+                    description: Maximum delegation chain depth (default 3).
+                    default: 3
+                guardrails:
+                    type: object
+                    description: Additional guardrail constraints for this delegation.
+                delegation_mode:
+                    type: string
+                    enum: [caller, target, both]
+                    description: "Execution mode: caller (use delegator's creds), target (use delegate's config), or both."
+                    default: caller
+                expires_at:
+                    type: string
+                    format: date-time
+                    description: Optional expiration timestamp.
+
+        UpdateDelegationRequest:
+            type: object
+            properties:
+                allowed_tools:
+                    type: array
+                    items:
+                        type: string
+                blocked_tools:
+                    type: array
+                    items:
+                        type: string
+                max_daily_delegations:
+                    type: integer
+                max_depth:
+                    type: integer
+                guardrails:
+                    type: object
+                delegation_mode:
+                    type: string
+                    enum: [caller, target, both]
+                is_active:
+                    type: boolean
+                expires_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+
+        DelegationResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                delegator_id:
+                    type: string
+                    format: uuid
+                delegate_id:
+                    type: string
+                    format: uuid
+                delegator_name:
+                    type: string
+                delegate_name:
+                    type: string
+                allowed_tools:
+                    type: array
+                    items:
+                        type: string
+                blocked_tools:
+                    type: array
+                    items:
+                        type: string
+                max_daily_delegations:
+                    type: integer
+                    nullable: true
+                max_depth:
+                    type: integer
+                guardrails:
+                    type: object
+                delegation_mode:
+                    type: string
+                    enum: [caller, target, both]
+                is_active:
+                    type: boolean
+                created_by:
+                    type: string
+                    format: uuid
+                expires_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+                delegations_today:
+                    type: integer
+                    description: Number of delegations used today (present in effective endpoint).
+
+        DelegationListResponse:
+            type: object
+            properties:
+                delegations:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/DelegationResponse"
+
         # Unified Signing Intent
         SignIntentRequest:
             type: object
@@ -12955,6 +13374,12 @@ components:
                             type: string
                             format: uuid
                             nullable: true
+                        agent_ids:
+                            type: array
+                            items:
+                                type: string
+                                format: uuid
+                            description: All agent IDs provisioned by the template (when multiple agents are defined)
                         policy_ids:
                             type: array
                             items:
@@ -13000,6 +13425,61 @@ components:
                                 format: uuid
                             description: IDs of automations provisioned by the template
 
+        PlatformAppStatsResponse:
+            type: object
+            required: [total_connections, active_connections, claimed_connections, total_bootstraps, total_grants]
+            properties:
+                total_connections:
+                    type: integer
+                    description: Total number of user connections (all statuses)
+                active_connections:
+                    type: integer
+                    description: Number of active connections
+                claimed_connections:
+                    type: integer
+                    description: Number of claimed connections
+                total_bootstraps:
+                    type: integer
+                    description: Total bootstrap operations performed
+                total_grants:
+                    type: integer
+                    description: Total resource grants issued
+
+        MarketplaceResponse:
+            type: object
+            properties:
+                apps:
+                    type: array
+                    items:
+                        type: object
+                        properties:
+                            id:
+                                type: string
+                                format: uuid
+                            name:
+                                type: string
+                            slug:
+                                type: string
+                            description:
+                                type: string
+                            logo_url:
+                                type: string
+                                nullable: true
+                            category:
+                                type: string
+                                nullable: true
+                            listing_tags:
+                                type: array
+                                items:
+                                    type: string
+                            listing_screenshots:
+                                type: array
+                                items:
+                                    type: string
+                            pricing_summary:
+                                type: string
+                                nullable: true
+
         ConnectedAppResponse:
             type: object
             properties:
@@ -13412,6 +13892,10 @@ components:
                 expires_in:
                     type: integer
                     description: Token lifetime in seconds
+                refresh_token:
+                    type: string
+                    nullable: true
+                    description: Refresh token for obtaining new access tokens (when offline_access scope was granted)
                 id_token:
                     type: string
                     nullable: true
@@ -14726,6 +15210,24 @@ components:
                         Telegram: { bot_token }.
                         WhatsApp: { phone_number_id, access_token, verify_token }.
                         Discord: { bot_token, application_id }.
+                slash_commands_enabled:
+                    type: boolean
+                    description: |
+                        Enable Hermes-compatible slash commands on this channel. When true,
+                        messages starting with `/` are handled before the LLM. Commands:
+                        /help, /new, /reset, /clear, /model, /mode, /personality, /retry,
+                        /undo, /compress, /summarize, /stop, /status, /skills, /usage, /sethome.
+                voice_transcription_enabled:
+                    type: boolean
+                    description: Enable voice message transcription
+                sender_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: List of allowed sender IDs
+                auto_respond_enabled:
+                    type: boolean
+                    description: Enable auto-respond
 
         UpdateChannelRequest:
             type: object
@@ -14738,6 +15240,16 @@ components:
                     type: object
                     additionalProperties:
                         type: string
+                slash_commands_enabled:
+                    type: boolean
+                voice_transcription_enabled:
+                    type: boolean
+                sender_allowlist:
+                    type: array
+                    items:
+                        type: string
+                auto_respond_enabled:
+                    type: boolean
 
         ChannelResponse:
             type: object
@@ -14770,6 +15282,32 @@ components:
                         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
+                slash_commands_enabled:
+                    type: boolean
+                    description: |
+                        Whether Hermes-compatible slash commands are enabled for this channel.
+                        Commands: /help, /new, /reset, /clear, /model, /mode, /personality, /retry,
+                        /undo, /compress, /summarize, /stop, /status, /skills, /usage, /sethome.
+                voice_transcription_enabled:
+                    type: boolean
+                    description: Whether voice message transcription is enabled
+                unified_conversation_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: ID linking this channel to a unified cross-platform conversation
+                is_home_platform:
+                    type: boolean
+                    description: Whether this is the agent's home platform channel
+                sender_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    nullable: true
+                    description: List of allowed sender IDs for auto-respond
+                auto_respond_enabled:
+                    type: boolean
+                    description: Whether auto-respond is enabled for this channel
                 created_at:
                     type: string
                     format: date-time
@@ -14820,6 +15358,22 @@ components:
                     type: string
                 media_url:
                     type: string
+                is_voice_message:
+                    type: boolean
+                    description: Whether this message was a voice message
+                voice_file_id:
+                    type: string
+                    nullable: true
+                    description: Telegram voice file ID
+                voice_duration_secs:
+                    type: integer
+                    nullable: true
+                    description: Duration of voice message in seconds
+                transcription_status:
+                    type: string
+                    nullable: true
+                    enum: [pending, completed, failed]
+                    description: Status of voice transcription
                 created_at:
                     type: string
                     format: date-time

package/package.json

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