@1claw/openapi-spec 0.61.8 → 0.61.10

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.8",
+    "version": "0.61.10",
     "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"
@@ -24669,6 +24669,201 @@
         }
       }
     },
+    "/v1/platform/connections/{connection_id}/otel/topology": {
+      "get": {
+        "tags": [
+          "Platform",
+          "Observability"
+        ],
+        "summary": "Topology for one connection's agents",
+        "description": "The same graph as `/v1/otel/topology`, restricted to what this connection's agents reach: the agents, the policies they hold, the vaults those grant, the chains they sign on and the systems they call. Restricted before the 500-node cap, so a large org's cap cannot cut the connection's own agents out. Walking is directed (agent → policy → vault), so a vault shared with another tenant's agent does not reveal that agent.\n\nA `plt_` key sees one connection's agents, never the end-user's org: that org may hold agents from other platforms or the user's own. The set is agents attributed to the connection plus the ones listed on it, constrained to the connection's org. A connection that does not belong to the calling app is a 404.",
+        "operationId": "get_platform_connection_otel_topology",
+        "parameters": [
+          {
+            "name": "connection_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Nodes and edges reachable from the connection's agents",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/paths/~1v1~1otel~1topology/get/responses/200/content/application~1json/schema"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Not a plt_ key"
+          },
+          "404": {
+            "description": "Connection not found for this app"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connection_id}/otel/threats": {
+      "get": {
+        "tags": [
+          "Platform",
+          "Observability"
+        ],
+        "summary": "Open threats on one connection's agents",
+        "description": "`/v1/otel/threats` filtered to the connection's agents, same ranking (blast radius, then recency).\n\nA `plt_` key sees one connection's agents, never the end-user's org: that org may hold agents from other platforms or the user's own. The set is agents attributed to the connection plus the ones listed on it, constrained to the connection's org. A connection that does not belong to the calling app is a 404.",
+        "operationId": "get_platform_connection_otel_threats",
+        "parameters": [
+          {
+            "name": "connection_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "state",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "open",
+                "all"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Threats on the connection's agents, highest blast radius first",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/paths/~1v1~1otel~1threats/get/responses/200/content/application~1json/schema"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Not a plt_ key"
+          },
+          "404": {
+            "description": "Connection not found for this app"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connection_id}/otel/summary": {
+      "get": {
+        "tags": [
+          "Platform",
+          "Observability"
+        ],
+        "summary": "Posture score and counts for one connection's agents",
+        "description": "`/v1/otel/summary` over a smaller world: the posture score uses the connection's agents' trust scores and the resources they reach; threat and pending-approval counts are the connection's agents' only.\n\nA `plt_` key sees one connection's agents, never the end-user's org: that org may hold agents from other platforms or the user's own. The set is agents attributed to the connection plus the ones listed on it, constrained to the connection's org. A connection that does not belong to the calling app is a 404.",
+        "operationId": "get_platform_connection_otel_summary",
+        "parameters": [
+          {
+            "name": "connection_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Posture and counts for the connection",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/paths/~1v1~1otel~1summary/get/responses/200/content/application~1json/schema"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Not a plt_ key"
+          },
+          "404": {
+            "description": "Connection not found for this app"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connection_id}/otel/stream": {
+      "get": {
+        "tags": [
+          "Platform",
+          "Observability"
+        ],
+        "summary": "Live signal stream for one connection's agents (SSE)",
+        "description": "The same protocol as `/v1/otel/stream` — `Last-Event-ID` resume, `event: gap` on a stale cursor or a lagged subscriber — filtered to signals whose agent is one of the connection's. Signals with no agent (a human's own dashboard actions) are never emitted here. The agent set is fixed at connect time; an agent added later appears on the next connect.\n\nStream slots are counted per platform app (five), not per connection.\n\nA `plt_` key sees one connection's agents, never the end-user's org: that org may hold agents from other platforms or the user's own. The set is agents attributed to the connection plus the ones listed on it, constrained to the connection's org. A connection that does not belong to the calling app is a 404.",
+        "operationId": "get_platform_connection_otel_stream",
+        "parameters": [
+          {
+            "name": "connection_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "Last-Event-ID",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "text/event-stream",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Not a plt_ key"
+          },
+          "404": {
+            "description": "Connection not found for this app"
+          },
+          "429": {
+            "description": "Stream slot cap for this app reached"
+          }
+        }
+      }
+    },
     "/v1/platform/connections/{connection_id}/resources": {
       "parameters": [
         {
@@ -25551,6 +25746,154 @@
         }
       }
     },
+    "/v1/otel/agents/{agent_id}/trust": {
+      "get": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "The breakdown behind one agent's trust score",
+        "description": "The topology carries a single 0-100 trust number per agent. This is what it is made of: each weighted component (`null` when this deployment has no source for it — not measured, not zero), a 24-hour history for a sparkline, and the agent's last audit actions. Actions and resource types only; audit `metadata` is where secret paths live and it is not returned.\n\nScores are `shadow` until the engine is promoted out of recommend-only mode; an agent the engine has not yet reached returns `score: null` and `shadow: true`.\n\nHuman users only. An agent id outside the caller's org is a 404, not a 403, so the response does not confirm the id exists.",
+        "operationId": "get_otel_agent_trust",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Current score, components, history, recent actions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "agent_id",
+                    "shadow",
+                    "components",
+                    "history",
+                    "recent"
+                  ],
+                  "properties": {
+                    "agent_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "score": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 100,
+                      "nullable": true
+                    },
+                    "shadow": {
+                      "type": "boolean",
+                      "description": "True while the engine is recommend-only or the agent is unscored."
+                    },
+                    "updated_at": {
+                      "type": "string",
+                      "format": "date-time",
+                      "nullable": true
+                    },
+                    "components": {
+                      "type": "object",
+                      "description": "0-100 per component; null means no source in this deployment.",
+                      "properties": {
+                        "denial_rate": {
+                          "type": "integer",
+                          "nullable": true
+                        },
+                        "threat_hits": {
+                          "type": "integer",
+                          "nullable": true
+                        },
+                        "egress_blocks": {
+                          "type": "integer",
+                          "nullable": true
+                        },
+                        "spend_velocity": {
+                          "type": "integer",
+                          "nullable": true
+                        },
+                        "off_hours": {
+                          "type": "integer",
+                          "nullable": true
+                        },
+                        "consensus_bypass": {
+                          "type": "integer",
+                          "nullable": true
+                        }
+                      }
+                    },
+                    "history": {
+                      "type": "array",
+                      "maxItems": 96,
+                      "description": "Oldest first, last 24 hours.",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "at",
+                          "score"
+                        ],
+                        "properties": {
+                          "at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "score": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "maximum": 100
+                          }
+                        }
+                      }
+                    },
+                    "recent": {
+                      "type": "array",
+                      "maxItems": 12,
+                      "description": "Newest first.",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "at",
+                          "action"
+                        ],
+                        "properties": {
+                          "at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "action": {
+                            "type": "string"
+                          },
+                          "resource_type": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Not a human user"
+          },
+          "404": {
+            "description": "No such agent in the caller's organization"
+          }
+        }
+      }
+    },
     "/v1/otel/flows": {
       "get": {
         "tags": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.8"
+    version: "0.61.10"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -15877,6 +15877,151 @@ paths:
                     description: Forbidden, or the plan does not include this
                 '404':
                     description: Not found
+    /v1/platform/connections/{connection_id}/otel/topology:
+        get:
+            tags: [Platform, Observability]
+            summary: "Topology for one connection's agents"
+            description: >-
+                The same graph as `/v1/otel/topology`, restricted to what this
+                connection's agents reach: the agents, the policies they hold,
+                the vaults those grant, the chains they sign on and the systems
+                they call. Restricted before the 500-node cap, so a large org's
+                cap cannot cut the connection's own agents out. Walking is
+                directed (agent → policy → vault), so a vault shared with
+                another tenant's agent does not reveal that agent.
+
+
+                A `plt_` key sees one connection's agents, never the end-user's org:
+                that org may hold agents from other platforms or the user's
+                own. The set is agents attributed to the connection plus the
+                ones listed on it, constrained to the connection's org. A
+                connection that does not belong to the calling app is a 404.
+            operationId: get_platform_connection_otel_topology
+            parameters:
+                - name: connection_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: Nodes and edges reachable from the connection's agents
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/paths/~1v1~1otel~1topology/get/responses/200/content/application~1json/schema'
+                '401': { description: Unauthenticated }
+                '403': { description: Not a plt_ key }
+                '404': { description: Connection not found for this app }
+    /v1/platform/connections/{connection_id}/otel/threats:
+        get:
+            tags: [Platform, Observability]
+            summary: "Open threats on one connection's agents"
+            description: >-
+                `/v1/otel/threats` filtered to the connection's agents, same
+                ranking (blast radius, then recency).
+
+
+                A `plt_` key sees one connection's agents, never the end-user's org:
+                that org may hold agents from other platforms or the user's
+                own. The set is agents attributed to the connection plus the
+                ones listed on it, constrained to the connection's org. A
+                connection that does not belong to the calling app is a 404.
+            operationId: get_platform_connection_otel_threats
+            parameters:
+                - name: connection_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+                - name: state
+                  in: query
+                  required: false
+                  schema:
+                      type: string
+                      enum: [open, all]
+            responses:
+                '200':
+                    description: Threats on the connection's agents, highest blast radius first
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/paths/~1v1~1otel~1threats/get/responses/200/content/application~1json/schema'
+                '401': { description: Unauthenticated }
+                '403': { description: Not a plt_ key }
+                '404': { description: Connection not found for this app }
+    /v1/platform/connections/{connection_id}/otel/summary:
+        get:
+            tags: [Platform, Observability]
+            summary: "Posture score and counts for one connection's agents"
+            description: >-
+                `/v1/otel/summary` over a smaller world: the posture score uses
+                the connection's agents' trust scores and the resources they
+                reach; threat and pending-approval counts are the connection's
+                agents' only.
+
+
+                A `plt_` key sees one connection's agents, never the end-user's org:
+                that org may hold agents from other platforms or the user's
+                own. The set is agents attributed to the connection plus the
+                ones listed on it, constrained to the connection's org. A
+                connection that does not belong to the calling app is a 404.
+            operationId: get_platform_connection_otel_summary
+            parameters:
+                - name: connection_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: Posture and counts for the connection
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/paths/~1v1~1otel~1summary/get/responses/200/content/application~1json/schema'
+                '401': { description: Unauthenticated }
+                '403': { description: Not a plt_ key }
+                '404': { description: Connection not found for this app }
+    /v1/platform/connections/{connection_id}/otel/stream:
+        get:
+            tags: [Platform, Observability]
+            summary: "Live signal stream for one connection's agents (SSE)"
+            description: >-
+                The same protocol as `/v1/otel/stream` — `Last-Event-ID` resume,
+                `event: gap` on a stale cursor or a lagged subscriber — filtered
+                to signals whose agent is one of the connection's. Signals with
+                no agent (a human's own dashboard actions) are never emitted
+                here. The agent set is fixed at connect time; an agent added
+                later appears on the next connect.
+
+
+                Stream slots are counted per platform app (five), not per
+                connection.
+
+
+                A `plt_` key sees one connection's agents, never the end-user's org:
+                that org may hold agents from other platforms or the user's
+                own. The set is agents attributed to the connection plus the
+                ones listed on it, constrained to the connection's org. A
+                connection that does not belong to the calling app is a 404.
+            operationId: get_platform_connection_otel_stream
+            parameters:
+                - name: connection_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+                - name: Last-Event-ID
+                  in: header
+                  required: false
+                  schema: { type: string }
+            responses:
+                '200':
+                    description: text/event-stream
+                    content:
+                        text/event-stream:
+                            schema: { type: string }
+                '401': { description: Unauthenticated }
+                '403': { description: Not a plt_ key }
+                '404': { description: Connection not found for this app }
+                '429': { description: Stream slot cap for this app reached }
     /v1/platform/connections/{connection_id}/resources:
         parameters:
             - name: connection_id
@@ -16402,6 +16547,79 @@ paths:
                     description: Unauthenticated
                 '403':
                     description: Not a human user
+    /v1/otel/agents/{agent_id}/trust:
+        get:
+            tags: [Observability]
+            summary: "The breakdown behind one agent's trust score"
+            description: >-
+                The topology carries a single 0-100 trust number per agent.
+                This is what it is made of: each weighted component (`null`
+                when this deployment has no source for it — not measured, not
+                zero), a 24-hour history for a sparkline, and the agent's last
+                audit actions. Actions and resource types only; audit
+                `metadata` is where secret paths live and it is not returned.
+
+
+                Scores are `shadow` until the engine is promoted out of
+                recommend-only mode; an agent the engine has not yet reached
+                returns `score: null` and `shadow: true`.
+
+
+                Human users only. An agent id outside the caller's org is a
+                404, not a 403, so the response does not confirm the id exists.
+            operationId: get_otel_agent_trust
+            parameters:
+                - name: agent_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: Current score, components, history, recent actions
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [agent_id, shadow, components, history, recent]
+                                properties:
+                                    agent_id: { type: string, format: uuid }
+                                    score: { type: integer, minimum: 0, maximum: 100, nullable: true }
+                                    shadow: { type: boolean, description: "True while the engine is recommend-only or the agent is unscored." }
+                                    updated_at: { type: string, format: date-time, nullable: true }
+                                    components:
+                                        type: object
+                                        description: "0-100 per component; null means no source in this deployment."
+                                        properties:
+                                            denial_rate: { type: integer, nullable: true }
+                                            threat_hits: { type: integer, nullable: true }
+                                            egress_blocks: { type: integer, nullable: true }
+                                            spend_velocity: { type: integer, nullable: true }
+                                            off_hours: { type: integer, nullable: true }
+                                            consensus_bypass: { type: integer, nullable: true }
+                                    history:
+                                        type: array
+                                        maxItems: 96
+                                        description: "Oldest first, last 24 hours."
+                                        items:
+                                            type: object
+                                            required: [at, score]
+                                            properties:
+                                                at: { type: string, format: date-time }
+                                                score: { type: integer, minimum: 0, maximum: 100 }
+                                    recent:
+                                        type: array
+                                        maxItems: 12
+                                        description: "Newest first."
+                                        items:
+                                            type: object
+                                            required: [at, action]
+                                            properties:
+                                                at: { type: string, format: date-time }
+                                                action: { type: string }
+                                                resource_type: { type: string, nullable: true }
+                '401': { description: Unauthenticated }
+                '403': { description: Not a human user }
+                '404': { description: No such agent in the caller's organization }
     /v1/otel/flows:
         get:
             tags: [Observability]

package/package.json

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