Policies API

Policies apply rulesets to specific resources or environments in Aegis. This API allows you to manage policies.

Endpoints

List Policies

Retrieve a list of policies that match the specified name pattern.

GET /api/policies/{policy_name}

Path Parameters:

Parameter	Description
policy_name	Name or pattern to filter policies (e.g., exact name or wildcard pattern)

Example RequestResponse Body

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

[
  {
    "name": "deployments",
    "uuid": "6c33d95b-3dc9-533f-b77b-aaab693ce909",
    "description": "Deployment security policy for Kubernetes",
    "instruction": "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment.",
    "labels": {
      "platform": "kubernetes",
      "resource": "deployment"
    },
    "version": "1.0.0",
    "createdAt": "2025-06-01T10:00:00Z",
    "updatedAt": "2025-06-01T10:00:00Z"
  }
]

Get Policy by UUID

Retrieve a specific policy by its UUID.

GET /api/policies/uuid/{uuid}

Path Parameters:

Parameter	Description
uuid	The UUID of the policy to retrieve

Query Parameters:

Parameter	Description
version	Optional specific version to retrieve (e.g., "1.0.0")

Example RequestResponse Body

curl -X GET "https://<your-instance>.aegis.pegasys.cloud/api/policies/uuid/6c33d95b-3dc9-533f-b77b-aaab693ce909" \
  -H "Authorization: Bearer <your_token>"

{
  "name": "deployments",
  "uuid": "6c33d95b-3dc9-533f-b77b-aaab693ce909",
  "description": "Deployment security policy for Kubernetes",
  "instruction": "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment.",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "version": "1.0.0",
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2025-06-01T10:00:00Z"
}

Create Policy

Create a new policy using natural language instructions.

POST /api/policies/{policy_name}

Path Parameters:

Parameter	Description
policy_name	The name of the policy to create

Example RequestRequest BodyResponse Body

curl -X POST "https://<your-instance>.aegis.pegasys.cloud/api/policies/demo" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/x-yaml" \
  -d @- <<EOF
        instruction: "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment."
        labels:
          platform: kubernetes
          resource: deployment
        EOF

instruction: "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment."
labels:
  platform: kubernetes
  resource: deployment

{
  "name": "demo",
  "uuid": "8d7e6f5a-4b3c-2d1e-0f9a-8b7c6d5e4f3a",
  "description": "Kubernetes deployment security policy",
  "instruction": "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment.",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "version": "1.0.0",
  "createdAt": "2025-06-16T14:30:00Z"
}

Update Policy

Update an existing policy.

PUT /api/policies/{policy_name}

Path Parameters:

Parameter	Description
policy_name	The name of the policy to update

Example RequestRequest BodyResponse Body

curl -X PUT "https://<your-instance>.aegis.pegasys.cloud/api/policies/demo" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/x-yaml" \
  -d @- <<EOF
            instruction: "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment or deploy."
            labels:
              platform: kubernetes
              resource: deployment
        EOF

instruction: "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment or deploy."
labels:
  platform: kubernetes
  resource: deployment

{
  "name": "demo",
  "uuid": "8d7e6f5a-4b3c-2d1e-0f9a-8b7c6d5e4f3a",
  "description": "Kubernetes deployment security policy",
  "instruction": "Filter rulesets to include only those with a platform value of kubernetes and a resource value of deployment or deploy.",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "version": "1.0.1",
  "createdAt": "2025-06-16T14:30:00Z",
  "updatedAt": "2025-06-16T14:45:00Z"
}

Delete Policy

Delete a policy.

DELETE /api/policies/{policy_name}

Path Parameters:

Parameter	Description
policy_name	The name of the policy to delete

Example Request

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

Evaluation

Evaluate Policy

Evaluate a policy against a provided input.

POST /api/eval/policies/{policy_name}

Path Parameters:

Parameter	Description
policy_name	The name of the policy to evaluate

Example RequestRequest BodyResponse Body

curl -X POST "https://<your-instance>.aegis.pegasys.cloud/api/eval/policies/demo" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
            {
              "_filters": "name=demo or name=deployment",
              "labels": {
                "source": "api",
                "user": "user@example.com"
              },
              "inputData": {
                "apiVersion": "apps/v1",
                "kind": "Deployment",
                "metadata": {
                  "name": "nginx",
                  "namespace": "kube-app",
                  "labels": {
                    "env": "prod",
                    "app-id": "nginx",
                    "platform": "kubernetes",
                    "resource": "deployment"
                  }
                },
                "spec": {
                  "replicas": 0
                }
              }
            }
        EOF

{
  "_filters": "name=demo or name=deployment",
  "labels": {
    "source": "api",
    "user": "user@example.com"
  },
  "inputData": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "nginx",
      "namespace": "kube-app",
      "labels": {
        "env": "prod",
        "app-id": "nginx",
        "platform": "kubernetes",
        "resource": "deployment"
      }
    },
    "spec": {
      "replicas": 0
    }
  }
}

{
  "policy": "demo",
  "passed": false,
  "rulesets": [
    {
      "name": "kubernetes-deployment-security",
      "passed": false,
      "results": [
        {
          "rule": "enforce-replicas-gt-3",
          "status": "failed",
          "message": "Deployment must have at least 3 replicas for high availability"
        }
      ]
    }
  ]
}