OpenAPI Specification¶

Machine-readable API contract for the AEGIS Governance Lambda HTTP endpoint.

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 Lambda function, including request/response schemas, parameter validation rules, and error formats.

Endpoints Summary¶

The AEGIS Lambda function (behind API Gateway) 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: API Gateway uses IAM authorization. Requests must be signed with AWS Signature Version 4.

Using with curl¶

# Evaluate a proposal (requires AWS credentials)
aws lambda invoke \
  --function-name aegis-evaluate-proposal-dev \
  --payload '{
    "httpMethod": "POST",
    "path": "/evaluate",
    "body": "{\"proposal_summary\":\"Test proposal\",\"estimated_impact\":\"medium\",\"risk_proposed\":0.2}"
  }' \
  --cli-binary-format raw-in-base64-out \
  /tmp/response.json

cat /tmp/response.json | python3 -c "import json,sys; print(json.dumps(json.loads(json.load(sys.stdin)['body']), indent=2))"

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.