@1claw/openapi-spec 0.61.46 → 0.61.48

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.46",
+    "version": "0.61.48",
     "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"
@@ -11372,6 +11372,146 @@
         }
       }
     },
+    "/v1/treasury/wallets/{chain}/sign-message": {
+      "post": {
+        "tags": [
+          "Treasury"
+        ],
+        "summary": "Sign a message with a human wallet (EIP-191)",
+        "description": "`personal_sign` over the given text, hashed as `\\x19Ethereum Signed Message:\\n<len>` + message — what viem's `verifyMessage` and ethers' `verifyMessage` expect.\n\nHuman callers only; an agent signs with its own key via `POST /v1/agents/{agent_id}/sign`. Gated exactly as a send is: `X-Auth-Confirm` step-up scored as a Send action, wallet access policies (`WalletAction::Sign`), and a refusal for wallets whose key is split or passkey-owned — those have no server-side key and will not fall back to one.\n\nEVM chains only.\n",
+        "operationId": "signTreasuryMessage",
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "example": "ethereum"
+            }
+          },
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Account password, or a `rat_` token from `POST /v1/auth/reauth/complete`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "message"
+                ],
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "maxLength": 16384,
+                    "example": "Sign in to Example at 2026-10-01T10:00:00Z"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Signature",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WalletSignature"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Empty or oversized message, or a non-EVM chain"
+          },
+          "403": {
+            "description": "Agent caller, missing or insufficient step-up, denied by a wallet access policy, or a self-custody wallet the server cannot sign for.\n"
+          },
+          "404": {
+            "description": "No wallet on that chain for this user"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}/sign-typed-data": {
+      "post": {
+        "tags": [
+          "Treasury"
+        ],
+        "summary": "Sign EIP-712 typed data with a human wallet",
+        "description": "Hashes and signs a full EIP-712 payload. Include `EIP712Domain` in `types` — viem and ethers synthesise that entry and omit it, and this hashes exactly what you send.\n\nSame gates as `sign-message`.\n",
+        "operationId": "signTreasuryTypedData",
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "example": "base"
+            }
+          },
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "typed_data"
+                ],
+                "properties": {
+                  "typed_data": {
+                    "type": "object",
+                    "description": "`types`, `primaryType`, `domain`, `message`."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Signature",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WalletSignature"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Malformed EIP-712 payload, or a non-EVM chain"
+          },
+          "403": {
+            "description": "Same refusals as sign-message"
+          },
+          "404": {
+            "description": "No wallet on that chain for this user"
+          }
+        }
+      }
+    },
     "/v1/treasury/wallets/{chain}/swap": {
       "post": {
         "tags": [
@@ -28340,6 +28480,301 @@
         }
       }
     },
