@1claw/openapi-spec 0.61.5 → 0.61.7

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.5",
+    "version": "0.61.7",
     "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"
@@ -25248,6 +25248,309 @@
         }
       }
     },
+    "/v1/org/settings/otel-export": {
+      "get": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "Read the org's OTLP export configuration",
+        "description": "Owner or admin, Team tier and above. Returns header *names* only — the values are the customer's collector credentials and never round-trip through the browser.",
+        "operationId": "get_otel_export_config",
+        "responses": {
+          "200": {
+            "description": "Current config, or null when unconfigured",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "nullable": true,
+                  "type": "object",
+                  "properties": {
+                    "enabled": {
+                      "type": "boolean"
+                    },
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "header_names": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "resource_attributes": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    },
+                    "signal_filter": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "spans",
+                          "metrics",
+                          "logs"
+                        ]
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "402": {
+            "description": "Requires the Team plan or higher"
+          },
+          "403": {
+            "description": "Not an owner or admin"
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "Update the org's OTLP export configuration",
+        "description": "Every field is optional and only present fields change. The endpoint is validated *and DNS-resolved* on save: HTTPS only, no embedded credentials, and refused if any resolved address is private, loopback, link-local, metadata or ULA. A URL that resolves to a private address is the SSRF, and it is refused here rather than left in the database looking configured.\n\n`headers` replaces the whole map when present and is encrypted at rest under the org's key. Omit it to change other fields without touching stored header values you cannot read back.\n\nTransport is OTLP over HTTP with JSON encoding, posted to `<endpoint>/v1/traces`, `/v1/metrics` and `/v1/logs`. What leaves is exactly what the org's own dashboard stream carries — signals already through the collector's redaction pass.",
+        "operationId": "patch_otel_export_config",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean"
+                  },
+                  "endpoint": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "HTTPS only."
+                  },
+                  "headers": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    },
+                    "description": "Sent on every export request, e.g. an Authorization header. Reserved hop-by-hop names are refused."
+                  },
+                  "resource_attributes": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  },
+                  "signal_filter": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "spans",
+                        "metrics",
+                        "logs"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated config, header names only"
+          },
+          "400": {
+            "description": "Endpoint refused (scheme",
+            "credentials": null,
+            "private or unresolvable host)": null,
+            "reserved header": null,
+            "or enabling with no endpoint": null
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "402": {
+            "description": "Requires the Team plan or higher"
+          },
+          "403": {
+            "description": "Not an owner or admin"
+          }
+        }
+      }
+    },
+    "/v1/org/settings/otel-export/test": {
+      "post": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "Send one synthetic span to the configured endpoint",
+        "description": "Re-resolves the endpoint at send time and pins the connection to the resolved address, with redirects disabled. Rate-limited to 5 per minute per org: even a validated endpoint is an outbound request the caller chose the target of.",
+        "operationId": "test_otel_export",
+        "responses": {
+          "200": {
+            "description": "The collector's HTTP status for the probe",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "status": {
+                      "type": "integer"
+                    },
+                    "ok": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Not configured",
+            "or the send failed": null
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "402": {
+            "description": "Requires the Team plan or higher"
+          },
+          "403": {
+            "description": "Not an owner or admin"
+          },
+          "429": {
+            "description": "More than 5 test sends this minute"
+          }
+        }
+      }
+    },
+    "/v1/otel/metrics": {
+      "get": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "Time-bucketed rollups from durable tables",
+        "description": "Volume, denials and latency over a window. Sourced from durable tables, never from in-process counters: an in-memory histogram is per-replica and resets on deploy, so a 24h chart drawn from one disagrees between instances and is wrong after every release.\n\nEvery bucket in the range is returned, including empty ones. A quiet hour is a zero, not a missing point — a line chart given a hole joins across it as though nothing happened.\n\n`step` may be widened from what was requested when the window would otherwise produce more than 500 buckets. The response echoes the window and step actually used, so a chart can label its own resolution rather than the one it asked for.",
+        "operationId": "get_otel_metrics",
+        "parameters": [
+          {
+            "name": "window",
+            "in": "query",
+            "required": false,
+            "description": "Lookback, e.g. `30m`, `24h`, `7d`. Default 24h, maximum 30d.",
+            "schema": {
+              "type": "string",
+              "default": "24h"
+            }
+          },
+          {
+            "name": "step",
+            "in": "query",
+            "required": false,
+            "description": "Bucket width. Defaults to a twenty-fourth of the window, minimum 60s.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Bucketed metrics",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "window",
+                    "buckets",
+                    "total_executions",
+                    "total_denials"
+                  ],
+                  "properties": {
+                    "window": {
+                      "type": "object",
+                      "description": "The window and step actually used.",
+                      "properties": {
+                        "window_secs": {
+                          "type": "integer"
+                        },
+                        "step_secs": {
+                          "type": "integer"
+                        }
+                      }
+                    },
+                    "buckets": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "t",
+                          "executions",
+                          "denials",
+                          "transactions",
+                          "llm_calls"
+                        ],
+                        "properties": {
+                          "t": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "executions": {
+                            "type": "integer"
+                          },
+                          "denials": {
+                            "type": "integer"
+                          },
+                          "transactions": {
+                            "type": "integer"
+                          },
+                          "llm_calls": {
+                            "type": "integer"
+                          }
+                        }
+                      }
+                    },
+                    "latency_p50_ms": {
+                      "type": "number",
+                      "nullable": true,
+                      "description": "Null when nothing in the window recorded a duration."
+                    },
+                    "latency_p95_ms": {
+                      "type": "number",
+                      "nullable": true
+                    },
+                    "total_executions": {
+                      "type": "integer"
+                    },
+                    "total_denials": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Unparseable window or step, window over 30d, or step larger than window"
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Not a human user"
+          }
+        }
+      }
+    },
     "/v1/otel/summary": {
       "get": {
         "tags": [
@@ -25383,6 +25686,12 @@
                               "suspended",
                               "ok"
                             ]
+                          },
+                          "trust": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "maximum": 100,
+                            "description": "Agents only. Absent until the trust engine has scored the agent."
                           }
                         }
                       }

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.5"
+    version: "0.61.7"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -16230,6 +16230,178 @@ paths:
                     description: Unauthenticated
                 '403':
                     description: Not a human user
