@1claw/openapi-spec 0.53.3 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/openapi.json +399 -8
  2. package/openapi.yaml +263 -8
  3. package/package.json +1 -1
package/openapi.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "1Claw API",
5
- "version": "0.53.2",
5
+ "version": "0.53.4",
6
6
  "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\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
7
7
  "contact": {
8
8
  "email": "ops@1claw.xyz"
@@ -3750,6 +3750,16 @@
3750
3750
  }
3751
3751
  }
3752
3752
  },
3753
+ "202": {
3754
+ "description": "Transaction held for human approval (graduated tx_approval_policy)",
3755
+ "content": {
3756
+ "application/json": {
3757
+ "schema": {
3758
+ "$ref": "#/components/schemas/TxAwaitingApproval"
3759
+ }
3760
+ }
3761
+ }
3762
+ },
3753
3763
  "402": {
3754
3764
  "$ref": "#/components/responses/PaymentRequired"
3755
3765
  },
@@ -5049,11 +5059,55 @@
5049
5059
  }
5050
5060
  }
5051
5061
  },
5062
+ "202": {
5063
+ "description": "Execution requires human approval before running",
5064
+ "content": {
5065
+ "application/json": {
5066
+ "schema": {
5067
+ "$ref": "#/components/schemas/ExecutionApprovalRequired"
5068
+ }
5069
+ }
5070
+ }
5071
+ },
5052
5072
  "400": {
5053
5073
  "$ref": "#/components/responses/BadRequest"
5054
5074
  },
5055
5075
  "403": {
5056
- "$ref": "#/components/responses/Forbidden"
5076
+ "description": "Guardrail violation or permission denied",
5077
+ "content": {
5078
+ "application/json": {
5079
+ "schema": {
5080
+ "oneOf": [
5081
+ {
5082
+ "$ref": "#/components/schemas/GuardrailViolation"
5083
+ },
5084
+ {
5085
+ "$ref": "#/components/schemas/ProblemDetails"
5086
+ }
5087
+ ]
5088
+ }
5089
+ }
5090
+ }
5091
+ },
5092
+ "413": {
5093
+ "description": "Request params exceed binding max_request_bytes",
5094
+ "content": {
5095
+ "application/json": {
5096
+ "schema": {
5097
+ "$ref": "#/components/schemas/GuardrailViolation"
5098
+ }
5099
+ }
5100
+ }
5101
+ },
5102
+ "429": {
5103
+ "description": "Binding or agent execution rate limit exceeded",
5104
+ "content": {
5105
+ "application/json": {
5106
+ "schema": {
5107
+ "$ref": "#/components/schemas/GuardrailViolation"
5108
+ }
5109
+ }
5110
+ }
5057
5111
  }
5058
5112
  }
5059
5113
  }
@@ -10184,6 +10238,45 @@
10184
10238
  }
10185
10239
  }
10186
10240
  },
