@1claw/openapi-spec 0.61.31 → 0.61.35

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.31"
+    version: "0.61.35"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -10956,6 +10956,64 @@ paths:
                 "400":
                     description: Invalid request
 
+    /v1/x402/topup:
+        post:
+            tags: [Billing]
+            summary: x402 ledger top-up (agent door)
+            description: |
+                The wallet rail for Shroud (Shroud AI plan). Without `X-PAYMENT` the response is a
+                **402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)
+                for `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`
+                the facilitator verifies it, the proof is claimed once, the payer wallet's org
+                ledger is credited in micro-USD, and the facilitator settles.
+
+                **Payment is the account.** An unknown wallet's first settled top-up provisions a
+                shadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the
+                wallet (returned once as `router_key`), after screening the wallet against the OFAC
+                SDN list (fails closed when the list is missing or stale) and the caller's region
+                against the custody geofence. Same wallet = same org on every later top-up. The
+                response always carries a ≤60 s `access_token` for the wallet's agent so the
+                gateway can serve the paid request immediately. The Shroud gateway drives this for
+                `Authorization: Bearer x402` requests and relays the quote or the result.
+            operationId: x402Topup
+            security: []
+            parameters:
+                - name: X-PAYMENT
+                  in: header
+                  required: false
+                  schema: { type: string }
+                  description: Base64 x402 payment payload (EIP-3009 USDC authorization on Base)
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            additionalProperties: false
+                            properties:
+                                amount_usd:
+                                    type: integer
+                                    minimum: 1
+                                    maximum: 100
+                                    description: Whole dollars to add to the ledger (default 1)
+            responses:
+                "200":
+                    description: Credited
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/X402TopupResponse"
+                "402":
+                    description: Payment required — the quote to sign, or why the payment was refused
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PaymentRequirement"
+                "403":
+                    description: The wallet is sanctioned or the region is fenced; no account is opened
+                "503":
+                    description: The sanctions list is unavailable (fails closed)
+
     /v1/oauth/token:
         post:
             tags: [OAuth]
@@ -11931,6 +11989,10 @@ paths:
             tags: [Automations]
             summary: Trigger automation
             operationId: triggerAutomation
+            description: |
+                Start a run now. With an `idempotency_key` (body or `Idempotency-Key` header) the
+                same key returns the run already started for it (200) rather than a second run
+                (201). `input` is exposed to steps as `{{trigger.*}}`.
             parameters:
                 - name: automationId
                   in: path
@@ -11938,9 +12000,21 @@ paths:
                   schema:
                       type: string
                       format: uuid
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/TriggerAutomationRequest"
             responses:
+                "201":
+                    description: Run started
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationRunResponse"
                 "200":
-                    description: Automation triggered
+                    description: An earlier run with the same idempotency key
                     content:
                         application/json:
                             schema:
@@ -12214,6 +12288,126 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/automations/{automationId}/runs/{runId}/callback/{token}:
+        post:
+            tags: [Automations]
+            summary: Continue a run parked on awaiting_callback
+            operationId: automationRunCallback
+            security: []
+            description: |
+                Public, authenticated by the per-run token. A spec with an `awaiting_callback`
+                step gets the token at run start as `{{run.callback_url}}` / `{{run.callback_token}}`;
+                an earlier step hands the URL to the external system, the step parks the run
+                (`awaiting_callback`, up to its `timeout_secs`), and this POST continues it. The
+                JSON body becomes `{{resume.*}}`. 409 when the run is not (yet) parked on a
+                callback; 401 for a wrong token.
+            parameters:
+                - name: automationId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: runId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: token
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            additionalProperties: true
+            responses:
+                "202":
+                    description: The run, continuing
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationRunResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "409":
+                    $ref: "#/components/responses/Conflict"
+
+    /v1/automations/{automationId}/versions:
+        get:
+            tags: [Automations]
+            summary: List spec versions
+            operationId: listAutomationVersions
+            description: |
+                Every `workflow_spec` the automation has had, newest first. Version 1 is the
+                spec it was created with; every update that changes the spec publishes the
+                next one. Runs record the version they executed.
+            parameters:
+                - name: automationId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Versions
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationVersionListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/automations/{automationId}/versions/{version}/rollback:
+        post:
+            tags: [Automations]
+            summary: Roll back to an earlier spec version
+            operationId: rollbackAutomationVersion
+            description: |
+                Publishes the chosen version's spec as a new version and makes it current.
+                Human-only. A rollback that widens what the automation can do relative to the
+                live spec goes through the `automation.widen` control-plane consensus gate,
+                like an edit would.
+            parameters:
+                - name: automationId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: version
+                  in: path
+                  required: true
+                  schema:
+                      type: integer
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/RollbackAutomationRequest"
+            responses:
+                "200":
+                    description: The automation with the rolled-back spec current
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/automations/presets:
         get:
             tags: [Automations]
