REST API Reference

Complete reference for the Aegis REST API endpoints.

---

Base URL

https://api.aegispreflight.com

For self-hosted deployments, use your configured API base URL.

---

Interactive Documentation

The API includes interactive documentation:

• Scalar UI: https://api.aegispreflight.com/docs
• OpenAPI Spec: https://api.aegispreflight.com/openapi.json

---

Preflight Endpoints

Check Text Content

Check text content for sensitive data.

POST /api/preflight/text

Headers:

Header	Required	Description
X-Aegis-API-Key	Yes	Policy API key
Content-Type	Yes	application/json

Request Body:

{
  "text": "Content to check",
  "destination": "AI_TOOL",
  "org_id": "optional-org-id",
  "policy_id": "optional-policy-id"
}

Field	Type	Required	Description
text	string	Yes	Content to check
destination	string	Yes	AI_TOOL, VENDOR, or CUSTOMER
org_id	string	No	Organization ID (if multi-tenant)
policy_id	string	No	Specific policy to use

Response:

{
  "preflight_id": "pf_abc123",
  "decision": "ALLOWED_WITH_MASKING",
  "summary": "PII detected and masked",
  "detected": [
    {
      "type": "EMAIL",
      "count": 1,
      "sample": "user@***.com"
    },
    {
      "type": "SSN",
      "count": 1,
      "sample": "123-45-****"
    }
  ],
  "masked_content": "Masked version of content...",
  "policy_version": "1.0",
  "created_at": "2024-01-15T10:30:00Z"
}

Example:

curl -X POST https://api.aegispreflight.com/api/preflight/text \
  -H "X-Aegis-API-Key: aegis_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Email me at [email protected]",
    "destination": "AI_TOOL"
  }'

---

Check File

Check a file for sensitive data.

POST /api/preflight

Headers:

Header	Required	Description
X-Aegis-API-Key	Yes	Policy API key
Content-Type	Yes	multipart/form-data

Form Fields:

Field	Type	Required	Description
file	file	Yes	File to check
destination	string	Yes	AI_TOOL, VENDOR, or CUSTOMER
org_id	string	No	Organization ID
policy_id	string	No	Specific policy

Response:

{
  "preflight_id": "pf_xyz789",
  "decision": "BLOCKED",
  "summary": "File contains PHI which is blocked for this destination",
  "detected": [
    {
      "type": "PHI",
      "count": 5,
      "sample": null
    }
  ],
  "masked_file_url": null,
  "policy_version": "1.0",
  "created_at": "2024-01-15T10:30:00Z"
}

Example:

curl -X POST https://api.aegispreflight.com/api/preflight \
  -H "X-Aegis-API-Key: aegis_sk_xxx" \
  -F "[email protected]" \
  -F "destination=VENDOR"

---

Get Preflight Result

Retrieve a previous preflight check result.

GET /api/preflight/{preflight_id}

Parameters:

Parameter	Type	Description
preflight_id	string	Preflight check ID

Response:

Same as check response above.

Example:

curl https://api.aegispreflight.com/api/preflight/pf_abc123 \
  -H "X-Aegis-API-Key: aegis_sk_xxx"

---

Organization Endpoints

List Organizations

GET /api/organizations

Response:

[
  {
    "org_id": "acme",
    "name": "Acme Corp",
    "slug": "acme",
    "settings": {
      "primary_color": "#6366f1",
      "admin_email": "[email protected]"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

---

Create Organization

POST /api/organizations

Request Body:

{
  "name": "New Organization",
  "slug": "new-org",
  "settings": {
    "admin_email": "[email protected]",
    "primary_color": "#10b981"
  }
}

Response:

{
  "org_id": "org_abc123",
  "name": "New Organization",
  "slug": "new-org",
  "settings": {...},
  "license_id": "lic_xyz789",
  "license_key": "aegis_lic_xxx",
  "license_type": "trial",
  "license_expires_at": "2025-01-15T00:00:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Auto-created License

A license and default policy group are automatically created with new organizations.

---

Get Organization

GET /api/organizations/{org_id}

Parameters:

Parameter	Type	Description
org_id	string	Organization ID or slug

---

Update Organization

PATCH /api/organizations/{org_id}

Request Body:

{
  "name": "Updated Name",
  "settings": {
    "admin_email": "[email protected]"
  }
}

---

Delete Organization

DELETE /api/organizations/{org_id}

Response: 204 No Content

---

Policy Endpoints

List Policies

GET /api/orgs/{org_id}/policies

Response:

[
  {
    "policy_id": "pol_abc123",
    "org_id": "acme",
    "name": "Engineering Policy",
    "description": "Policy for engineering team",
    "version": "1.0",
    "tags": ["engineering", "dev"],
    "is_active": true,
    "api_key": "aegis_sk_xxx",
    "rules": [
      {
        "id": "rule-001",
        "name": "Block PII to AI",
        "enabled": true,
        "dataTypes": ["PII"],
        "destinations": ["AI_TOOL"],
        "action": "BLOCK"
      }
    ],
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

---

Create Policy

POST /api/orgs/{org_id}/policies

Request Body:

{
  "name": "New Policy",
  "description": "Policy description",
  "tags": ["production"],
  "rules": [
    {
      "name": "Block SSN",
      "enabled": true,
      "dataTypes": ["PII"],
      "destinations": ["AI_TOOL"],
      "action": "BLOCK"
    }
  ]
}

---

Get Policy

GET /api/orgs/{org_id}/policies/{policy_id}

---

Update Policy

PATCH /api/orgs/{org_id}/policies/{policy_id}

Request Body:

{
  "name": "Updated Policy Name",
  "is_active": true,
  "rules": [...]
}

---

Delete Policy

DELETE /api/orgs/{org_id}/policies/{policy_id}

---

Regenerate Policy API Key

POST /api/orgs/{org_id}/policies/{policy_id}/regenerate-key

Response:

{
  "api_key": "aegis_sk_new_key",
  "policy_id": "pol_abc123"
}

---

License Endpoints

List Licenses

GET /api/orgs/{org_id}/licenses

Response:

[
  {
    "license_id": "lic_abc123",
    "org_id": "acme",
    "license_key": "aegis_lic_xxx",
    "license_type": "standard",
    "status": "active",
    "expires_at": "2025-12-31T00:00:00Z",
    "max_checks_per_month": 100000,
    "default_policy_group": "default",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

---

Validate License (SDK)

GET /v1/license/validate

Headers:

Header	Required	Description
Authorization	Yes	Bearer aegis_lic_xxx

Response:

{
  "valid": true,
  "expires": "2025-12-31T00:00:00Z",
  "org_id": "acme",
  "policy_version": "1.0",
  "policy_config": {...},
  "policy_groups": ["default", "engineering"],
  "default_policy_group": "default",
  "jwt_token": "eyJhbGciOiJSUzI1NiIs..."
}

---

Get Public Key

GET /v1/license/public-key

Response:

{
  "key_id": "key_abc123",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...",
  "algorithm": "RS256"
}

---

Revoke License

DELETE /api/orgs/{org_id}/licenses/{license_id}

Response: 204 No Content

Cascade Effect

Revoking a license deactivates all associated policies.

---

Analytics Endpoints

Organization Analytics

GET /api/orgs/{org_id}/analytics?period=30d

Parameters:

Parameter	Type	Default	Description
period	string	30d	7d, 30d, or 90d

Response:

{
  "org_id": "acme",
  "org_name": "Acme Corp",
  "total_checks": 15420,
  "bytes_protected": 1048576000,
  "allowed": 12000,
  "masked": 2500,
  "blocked": 920,
  "safe_share_rate": 94.0,
  "prevented_exposures": 920,
  "from_date": "2024-01-01",
  "to_date": "2024-01-31"
}

---

Time Series Data

GET /api/orgs/{org_id}/analytics/timeseries?period=30d

Response:

{
  "org_id": "acme",
  "period": "30d",
  "data": [
    {
      "date": "2024-01-01",
      "checks_total": 500,
      "allowed": 400,
      "masked": 80,
      "blocked": 20,
      "bytes_processed": 10485760
    }
  ]
}

---

Detection Breakdown

GET /api/orgs/{org_id}/analytics/detections?period=30d

Response:

{
  "org_id": "acme",
  "total_detections": 3420,
  "types": [
    {
      "type": "EMAIL",
      "label": "Email Addresses",
      "count": 1500,
      "percentage": 43.8
    },
    {
      "type": "SSN",
      "label": "Social Security Numbers",
      "count": 800,
      "percentage": 23.4
    }
  ],
  "from_date": "2024-01-01",
  "to_date": "2024-01-31"
}

---

Audit Endpoints

List Audit Log

GET /api/audit?limit=50&offset=0&org_id=acme

Parameters:

Parameter	Type	Default	Description
limit	int	50	Results per page
offset	int	0	Pagination offset
org_id	string	-	Filter by organization
search	string	-	Search query

Response:

{
  "items": [
    {
      "preflight_id": "pf_abc123",
      "created_at": "2024-01-15T10:30:00Z",
      "destination": "AI_TOOL",
      "decision": "BLOCKED",
      "summary": "Content blocked due to SSN",
      "policy_version": "1.0",
      "policy_name": "Engineering Policy",
      "org_id": "acme",
      "org_name": "Acme Corp"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1520
}

---

Error Responses

Standard Error Format

{
  "detail": "Error message here"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

---

See Also

• Authentication - API authentication guide
• SDK Reference - Python SDK documentation