@1claw/openapi-spec 0.53.3 → 0.55.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 +622 -8
  2. package/openapi.yaml +416 -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
  }
@@ -5557,6 +5611,80 @@
5557
5611
  }
5558
5612
  }
5559
5613
  },
5614
+ "/v1/org/freeze": {
5615
+ "post": {
5616
+ "tags": [
5617
+ "Organization"
5618
+ ],
5619
+ "summary": "Emergency org-wide freeze",
5620
+ "description": "Sets organizations.frozen_at — blocks agent tx/execution until unfreeze. Owner/admin only.",
5621
+ "operationId": "freezeOrg",
5622
+ "responses": {
5623
+ "200": {
5624
+ "description": "Organization frozen",
5625
+ "content": {
5626
+ "application/json": {
5627
+ "schema": {
5628
+ "type": "object",
5629
+ "properties": {
5630
+ "status": {
5631
+ "type": "string",
5632
+ "enum": [
5633
+ "frozen"
5634
+ ]
5635
+ },
5636
+ "org_id": {
5637
+ "type": "string",
5638
+ "format": "uuid"
5639
+ }
5640
+ }
5641
+ }
5642
+ }
5643
+ }
5644
+ },
5645
+ "403": {
5646
+ "description": "Forbidden"
5647
+ }
5648
+ }
5649
+ }
5650
+ },
5651
+ "/v1/org/unfreeze": {
5652
+ "post": {
5653
+ "tags": [
5654
+ "Organization"
5655
+ ],
5656
+ "summary": "Clear org-wide freeze",
5657
+ "description": "Clears organizations.frozen_at. Owner/admin only.",
5658
+ "operationId": "unfreezeOrg",
5659
+ "responses": {
5660
+ "200": {
5661
+ "description": "Organization unfrozen",
5662
+ "content": {
5663
+ "application/json": {
5664
+ "schema": {
5665
+ "type": "object",
5666
+ "properties": {
5667
+ "status": {
5668
+ "type": "string",
5669
+ "enum": [
5670
+ "unfrozen"
5671
+ ]
5672
+ },
5673
+ "org_id": {
5674
+ "type": "string",
5675
+ "format": "uuid"
5676
+ }
5677
+ }
5678
+ }
5679
+ }
5680
+ }
5681
+ },
5682
+ "403": {
5683
+ "description": "Forbidden"
5684
+ }
5685
+ }
5686
+ }
5687
+ },
5560
5688
  "/v1/org/bankr-config": {
5561
5689
  "get": {
5562
5690
  "tags": [
@@ -10184,6 +10312,45 @@
10184
10312
  }
10185
10313
  }
10186
10314
  },