@@ -15270,6 +15464,86 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/tool-bindings:
+        post:
+            tags: [Agents]
+            summary: Create a secret → tool binding (rehydration policy)
+            description: |
+                Authorises the enclave to rehydrate the `⟦sk:…⟧` placeholder for `secret_path`
+                into `tool_name` at `arg_path` — and only when the call's destination host is one
+                of `destination_hosts`. Redaction replaces vault secrets in prompts with
+                deterministic placeholders the model can place but never read; a placeholder is
+                substituted back only inside an authorised tool-call argument, at the moment the
+                enclave performs the call (`execution_mode: "tee"`). No binding, wrong argument,
+                wrong host, bad checksum or an unknown tag is a 403 at execution time. Human users
+                only; up to 200 per agent.
+            operationId: createToolBinding
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateToolBindingRequest"
+            responses:
+                "201":
+                    description: Created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretToolBinding"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    description: A binding for this secret, tool and argument already exists
+        get:
+            tags: [Agents]
+            summary: List secret → tool bindings
+            operationId: listToolBindings
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Bindings
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [bindings]
+                                properties:
+                                    bindings:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/SecretToolBinding"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/tool-bindings/{binding_id}:
+        delete:
+            tags: [Agents]
+            summary: Delete a secret → tool binding
+            operationId: deleteToolBinding
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: binding_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                "204":
+                    description: Deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/agents/{agent_id}/oauth/connections:
         get:
             tags: [OAuth Connect]
@@ -23430,6 +23704,11 @@ components:
                     type: string
                 credit_balance_cents:
                     type: integer
+                    description: Derived (rounded down); the ledger unit is micro-USD
+                credit_balance_micro_usd:
+                    type: integer
+                    format: int64
+                    description: The ledger value. One inspected Shroud request costs 5,000 micro-USD ($0.005).
                 credit_balance_usd:
                     type: string
                 overage_method:
@@ -23586,8 +23865,14 @@ components:
             properties:
                 balance_cents:
                     type: integer
+                    description: Derived (rounded down); the ledger unit is micro-USD
+                balance_micro_usd:
+                    type: integer
+                    format: int64
+                    description: The ledger value (1 = $0.000001)
                 balance_usd:
                     type: string
+                    description: Dollars at the ledger's precision (e.g. "4.995"), never fewer than two decimals
                 expiring_within_90_days:
                     type: object
                     properties:
@@ -25982,6 +26267,63 @@ components:
                           description: The Shroud gateway to point the SDK at
                           example: https://shroud.1claw.co
 
+        CreateToolBindingRequest:
+            type: object
+            additionalProperties: false
+            required: [secret_path, tool_name, destination_hosts]
+            properties:
+                secret_path:
+                    type: string
+                    description: Vault path of the secret the placeholder stands for
+                tool_name:
+                    type: string
+                    description: Tool the binding applies to (`http_request`, `run_sql`, …) or `*`
+                arg_path:
+                    type: string
+                    description: JSON pointer into the tool's arguments (`/headers/Authorization`, `/body/*`) or `*` (default)
+                destination_hosts:
+                    type: array
+                    minItems: 1
+                    maxItems: 32
+                    items: { type: string }
+                    description: Hosts the rehydrated call may reach (`api.stripe.com`, `*.googleapis.com`); required
+
+        SecretToolBinding:
+            type: object
+            required: [id, org_id, agent_id, secret_path, tool_name, arg_path, destination_hosts, created_at]
+            properties:
+                id: { type: string, format: uuid }
+                org_id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                secret_path: { type: string }
+                tool_name: { type: string }
+                arg_path: { type: string }
+                destination_hosts:
+                    type: array
+                    items: { type: string }
+                created_by: { type: string, format: uuid, nullable: true }
+                created_at: { type: string, format: date-time }
+
+        X402TopupResponse:
+            type: object
+            required: [wallet, org_id, agent_id, credited_micro_usd, balance_micro_usd, balance_usd, access_token, expires_in, base_url, provisioned]
+            properties:
+                wallet: { type: string, description: Payer address (lower-case) }
+                org_id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                credited_micro_usd: { type: integer, format: int64 }
+                balance_micro_usd: { type: integer, format: int64 }
+                balance_usd: { type: string }
+                router_key:
+                    type: string
+                    description: Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once.
+                access_token:
+                    type: string
+                    description: A ≤60 s agent token for the wallet's agent (carries the `router_key` claim)
+                expires_in: { type: integer }
+                base_url: { type: string, description: The Shroud gateway }
+                provisioned: { type: boolean, description: True when this top-up created the account }
+
         EventSubscription:
             type: object
             required: [id, agent_id, binding_id, event_type, interval_secs, is_active, primed, next_poll_at, consecutive_errors, events_emitted, created_at]