+    "/v1/secret-requests": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Ask a human for a credential",
+        "description": "Agent-authenticated. The agent says what it needs and why; the human sees a secure field in the dashboard, stores the value straight into the vault over their own session, and the agent is later told **where** it went — never what it is.\n\nThis exists because the alternative is worse than it looks. Typing a credential into runtime chat persists it to the conversation, writes it into the agent's memory, and replays it to the model on every later turn: one paste, four copies, no way back.\n\nOne open request per agent per label: asking again with the same label refreshes the existing one rather than queueing a duplicate. Unanswered requests expire after 24 hours.\n",
+        "operationId": "create_secret_request",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "label",
+                  "purpose"
+                ],
+                "properties": {
+                  "label": {
+                    "type": "string",
+                    "maxLength": 120,
+                    "example": "X API access token"
+                  },
+                  "purpose": {
+                    "type": "string",
+                    "maxLength": 500,
+                    "description": "Shown to the person being asked. They are handing over a secret and need to know what for.\n",
+                    "example": "To post the daily update to X on your behalf."
+                  },
+                  "suggested_path": {
+                    "type": "string",
+                    "nullable": true,
+                    "description": "A suggestion only — the human picks the vault and may change the path.\n",
+                    "example": "api-keys/x-access-token"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Asked. Poll the status route; do not ask in conversation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "status",
+                    "expires_at",
+                    "next"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "status": {
+                      "type": "string",
+                      "example": "pending"
+                    },
+                    "expires_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "next": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Missing label or purpose, or an invalid suggested path"
+          },
+          "403": {
+            "description": "Not an agent. A person storing a credential uses the vault directly.\n"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "What your agents have asked you for",
+        "description": "User-authenticated. Open requests for the caller's org, newest first, excluding expired ones. Agents cannot call this — they read their own request by id, so one agent can never enumerate which credentials an org holds.\n",
+        "operationId": "list_secret_requests",
+        "responses": {
+          "200": {
+            "description": "Open requests",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "requests"
+                  ],
+                  "properties": {
+                    "requests": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/SecretRequest"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Called by an agent"
+          }
+        }
+      }
+    },
+    "/v1/secret-requests/{id}": {
+      "get": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Has my human answered yet?",
+        "description": "The asking agent's own view, and only its own — another agent's request reads as 404 rather than 403, so its existence is not disclosed. A fulfilled request returns a vault id and a path; the value is read separately with `get_secret`.\n\nExpiry is computed on read, so a lapsed request cannot appear live because no sweeper has run.\n",
+        "operationId": "get_secret_request",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Status and, once fulfilled, where to look",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretRequestAgentView"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No such request, or it belongs to another agent"
+          }
+        }
+      }
+    },
+    "/v1/secret-requests/{id}/fulfil": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Tell the agent where you put it",
+        "description": "User-authenticated. Takes a **location, never a value** — by the time this is called the secret is already in the vault, written by the browser with `PUT /v1/vaults/{vault_id}/secrets/{path}` over the user's own session. There is no field here that could carry a plaintext credential, and there should never be one.\n\nFulfilment also grants the asking agent read on exactly that path, and binds the vault to it if the agent has an explicit vault list. Without both, the user hands over a credential and the agent still gets a 403 — the failure this whole flow exists to remove.\n",
+        "operationId": "fulfil_secret_request",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "vault_id",
+                  "path"
+                ],
+                "properties": {
+                  "vault_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "path": {
+                    "type": "string",
+                    "example": "api-keys/x-access-token"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Fulfilled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "status",
+                    "path",
+                    "vault_id",
+                    "granted_read"
+                  ],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "example": "fulfilled"
+                    },
+                    "path": {
+                      "type": "string"
+                    },
+                    "vault_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "granted_read": {
+                      "type": "boolean",
+                      "description": "False when the secret was stored but the read grant could not be written — the agent will need access granted by hand.\n"
+                    },
+                    "bound_new_vault": {
+                      "type": "boolean",
+                      "description": "True when the agent had to be bound to a vault it was not bound to before. Its access is correct from now on, but a JWT carries the `vault_ids` it was minted with, so a token the agent already holds is refused until it re-mints. Answering into a vault the agent already reaches avoids this.\n"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Already answered, expired, an invalid path, or nothing is stored at that path — the location the agent is sent to has to be real.\n"
+          },
+          "403": {
+            "description": "Called by an agent"
+          },
+          "404": {
+            "description": "No such request, or no such vault in this org"
+          }
+        }
+      }
+    },
+    "/v1/secret-requests/{id}/decline": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "No, and stop asking",
+        "description": "User-authenticated. The agent's next poll returns `declined` with an instruction not to ask again for the same thing and to say plainly what it cannot do.\n",
+        "operationId": "decline_secret_request",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Declined",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "status"
+                  ],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "example": "declined"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Already answered"
+          },
+          "403": {
+            "description": "Called by an agent"
+          }
+        }
+      }
+    },
     "/v1/billing/promo/preview": {
       "get": {
         "tags": [
@@ -42117,6 +42552,131 @@
           }
         }
       },