10241
+ "/v1/approvals/{approval_id}/status": {
10242
+ "get": {
10243
+ "tags": [
10244
+ "Approvals"
10245
+ ],
10246
+ "summary": "Poll approval status (agent-only)",
10247
+ "description": "Lightweight status poll for agents waiting on human approval.\nReturns `status` and `expires_at` only. Agents may only poll\napprovals they created (`agent_id` must match the caller).\n",
10248
+ "operationId": "getApprovalStatus",
10249
+ "parameters": [
10250
+ {
10251
+ "name": "approval_id",
10252
+ "in": "path",
10253
+ "required": true,
10254
+ "schema": {
10255
+ "type": "string",
10256
+ "format": "uuid"
10257
+ }
10258
+ }
10259
+ ],
10260
+ "responses": {
10261
+ "200": {
10262
+ "description": "Approval status",
10263
+ "content": {
10264
+ "application/json": {
10265
+ "schema": {
10266
+ "$ref": "#/components/schemas/ApprovalStatusResponse"
10267
+ }
10268
+ }
10269
+ }
10270
+ },
10271
+ "403": {
10272
+ "$ref": "#/components/responses/Forbidden"
10273
+ },
10274
+ "404": {
10275
+ "$ref": "#/components/responses/NotFound"
10276
+ }
10277
+ }
10278
+ }
10279
+ },
10187
10280
  "/v1/approvals/{approval_id}/decide": {
10188
10281
  "post": {
10189
10282
  "tags": [
@@ -18528,6 +18621,28 @@
18528
18621
  "default": true,
18529
18622
  "description": "When true, card orders route through the human approval queue before x402 payment."
18530
18623
  },
18624
+ "tx_approval_policy": {
18625
+ "type": "object",
18626
+ "additionalProperties": true,
18627
+ "nullable": true,
18628
+ "description": "Graduated transaction approval policy (HITL thresholds). Separate from hard guardrails."
18629
+ },
18630
+ "typed_data_policy": {
18631
+ "type": "string",
18632
+ "enum": [
18633
+ "deny",
18634
+ "approve"
18635
+ ],
18636
+ "description": "EIP-712 escalation when typed_data matches no allowlist — deny (403) or route to HITL (approve)."
18637
+ },
18638
+ "simulation_failure_policy": {
18639
+ "type": "string",
18640
+ "enum": [
18641
+ "deny",
18642
+ "approve"
18643
+ ],
18644
+ "description": "Simulation failure escalation — deny (422) or route to HITL (approve)."
18645
+ },
18531
18646
  "api_key_expires_at": {
18532
18647
  "type": "string",
18533
18648
  "format": "date-time",
@@ -18691,6 +18806,34 @@
18691
18806
  "type": "boolean",
18692
18807
  "description": "When true, card orders route through the human approval queue before x402 payment."
18693
18808
  },
18809
+ "tx_approval_policy": {
18810
+ "type": "object",
18811
+ "additionalProperties": true,
18812
+ "nullable": true,
18813
+ "description": "Graduated transaction approval policy (HITL thresholds)."
18814
+ },
18815
+ "typed_data_policy": {
18816
+ "type": "string",
18817
+ "enum": [
18818
+ "deny",
18819
+ "approve"
18820
+ ],
18821
+ "nullable": true,
18822
+ "description": "EIP-712 escalation policy."
18823
+ },
18824
+ "simulation_failure_policy": {
18825
+ "type": "string",
18826
+ "enum": [
18827
+ "deny",
18828
+ "approve"
18829
+ ],
18830
+ "nullable": true,
18831
+ "description": "Simulation failure escalation policy."
18832
+ },
18833
+ "clear_auto_suspended": {
18834
+ "type": "boolean",
18835
+ "description": "When true, clears circuit-breaker auto-suspension (human owner/admin only)."
18836
+ },
18694
18837
  "federation_enabled": {
18695
18838
  "type": "boolean",
18696
18839
  "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n"
@@ -18943,6 +19086,32 @@
18943
19086
  "type": "boolean",
18944
19087
  "description": "When true, card orders route through the human approval queue before x402 payment."
18945
19088
  },
19089
+ "tx_approval_policy": {
19090
+ "type": "object",
19091
+ "additionalProperties": true,
19092
+ "nullable": true,
19093
+ "description": "Graduated transaction approval policy (HITL thresholds)."
19094
+ },
19095
+ "typed_data_policy": {
19096
+ "type": "string",
19097
+ "enum": [
19098
+ "deny",
19099
+ "approve"
19100
+ ],
19101
+ "nullable": true
19102
+ },
19103
+ "simulation_failure_policy": {
19104
+ "type": "string",
19105
+ "enum": [
19106
+ "deny",
19107
+ "approve"
19108
+ ],
19109
+ "nullable": true
19110
+ },
19111
+ "auto_suspended": {
19112
+ "type": "boolean",
19113
+ "description": "True when circuit breaker auto-suspended the agent after repeated guardrail denials."
19114
+ },
18946
19115
  "tx_count_today": {
18947
19116
  "type": "integer",
18948
19117
  "description": "Today's transaction count (UTC calendar day). Present when intents_api_enabled."
@@ -24423,6 +24592,89 @@
24423
24592
  }
24424
24593
  }
24425
24594
  },