10315
+ "/v1/approvals/{approval_id}/status": {
10316
+ "get": {
10317
+ "tags": [
10318
+ "Approvals"
10319
+ ],
10320
+ "summary": "Poll approval status (agent-only)",
10321
+ "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",
10322
+ "operationId": "getApprovalStatus",
10323
+ "parameters": [
10324
+ {
10325
+ "name": "approval_id",
10326
+ "in": "path",
10327
+ "required": true,
10328
+ "schema": {
10329
+ "type": "string",
10330
+ "format": "uuid"
10331
+ }
10332
+ }
10333
+ ],
10334
+ "responses": {
10335
+ "200": {
10336
+ "description": "Approval status",
10337
+ "content": {
10338
+ "application/json": {
10339
+ "schema": {
10340
+ "$ref": "#/components/schemas/ApprovalStatusResponse"
10341
+ }
10342
+ }
10343
+ }
10344
+ },
10345
+ "403": {
10346
+ "$ref": "#/components/responses/Forbidden"
10347
+ },
10348
+ "404": {
10349
+ "$ref": "#/components/responses/NotFound"
10350
+ }
10351
+ }
10352
+ }
10353
+ },
10187
10354
  "/v1/approvals/{approval_id}/decide": {
10188
10355
  "post": {
10189
10356
  "tags": [
@@ -18528,6 +18695,83 @@
18528
18695
  "default": true,
18529
18696
  "description": "When true, card orders route through the human approval queue before x402 payment."
18530
18697
  },
18698
+ "tx_approval_policy": {
18699
+ "type": "object",
18700
+ "additionalProperties": true,
18701
+ "nullable": true,
18702
+ "description": "Graduated transaction approval policy (HITL thresholds). Separate from hard guardrails."
18703
+ },
18704
+ "typed_data_policy": {
18705
+ "type": "string",
18706
+ "enum": [
18707
+ "deny",
18708
+ "approve"
18709
+ ],
18710
+ "description": "EIP-712 escalation when typed_data matches no allowlist — deny (403) or route to HITL (approve)."
18711
+ },
18712
+ "simulation_failure_policy": {
18713
+ "type": "string",
18714
+ "enum": [
18715
+ "deny",
18716
+ "approve"
18717
+ ],
18718
+ "description": "Simulation failure escalation — deny (422) or route to HITL (approve)."
18719
+ },
18720
+ "tx_block_unlimited_approvals": {
18721
+ "type": "boolean",
18722
+ "default": false,
18723
+ "description": "Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll)."
18724
+ },
18725
+ "tx_per_recipient_max_per_day": {
18726
+ "type": "integer",
18727
+ "nullable": true,
18728
+ "description": "Max transactions to the same recipient address per UTC day."
18729
+ },
18730
+ "tx_per_recipient_daily_limit": {
18731
+ "type": "string",
18732
+ "nullable": true,
18733
+ "description": "Max native-unit spend to the same recipient per UTC day."
18734
+ },
18735
+ "new_recipient_cap_native": {
18736
+ "type": "string",
18737
+ "nullable": true,
18738
+ "description": "Cap on first-time recipient spend in native units."
18739
+ },
18740
+ "tx_max_value_usd": {
18741
+ "type": "string",
18742
+ "nullable": true,
18743
+ "description": "Per-transaction USD cap (requires price oracle)."
18744
+ },
18745
+ "tx_daily_limit_usd": {
18746
+ "type": "string",
18747
+ "nullable": true,
18748
+ "description": "Rolling 24h USD spend cap (requires price oracle)."
18749
+ },
18750
+ "raw_signing_policy": {
18751
+ "type": "string",
18752
+ "enum": [
18753
+ "allow",
18754
+ "deny",
18755
+ "approve"
18756
+ ],
18757
+ "default": "allow",
18758
+ "description": "Raw digest signing policy — allow, deny, or route to HITL (approve)."
18759
+ },
18760
+ "personal_sign_policy": {
18761
+ "type": "object",
18762
+ "additionalProperties": true,
18763
+ "description": "personal_sign guardrails (message allowlist, max bytes, etc.)."
18764
+ },
18765
+ "allow_erc4337": {
18766
+ "type": "boolean",
18767
+ "default": false,
18768
+ "description": "Allow ERC-4337 gasless UserOperations."
18769
+ },
18770
+ "allow_eip7702": {
18771
+ "type": "boolean",
18772
+ "default": false,
18773
+ "description": "Allow EIP-7702 (tx type 4) set-code transactions."
18774
+ },
18531
18775
  "api_key_expires_at": {
18532
18776
  "type": "string",
18533
18777
  "format": "date-time",
@@ -18691,6 +18935,85 @@
18691
18935
  "type": "boolean",
18692
18936
  "description": "When true, card orders route through the human approval queue before x402 payment."
18693
18937
  },
18938
+ "tx_approval_policy": {
18939
+ "type": "object",
18940
+ "additionalProperties": true,
18941
+ "nullable": true,
18942
+ "description": "Graduated transaction approval policy (HITL thresholds)."
18943
+ },
18944
+ "typed_data_policy": {
18945
+ "type": "string",
18946
+ "enum": [
18947
+ "deny",
18948
+ "approve"
18949
+ ],
18950
+ "nullable": true,
18951
+ "description": "EIP-712 escalation policy."
18952
+ },
18953
+ "simulation_failure_policy": {
18954
+ "type": "string",
18955
+ "enum": [
18956
+ "deny",
18957
+ "approve"
18958
+ ],
18959
+ "nullable": true,
18960
+ "description": "Simulation failure escalation policy."
18961
+ },
18962
+ "tx_block_unlimited_approvals": {
18963
+ "type": "boolean",
18964
+ "description": "Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll)."
18965
+ },
18966
+ "tx_per_recipient_max_per_day": {
18967
+ "type": "integer",
18968
+ "nullable": true,
18969
+ "description": "Max transactions to the same recipient per UTC day. Null clears."
18970
+ },
18971
+ "tx_per_recipient_daily_limit": {
18972
+ "type": "string",
18973
+ "nullable": true,
18974
+ "description": "Max native spend to same recipient per UTC day. Null clears."
18975
+ },
18976
+ "new_recipient_cap_native": {
18977
+ "type": "string",
18978
+ "nullable": true,
18979
+ "description": "First-time recipient native cap. Null clears."
18980
+ },
18981
+ "tx_max_value_usd": {
18982
+ "type": "string",
18983
+ "nullable": true,
18984
+ "description": "Per-tx USD cap. Null clears."
18985
+ },
18986
+ "tx_daily_limit_usd": {
18987
+ "type": "string",
18988
+ "nullable": true,
18989
+ "description": "Rolling 24h USD spend cap. Null clears."
18990
+ },
18991
+ "raw_signing_policy": {
18992
+ "type": "string",
18993
+ "enum": [
18994
+ "allow",
18995
+ "deny",
18996
+ "approve"
18997
+ ],
18998
+ "description": "Raw digest signing policy."
18999
+ },
19000
+ "personal_sign_policy": {
19001
+ "type": "object",
19002
+ "additionalProperties": true,
19003
+ "description": "personal_sign guardrails JSON."
19004
+ },
19005
+ "allow_erc4337": {
19006
+ "type": "boolean",
19007
+ "description": "Allow ERC-4337 gasless UserOperations."
19008
+ },
19009
+ "allow_eip7702": {
19010
+ "type": "boolean",
19011
+ "description": "Allow EIP-7702 (tx type 4)."
19012
+ },
19013
+ "clear_auto_suspended": {
19014
+ "type": "boolean",
19015
+ "description": "When true, clears circuit-breaker auto-suspension (human owner/admin only)."
19016
+ },
18694
19017
  "federation_enabled": {
18695
19018
  "type": "boolean",
18696
19019
  "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 +19266,75 @@
18943
19266
  "type": "boolean",
18944
19267
  "description": "When true, card orders route through the human approval queue before x402 payment."
18945
19268
  },
19269
+ "tx_approval_policy": {
19270
+ "type": "object",
19271
+ "additionalProperties": true,
19272
+ "nullable": true,
19273
+ "description": "Graduated transaction approval policy (HITL thresholds)."
19274
+ },
19275
+ "typed_data_policy": {
19276
+ "type": "string",
19277
+ "enum": [
19278
+ "deny",
19279
+ "approve"
19280
+ ],
19281
+ "nullable": true
19282
+ },
19283
+ "simulation_failure_policy": {
19284
+ "type": "string",
19285
+ "enum": [
19286
+ "deny",
19287
+ "approve"
19288
+ ],
19289
+ "nullable": true
19290
+ },
19291
+ "tx_block_unlimited_approvals": {
19292
+ "type": "boolean",
19293
+ "description": "Block unlimited ERC-20 approvals."
19294
+ },
19295
+ "tx_per_recipient_max_per_day": {
19296
+ "type": "integer",
19297
+ "nullable": true
19298
+ },
19299
+ "tx_per_recipient_daily_limit": {
19300
+ "type": "string",
19301
+ "nullable": true
19302
+ },
19303
+ "new_recipient_cap_native": {
19304
+ "type": "string",
19305
+ "nullable": true
19306
+ },
19307
+ "tx_max_value_usd": {
19308
+ "type": "string",
19309
+ "nullable": true
19310
+ },
19311
+ "tx_daily_limit_usd": {
19312
+ "type": "string",
19313
+ "nullable": true
19314
+ },
19315
+ "raw_signing_policy": {
19316
+ "type": "string",
19317
+ "enum": [
19318
+ "allow",
19319
+ "deny",
19320
+ "approve"
19321
+ ]
19322
+ },
19323
+ "personal_sign_policy": {
19324
+ "type": "object",
19325
+ "additionalProperties": true,
19326
+ "nullable": true
19327
+ },
19328
+ "allow_erc4337": {
19329
+ "type": "boolean"
19330
+ },
19331
+ "allow_eip7702": {
19332
+ "type": "boolean"
19333
+ },
19334
+ "auto_suspended": {
19335
+ "type": "boolean",
19336
+ "description": "True when circuit breaker auto-suspended the agent after repeated guardrail denials."
19337
+ },
18946
19338
  "tx_count_today": {
18947
19339
  "type": "integer",
18948
19340
  "description": "Today's transaction count (UTC calendar day). Present when intents_api_enabled."
@@ -24423,6 +24815,89 @@
24423
24815
  }
24424
24816
  }
24425
24817
  },
