API Usage¶

Prerequisite: Before using the Aegis API, you must create an API token. See API Tokens for instructions on creating and managing tokens.

The Aegis Platform provides a comprehensive RESTful API that allows you to programmatically interact with all aspects of the system. This guide provides information on how to use the Aegis API effectively.

Base URL¶

All API endpoints are relative to your Aegis instance URL:

https://<your-instance>.aegis.pegasys.cloud/

Authentication¶

All API requests require authentication. Aegis uses Bearer Token authentication. Include your token in the Authorization header:

Authorization: Bearer <your_token>

See the Authentication page for details on obtaining and managing tokens. For instructions on creating and managing API tokens, see API Tokens.

Content Types¶

The Aegis API supports the following content types:

JSON: application/json - Used for most requests and responses
YAML: application/x-yaml - Used for some configuration endpoints

Specify the content type in your request headers:

Content-Type: application/json

Available APIs¶

Aegis provides the following API categories:

API	Description
Authentication	User authentication and token management
API Tokens	Create and manage API authentication tokens
Rulesets	Create collections of rules
Policies	Apply rulesets to resources
Eval	Evaluate resources against policies and rulesets
Audit	Access policy evaluation audit records
Timeseries	Analyze time-based metrics and events
Remediations	Manage remediation guidance
Labels	List available labels for policies and rulesets
Hints	Get AI-powered hints for policy and ruleset creation
Recommendations	Get intelligent recommendations for improvements
Prompt Validation	Validate prompts before using them to create resources
Sample Data	Generate sample data for testing and development

API Versioning¶

The API version is embedded in the response headers. The current version can be retrieved from:

GET /version

Error Handling¶

Aegis uses standard HTTP status codes:

200 OK: Request succeeded
201 Created: Resource was successfully created
400 Bad Request: Invalid request format or parameters
401 Unauthorized: Authentication required or failed
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
409 Conflict: Request conflicts with current state
500 Internal Server Error: Server error

Error responses include a JSON body with details:

{
  "error": "Invalid request parameters",
  "details": "Missing required field: name"
}

Examples¶

Evaluating a Kubernetes Deployment Against a Policy¶

curl -X POST https://<your-instance>.aegis.pegasys.cloud/api/eval/policies/demo \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputData": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "nginx",
        "namespace": "kube-app",
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "replicas": 1
      }
    }
  }'

Creating a New Ruleset¶

curl -X POST https://<your-instance>.aegis.pegasys.cloud/api/rulesets/security-baseline \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/x-yaml" \
  -d 'instruction: "create ruleset for kubernetes deployment with rules that check for resource limits and security context"
labels:
  platform: kubernetes
  resource: deployment'

Additional API Endpoints¶

Get Policy Labels¶

curl -X GET https://<your-instance>.aegis.pegasys.cloud/api/labels/policies \
  -H "Authorization: Bearer <your_token>"

Get Ruleset Labels¶

curl -X GET https://<your-instance>.aegis.pegasys.cloud/api/labels/rulesets \
  -H "Authorization: Bearer <your_token>"

Get Policy Hints¶

curl -X POST https://<your-instance>.aegis.pegasys.cloud/api/hints/policy \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"instruction": "validate kubernetes deployments"}'

Get Ruleset Hints¶

curl -X POST https://<your-instance>.aegis.pegasys.cloud/api/hints/ruleset \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"instruction": "security rules for containers"}'

Validate Prompt¶

curl -X POST https://<your-instance>.aegis.pegasys.cloud/api/prompt \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"instruction": "create security rules"}'

Generate Sample Data¶

curl -X POST https://<your-instance>.aegis.pegasys.cloud/api/samples \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"instruction": "kubernetes deployment manifest", "category": "kubernetes", "type": "deployment"}'

Rate Limiting¶

API requests are subject to rate limiting to ensure fair usage and system stability. If you exceed the rate limit, you'll receive a 429 Too Many Requests response.