24595
+ "ApprovalStatusResponse": {
24596
+ "type": "object",
24597
+ "required": [
24598
+ "status"
24599
+ ],
24600
+ "properties": {
24601
+ "status": {
24602
+ "type": "string",
24603
+ "enum": [
24604
+ "pending",
24605
+ "approved",
24606
+ "rejected",
24607
+ "expired"
24608
+ ]
24609
+ },
24610
+ "expires_at": {
24611
+ "type": "string",
24612
+ "format": "date-time",
24613
+ "nullable": true
24614
+ }
24615
+ }
24616
+ },
24617
+ "GuardrailViolation": {
24618
+ "type": "object",
24619
+ "required": [
24620
+ "error",
24621
+ "reason_code",
24622
+ "approval_available"
24623
+ ],
24624
+ "properties": {
24625
+ "error": {
24626
+ "type": "string",
24627
+ "enum": [
24628
+ "guardrail_violation"
24629
+ ]
24630
+ },
24631
+ "reason_code": {
24632
+ "type": "string",
24633
+ "enum": [
24634
+ "binding_rpm_exceeded",
24635
+ "agent_rpm_exceeded",
24636
+ "graphql_mutation_blocked",
24637
+ "graphql_depth_exceeded",
24638
+ "graphql_parse_failed",
24639
+ "graphql_introspection_blocked",
24640
+ "response_too_large",
24641
+ "request_too_large",
24642
+ "method_not_allowed",
24643
+ "header_not_allowed",
24644
+ "dns_private_ip_blocked",
24645
+ "agent_suspended",
24646
+ "outside_time_window",
24647
+ "secret_in_request",
24648
+ "concurrency_exceeded",
24649
+ "org_frozen"
24650
+ ]
24651
+ },
24652
+ "limit": {
24653
+ "type": "string",
24654
+ "nullable": true
24655
+ },
24656
+ "current": {
24657
+ "type": "string",
24658
+ "nullable": true
24659
+ },
24660
+ "attempted": {
24661
+ "type": "string",
24662
+ "nullable": true
24663
+ },
24664
+ "approval_available": {
24665
+ "type": "boolean",
24666
+ "default": false
24667
+ },
24668
+ "retry_after_seconds": {
24669
+ "type": "integer",
24670
+ "nullable": true
24671
+ },
24672
+ "detail": {
24673
+ "type": "string",
24674
+ "nullable": true
24675
+ }
24676
+ }
24677
+ },
24426
24678
  "EmailOtpVerifyResponse": {
24427
24679
  "type": "object",
24428
24680
  "required": [
@@ -25012,8 +25264,7 @@
25012
25264
  "additionalProperties": true
25013
25265
  },
25014
25266
  "guardrails": {
25015
- "type": "object",
25016
- "additionalProperties": true
25267
+ "$ref": "#/components/schemas/BindingGuardrails"
25017
25268
  },
25018
25269
  "credential": {
25019
25270
  "type": "object",
@@ -25033,8 +25284,7 @@
25033
25284
  "additionalProperties": true
25034
25285
  },
25035
25286
  "guardrails": {
25036
- "type": "object",
25037
- "additionalProperties": true
25287
+ "$ref": "#/components/schemas/BindingGuardrails"
25038
25288
  },
25039
25289
  "is_active": {
25040
25290
  "type": "boolean"
@@ -25049,6 +25299,78 @@
25049
25299
  }
25050
25300
  }
25051
25301
  },
