OpenAPI Specification

Machine-readable API contract for the AEGIS Governance REST API.

Specification File

The full OpenAPI 3.0 specification is available at:

• openapi.yaml (this directory)

This YAML file defines the complete HTTP API contract for the AEGIS Cloud Run API, including request/response schemas, parameter validation rules, and error formats.

Endpoints Summary

The AEGIS Cloud Run API exposes the following routes:

POST /evaluate

Full governance gate evaluation. Accepts a proposal payload and returns a structured decision with per-gate results, rationale, and next steps.

Request body: JSON object with proposal_summary, estimated_impact, and optional metrics (risk, profit, novelty, complexity, quality scores).

Response: JSON object with status (proceed/pause/halt/escalate), confidence, gates, rationale, next_steps, and audit fields.

POST /risk-check

Simplified risk threshold check. Returns whether the risk score is below a configurable threshold.

GET /health

Returns service health status and configuration details.

Interactive Documentation

To explore the API interactively, you can use the OpenAPI spec with:

Swagger UI

# Using Docker
docker run -p 8081:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v $(pwd)/docs/api:/spec \
  swaggerapi/swagger-ui

# Then open http://localhost:8081

Redoc

# Using npx
npx @redocly/cli preview-docs docs/api/openapi.yaml

# Or via Docker
docker run -p 8082:80 \
  -v $(pwd)/docs/api/openapi.yaml:/usr/share/nginx/html/openapi.yaml \
  -e SPEC_URL=openapi.yaml \
  redocly/redoc

Stoplight Studio

Import docs/api/openapi.yaml into Stoplight Studio for a visual API editor.

Live Endpoints

Authentication: All endpoints except /health require an API key passed as a Bearer token in the Authorization header (Unkey-verified).

Using with curl

curl -s -X POST \
  https://aegis-api-980022636831.us-central1.run.app/evaluate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "proposal_summary": "Test proposal",
    "estimated_impact": "medium",
    "risk_proposed": 0.2
  }' | python3 -m json.tool

Schema Validation

The OpenAPI spec can be used for request/response validation in client libraries:

# Example: validate a request payload against the spec
# (requires openapi-core or similar library)
from openapi_core import OpenAPI

api = OpenAPI.from_file_path("docs/api/openapi.yaml")
# Use api.validate_request() and api.validate_response()

Relationship to Other Interfaces

The AEGIS governance engine is accessible through four interfaces, all backed by the same pcw_decide() core:

All interfaces enforce the same six gates, use the same frozen parameters from schema/interface-contract.yaml, and produce the same decision structure.