@1claw/openapi-spec 0.61.25 → 0.61.28

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.25",
+    "version": "0.61.28",
     "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."
                           }
                         }
                       }
@@ -23342,6 +23544,203 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/event-subscriptions": {
+      "post": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "Subscribe to a connector event source",
+        "description": "Pairs an installed connector binding with one of its preset's event\nsources (see `event_sources` on `GET /v1/connectors/presets`). 1Claw\nthen polls the source through the binding — same host and path\nallowlists, same credential, same SSRF guard — keeps the item ids it has\nseen, and dispatches each new item as an automation event of\n`event_type`, so an automation with `trigger_type: event` and\n`event_filter: { \"event_type\": \"gmail.message.received\" }` reacts within\none poll interval instead of on a cron it has to dedupe itself.\n\nThe first poll primes the subscription: it records what already exists\nand emits nothing, so a new subscription does not replay the inbox. At\nmost 25 new items are emitted per poll (oldest first); lists come from\nthe source's first page only. Failures back off exponentially on the\ninterval and switch the subscription off after 20 in a row.\n\nHuman users only; the agent needs Execution Intents enabled. At most 20\nsubscriptions per agent. The event payload is\n`{ \"event_type\", \"payload\": { \"subscription_id\", \"binding_id\", \"binding\", \"connector\", \"item\" } }`.\n",
+        "operationId": "createEventSubscription",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "binding_id",
+                  "event_type"
+                ],
+                "properties": {
+                  "binding_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "event_type": {
+                    "type": "string",
+                    "example": "gmail.message.received"
+                  },
+                  "interval_secs": {
+                    "type": "integer",
+                    "description": "Poll interval, at least the source's `min_interval_secs` and at most 86400. Defaults to the minimum."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Subscribed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventSubscription"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "This binding already subscribes to that event type"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "List an agent's event subscriptions",
+        "operationId": "listEventSubscriptions",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Subscriptions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "subscriptions": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/EventSubscription"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/event-subscriptions/{id}": {
+      "delete": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "Delete an event subscription",
+        "description": "Human users only.",
+        "operationId": "deleteEventSubscription",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/event-subscriptions/{id}/poll": {
+      "post": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "Poll an event subscription now",
+        "description": "Runs one poll immediately instead of waiting for the interval. The first\npoll of a fresh subscription primes it; a subscription switched off by\nrepeated failures is switched back on if the poll succeeds. Human users\nonly. A failed poll returns 400 with the source's error and is recorded\non the subscription like a scheduled failure.\n",
+        "operationId": "pollEventSubscriptionNow",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Polled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "emitted",
+                    "subscription"
+                  ],
+                  "properties": {
+                    "emitted": {
+                      "type": "integer"
+                    },
+                    "subscription": {
+                      "$ref": "#/components/schemas/EventSubscription"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/oauth/connections": {
       "get": {
         "tags": [
@@ -32594,6 +32993,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."
@@ -39324,6 +39736,120 @@
           },
           "requires_oauth": {
             "type": "boolean"
+          },
+          "event_sources": {
+            "type": "array",
+            "description": "Events 1Claw can synthesise for this connector by polling a list\nendpoint through the installed binding (nanobots item 4, polling\ninterim). Subscribe with `POST /v1/agents/{agent_id}/event-subscriptions`.\n",
+            "items": {
+              "$ref": "#/components/schemas/ConnectorEventSource"
+            }
+          }
+        }
+      },
+      "ConnectorEventSource": {
+        "type": "object",
+        "required": [
+          "event_type",
+          "description",
+          "path",
+          "items_pointer",
+          "id_pointers",
+          "min_interval_secs"
+        ],
+        "properties": {
+          "event_type": {
+            "type": "string",
+            "example": "gmail.message.received"
+          },
+          "description": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string",
+            "description": "Path (with query) relative to the binding's base URL, inside the preset's allowed paths."
+          },
+          "items_pointer": {
+            "type": "string",
+            "description": "JSON pointer to the array of items in the response body; empty means the body is the array."
+          },
+          "id_pointers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Pointers within one item whose values together identify it."
+          },
+          "min_interval_secs": {
+            "type": "integer",
+            "example": 60
+          }
+        }
+      },
+      "EventSubscription": {
+        "type": "object",
+        "required": [
+          "id",
+          "agent_id",
+          "binding_id",
+          "event_type",
+          "interval_secs",
+          "is_active",
+          "primed",
+          "next_poll_at",
+          "consecutive_errors",
+          "events_emitted",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "binding_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "event_type": {
+            "type": "string",
+            "example": "gmail.message.received"
+          },
+          "interval_secs": {
+            "type": "integer"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "primed": {
+            "type": "boolean",
+            "description": "False until the first poll has recorded what already exists. That poll emits nothing."
+          },
+          "next_poll_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "last_polled_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "last_error": {
+            "type": "string",
+            "nullable": true
+          },
+          "consecutive_errors": {
+            "type": "integer"
+          },
+          "events_emitted": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
           }
         }
       },
@@ -43512,6 +44038,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.28"
     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 }
