Skip to content

Latest commit

 

History

History
104 lines (89 loc) · 6.81 KB

api.md

File metadata and controls

104 lines (89 loc) · 6.81 KB

API overview

The versioned OpenAPI document is the contract source. This page summarizes the current routes; consult the contract for request schemas and the full route list.

For the domain model, read core concepts. For a runnable sequence, follow Getting started.

API surfaces and credentials

Management routes use /api/v1alpha1; machine evaluation routes use /runtime/v1alpha1. The policy document's guardrail.open/v1alpha1 is the GuardrailSpec format identifier, not an HTTP path.

Caller Credential Access
Administrator Browser or CLI administrator session Manage Scenes, Policies and keys; inspect management Run views
Orchestrator Project key with effective endpoint scopes Create/read Runs and rotate an open Run's Submission Credential
Policy publisher Project key with publication scopes Create Policies and publish Revisions; no administrator Draft or activation access
Evaluator Submission Credential bound to one Run Submit complete intermediate or final Snapshots to that Run

Scopes are checked on the server. A Run credential cannot use the Run, Revision or Submission readers; a Project key cannot submit an assessment. See credential management and Run recovery.

CLI transport

open-guardrail serve starts the service; guardrailctl calls an existing service:

guardrailctl --server http://127.0.0.1:8080 status
guardrailctl --server https://guardrail.example.com version

The CLI also accepts OPEN_GUARDRAIL_URL and OPEN_GUARDRAIL_TOKEN. It uses the client generated from the published OpenAPI contract, and management commands verify the server's API/CLI compatibility window before sending credentials or changing state. Stable automation exit codes are documented in the CLI guide. Diagnostic commands only attach the optional token over HTTPS and never follow redirects; the public diagnostic endpoints do not require it. Identity and Run commands use explicit credential files and allow plain HTTP only for literal loopback addresses. Every HTTP response includes a server-generated X-Trace-ID. Error responses repeat that value as traceId so operators can correlate a CLI failure without exposing database or credential details.

Current endpoint summary

Endpoint Purpose
GET /livez Process liveness, independent of database availability
GET /readyz Database connection readiness; 503 on failure
GET /api/v1alpha1/meta/version Public product version; never includes commit metadata
GET /api/v1alpha1/meta/capabilities API/CLI compatibility, features and non-sensitive storage operating envelope
GET /openapi.yaml Public OpenAPI contract
GET /runtime/v1alpha1/identity Project machine identity, role and effective scopes
GET/POST /api/v1alpha1/auth/api-keys List secret-free key metadata or issue an expiring Project key
DELETE /api/v1alpha1/auth/api-keys/{keyId} Revoke a Project key using an administrator session
POST /api/v1alpha1/auth/api-keys/{keyId}/rotation Replace an active key secret using its current version
POST /runtime/v1alpha1/runs Create an immutable Run using a Project key and Idempotency-Key
GET /runtime/v1alpha1/runs List Runs in the authenticated Project
POST /runtime/v1alpha1/runs/{runId}/submission-credential:rotate Replace an open Run's Submission Credential using its Project key
POST /runtime/v1alpha1/runs/{runId}/submissions Submit a complete intermediate or final Snapshot using the bound Run credential
GET /runtime/v1alpha1/runs/{runId} Query a Run in the authenticated Project
GET /runtime/v1alpha1/runs/{runId}/policy-revision Read the immutable Policy Revision selected by a Run
GET /runtime/v1alpha1/runs/{runId}/submissions/{submissionId} Read a persisted Submission and its complete Snapshot within a Run
GET /api/v1alpha1/audit-events Administrator audit query with filters, cursor pagination and optional redaction
GET /api/v1alpha1/runs/{runId}/report Administrator diagnostic report
GET /runtime/v1alpha1/runs/{runId}/report Diagnostic report using a Project key with runs:read
GET /api/v1alpha1/runs List Runs for the authenticated administrator's read-only management view
GET /api/v1alpha1/runs/{runId} Inspect one Run from the management view
POST /api/v1alpha1/scenes/{key}:initialize Atomically create Scene, default Policy and Revision 1
GET /api/v1alpha1/scenes/{key}/bindings List exact resource bindings with limit/after pagination
PUT /api/v1alpha1/scenes/{key}/bindings/{kind}/{resourceId} Idempotently create/replace a binding; optional published Revision pin
DELETE /api/v1alpha1/scenes/{key}/bindings/{kind}/{resourceId} Remove a binding; absent bindings return 204
POST /api/v1alpha1/scenes/{key}/policies Create another Policy
GET /api/v1alpha1/policies/{policyId}/draft Read the current Draft Revision, or 404 when absent
PUT /api/v1alpha1/policies/{policyId}/draft Save and return the Draft Revision
POST /api/v1alpha1/policies/{policyId}/draft:publish Publish the reviewed Draft as the same Revision
POST /api/v1alpha1/policies/{policyId}/revisions Publish a Revision directly
GET /api/v1alpha1/policies/{policyId}/revisions?pageSize=20 Page through Revision summaries; follow nextBefore and fetch YAML by ID
PUT /api/v1alpha1/policies/{policyId}/active-revision Activate a Revision
GET / Embedded management shell

Run creation and Submission require Idempotency-Key; retry the same logical operation with the same key and content. Read the Run's finalSubmissionId, then use the Submission reader to inspect accepted evidence. A FINISHED Run exposes its Result, Decision and decisionExpiresAt; callers must also verify the evidence and evaluation identity they rely on. Execution Claims and ActionResults remain planned. See Runs and submissions for the full lifecycle.

Binding management uses existing administrator sessions and the write CSRF header. Encode resource IDs in paths, including slash. Run resources are trusted inputs and cannot be combined with an explicit Revision override. Optional selection evidence is recorded only for matched bindings; default/explicit paths omit it. Use guardrailctl binding list|put|delete with an administrator session and guardrailctl run create --resources FILE with a Project key. See the CLI walkthrough and the contract and trust boundaries.

See audit and report exports for privacy boundaries and bounded history.