24818
+ "ApprovalStatusResponse": {
24819
+ "type": "object",
24820
+ "required": [
24821
+ "status"
24822
+ ],
24823
+ "properties": {
24824
+ "status": {
24825
+ "type": "string",
24826
+ "enum": [
24827
+ "pending",
24828
+ "approved",
24829
+ "rejected",
24830
+ "expired"
24831
+ ]
24832
+ },
24833
+ "expires_at": {
24834
+ "type": "string",
24835
+ "format": "date-time",
24836
+ "nullable": true
24837
+ }
24838
+ }
24839
+ },
24840
+ "GuardrailViolation": {
24841
+ "type": "object",
24842
+ "required": [
24843
+ "error",
24844
+ "reason_code",
24845
+ "approval_available"
24846
+ ],
24847
+ "properties": {
24848
+ "error": {
24849
+ "type": "string",
24850
+ "enum": [
24851
+ "guardrail_violation"
24852
+ ]
24853
+ },
24854
+ "reason_code": {
24855
+ "type": "string",
24856
+ "enum": [
24857
+ "binding_rpm_exceeded",
24858
+ "agent_rpm_exceeded",
24859
+ "graphql_mutation_blocked",
24860
+ "graphql_depth_exceeded",
24861
+ "graphql_parse_failed",
24862
+ "graphql_introspection_blocked",
24863
+ "response_too_large",
24864
+ "request_too_large",
24865
+ "method_not_allowed",
24866
+ "header_not_allowed",
24867
+ "dns_private_ip_blocked",
24868
+ "agent_suspended",
24869
+ "outside_time_window",
24870
+ "secret_in_request",
24871
+ "concurrency_exceeded",
24872
+ "org_frozen"
24873
+ ]
24874
+ },
24875
+ "limit": {
24876
+ "type": "string",
24877
+ "nullable": true
24878
+ },
24879
+ "current": {
24880
+ "type": "string",
24881
+ "nullable": true
24882
+ },
24883
+ "attempted": {
24884
+ "type": "string",
24885
+ "nullable": true
24886
+ },
24887
+ "approval_available": {
24888
+ "type": "boolean",
24889
+ "default": false
24890
+ },
24891
+ "retry_after_seconds": {
24892
+ "type": "integer",
24893
+ "nullable": true
24894
+ },
24895
+ "detail": {
24896
+ "type": "string",
24897
+ "nullable": true
24898
+ }
24899
+ }
24900
+ },
24426
24901
  "EmailOtpVerifyResponse": {
24427
24902
  "type": "object",
24428
24903
  "required": [
@@ -25012,8 +25487,7 @@
25012
25487
  "additionalProperties": true
25013
25488
  },
25014
25489
  "guardrails": {
25015
- "type": "object",
25016
- "additionalProperties": true
25490
+ "$ref": "#/components/schemas/BindingGuardrails"
25017
25491
  },
25018
25492
  "credential": {
25019
25493
  "type": "object",
@@ -25033,8 +25507,7 @@
25033
25507
  "additionalProperties": true
25034
25508
  },
25035
25509
  "guardrails": {
25036
- "type": "object",
25037
- "additionalProperties": true
25510
+ "$ref": "#/components/schemas/BindingGuardrails"
25038
25511
  },
25039
25512
  "is_active": {
25040
25513
  "type": "boolean"
@@ -25049,6 +25522,78 @@
25049
25522
  }
25050
25523
  }
