@1claw/openapi-spec 0.61.25 → 0.61.27

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.25",
+    "version": "0.61.27",
     "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"
@@ -3861,6 +3861,136 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/children": {
+      "parameters": [
+        {
+          "name": "agent_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      ],
+      "get": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "List an agent's child agents",
+        "operationId": "listChildAgents",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Children",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Create a child agent",
+        "description": "A cheap sub-agent under a parent. The child has its own API key, memory\nnamespaces and `action_approval_policy`; is created with a subset of the\nparent's `vault_ids` and `scopes` (a superset is refused, not trimmed);\ninherits the parent's vault access policies (policy lookups include the\nparent's rows) and guardrails; does not count against the plan's agent cap\n(capped at 50 per parent); and cannot have children of its own. Human-only.\nAudited as `agent.child_created`.\n",
+        "operationId": "createChildAgent",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "name"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "maxLength": 100
+                  },
+                  "description": {
+                    "type": "string"
+                  },
+                  "vault_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "description": "Subset of the parent's vault_ids. Default the parent's."
+                  },
+                  "scopes": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Subset of the parent's scopes. Default the parent's."
+                  },
+                  "memory_namespace_allowlist": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "The child's own namespaces. Default `[\"child:{child_id}\"]`."
+                  },
+                  "action_approval_policy": {
+                    "type": "object",
+                    "description": "The child's own policy. Default the parent's."
+                  },
+                  "expires_at": {
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "approval_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created; `api_key` shown once",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentCreatedResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/rotate-key": {
       "post": {
         "tags": [
@@ -19001,6 +19131,73 @@
         }
       }
     },