+      "WalletSignature": {
+        "type": "object",
+        "required": [
+          "signature",
+          "address",
+          "chain"
+        ],
+        "properties": {
+          "signature": {
+            "type": "string",
+            "description": "65-byte `0x`-prefixed signature, r‖s‖v."
+          },
+          "address": {
+            "type": "string",
+            "description": "The signing wallet, so it can be passed straight to `verifyMessage`."
+          },
+          "chain": {
+            "type": "string"
+          }
+        }
+      },
+      "SecretRequest": {
+        "type": "object",
+        "description": "An agent's open ask, as the human sees it. Carries the request and, once fulfilled, a reference — never a value.\n",
+        "required": [
+          "id",
+          "label",
+          "purpose",
+          "status",
+          "expires_at",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "agent_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "label": {
+            "type": "string",
+            "description": "Written by the agent. Untrusted text — render it as text, never as markup.\n"
+          },
+          "purpose": {
+            "type": "string"
+          },
+          "suggested_path": {
+            "type": "string",
+            "nullable": true
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "fulfilled",
+              "declined",
+              "expired"
+            ]
+          },
+          "stored_path": {
+            "type": "string",
+            "nullable": true,
+            "description": "Set on fulfilment. Where the secret went, not what it is."
+          },
+          "vault_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "SecretRequestAgentView": {
+        "type": "object",
+        "description": "The same request as the *agent* is allowed to see it: status, and once fulfilled where to look. Deliberately narrower than `SecretRequest` — no `fulfilled_by`, no timestamps, and no field anywhere that could hold a credential.\n",
+        "required": [
+          "id",
+          "status",
+          "next"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "fulfilled",
+              "declined",
+              "expired"
+            ]
+          },
+          "vault_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "Present only once fulfilled."
+          },
+          "path": {
+            "type": "string",
+            "nullable": true,
+            "description": "Present only once fulfilled. Read the credential from here with `get_secret`.\n"
+          },
+          "next": {
+            "type": "string",
+            "description": "What to do about this status, in the agent's terms."
+          }
+        }
+      },
       "ConnectorPreset": {
         "type": "object",
         "required": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.46"
+    version: "0.61.48"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -7207,6 +7207,109 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/treasury/wallets/{chain}/sign-message:
+        post:
+            tags: [Treasury]
+            summary: "Sign a message with a human wallet (EIP-191)"
+            description: >
+                `personal_sign` over the given text, hashed as
+                `\x19Ethereum Signed Message:\n<len>` + message — what
+                viem's `verifyMessage` and ethers' `verifyMessage` expect.
+
+
+                Human callers only; an agent signs with its own key via
+                `POST /v1/agents/{agent_id}/sign`. Gated exactly as a send
+                is: `X-Auth-Confirm` step-up scored as a Send action, wallet
+                access policies (`WalletAction::Sign`), and a refusal for
+                wallets whose key is split or passkey-owned — those have no
+                server-side key and will not fall back to one.
+
+
+                EVM chains only.
+            operationId: signTreasuryMessage
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema: { type: string, example: ethereum }
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  schema: { type: string }
+                  description: Account password, or a `rat_` token from `POST /v1/auth/reauth/complete`.
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [message]
+                            properties:
+                                message:
+                                    type: string
+                                    maxLength: 16384
+                                    example: Sign in to Example at 2026-10-01T10:00:00Z
+            responses:
+                '200':
+                    description: Signature
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/WalletSignature'
+                '400':
+                    description: Empty or oversized message, or a non-EVM chain
+                '403':
+                    description: >
+                        Agent caller, missing or insufficient step-up, denied by a
+                        wallet access policy, or a self-custody wallet the server
+                        cannot sign for.
+                '404':
+                    description: No wallet on that chain for this user
+    /v1/treasury/wallets/{chain}/sign-typed-data:
+        post:
+            tags: [Treasury]
+            summary: "Sign EIP-712 typed data with a human wallet"
+            description: >
+                Hashes and signs a full EIP-712 payload. Include
+                `EIP712Domain` in `types` — viem and ethers synthesise that
+                entry and omit it, and this hashes exactly what you send.
+
+
+                Same gates as `sign-message`.
+            operationId: signTreasuryTypedData
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema: { type: string, example: base }
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  schema: { type: string }
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [typed_data]
+                            properties:
+                                typed_data:
+                                    type: object
+                                    description: '`types`, `primaryType`, `domain`, `message`.'
+            responses:
+                '200':
+                    description: Signature
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/WalletSignature'
+                '400':
+                    description: Malformed EIP-712 payload, or a non-EVM chain
+                '403':
+                    description: Same refusals as sign-message
+                '404':
+                    description: No wallet on that chain for this user
     /v1/treasury/wallets/{chain}/swap:
         post:
             tags: [Treasury Wallets]
@@ -18104,6 +18207,229 @@ paths:
                                             - $ref: '#/components/schemas/ConnectorPreset'
                 '401':
                     description: Unauthenticated
+    /v1/secret-requests:
+        post:
+            tags: [Secrets]
+            summary: "Ask a human for a credential"
+            description: >
+                Agent-authenticated. The agent says what it needs and why; the
+                human sees a secure field in the dashboard, stores the value
+                straight into the vault over their own session, and the agent
+                is later told **where** it went — never what it is.
+
+
+                This exists because the alternative is worse than it looks.
+                Typing a credential into runtime chat persists it to the
+                conversation, writes it into the agent's memory, and replays it
+                to the model on every later turn: one paste, four copies, no
+                way back.
+
+
+                One open request per agent per label: asking again with the
+                same label refreshes the existing one rather than queueing a
+                duplicate. Unanswered requests expire after 24 hours.
+            operationId: create_secret_request
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [label, purpose]
+                            properties:
+                                label:
+                                    type: string
+                                    maxLength: 120
+                                    example: X API access token
+                                purpose:
+                                    type: string
+                                    maxLength: 500
+                                    description: >
+                                        Shown to the person being asked. They are
+                                        handing over a secret and need to know
+                                        what for.
+                                    example: To post the daily update to X on your behalf.
+                                suggested_path:
+                                    type: string
+                                    nullable: true
+                                    description: >
+                                        A suggestion only — the human picks the
+                                        vault and may change the path.
+                                    example: api-keys/x-access-token
+            responses:
+                '202':
+                    description: Asked. Poll the status route; do not ask in conversation.
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [id, status, expires_at, next]
+                                properties:
+                                    id: { type: string, format: uuid }
+                                    status: { type: string, example: pending }
+                                    expires_at: { type: string, format: date-time }
+                                    next: { type: string }
+                '400':
+                    description: Missing label or purpose, or an invalid suggested path
+                '403':
+                    description: >
+                        Not an agent. A person storing a credential uses the
+                        vault directly.
+        get:
+            tags: [Secrets]
+            summary: "What your agents have asked you for"
+            description: >
+                User-authenticated. Open requests for the caller's org, newest
+                first, excluding expired ones. Agents cannot call this — they
+                read their own request by id, so one agent can never enumerate
+                which credentials an org holds.
+            operationId: list_secret_requests
+            responses:
+                '200':
+                    description: Open requests
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [requests]
+                                properties:
+                                    requests:
+                                        type: array
+                                        items:
+                                            $ref: '#/components/schemas/SecretRequest'
+                '403':
+                    description: Called by an agent
+    /v1/secret-requests/{id}:
+        get:
+            tags: [Secrets]
+            summary: "Has my human answered yet?"
+            description: >
+                The asking agent's own view, and only its own — another agent's
+                request reads as 404 rather than 403, so its existence is not
+                disclosed. A fulfilled request returns a vault id and a path;
+                the value is read separately with `get_secret`.
+
+
+                Expiry is computed on read, so a lapsed request cannot appear
+                live because no sweeper has run.
+            operationId: get_secret_request
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: Status and, once fulfilled, where to look
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/SecretRequestAgentView'
+                '404':
+                    description: No such request, or it belongs to another agent
+    /v1/secret-requests/{id}/fulfil:
+        post:
+            tags: [Secrets]
+            summary: "Tell the agent where you put it"
+            description: >
+                User-authenticated. Takes a **location, never a value** — by
+                the time this is called the secret is already in the vault,
+                written by the browser with
+                `PUT /v1/vaults/{vault_id}/secrets/{path}` over the user's own
+                session. There is no field here that could carry a plaintext
+                credential, and there should never be one.
+
+
+                Fulfilment also grants the asking agent read on exactly that
+                path, and binds the vault to it if the agent has an explicit
+                vault list. Without both, the user hands over a credential and
+                the agent still gets a 403 — the failure this whole flow
+                exists to remove.
+            operationId: fulfil_secret_request
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [vault_id, path]
+                            properties:
+                                vault_id: { type: string, format: uuid }
+                                path:
+                                    type: string
+                                    example: api-keys/x-access-token
+            responses:
+                '200':
+                    description: Fulfilled
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [status, path, vault_id, granted_read]
+                                properties:
+                                    status: { type: string, example: fulfilled }
+                                    path: { type: string }
+                                    vault_id: { type: string, format: uuid }
+                                    granted_read:
+                                        type: boolean
+                                        description: >
+                                            False when the secret was stored but
+                                            the read grant could not be written —
+                                            the agent will need access granted
+                                            by hand.
+                                    bound_new_vault:
+                                        type: boolean
+                                        description: >
+                                            True when the agent had to be bound to
+                                            a vault it was not bound to before. Its
+                                            access is correct from now on, but a
+                                            JWT carries the `vault_ids` it was
+                                            minted with, so a token the agent
+                                            already holds is refused until it
+                                            re-mints. Answering into a vault the
+                                            agent already reaches avoids this.
+                '400':
+                    description: >
+                        Already answered, expired, an invalid path, or nothing is
+                        stored at that path — the location the agent is sent to has
+                        to be real.
+                '403':
+                    description: Called by an agent
+                '404':
+                    description: No such request, or no such vault in this org
+    /v1/secret-requests/{id}/decline:
+        post:
+            tags: [Secrets]
+            summary: "No, and stop asking"
+            description: >
+                User-authenticated. The agent's next poll returns `declined`
+                with an instruction not to ask again for the same thing and to
+                say plainly what it cannot do.
+            operationId: decline_secret_request
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: Declined
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [status]
+                                properties:
+                                    status: { type: string, example: declined }
+                '400':
+                    description: Already answered
+                '403':
+                    description: Called by an agent
     /v1/billing/promo/preview:
         get:
             tags: [Billing]
@@ -27089,6 +27415,74 @@ components:
                         an approval by reply.
                 created_at: { type: string, format: date-time }
 
+        WalletSignature:
+            type: object
+            required: [signature, address, chain]
+            properties:
+                signature:
+                    type: string
+                    description: 65-byte `0x`-prefixed signature, r‖s‖v.
+                address:
+                    type: string
+                    description: The signing wallet, so it can be passed straight to `verifyMessage`.
+                chain: { type: string }
+
+        SecretRequest:
+            type: object
+            description: >
+                An agent's open ask, as the human sees it. Carries the request
+                and, once fulfilled, a reference — never a value.
+            required: [id, label, purpose, status, expires_at, created_at]
+            properties:
+                id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid, nullable: true }
+                agent_name: { type: string, nullable: true }
+                label:
+                    type: string
+                    description: >
+                        Written by the agent. Untrusted text — render it as
+                        text, never as markup.
+                purpose: { type: string }
+                suggested_path: { type: string, nullable: true }
+                status:
+                    type: string
+                    enum: [pending, fulfilled, declined, expired]
+                stored_path:
+                    type: string
+                    nullable: true
+                    description: Set on fulfilment. Where the secret went, not what it is.
+                vault_id: { type: string, format: uuid, nullable: true }
+                expires_at: { type: string, format: date-time }
+                created_at: { type: string, format: date-time }
+
+        SecretRequestAgentView:
+            type: object
+            description: >
+                The same request as the *agent* is allowed to see it: status,
+                and once fulfilled where to look. Deliberately narrower than
+                `SecretRequest` — no `fulfilled_by`, no timestamps, and no
+                field anywhere that could hold a credential.
+            required: [id, status, next]
+            properties:
+                id: { type: string, format: uuid }
+                status:
+                    type: string
+                    enum: [pending, fulfilled, declined, expired]
+                vault_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: Present only once fulfilled.
+                path:
+                    type: string
+                    nullable: true
+                    description: >
+                        Present only once fulfilled. Read the credential from
+                        here with `get_secret`.
+                next:
+                    type: string
+                    description: What to do about this status, in the agent's terms.
+
         ConnectorPreset:
             type: object
             required: [slug, display_name, description, category, binding_type, base_url, requires_oauth]

package/package.json

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