25051
25524
  },
25525
+ "BindingGuardrails": {
25526
+ "type": "object",
25527
+ "description": "Per-binding execution guardrails enforced at execute time.",
25528
+ "properties": {
25529
+ "allowed_hosts": {
25530
+ "type": "array",
25531
+ "items": {
25532
+ "type": "string"
25533
+ },
25534
+ "description": "Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level."
25535
+ },
25536
+ "allowed_paths": {
25537
+ "type": "array",
25538
+ "items": {
25539
+ "type": "string"
25540
+ },
25541
+ "description": "Path allowlist for HTTP/GraphQL bindings."
25542
+ },
25543
+ "max_requests_per_minute": {
25544
+ "type": "integer",
25545
+ "minimum": 1,
25546
+ "description": "Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count."
25547
+ },
25548
+ "max_duration_ms": {
25549
+ "type": "integer",
25550
+ "description": "Upstream timeout cap for this binding."
25551
+ },
25552
+ "max_request_bytes": {
25553
+ "type": "integer",
25554
+ "default": 262144,
25555
+ "description": "Max serialized execute `params` size in bytes (default 256 KiB)."
25556
+ },
25557
+ "max_response_bytes": {
25558
+ "type": "integer",
25559
+ "description": "Max upstream response body bytes (default 1 MiB, hard cap 4 MiB)."
25560
+ },
25561
+ "allowed_request_headers": {
25562
+ "type": "array",
25563
+ "items": {
25564
+ "type": "string"
25565
+ },
25566
+ "description": "Agent-supplied headers permitted in execute params. Defaults to content-type, accept, user-agent, idempotency-key."
25567
+ },
25568
+ "allow_mutations": {
25569
+ "type": "boolean",
25570
+ "default": true,
25571
+ "description": "GraphQL only — when false, mutation operations return 403 guardrail_violation."
25572
+ },
25573
+ "allow_introspection": {
25574
+ "type": "boolean",
25575
+ "default": false,
25576
+ "description": "GraphQL only — when false, __schema/__type introspection is blocked."
25577
+ },
25578
+ "max_query_depth": {
25579
+ "type": "integer",
25580
+ "default": 10,
25581
+ "description": "GraphQL max selection depth."
25582
+ },
25583
+ "max_aliases": {
25584
+ "type": "integer",
25585
+ "default": 30,
25586
+ "description": "GraphQL max alias count."
25587
+ },
25588
+ "allowed_operations": {
25589
+ "type": "array",
25590
+ "items": {
25591
+ "type": "string"
25592
+ },
25593
+ "description": "GraphQL operation kinds allowed (query, mutation, subscription)."
25594
+ }
25595
+ }
25596
+ },
25052
25597
  "BindingResponse": {
25053
25598
  "type": "object",
25054
25599
  "required": [
@@ -25092,8 +25637,7 @@
25092
25637
  "additionalProperties": true
25093
25638
  },
25094
25639
  "guardrails": {
25095
- "type": "object",
25096
- "additionalProperties": true
25640
+ "$ref": "#/components/schemas/BindingGuardrails"
25097
25641
  },
25098
25642
  "is_active": {
25099
25643
  "type": "boolean"
@@ -25180,6 +25724,76 @@
25180
25724
  "type": "object",
25181
25725
  "additionalProperties": true,
25182
25726
  "description": "Intent-specific parameters"
25727
+ },
25728
+ "dry_run": {
25729
+ "type": "boolean",
25730
+ "default": false,
25731
+ "description": "When true, validate guardrails and approval policy without executing or persisting side effects."
25732
+ },
25733
+ "resume_after_approval_id": {
25734
+ "type": "string",
25735
+ "format": "uuid",
25736
+ "description": "Internal — resume execution after human approval (server-injected)."
25737
+ }
25738
+ }
25739
+ },
25740
+ "ExecutionApprovalRequired": {
25741
+ "type": "object",
25742
+ "required": [
25743
+ "error",
25744
+ "approval_id",
25745
+ "status"
25746
+ ],
25747
+ "properties": {
25748
+ "error": {
25749
+ "type": "string",
25750
+ "enum": [
25751
+ "approval_required"
25752
+ ]
25753
+ },
25754
+ "approval_id": {
25755
+ "type": "string",
25756
+ "format": "uuid"
25757
+ },
25758
+ "status": {
25759
+ "type": "string",
25760
+ "enum": [
25761
+ "pending"
25762
+ ]
25763
+ },
25764
+ "expires_at": {
25765
+ "type": "string",
25766
+ "format": "date-time",
25767
+ "nullable": true
25768
+ }
25769
+ }
25770
+ },
25771
+ "TxAwaitingApproval": {
25772
+ "type": "object",
25773
+ "required": [
25774
+ "status",
25775
+ "approval_id"
25776
+ ],
25777
+ "properties": {
25778
+ "status": {
25779
+ "type": "string",
25780
+ "enum": [
25781
+ "awaiting_approval"
25782
+ ]
25783
+ },
25784
+ "approval_id": {
25785
+ "type": "string",
25786
+ "format": "uuid"
25787
+ },
25788
+ "tx_id": {
25789
+ "type": "string",
25790
+ "format": "uuid",
25791
+ "nullable": true
25792
+ },
25793
+ "expires_at": {
25794
+ "type": "string",
25795
+ "format": "date-time",
25796
+ "nullable": true
25183
25797
  }
25184
25798
  }
25185
25799
  },
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:
@@ -3606,6 +3636,52 @@ paths:
3606
3636
  "404":