25302
+ "BindingGuardrails": {
25303
+ "type": "object",
25304
+ "description": "Per-binding execution guardrails enforced at execute time.",
25305
+ "properties": {
25306
+ "allowed_hosts": {
25307
+ "type": "array",
25308
+ "items": {
25309
+ "type": "string"
25310
+ },
25311
+ "description": "Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level."
25312
+ },
25313
+ "allowed_paths": {
25314
+ "type": "array",
25315
+ "items": {
25316
+ "type": "string"
25317
+ },
25318
+ "description": "Path allowlist for HTTP/GraphQL bindings."
25319
+ },
25320
+ "max_requests_per_minute": {
25321
+ "type": "integer",
25322
+ "minimum": 1,
25323
+ "description": "Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count."
25324
+ },
25325
+ "max_duration_ms": {
25326
+ "type": "integer",
25327
+ "description": "Upstream timeout cap for this binding."
25328
+ },
25329
+ "max_request_bytes": {
25330
+ "type": "integer",
25331
+ "default": 262144,
25332
+ "description": "Max serialized execute `params` size in bytes (default 256 KiB)."
25333
+ },
25334
+ "max_response_bytes": {
25335
+ "type": "integer",
25336
+ "description": "Max upstream response body bytes (default 1 MiB, hard cap 4 MiB)."
25337
+ },
25338
+ "allowed_request_headers": {
25339
+ "type": "array",
25340
+ "items": {
25341
+ "type": "string"
25342
+ },
25343
+ "description": "Agent-supplied headers permitted in execute params. Defaults to content-type, accept, user-agent, idempotency-key."
25344
+ },
25345
+ "allow_mutations": {
25346
+ "type": "boolean",
25347
+ "default": true,
25348
+ "description": "GraphQL only — when false, mutation operations return 403 guardrail_violation."
25349
+ },
25350
+ "allow_introspection": {
25351
+ "type": "boolean",
25352
+ "default": false,
25353
+ "description": "GraphQL only — when false, __schema/__type introspection is blocked."
25354
+ },
25355
+ "max_query_depth": {
25356
+ "type": "integer",
25357
+ "default": 10,
25358
+ "description": "GraphQL max selection depth."
25359
+ },
25360
+ "max_aliases": {
25361
+ "type": "integer",
25362
+ "default": 30,
25363
+ "description": "GraphQL max alias count."
25364
+ },
25365
+ "allowed_operations": {
25366
+ "type": "array",
25367
+ "items": {
25368
+ "type": "string"
25369
+ },
25370
+ "description": "GraphQL operation kinds allowed (query, mutation, subscription)."
25371
+ }
25372
+ }
25373
+ },
25052
25374
  "BindingResponse": {
25053
25375
  "type": "object",
25054
25376
  "required": [
@@ -25092,8 +25414,7 @@
25092
25414
  "additionalProperties": true
25093
25415
  },
25094
25416
  "guardrails": {
25095
- "type": "object",
25096
- "additionalProperties": true
25417
+ "$ref": "#/components/schemas/BindingGuardrails"
25097
25418
  },
25098
25419
  "is_active": {
25099
25420
  "type": "boolean"
@@ -25180,6 +25501,76 @@
25180
25501
  "type": "object",
25181
25502
  "additionalProperties": true,
25182
25503
  "description": "Intent-specific parameters"
25504
+ },
25505
+ "dry_run": {
25506
+ "type": "boolean",
25507
+ "default": false,
25508
+ "description": "When true, validate guardrails and approval policy without executing or persisting side effects."
25509
+ },
25510
+ "resume_after_approval_id": {
25511
+ "type": "string",
25512
+ "format": "uuid",
25513
+ "description": "Internal — resume execution after human approval (server-injected)."
25514
+ }
25515
+ }
25516
+ },
25517
+ "ExecutionApprovalRequired": {
25518
+ "type": "object",
25519
+ "required": [
25520
+ "error",
25521
+ "approval_id",
25522
+ "status"
25523
+ ],
25524
+ "properties": {
25525
+ "error": {
25526
+ "type": "string",
25527
+ "enum": [
25528
+ "approval_required"
25529
+ ]
25530
+ },
25531
+ "approval_id": {
25532
+ "type": "string",
25533
+ "format": "uuid"
25534
+ },
25535
+ "status": {
25536
+ "type": "string",
25537
+ "enum": [
25538
+ "pending"
25539
+ ]
25540
+ },
25541
+ "expires_at": {
25542
+ "type": "string",
25543
+ "format": "date-time",
25544
+ "nullable": true
25545
+ }
25546
+ }
25547
+ },
25548
+ "TxAwaitingApproval": {
25549
+ "type": "object",
25550
+ "required": [
25551
+ "status",
25552
+ "approval_id"
25553
+ ],
25554
+ "properties": {
25555
+ "status": {
25556
+ "type": "string",
25557
+ "enum": [
25558
+ "awaiting_approval"
25559
+ ]
25560
+ },
25561
+ "approval_id": {
25562
+ "type": "string",
25563
+ "format": "uuid"
25564
+ },
25565
+ "tx_id": {
25566
+ "type": "string",
25567
+ "format": "uuid",
25568
+ "nullable": true
25569
+ },
25570
+ "expires_at": {
25571
+ "type": "string",
25572
+ "format": "date-time",
25573
+ "nullable": true
25183
25574
  }
25184
25575
  }
25185
25576
  },
package/openapi.yaml CHANGED
@@ -2,7 +2,7 @@ openapi: 3.1.0
2
2
 
3
3
  info:
4
4
  title: 1Claw API
5
- version: 0.53.2
5
+ version: 0.53.4
6
6
  description: |
7
7
  Secure secret management for AI agents. Provides vaults, secrets,
8
8
  policy-based access control, agent identity, Intents API,
@@ -2476,6 +2476,12 @@ paths:
2476
2476
  application/json:
2477
2477
  schema:
2478
2478
  $ref: "#/components/schemas/TransactionResponse"
2479
+ "202":
2480
+ description: Transaction held for human approval (graduated tx_approval_policy)
2481
+ content:
2482
+ application/json:
2483
+ schema:
2484
+ $ref: "#/components/schemas/TxAwaitingApproval"
2479
2485
  get:
2480
2486
  tags: [Transactions]
2481
2487
  summary: List agent transactions
@@ -3282,7 +3288,31 @@ paths:
3282
3288
  "400":
3283
3289
  $ref: "#/components/responses/BadRequest"
3284
3290
  "403":
3285
- $ref: "#/components/responses/Forbidden"
3291
+ description: Guardrail violation or permission denied
3292
+ content:
3293
+ application/json:
3294
+ schema:
3295
+ oneOf:
3296
+ - $ref: "#/components/schemas/GuardrailViolation"
3297
+ - $ref: "#/components/schemas/ProblemDetails"
3298
+ "413":
3299
+ description: Request params exceed binding max_request_bytes
3300
+ content:
3301
+ application/json:
3302
+ schema:
3303
+ $ref: "#/components/schemas/GuardrailViolation"
3304
+ "429":
3305
+ description: Binding or agent execution rate limit exceeded
3306
+ content:
3307
+ application/json:
3308
+ schema:
3309
+ $ref: "#/components/schemas/GuardrailViolation"
3310
+ "202":
3311
+ description: Execution requires human approval before running
3312
+ content:
3313
+ application/json:
3314
+ schema:
3315
+ $ref: "#/components/schemas/ExecutionApprovalRequired"
3286
3316
 
3287
3317
  /v1/agents/{agent_id}/executions:
3288
3318
  get:
@@ -6550,6 +6580,34 @@ paths:
6550
6580
  "404":
6551
6581
  $ref: "#/components/responses/NotFound"
6552
6582
 
6583
+ /v1/approvals/{approval_id}/status:
6584
+ get:
6585
+ tags: [Approvals]
6586
+ summary: Poll approval status (agent-only)
6587
+ description: |
6588
+ Lightweight status poll for agents waiting on human approval.
6589
+ Returns `status` and `expires_at` only. Agents may only poll
6590
+ approvals they created (`agent_id` must match the caller).
6591
+ operationId: getApprovalStatus
6592
+ parameters:
6593
+ - name: approval_id
6594
+ in: path
6595
+ required: true
6596
+ schema:
6597
+ type: string
6598
+ format: uuid
6599
+ responses:
6600
+ "200":
6601
+ description: Approval status
6602
+ content:
6603
+ application/json:
6604
+ schema:
6605
+ $ref: "#/components/schemas/ApprovalStatusResponse"
6606
+ "403":
6607
+ $ref: "#/components/responses/Forbidden"
6608
+ "404":
6609
+ $ref: "#/components/responses/NotFound"
6610
+
6553
6611
  /v1/approvals/{approval_id}/decide:
6554
6612
  post:
6555
6613
  tags: [Approvals]
@@ -11950,6 +12008,19 @@ components:
11950
12008
  type: boolean
11951
12009
  default: true
11952
12010
  description: When true, card orders route through the human approval queue before x402 payment.
12011
+ tx_approval_policy:
12012
+ type: object
12013
+ additionalProperties: true
12014
+ nullable: true
12015
+ description: Graduated transaction approval policy (HITL thresholds). Separate from hard guardrails.
12016
+ typed_data_policy:
12017
+ type: string
12018
+ enum: [deny, approve]
12019
+ description: EIP-712 escalation when typed_data matches no allowlist — deny (403) or route to HITL (approve).
12020
+ simulation_failure_policy:
12021
+ type: string
12022
+ enum: [deny, approve]
12023
+ description: Simulation failure escalation — deny (422) or route to HITL (approve).
11953
12024
  api_key_expires_at:
11954
12025
  type: string
11955
12026
  format: date-time
@@ -12074,6 +12145,24 @@ components:
12074
12145
  card_require_approval:
12075
12146
  type: boolean
12076
12147
  description: When true, card orders route through the human approval queue before x402 payment.