@@ -27529,6 +27871,104 @@ components:
                           additionalProperties: true
                 is_active:
                     type: boolean
+                approval_id:
+                    type: string
+                    format: uuid
+                    description: |
+                        Control-plane approval authorising a widening change (adding a step that
+                        moves funds or reaches the network, raising or removing a `budget` cap).
+                        Required only when the org's consensus policy gates `automation.widen`.
+                version_note:
+                    type: string
+                    description: Note recorded on the new spec version.
+                webhook_signature:
+                    nullable: true
+                    description: |
+                        Inbound signature scheme for a webhook-triggered automation. `stripe`
+                        (`Stripe-Signature: t=…,v1=…` over `<t>.<body>`), `github`
+                        (`X-Hub-Signature-256: sha256=…` over the body) or `hmac_sha256`
+                        (`<header>: <hex|base64>` over the body). The secret is stored encrypted
+                        and never returned; `null` removes the scheme. With a scheme set, an
+                        unsigned or mis-signed delivery starts nothing.
+                    type: object
+                    properties:
+                        scheme:
+                            type: string
+                            enum: [stripe, github, hmac_sha256]
+                        secret:
+                            type: string
+                            minLength: 8
+                            maxLength: 512
+                        header:
+                            type: string
+                            description: Header carrying the signature (defaults per scheme).
+                        tolerance_secs:
+                            type: integer
+                            default: 300
+                            description: Timestamp tolerance for schemes that carry one (stripe).
+
+        AutomationVersionResponse:
+            type: object
+            required: [version, spec_hash, workflow_spec, created_by_type, created_at, current]
+            properties:
+                version:
+                    type: integer
+                spec_hash:
+                    type: string
+                    description: SHA-256 of the canonical (sorted-key) JSON of the spec.
+                workflow_spec:
+                    oneOf:
+                        - type: array
+                          items:
+                              type: object
+                              additionalProperties: true
+                        - type: object
+                          additionalProperties: true
+                created_by_type:
+                    type: string
+                note:
+                    type: string
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time
+                current:
+                    type: boolean
+
+        AutomationVersionListResponse:
+            type: object
+            required: [current_version, versions]
+            properties:
+                current_version:
+                    type: integer
+                versions:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/AutomationVersionResponse"
+
+        RollbackAutomationRequest:
+            type: object
+            properties:
+                note:
+                    type: string
+                approval_id:
+                    type: string
+                    format: uuid
+                    description: Control-plane approval when rolling back to a wider spec.
+
+        TriggerAutomationRequest:
+            type: object
+            properties:
+                input:
+                    type: object
+                    additionalProperties: true
+                    description: Exposed to steps as `{{trigger.*}}`.
+                idempotency_key:
+                    type: string
+                    maxLength: 128
+                    description: |
+                        Same key twice for one automation returns the existing run (200) instead
+                        of starting a second (201). `Idempotency-Key` header is equivalent.
 
         AutomationResponse:
             type: object
@@ -27598,6 +28038,13 @@ components:
                 updated_at:
                     type: string
                     format: date-time
+                spec_version:
+                    type: integer
+                    description: Current `automation_versions` version.
+                webhook_signature_scheme:
+                    type: string
+                    nullable: true
+                    description: Inbound signature scheme name, never the secret.
 
         AutomationCreatedResponse:
             allOf:
@@ -27676,7 +28123,41 @@ components:
                     format: uuid
                 status:
                     type: string
-                    enum: [running, success, failed, timed_out, cancelled, awaiting_approval]
+                    enum: [running, success, completed_with_skips, failed, timed_out, cancelled, awaiting_approval, waiting, awaiting_callback]
+                    description: |
+                        `awaiting_approval`, `waiting` (a `wait_until` park) and `awaiting_callback`
+                        are parked states: the run's clock is stopped and it continues when the
+                        approval is decided, the wake time passes, or the callback URL is posted to.
+                paused_reason:
+                    type: string
+                    nullable: true
+                    enum: [approval, wait_until, callback]
+                paused_at_step:
+                    type: integer
+                    nullable: true
+                paused_approval_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                paused_until:
+                    type: string
+                    format: date-time
+                    nullable: true
+                paused_expires_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                spec_version:
+                    type: integer
+                    nullable: true
+                idempotency_key:
+                    type: string
+                    nullable: true
+                parent_run_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: Set when a `call_automation` step started this run.
                 step_results:
                     nullable: true
                 error:

package/package.json

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