3607
3637
  description: Agent-keys vault not found
3608
3638
 
3639
+ /v1/org/freeze:
3640
+ post:
3641
+ tags: [Organization]
3642
+ summary: Emergency org-wide freeze
3643
+ description: Sets organizations.frozen_at — blocks agent tx/execution until unfreeze. Owner/admin only.
3644
+ operationId: freezeOrg
3645
+ responses:
3646
+ "200":
3647
+ description: Organization frozen
3648
+ content:
3649
+ application/json:
3650
+ schema:
3651
+ type: object
3652
+ properties:
3653
+ status:
3654
+ type: string
3655
+ enum: [frozen]
3656
+ org_id:
3657
+ type: string
3658
+ format: uuid
3659
+ "403":
3660
+ description: Forbidden
3661
+
3662
+ /v1/org/unfreeze:
3663
+ post:
3664
+ tags: [Organization]
3665
+ summary: Clear org-wide freeze
3666
+ description: Clears organizations.frozen_at. Owner/admin only.
3667
+ operationId: unfreezeOrg
3668
+ responses:
3669
+ "200":
3670
+ description: Organization unfrozen
3671
+ content:
3672
+ application/json:
3673
+ schema:
3674
+ type: object
3675
+ properties:
3676
+ status:
3677
+ type: string
3678
+ enum: [unfrozen]
3679
+ org_id:
3680
+ type: string
3681
+ format: uuid
3682
+ "403":
3683
+ description: Forbidden
3684
+
3609
3685
  /v1/org/bankr-config:
3610
3686
  get:
3611
3687
  tags: [Organization]
@@ -6550,6 +6626,34 @@ paths:
6550
6626
  "404":
6551
6627
  $ref: "#/components/responses/NotFound"
6552
6628
 
