@1claw/openapi-spec 0.61.31 → 0.61.35

package/openapi.json

@@ -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,\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\n## Domains\n\n`api.1claw.co` is canonical: it is the OIDC issuer, the `aud` the API\nmints, and the first entry in `servers` — a generated client takes its\nbase URL from there, and the previous ordering pointed every SDK at the\ndomain the issuer had already left. `api.1claw.xyz` still answers and is\nstill accepted on token validation, because tokens minted before the\nmove carry it; it is never minted now.\n\nOne deliberate exception: the Shroud attestation identity token is\nrequested from GCP with `audience: https://api.1claw.xyz`, so\n`/v1/shroud/attestation` reports that as its `expected_audience`. That\nis accurate rather than stale — the audience is a verification contract\nwith anyone already checking the token, and moving it is a breaking\nchange for them, not a rename.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.co"
@@ -17221,6 +17221,75 @@
         }
       }
     },
+    "/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\n**402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)\nfor `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`\nthe facilitator verifies it, the proof is claimed once, the payer wallet's org\nledger is credited in micro-USD, and the facilitator settles.\n\n**Payment is the account.** An unknown wallet's first settled top-up provisions a\nshadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the\nwallet (returned once as `router_key`), after screening the wallet against the OFAC\nSDN list (fails closed when the list is missing or stale) and the caller's region\nagainst the custody geofence. Same wallet = same org on every later top-up. The\nresponse always carries a ≤60 s `access_token` for the wallet's agent so the\ngateway can serve the paid request immediately. The Shroud gateway drives this for\n`Authorization: Bearer x402` requests and relays the quote or the result.\n",
+        "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": [
@@ -18770,6 +18839,7 @@
         ],
         "summary": "Trigger automation",
         "operationId": "triggerAutomation",
+        "description": "Start a run now. With an `idempotency_key` (body or `Idempotency-Key` header) the\nsame key returns the run already started for it (200) rather than a second run\n(201). `input` is exposed to steps as `{{trigger.*}}`.\n",
         "parameters": [
           {
             "name": "automationId",
@@ -18781,9 +18851,29 @@
             }
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TriggerAutomationRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
-            "description": "Automation triggered",
+            "description": "An earlier run with the same idempotency key",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AutomationRunResponse"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "Run started",
             "content": {
               "application/json": {
                 "schema": {
@@ -19198,6 +19288,173 @@
         }
       }
     },
+    "/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`\nstep gets the token at run start as `{{run.callback_url}}` / `{{run.callback_token}}`;\nan earlier step hands the URL to the external system, the step parks the run\n(`awaiting_callback`, up to its `timeout_secs`), and this POST continues it. The\nJSON body becomes `{{resume.*}}`. 409 when the run is not (yet) parked on a\ncallback; 401 for a wrong token.\n",
+        "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\nspec it was created with; every update that changes the spec publishes the\nnext one. Runs record the version they executed.\n",
+        "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.\nHuman-only. A rollback that widens what the automation can do relative to the\nlive spec goes through the `automation.widen` control-plane consensus gate,\nlike an edit would.\n",
+        "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": [
@@ -23871,6 +24128,130 @@
         }
       }
     },
+    "/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`\ninto `tool_name` at `arg_path` — and only when the call's destination host is one\nof `destination_hosts`. Redaction replaces vault secrets in prompts with\ndeterministic placeholders the model can place but never read; a placeholder is\nsubstituted back only inside an authorised tool-call argument, at the moment the\nenclave performs the call (`execution_mode: \"tee\"`). No binding, wrong argument,\nwrong host, bad checksum or an unknown tag is a 403 at execution time. Human users\nonly; up to 200 per agent.\n",
+        "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": [
@@ -36090,7 +36471,13 @@
             "type": "string"
           },
           "credit_balance_cents": {
-            "type": "integer"
+            "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"
@@ -36313,10 +36700,17 @@
         "type": "object",
         "properties": {
           "balance_cents": {
-            "type": "integer"
+            "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"
+            "type": "string",
+            "description": "Dollars at the ledger's precision (e.g. \"4.995\"), never fewer than two decimals"
           },
           "expiring_within_90_days": {
             "type": "object",
@@ -40035,6 +40429,148 @@
           }
         ]
       },
+      "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": [
@@ -42543,6 +43079,139 @@
           },
           "is_active": {
             "type": "boolean"
+          },
+          "approval_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Control-plane approval authorising a widening change (adding a step that\nmoves funds or reaches the network, raising or removing a `budget` cap).\nRequired only when the org's consensus policy gates `automation.widen`.\n"
+          },
+          "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`\n(`Stripe-Signature: t=…,v1=…` over `<t>.<body>`), `github`\n(`X-Hub-Signature-256: sha256=…` over the body) or `hmac_sha256`\n(`<header>: <hex|base64>` over the body). The secret is stored encrypted\nand never returned; `null` removes the scheme. With a scheme set, an\nunsigned or mis-signed delivery starts nothing.\n",
+            "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\nof starting a second (201). `Idempotency-Key` header is equivalent.\n"
           }
         }
       },
@@ -42655,6 +43324,15 @@
           "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."
           }
         }
       },
@@ -42787,12 +43465,58 @@
             "enum": [
               "running",
               "success",
+              "completed_with_skips",
               "failed",
               "timed_out",
               "cancelled",
-              "awaiting_approval"
+              "awaiting_approval",
+              "waiting",
+              "awaiting_callback"
+            ],
+            "description": "`awaiting_approval`, `waiting` (a `wait_until` park) and `awaiting_callback`\nare parked states: the run's clock is stopped and it continues when the\napproval is decided, the wake time passes, or the callback URL is posted to.\n"
+          },
+          "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
           },