@@ -14900,6 +15047,139 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/event-subscriptions:
+        post:
+            tags: [Connectors]
+            summary: Subscribe to a connector event source
+            description: |
+                Pairs an installed connector binding with one of its preset's event
+                sources (see `event_sources` on `GET /v1/connectors/presets`). 1Claw
+                then polls the source through the binding — same host and path
+                allowlists, same credential, same SSRF guard — keeps the item ids it has
+                seen, and dispatches each new item as an automation event of
+                `event_type`, so an automation with `trigger_type: event` and
+                `event_filter: { "event_type": "gmail.message.received" }` reacts within
+                one poll interval instead of on a cron it has to dedupe itself.
+
+                The first poll primes the subscription: it records what already exists
+                and emits nothing, so a new subscription does not replay the inbox. At
+                most 25 new items are emitted per poll (oldest first); lists come from
+                the source's first page only. Failures back off exponentially on the
+                interval and switch the subscription off after 20 in a row.
+
+                Human users only; the agent needs Execution Intents enabled. At most 20
+                subscriptions per agent. The event payload is
+                `{ "event_type", "payload": { "subscription_id", "binding_id", "binding", "connector", "item" } }`.
+            operationId: createEventSubscription
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [binding_id, event_type]
+                            properties:
+                                binding_id: { type: string, format: uuid }
+                                event_type: { type: string, example: gmail.message.received }
+                                interval_secs:
+                                    type: integer
+                                    description: Poll interval, at least the source's `min_interval_secs` and at most 86400. Defaults to the minimum.
+            responses:
+                "201":
+                    description: Subscribed
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EventSubscription"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    description: This binding already subscribes to that event type
+        get:
+            tags: [Connectors]
+            summary: List an agent's event subscriptions
+            operationId: listEventSubscriptions
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Subscriptions
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    subscriptions:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/EventSubscription"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/event-subscriptions/{id}:
+        delete:
+            tags: [Connectors]
+            summary: Delete an event subscription
+            description: Human users only.
+            operationId: deleteEventSubscription
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                "204":
+                    description: Deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/event-subscriptions/{id}/poll:
+        post:
+            tags: [Connectors]
+            summary: Poll an event subscription now
+            description: |
+                Runs one poll immediately instead of waiting for the interval. The first
+                poll of a fresh subscription primes it; a subscription switched off by
+                repeated failures is switched back on if the poll succeeds. Human users
+                only. A failed poll returns 400 with the source's error and is recorded
+                on the subscription like a scheduled failure.
+            operationId: pollEventSubscriptionNow
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                "200":
+                    description: Polled
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [emitted, subscription]
+                                properties:
+                                    emitted: { type: integer }
+                                    subscription:
+                                        $ref: "#/components/schemas/EventSubscription"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/agents/{agent_id}/oauth/connections:
         get:
             tags: [OAuth Connect]
@@ -20916,6 +21196,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: >-
@@ -25507,6 +25795,52 @@ components:
                 documentation_url: { type: string, format: uri }
                 tier_required: { type: string, example: free }
                 requires_oauth: { type: boolean }
+                event_sources:
+                    type: array
+                    description: |
+                        Events 1Claw can synthesise for this connector by polling a list
+                        endpoint through the installed binding (nanobots item 4, polling
+                        interim). Subscribe with `POST /v1/agents/{agent_id}/event-subscriptions`.
+                    items:
+                        $ref: "#/components/schemas/ConnectorEventSource"
+
+        ConnectorEventSource:
+            type: object
+            required: [event_type, description, path, items_pointer, id_pointers, min_interval_secs]
+            properties:
+                event_type: { type: string, example: gmail.message.received }
+                description: { type: string }
+                path:
+                    type: string
+                    description: Path (with query) relative to the binding's base URL, inside the preset's allowed paths.
+                items_pointer:
+                    type: string
+                    description: JSON pointer to the array of items in the response body; empty means the body is the array.
+                id_pointers:
+                    type: array
+                    items: { type: string }
+                    description: Pointers within one item whose values together identify it.
+                min_interval_secs: { type: integer, example: 60 }
+
+        EventSubscription:
+            type: object
+            required: [id, agent_id, binding_id, event_type, interval_secs, is_active, primed, next_poll_at, consecutive_errors, events_emitted, created_at]
+            properties:
+                id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                binding_id: { type: string, format: uuid }
+                event_type: { type: string, example: gmail.message.received }
+                interval_secs: { type: integer }
+                is_active: { type: boolean }
+                primed:
+                    type: boolean
+                    description: False until the first poll has recorded what already exists. That poll emits nothing.
+                next_poll_at: { type: string, format: date-time }
+                last_polled_at: { type: string, format: date-time, nullable: true }
+                last_error: { type: string, nullable: true }
+                consecutive_errors: { type: integer }
+                events_emitted: { type: integer, format: int64 }
+                created_at: { type: string, format: date-time }
 
         InstalledConnector:
             type: object
@@ -28213,6 +28547,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.28",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
   "license": "MIT",
   "repository": {