6629
+ /v1/approvals/{approval_id}/status:
6630
+ get:
6631
+ tags: [Approvals]
6632
+ summary: Poll approval status (agent-only)
6633
+ description: |
6634
+ Lightweight status poll for agents waiting on human approval.
6635
+ Returns `status` and `expires_at` only. Agents may only poll
6636
+ approvals they created (`agent_id` must match the caller).
6637
+ operationId: getApprovalStatus
6638
+ parameters:
6639
+ - name: approval_id
6640
+ in: path
6641
+ required: true
6642
+ schema:
6643
+ type: string
6644
+ format: uuid
6645
+ responses:
6646
+ "200":
6647
+ description: Approval status
6648
+ content:
6649
+ application/json:
6650
+ schema:
6651
+ $ref: "#/components/schemas/ApprovalStatusResponse"
6652
+ "403":
6653
+ $ref: "#/components/responses/Forbidden"
6654
+ "404":
6655
+ $ref: "#/components/responses/NotFound"
6656
+
6553
6657
  /v1/approvals/{approval_id}/decide:
6554
6658
  post:
6555
6659
  tags: [Approvals]
@@ -11950,6 +12054,60 @@ components:
11950
12054
  type: boolean
11951
12055
  default: true
11952
12056
  description: When true, card orders route through the human approval queue before x402 payment.
12057
+ tx_approval_policy:
12058
+ type: object
12059
+ additionalProperties: true
12060
+ nullable: true
12061
+ description: Graduated transaction approval policy (HITL thresholds). Separate from hard guardrails.
12062
+ typed_data_policy:
12063
+ type: string
12064
+ enum: [deny, approve]
12065
+ description: EIP-712 escalation when typed_data matches no allowlist — deny (403) or route to HITL (approve).
12066
+ simulation_failure_policy:
12067
+ type: string
12068
+ enum: [deny, approve]
12069
+ description: Simulation failure escalation — deny (422) or route to HITL (approve).
12070
+ tx_block_unlimited_approvals:
12071
+ type: boolean
12072
+ default: false
12073
+ description: Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll).
12074
+ tx_per_recipient_max_per_day:
12075
+ type: integer
12076
+ nullable: true
12077
+ description: Max transactions to the same recipient address per UTC day.
12078
+ tx_per_recipient_daily_limit:
12079
+ type: string
12080
+ nullable: true
12081
+ description: Max native-unit spend to the same recipient per UTC day.
12082
+ new_recipient_cap_native:
12083
+ type: string
12084
+ nullable: true
12085
+ description: Cap on first-time recipient spend in native units.
12086
+ tx_max_value_usd:
12087
+ type: string
12088
+ nullable: true
12089
+ description: Per-transaction USD cap (requires price oracle).
12090
+ tx_daily_limit_usd:
12091
+ type: string
12092
+ nullable: true
12093
+ description: Rolling 24h USD spend cap (requires price oracle).
12094
+ raw_signing_policy:
12095
+ type: string
12096
+ enum: [allow, deny, approve]
12097
+ default: allow
12098
+ description: Raw digest signing policy — allow, deny, or route to HITL (approve).
12099
+ personal_sign_policy:
12100
+ type: object
12101
+ additionalProperties: true
12102
+ description: personal_sign guardrails (message allowlist, max bytes, etc.).
12103
+ allow_erc4337:
12104
+ type: boolean
12105
+ default: false
12106
+ description: Allow ERC-4337 gasless UserOperations.
12107
+ allow_eip7702:
12108
+ type: boolean
12109
+ default: false
12110
+ description: Allow EIP-7702 (tx type 4) set-code transactions.
11953
12111
  api_key_expires_at:
11954
12112
  type: string
11955
12113
  format: date-time
@@ -12074,6 +12232,61 @@ components:
12074
12232
  card_require_approval:
12075
12233
  type: boolean
12076
12234
  description: When true, card orders route through the human approval queue before x402 payment.
12235
+ tx_approval_policy:
12236
+ type: object
12237
+ additionalProperties: true
12238
+ nullable: true
12239
+ description: Graduated transaction approval policy (HITL thresholds).
12240
+ typed_data_policy:
12241
+ type: string
12242
+ enum: [deny, approve]
12243
+ nullable: true
12244
+ description: EIP-712 escalation policy.
12245
+ simulation_failure_policy:
12246
+ type: string
12247
+ enum: [deny, approve]
12248
+ nullable: true
12249
+ description: Simulation failure escalation policy.
12250
+ tx_block_unlimited_approvals:
12251
+ type: boolean
12252
+ description: Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll).
12253
+ tx_per_recipient_max_per_day:
12254
+ type: integer
12255
+ nullable: true
12256
+ description: Max transactions to the same recipient per UTC day. Null clears.
12257
+ tx_per_recipient_daily_limit:
12258
+ type: string
12259
+ nullable: true
12260
+ description: Max native spend to same recipient per UTC day. Null clears.
12261
+ new_recipient_cap_native:
12262
+ type: string
12263
+ nullable: true
12264
+ description: First-time recipient native cap. Null clears.
12265
+ tx_max_value_usd:
12266
+ type: string
12267
+ nullable: true
12268
+ description: Per-tx USD cap. Null clears.
12269
+ tx_daily_limit_usd:
12270
+ type: string
12271
+ nullable: true
12272
+ description: Rolling 24h USD spend cap. Null clears.
12273
+ raw_signing_policy:
12274
+ type: string
12275
+ enum: [allow, deny, approve]
12276
+ description: Raw digest signing policy.
12277
+ personal_sign_policy:
12278
+ type: object
12279
+ additionalProperties: true
12280
+ description: personal_sign guardrails JSON.
12281
+ allow_erc4337:
12282
+ type: boolean
12283
+ description: Allow ERC-4337 gasless UserOperations.
12284
+ allow_eip7702:
12285
+ type: boolean
12286
+ description: Allow EIP-7702 (tx type 4).
12287
+ clear_auto_suspended:
12288
+ type: boolean
12289
+ description: When true, clears circuit-breaker auto-suspension (human owner/admin only).
12077
12290
  federation_enabled:
12078
12291
  type: boolean
12079
12292
  description: |
@@ -12275,6 +12488,51 @@ components:
12275
12488
  card_require_approval:
12276
12489
  type: boolean
12277
12490
  description: When true, card orders route through the human approval queue before x402 payment.
12491
+ tx_approval_policy:
12492
+ type: object
12493
+ additionalProperties: true
12494
+ nullable: true
12495
+ description: Graduated transaction approval policy (HITL thresholds).
12496
+ typed_data_policy:
12497
+ type: string
12498
+ enum: [deny, approve]
12499
+ nullable: true
12500
+ simulation_failure_policy:
12501
+ type: string
12502
+ enum: [deny, approve]
12503
+ nullable: true
12504
+ tx_block_unlimited_approvals:
12505
+ type: boolean
12506
+ description: Block unlimited ERC-20 approvals.
12507
+ tx_per_recipient_max_per_day:
12508
+ type: integer
12509
+ nullable: true
12510
+ tx_per_recipient_daily_limit:
12511
+ type: string
12512
+ nullable: true
12513
+ new_recipient_cap_native:
12514
+ type: string
12515
+ nullable: true
12516
+ tx_max_value_usd:
12517
+ type: string
12518
+ nullable: true
12519
+ tx_daily_limit_usd:
12520
+ type: string
12521
+ nullable: true
12522
+ raw_signing_policy:
12523
+ type: string
12524
+ enum: [allow, deny, approve]
12525
+ personal_sign_policy:
12526
+ type: object
12527
+ additionalProperties: true
12528
+ nullable: true
12529
+ allow_erc4337:
12530
+ type: boolean
12531
+ allow_eip7702:
12532
+ type: boolean
12533
+ auto_suspended:
12534
+ type: boolean
12535
+ description: True when circuit breaker auto-suspended the agent after repeated guardrail denials.
12278
12536
  tx_count_today:
12279
12537
  type: integer
12280
12538
  description: Today's transaction count (UTC calendar day). Present when intents_api_enabled.
@@ -16095,6 +16353,63 @@ components:
16095
16353
  type: string
16096
16354
  format: date-time
16097
16355
 
16356
+ ApprovalStatusResponse:
16357
+ type: object
16358
+ required: [status]
16359
+ properties:
16360
+ status:
16361
+ type: string
16362
+ enum: [pending, approved, rejected, expired]
16363
+ expires_at:
16364
+ type: string
16365
+ format: date-time
16366
+ nullable: true
16367
+
16368
+ GuardrailViolation:
16369
+ type: object
16370
+ required: [error, reason_code, approval_available]
16371
+ properties:
16372
+ error:
16373
+ type: string
16374
+ enum: [guardrail_violation]
16375
+ reason_code:
16376
+ type: string
16377
+ enum:
16378
+ - binding_rpm_exceeded
16379
+ - agent_rpm_exceeded
16380
+ - graphql_mutation_blocked
16381
+ - graphql_depth_exceeded
16382
+ - graphql_parse_failed
16383
+ - graphql_introspection_blocked
16384
+ - response_too_large
16385
+ - request_too_large
16386
+ - method_not_allowed
16387
+ - header_not_allowed
16388
+ - dns_private_ip_blocked
16389
+ - agent_suspended
16390
+ - outside_time_window
16391
+ - secret_in_request
16392
+ - concurrency_exceeded
16393
+ - org_frozen
16394
+ limit:
16395
+ type: string
16396
+ nullable: true
16397
+ current:
16398
+ type: string
16399
+ nullable: true
16400
+ attempted:
16401
+ type: string
16402
+ nullable: true
16403
+ approval_available:
16404
+ type: boolean
16405
+ default: false
16406
+ retry_after_seconds:
16407
+ type: integer
16408
+ nullable: true
16409
+ detail:
16410
+ type: string
16411
+ nullable: true
16412
+
16098
16413
  # --- Email OTP ---
16099
16414
 
16100
16415
  EmailOtpVerifyResponse:
@@ -16471,8 +16786,7 @@ components:
16471
16786
  type: object
16472
16787
  additionalProperties: true