12148
+ tx_approval_policy:
12149
+ type: object
12150
+ additionalProperties: true
12151
+ nullable: true
12152
+ description: Graduated transaction approval policy (HITL thresholds).
12153
+ typed_data_policy:
12154
+ type: string
12155
+ enum: [deny, approve]
12156
+ nullable: true
12157
+ description: EIP-712 escalation policy.
12158
+ simulation_failure_policy:
12159
+ type: string
12160
+ enum: [deny, approve]
12161
+ nullable: true
12162
+ description: Simulation failure escalation policy.
12163
+ clear_auto_suspended:
12164
+ type: boolean
12165
+ description: When true, clears circuit-breaker auto-suspension (human owner/admin only).
12077
12166
  federation_enabled:
12078
12167
  type: boolean
12079
12168
  description: |
@@ -12275,6 +12364,22 @@ components:
12275
12364
  card_require_approval:
12276
12365
  type: boolean
12277
12366
  description: When true, card orders route through the human approval queue before x402 payment.
12367
+ tx_approval_policy:
12368
+ type: object
12369
+ additionalProperties: true
12370
+ nullable: true
12371
+ description: Graduated transaction approval policy (HITL thresholds).
12372
+ typed_data_policy:
12373
+ type: string
12374
+ enum: [deny, approve]
12375
+ nullable: true
12376
+ simulation_failure_policy:
12377
+ type: string
12378
+ enum: [deny, approve]
12379
+ nullable: true
12380
+ auto_suspended:
12381
+ type: boolean
12382
+ description: True when circuit breaker auto-suspended the agent after repeated guardrail denials.
12278
12383
  tx_count_today:
12279
12384
  type: integer
12280
12385
  description: Today's transaction count (UTC calendar day). Present when intents_api_enabled.
@@ -16095,6 +16200,63 @@ components:
16095
16200
  type: string
16096
16201
  format: date-time
16097
16202
 
16203
+ ApprovalStatusResponse:
16204
+ type: object
16205
+ required: [status]
16206
+ properties:
16207
+ status:
16208
+ type: string
16209
+ enum: [pending, approved, rejected, expired]
16210
+ expires_at:
16211
+ type: string
16212
+ format: date-time
16213
+ nullable: true
16214
+
16215
+ GuardrailViolation:
16216
+ type: object
16217
+ required: [error, reason_code, approval_available]
16218
+ properties:
16219
+ error:
16220
+ type: string
16221
+ enum: [guardrail_violation]
16222
+ reason_code:
16223
+ type: string
16224
+ enum:
16225
+ - binding_rpm_exceeded
16226
+ - agent_rpm_exceeded
16227
+ - graphql_mutation_blocked
16228
+ - graphql_depth_exceeded
16229
+ - graphql_parse_failed
16230
+ - graphql_introspection_blocked
16231
+ - response_too_large
16232
+ - request_too_large
16233
+ - method_not_allowed
16234
+ - header_not_allowed
16235
+ - dns_private_ip_blocked
16236
+ - agent_suspended
16237
+ - outside_time_window
16238
+ - secret_in_request
16239
+ - concurrency_exceeded
16240
+ - org_frozen
16241
+ limit:
16242
+ type: string
16243
+ nullable: true
16244
+ current:
16245
+ type: string
16246
+ nullable: true
16247
+ attempted:
16248
+ type: string
16249
+ nullable: true
16250
+ approval_available:
16251
+ type: boolean
16252
+ default: false
16253
+ retry_after_seconds:
16254
+ type: integer
16255
+ nullable: true
16256
+ detail:
16257
+ type: string
16258
+ nullable: true
16259
+
16098
16260
  # --- Email OTP ---
16099
16261
 
16100
16262
  EmailOtpVerifyResponse:
@@ -16471,8 +16633,7 @@ components:
16471
16633
  type: object
16472
16634
  additionalProperties: true
16473
16635
  guardrails:
16474
- type: object
16475
- additionalProperties: true
16636
+ $ref: "#/components/schemas/BindingGuardrails"
16476
16637
  credential:
16477
16638
  type: object
16478
16639
  additionalProperties: true
@@ -16487,8 +16648,7 @@ components:
16487
16648
  type: object
16488
16649
  additionalProperties: true
16489
16650
  guardrails:
16490
- type: object
16491
- additionalProperties: true
16651
+ $ref: "#/components/schemas/BindingGuardrails"
16492
16652
  is_active:
16493
16653
  type: boolean
16494
16654
  credential:
@@ -16498,6 +16658,57 @@ components:
16498
16658
  credential_source:
16499
16659
  $ref: "#/components/schemas/CredentialSource"
16500
16660
 
16661
+ BindingGuardrails:
16662
+ type: object
16663
+ description: Per-binding execution guardrails enforced at execute time.
16664
+ properties:
16665
+ allowed_hosts:
16666
+ type: array
16667
+ items: { type: string }
16668
+ description: Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level.
16669
+ allowed_paths:
16670
+ type: array
16671
+ items: { type: string }
16672
+ description: Path allowlist for HTTP/GraphQL bindings.
16673
+ max_requests_per_minute:
16674
+ type: integer
16675
+ minimum: 1
16676
+ description: Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count.
16677
+ max_duration_ms:
16678
+ type: integer
16679
+ description: Upstream timeout cap for this binding.
16680
+ max_request_bytes:
16681
+ type: integer
16682
+ default: 262144
16683
+ description: Max serialized execute `params` size in bytes (default 256 KiB).
16684
+ max_response_bytes:
16685
+ type: integer
16686
+ description: Max upstream response body bytes (default 1 MiB, hard cap 4 MiB).
16687
+ allowed_request_headers:
16688
+ type: array
16689
+ items: { type: string }
16690
+ description: Agent-supplied headers permitted in execute params. Defaults to content-type, accept, user-agent, idempotency-key.
16691
+ allow_mutations:
16692
+ type: boolean
16693
+ default: true
16694
+ description: GraphQL only — when false, mutation operations return 403 guardrail_violation.
16695
+ allow_introspection:
16696
+ type: boolean
16697
+ default: false
16698
+ description: GraphQL only — when false, __schema/__type introspection is blocked.
16699
+ max_query_depth:
16700
+ type: integer
16701
+ default: 10
16702
+ description: GraphQL max selection depth.
16703
+ max_aliases:
16704
+ type: integer
16705
+ default: 30
16706
+ description: GraphQL max alias count.
16707
+ allowed_operations:
16708
+ type: array
16709
+ items: { type: string }
16710
+ description: GraphQL operation kinds allowed (query, mutation, subscription).
16711
+
16501
16712
  BindingResponse:
16502
16713
  type: object
16503
16714
  required: [id, agent_id, binding_type, name, is_active, created_at, updated_at]
@@ -16517,8 +16728,7 @@ components:
16517
16728
  type: object
16518
16729
  additionalProperties: true
16519
16730
  guardrails:
16520
- type: object
16521
- additionalProperties: true
16731
+ $ref: "#/components/schemas/BindingGuardrails"
16522
16732
  is_active:
16523
16733
  type: boolean
16524
16734
  credential_set:
@@ -16576,6 +16786,51 @@ components:
16576
16786
  type: object
16577
16787
  additionalProperties: true
16578
16788
  description: Intent-specific parameters
16789
+ dry_run:
16790
+ type: boolean
16791
+ default: false
16792
+ description: When true, validate guardrails and approval policy without executing or persisting side effects.
16793
+ resume_after_approval_id:
16794
+ type: string
16795
+ format: uuid
16796
+ description: Internal — resume execution after human approval (server-injected).
16797
+
16798
+ ExecutionApprovalRequired:
16799
+ type: object
16800
+ required: [error, approval_id, status]
16801
+ properties:
16802
+ error:
16803
+ type: string
16804
+ enum: [approval_required]
16805
+ approval_id:
16806
+ type: string
16807
+ format: uuid
16808
+ status:
16809
+ type: string
16810
+ enum: [pending]
16811
+ expires_at:
16812
+ type: string
16813
+ format: date-time
16814
+ nullable: true
16815
+
16816
+ TxAwaitingApproval:
16817
+ type: object
16818
+ required: [status, approval_id]
16819
+ properties:
16820
+ status:
16821
+ type: string
16822
+ enum: [awaiting_approval]
16823
+ approval_id:
16824
+ type: string
16825
+ format: uuid
16826
+ tx_id:
16827
+ type: string
16828
+ format: uuid
16829
+ nullable: true
16830
+ expires_at:
16831
+ type: string
16832
+ format: date-time
16833
+ nullable: true
16579
16834
 
16580
16835
  ExecuteResponse:
16581
16836
  type: object
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.53.3",
3
+ "version": "0.54.0",
4
4
  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
5
5
  "license": "MIT",
6
6
  "repository": {