+    /v1/org/settings/otel-export:
+        get:
+            tags: [Observability]
+            summary: "Read the org's OTLP export configuration"
+            description: >-
+                Owner or admin, Team tier and above. Returns header *names*
+                only — the values are the customer's collector credentials and
+                never round-trip through the browser.
+            operationId: get_otel_export_config
+            responses:
+                '200':
+                    description: Current config, or null when unconfigured
+                    content:
+                        application/json:
+                            schema:
+                                nullable: true
+                                type: object
+                                properties:
+                                    enabled: { type: boolean }
+                                    endpoint: { type: string }
+                                    header_names: { type: array, items: { type: string } }
+                                    resource_attributes: { type: object, additionalProperties: { type: string } }
+                                    signal_filter:
+                                        type: array
+                                        items: { type: string, enum: [spans, metrics, logs] }
+                '401': { description: Unauthenticated }
+                '402': { description: Requires the Team plan or higher }
+                '403': { description: Not an owner or admin }
+        patch:
+            tags: [Observability]
+            summary: "Update the org's OTLP export configuration"
+            description: >-
+                Every field is optional and only present fields change. The
+                endpoint is validated *and DNS-resolved* on save: HTTPS only, no
+                embedded credentials, and refused if any resolved address is
+                private, loopback, link-local, metadata or ULA. A URL that
+                resolves to a private address is the SSRF, and it is refused
+                here rather than left in the database looking configured.
+
+
+                `headers` replaces the whole map when present and is encrypted
+                at rest under the org's key. Omit it to change other fields
+                without touching stored header values you cannot read back.
+
+
+                Transport is OTLP over HTTP with JSON encoding, posted to
+                `<endpoint>/v1/traces`, `/v1/metrics` and `/v1/logs`. What
+                leaves is exactly what the org's own dashboard stream carries —
+                signals already through the collector's redaction pass.
+            operationId: patch_otel_export_config
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                enabled: { type: boolean }
+                                endpoint: { type: string, format: uri, description: "HTTPS only." }
+                                headers:
+                                    type: object
+                                    additionalProperties: { type: string }
+                                    description: "Sent on every export request, e.g. an Authorization header. Reserved hop-by-hop names are refused."
+                                resource_attributes: { type: object, additionalProperties: { type: string } }
+                                signal_filter:
+                                    type: array
+                                    minItems: 1
+                                    items: { type: string, enum: [spans, metrics, logs] }
+            responses:
+                '200':
+                    description: The updated config, header names only
+                '400': { description: Endpoint refused (scheme, credentials, private or unresolvable host), reserved header, or enabling with no endpoint }
+                '401': { description: Unauthenticated }
+                '402': { description: Requires the Team plan or higher }
+                '403': { description: Not an owner or admin }
+    /v1/org/settings/otel-export/test:
+        post:
+            tags: [Observability]
+            summary: "Send one synthetic span to the configured endpoint"
+            description: >-
+                Re-resolves the endpoint at send time and pins the connection to
+                the resolved address, with redirects disabled. Rate-limited to 5
+                per minute per org: even a validated endpoint is an outbound
+                request the caller chose the target of.
+            operationId: test_otel_export
+            responses:
+                '200':
+                    description: The collector's HTTP status for the probe
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    endpoint: { type: string }
+                                    status: { type: integer }
+                                    ok: { type: boolean }
+                '400': { description: Not configured, or the send failed }
+                '401': { description: Unauthenticated }
+                '402': { description: Requires the Team plan or higher }
+                '403': { description: Not an owner or admin }
+                '429': { description: More than 5 test sends this minute }
+    /v1/otel/metrics:
+        get:
+            tags: [Observability]
+            summary: "Time-bucketed rollups from durable tables"
+            description: >-
+                Volume, denials and latency over a window. Sourced from durable
+                tables, never from in-process counters: an in-memory histogram
+                is per-replica and resets on deploy, so a 24h chart drawn from
+                one disagrees between instances and is wrong after every
+                release.
+
+
+                Every bucket in the range is returned, including empty ones. A
+                quiet hour is a zero, not a missing point — a line chart given a
+                hole joins across it as though nothing happened.
+
+
+                `step` may be widened from what was requested when the window
+                would otherwise produce more than 500 buckets. The response
+                echoes the window and step actually used, so a chart can label
+                its own resolution rather than the one it asked for.
+            operationId: get_otel_metrics
+            parameters:
+                - name: window
+                  in: query
+                  required: false
+                  description: "Lookback, e.g. `30m`, `24h`, `7d`. Default 24h, maximum 30d."
+                  schema: { type: string, default: "24h" }
+                - name: step
+                  in: query
+                  required: false
+                  description: "Bucket width. Defaults to a twenty-fourth of the window, minimum 60s."
+                  schema: { type: string }
+            responses:
+                '200':
+                    description: Bucketed metrics
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [window, buckets, total_executions, total_denials]
+                                properties:
+                                    window:
+                                        type: object
+                                        description: The window and step actually used.
+                                        properties:
+                                            window_secs: { type: integer }
+                                            step_secs: { type: integer }
+                                    buckets:
+                                        type: array
+                                        items:
+                                            type: object
+                                            required: [t, executions, denials, transactions, llm_calls]
+                                            properties:
+                                                t: { type: string, format: date-time }
+                                                executions: { type: integer }
+                                                denials: { type: integer }
+                                                transactions: { type: integer }
+                                                llm_calls: { type: integer }
+                                    latency_p50_ms:
+                                        type: number
+                                        nullable: true
+                                        description: Null when nothing in the window recorded a duration.
+                                    latency_p95_ms: { type: number, nullable: true }
+                                    total_executions: { type: integer }
+                                    total_denials: { type: integer }
+                '400':
+                    description: Unparseable window or step, window over 30d, or step larger than window
+                '401':
+                    description: Unauthenticated
+                '403':
+                    description: Not a human user
     /v1/otel/summary:
         get:
             tags: [Observability]
@@ -16330,6 +16502,11 @@ paths:
                                                     type: string
                                                     description: Agents only. Derived, not stored.
                                                     enum: [compromised, warn, suspended, ok]
+                                                trust:
+                                                    type: integer
+                                                    minimum: 0
+                                                    maximum: 100
+                                                    description: Agents only. Absent until the trust engine has scored the agent.
                                     edges:
                                         type: array
                                         items:

package/package.json

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