16473
16788
  guardrails:
16474
- type: object
16475
- additionalProperties: true
16789
+ $ref: "#/components/schemas/BindingGuardrails"
16476
16790
  credential:
16477
16791
  type: object
16478
16792
  additionalProperties: true
@@ -16487,8 +16801,7 @@ components:
16487
16801
  type: object
16488
16802
  additionalProperties: true
16489
16803
  guardrails:
16490
- type: object
16491
- additionalProperties: true
16804
+ $ref: "#/components/schemas/BindingGuardrails"
16492
16805
  is_active:
16493
16806
  type: boolean
16494
16807
  credential:
@@ -16498,6 +16811,57 @@ components:
16498
16811
  credential_source:
16499
16812
  $ref: "#/components/schemas/CredentialSource"
16500
16813
 
16814
+ BindingGuardrails:
16815
+ type: object
16816
+ description: Per-binding execution guardrails enforced at execute time.
16817
+ properties:
16818
+ allowed_hosts:
16819
+ type: array
16820
+ items: { type: string }
16821
+ description: Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level.
16822
+ allowed_paths:
16823
+ type: array
16824
+ items: { type: string }
16825
+ description: Path allowlist for HTTP/GraphQL bindings.
16826
+ max_requests_per_minute:
16827
+ type: integer
16828
+ minimum: 1
16829
+ description: Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count.
16830
+ max_duration_ms:
16831
+ type: integer
16832
+ description: Upstream timeout cap for this binding.
16833
+ max_request_bytes:
16834
+ type: integer
16835
+ default: 262144
16836
+ description: Max serialized execute `params` size in bytes (default 256 KiB).
16837
+ max_response_bytes:
16838
+ type: integer
16839
+ description: Max upstream response body bytes (default 1 MiB, hard cap 4 MiB).
16840
+ allowed_request_headers:
16841
+ type: array
16842
+ items: { type: string }
16843
+ description: Agent-supplied headers permitted in execute params. Defaults to content-type, accept, user-agent, idempotency-key.
16844
+ allow_mutations:
16845
+ type: boolean
16846
+ default: true
16847
+ description: GraphQL only — when false, mutation operations return 403 guardrail_violation.
16848
+ allow_introspection:
16849
+ type: boolean
16850
+ default: false
16851
+ description: GraphQL only — when false, __schema/__type introspection is blocked.
16852
+ max_query_depth:
16853
+ type: integer
16854
+ default: 10
16855
+ description: GraphQL max selection depth.
16856
+ max_aliases:
16857
+ type: integer
16858
+ default: 30
16859
+ description: GraphQL max alias count.
16860
+ allowed_operations:
16861
+ type: array
16862
+ items: { type: string }
16863
+ description: GraphQL operation kinds allowed (query, mutation, subscription).
16864
+
16501
16865
  BindingResponse:
16502
16866
  type: object
16503
16867
  required: [id, agent_id, binding_type, name, is_active, created_at, updated_at]
@@ -16517,8 +16881,7 @@ components:
16517
16881
  type: object
16518
16882
  additionalProperties: true
16519
16883
  guardrails:
16520
- type: object
16521
- additionalProperties: true
16884
+ $ref: "#/components/schemas/BindingGuardrails"
16522
16885
  is_active:
16523
16886
  type: boolean
16524
16887
  credential_set:
@@ -16576,6 +16939,51 @@ components:
16576
16939
  type: object
16577
16940
  additionalProperties: true
16578
16941
  description: Intent-specific parameters
16942
+ dry_run:
16943
+ type: boolean
16944
+ default: false
16945
+ description: When true, validate guardrails and approval policy without executing or persisting side effects.
16946
+ resume_after_approval_id:
16947
+ type: string
16948
+ format: uuid
16949
+ description: Internal — resume execution after human approval (server-injected).
16950
+
16951
+ ExecutionApprovalRequired:
16952
+ type: object
16953
+ required: [error, approval_id, status]
16954
+ properties:
16955
+ error:
16956
+ type: string
16957
+ enum: [approval_required]
16958
+ approval_id:
16959
+ type: string
16960
+ format: uuid
16961
+ status:
16962
+ type: string
16963
+ enum: [pending]
16964
+ expires_at:
16965
+ type: string
16966
+ format: date-time
16967
+ nullable: true
16968
+
16969
+ TxAwaitingApproval:
16970
+ type: object
16971
+ required: [status, approval_id]
16972
+ properties:
16973
+ status:
16974
+ type: string
16975
+ enum: [awaiting_approval]
16976
+ approval_id:
16977
+ type: string
16978
+ format: uuid
16979
+ tx_id:
16980
+ type: string
16981
+ format: uuid
16982
+ nullable: true
16983
+ expires_at:
16984
+ type: string
16985
+ format: date-time
16986
+ nullable: true
16579
16987
 
16580
16988
  ExecuteResponse:
16581
16989
  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.55.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": {