+    "/v1/automations/{automationId}/runs/{runId}/resume": {
+      "post": {
+        "tags": [
+          "Automations"
+        ],
+        "summary": "Resume a run parked on an approval",
+        "operationId": "resumeAutomationRun",
+        "description": "An `approval_request` step parks the run in `awaiting_approval` and stops the\nclock. Deciding that approval — via the API, the one-tap email link or the\nphone — resumes the run automatically: `approved` continues from the next\nstep, `rejected` fails the run with the reason. This route is the hand-off\nfor a decision made elsewhere: it marks the approval approved on the caller's\nbehalf and continues the run. Human-only. Idempotent — a run that is not\nparked is returned unchanged. Later steps see the approval step's output as\n`{status, approval_id}` and the optional `payload` as `{{resume.*}}`. A\nparked run that nobody decides within 72 hours becomes `timed_out`.\nEmits `automation.run.resumed`.\n",
+        "parameters": [
+          {
+            "name": "automationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "payload": {
+                    "type": "object",
+                    "description": "Exposed to later steps as `{{resume.*}}`."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The run, now running (or unchanged if it was not parked)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AutomationRunResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/automations/presets": {
       "get": {
         "tags": [
@@ -20838,7 +21035,7 @@
           "Organization"
         ],
         "summary": "Apply a chart",
-        "description": "Create what the chart describes. Human users only.\n\n**Apply calls the same handlers the HTTP routes call.** Creating a vault\nruns five gates before anything is written — the delegation scope, a name\ncheck, control-plane consensus, a creation rate limit and the tier quota\n— and creating an agent runs its own. A reconciler that wrote through the\nrepositories would skip all of them and would look, in review, exactly\nlike one that did not.\n\nSo if your org has consensus configured on `vault.create`, applying a\nchart queues an approval exactly as a dashboard click would. That resource\ncomes back as `awaiting_approval` rather than failing the whole chart.\n\nPer-resource results: `created`, `unchanged`, `skipped`, `refused`,\n`awaiting_approval`, `failed`. `needs_attention` is true when the chart is\nnot fully applied — something is waiting on a person, whether an approval,\nan OAuth sign-in, or a resource that drifted and was left alone.\n\nSave `applied_state` to `.1claw/apply-state.json`. It records what apply\nset, which is what lets the next run tell drift from a first apply.\n\nv1 creates and reports; it does not delete, prune, or patch in place. An\napply that silently deletes is an apply nobody runs twice.\n",
+        "description": "Create what the chart describes. Human users only.\n\n**Apply calls the same handlers the HTTP routes call.** Creating a vault\nruns five gates before anything is written — the delegation scope, a name\ncheck, control-plane consensus, a creation rate limit and the tier quota\n— and creating an agent runs its own. A reconciler that wrote through the\nrepositories would skip all of them and would look, in review, exactly\nlike one that did not.\n\nSo if your org has consensus configured on `vault.create`, applying a\nchart queues an approval exactly as a dashboard click would. That resource\ncomes back as `awaiting_approval` rather than failing the whole chart.\n\nResource kinds, in the order apply walks them: `vault`, `agent`,\n`policy` (one per path pattern, named `vault:agent:path`), `connector`\n(`agent/binding_name`; `authorization_url` on the result when a person\nstill has to sign in) and `binding` (`agent/name`, from\n`spec.agents[].bindings` — declared in full with `binding_type`, `config`,\n`guardrails.allowed_hosts` and an optional `credential: {vault_ref, path}`\npointing into a chart vault). A dependent resource whose vault or agent\nwas queued for approval this run is `skipped` with \"waiting on …\" and is\ncreated by the next apply.\n\nPer-resource results: `created`, `patched`, `unchanged`, `skipped`,\n`refused`, `awaiting_approval`, `failed`. `needs_attention` is true when\nthe chart is not fully applied — something is waiting on a person, whether\nan approval, an OAuth sign-in, or a resource that drifted and was left\nalone.\n\nSave `applied_state` to `.1claw/apply-state.json`. It records what apply\nset, which is what lets the next run tell drift from a first apply.\n\nApply creates, and patches an agent's `description`/`system_prompt` in\nplace through the same `update_agent` gate a dashboard edit takes. Policy\npermissions, binding config and guardrails, connector presets and vault\nfields are create-only: a difference is `refused` with the endpoint that\nowns the change. It does not delete or prune. An apply that silently\ndeletes is an apply nobody runs twice.\n",
         "operationId": "applyChart",
         "requestBody": {
           "required": true,
@@ -20889,6 +21086,7 @@
                             "type": "string",
                             "enum": [
                               "created",
+                              "patched",
                               "unchanged",
                               "skipped",
                               "refused",
@@ -20902,6 +21100,10 @@
                           },
                           "detail": {
                             "type": "string"
+                          },
+                          "authorization_url": {
+                            "type": "string",
+                            "description": "Connectors only — where a person signs in to finish the install."
                           }
                         }
                       }
@@ -32594,6 +32796,19 @@
           "created_at"
         ],
         "properties": {
+          "agent_type": {
+            "type": "string",
+            "enum": [
+              "standard",
+              "child"
+            ],
+            "description": "A `child` is a sub-agent under `parent_agent_id` that inherits its parent's policies and does not count against the plan's agent cap."
+          },
+          "parent_agent_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Present on child agents."
+          },
           "memory_enabled": {
             "type": "boolean",
             "description": "Whether durable key-value and semantic memory is enabled. Omitted when false: the server skips serializing this field unless it is true, so an absent key means disabled."
@@ -43512,6 +43727,13 @@
             "items": {
               "$ref": "#/components/schemas/OAuthAppCredentialResponse"
             }
+          },
+          "platform_defaults": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Provider slugs 1Claw has its own OAuth app for. Where the organization has\nregistered no credentials for one of these, connections use 1Claw's app;\nan organization credential for the same provider always wins.\n"
           }
         }
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.25"
+    version: "0.61.27"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -2568,6 +2568,82 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/children:
+        parameters:
+            - name: agent_id
+              in: path
+              required: true
+              schema: { type: string, format: uuid }
+        get:
+            tags: [Agents]
+            summary: List an agent's child agents
+            operationId: listChildAgents
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Children
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AgentListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        post:
+            tags: [Agents]
+            summary: Create a child agent
+            description: |
+                A cheap sub-agent under a parent. The child has its own API key, memory
+                namespaces and `action_approval_policy`; is created with a subset of the
+                parent's `vault_ids` and `scopes` (a superset is refused, not trimmed);
+                inherits the parent's vault access policies (policy lookups include the
+                parent's rows) and guardrails; does not count against the plan's agent cap
+                (capped at 50 per parent); and cannot have children of its own. Human-only.
+                Audited as `agent.child_created`.
+            operationId: createChildAgent
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [name]
+                            properties:
+                                name: { type: string, maxLength: 100 }
+                                description: { type: string }
+                                vault_ids:
+                                    type: array
+                                    items: { type: string, format: uuid }
+                                    description: Subset of the parent's vault_ids. Default the parent's.
+                                scopes:
+                                    type: array
+                                    items: { type: string }
+                                    description: Subset of the parent's scopes. Default the parent's.
+                                memory_namespace_allowlist:
+                                    type: array
+                                    items: { type: string }
+                                    description: The child's own namespaces. Default `["child:{child_id}"]`.
+                                action_approval_policy:
+                                    type: object
+                                    description: The child's own policy. Default the parent's.
+                                expires_at: { type: string, format: date-time }
+                                approval_id: { type: string, format: uuid }
+            responses:
+                "201":
+                    description: Created; `api_key` shown once
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AgentCreatedResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/agents/{agent_id}/rotate-key:
         post:
             tags: [Agents]
@@ -12079,6 +12155,59 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/automations/{automationId}/runs/{runId}/resume:
+        post:
+            tags: [Automations]
+            summary: Resume a run parked on an approval
+            operationId: resumeAutomationRun
+            description: |
+                An `approval_request` step parks the run in `awaiting_approval` and stops the
+                clock. Deciding that approval — via the API, the one-tap email link or the
+                phone — resumes the run automatically: `approved` continues from the next
+                step, `rejected` fails the run with the reason. This route is the hand-off
+                for a decision made elsewhere: it marks the approval approved on the caller's
+                behalf and continues the run. Human-only. Idempotent — a run that is not
+                parked is returned unchanged. Later steps see the approval step's output as
+                `{status, approval_id}` and the optional `payload` as `{{resume.*}}`. A
+                parked run that nobody decides within 72 hours becomes `timed_out`.
+                Emits `automation.run.resumed`.
+            parameters:
+                - name: automationId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: runId
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                payload:
+                                    type: object
+                                    description: Exposed to later steps as `{{resume.*}}`.
+            responses:
+                "200":
+                    description: The run, now running (or unchanged if it was not parked)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AutomationRunResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/automations/presets:
         get:
             tags: [Automations]
@@ -13303,16 +13432,31 @@ paths:
                 chart queues an approval exactly as a dashboard click would. That resource
                 comes back as `awaiting_approval` rather than failing the whole chart.
 
-                Per-resource results: `created`, `unchanged`, `skipped`, `refused`,
-                `awaiting_approval`, `failed`. `needs_attention` is true when the chart is
-                not fully applied — something is waiting on a person, whether an approval,
-                an OAuth sign-in, or a resource that drifted and was left alone.
+                Resource kinds, in the order apply walks them: `vault`, `agent`,
+                `policy` (one per path pattern, named `vault:agent:path`), `connector`
+                (`agent/binding_name`; `authorization_url` on the result when a person
+                still has to sign in) and `binding` (`agent/name`, from
+                `spec.agents[].bindings` — declared in full with `binding_type`, `config`,
+                `guardrails.allowed_hosts` and an optional `credential: {vault_ref, path}`
+                pointing into a chart vault). A dependent resource whose vault or agent
+                was queued for approval this run is `skipped` with "waiting on …" and is
+                created by the next apply.
+
+                Per-resource results: `created`, `patched`, `unchanged`, `skipped`,
+                `refused`, `awaiting_approval`, `failed`. `needs_attention` is true when
+                the chart is not fully applied — something is waiting on a person, whether
+                an approval, an OAuth sign-in, or a resource that drifted and was left
+                alone.
 
                 Save `applied_state` to `.1claw/apply-state.json`. It records what apply
                 set, which is what lets the next run tell drift from a first apply.
 
-                v1 creates and reports; it does not delete, prune, or patch in place. An
-                apply that silently deletes is an apply nobody runs twice.
+                Apply creates, and patches an agent's `description`/`system_prompt` in
+                place through the same `update_agent` gate a dashboard edit takes. Policy
+                permissions, binding config and guardrails, connector presets and vault
+                fields are create-only: a difference is `refused` with the endpoint that
+                owns the change. It does not delete or prune. An apply that silently
+                deletes is an apply nobody runs twice.
             operationId: applyChart
             requestBody:
                 required: true
@@ -13346,9 +13490,12 @@ paths:
                                                 name: { type: string }
                                                 result:
                                                     type: string
-                                                    enum: [created, unchanged, skipped, refused, awaiting_approval, failed]
+                                                    enum: [created, patched, unchanged, skipped, refused, awaiting_approval, failed]
                                                 id: { type: string, format: uuid }
                                                 detail: { type: string }
+                                                authorization_url:
+                                                    type: string
+                                                    description: Connectors only — where a person signs in to finish the install.
                                     warnings:
                                         type: array
                                         items: { type: string }
@@ -20916,6 +21063,14 @@ components:
                     created_at,
                 ]
             properties:
+                agent_type:
+                    type: string
+                    enum: [standard, child]
+                    description: A `child` is a sub-agent under `parent_agent_id` that inherits its parent's policies and does not count against the plan's agent cap.
+                parent_agent_id:
+                    type: string
+                    format: uuid
+                    description: Present on child agents.
                 memory_enabled:
                     type: boolean
                     description: >-
@@ -28213,6 +28368,13 @@ components:
                     type: array
                     items:
                         $ref: "#/components/schemas/OAuthAppCredentialResponse"
+                platform_defaults:
+                    type: array
+                    items: { type: string }
+                    description: |
+                        Provider slugs 1Claw has its own OAuth app for. Where the organization has
+                        registered no credentials for one of these, connections use 1Claw's app;
+                        an organization credential for the same provider always wins.
 
         # -------------------------------------------------------------------
         # Key Import

package/package.json

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