API Reference

Complete reference for the AegisAI REST API at /api/v1. Interactive documentation is available at http://localhost:8000/docs.

Base URL

http://localhost:8000/api/v1

Authentication

Header	Value	Scope
X-API-Key	Tenant or user API key	Agent, policy, audit operations
Authorization	Bearer <jwt>	User management, API keys
X-Admin-Key	Admin provisioning key	Tenant creation

All requests should include Content-Type: application/json for POST/PUT bodies.

Common Response Codes

Code	Meaning
200	Success
201	Created
202	Accepted (async job)
204	No content (delete, logout)
401	Missing or invalid credentials
403	Insufficient permissions
404	Resource not found
422	Validation error

---

Auth

POST /auth/login

Authenticate with email and password. Returns JWT and session API key.

Body:

{
  "email": "admin@aegisai.com",
  "password": "admin123"
}

Response: LoginResponse — access_token, expires_in, user, api_key

POST /auth/logout

Invalidate session. Requires JWT.

Response: 204 No Content

GET /auth/me

Get current user profile. Requires JWT.

Response: UserResponse

GET /auth/sso/providers

List enabled SSO Identity Providers (no auth required).

Response: { "providers": [{ "id": "keycloak", "name": "Keycloak", "enabled": true }] }

GET /auth/sso/login

Start OIDC flow. Redirects browser to IdP.

Query: provider (keycloak, okta, google, microsoft), redirect (post-login path, default /dashboard)

GET /auth/sso/callback

OIDC callback from IdP. Redirects to frontend with one-time sso_code.

POST /auth/sso/exchange

Exchange one-time SSO code for session credentials.

Body: { "code": "<sso_code>" }

Response: Same as LoginResponse

---

Users

Requires JWT with Admin or Super Admin role unless noted.

Method	Endpoint	Description
GET	/users/me	Get own profile
PUT	/users/me	Update own profile
POST	/users/me/change-password	Change own password
POST	/users	Create user
GET	/users	List users (paginated)
GET	/users/{user_id}	Get user by ID
PUT	/users/{user_id}	Update user
POST	/users/{user_id}/reset-password	Admin password reset
PUT	/users/{user_id}/role	Change user role
POST	/users/{user_id}/block	Block user
POST	/users/{user_id}/unblock	Unblock user
DELETE	/users/{user_id}	Delete user

List query parameters: role, search, is_active, limit (max 200), offset

---

API Keys

Requires JWT.

Method	Endpoint	Description
POST	/api-keys	Create API key (raw key shown once)
GET	/api-keys	List user's API keys
DELETE	/api-keys/{key_id}	Revoke API key

---

Tenants

Requires X-Admin-Key for creation; Super Admin JWT for listing.

Method	Endpoint	Description
GET	/tenants	List all tenants (Super Admin)
POST	/tenants	Create tenant (returns api_key)

Create body:

{
  "name": "acme-corp",
  "settings": {}
}

---

Agents

Requires X-API-Key. Write operations require Developer+ role.

Method	Endpoint	Description
POST	/agents/register	Register new agent
POST	/agents/{agent_id}/heartbeat	Send heartbeat (also refreshes embeddings if stale)
GET	/agents	List agents (includes predicted_type / risk_score when available)
GET	/agents/search	Semantic search ?q=
GET	/agents/{agent_id}	Get agent
GET	/agents/{agent_id}/details	Get agent with details + embedding summary
PUT	/agents/{agent_id}	Update agent
DELETE	/agents/{agent_id}	Delete agent

Register body:

{
  "name": "my-agent",
  "type": "llm",
  "capabilities": ["observe", "track"],
  "permissions": {}
}

---

Discovery (Shadow AI)

Requires X-API-Key. Write operations require agents:update.

Method	Endpoint	Description
GET	/discovery/candidates	List discovery candidates
POST	/discovery/ingest	Ingest unknown-agent event
POST	/discovery/ingest/batch	Batch ingest (+ optional cluster)
POST	/discovery/cluster	Schedule async cluster merge
POST	/discovery/candidates/{id}/confirm	Confirm → register agent
POST	/discovery/candidates/{id}/dismiss	Dismiss candidate

---

Policies

Requires X-API-Key. Write operations require Admin role.

Method	Endpoint	Description
POST	/policies	Create policy
GET	/policies	List policies
GET	/policies/templates	List Rego templates
POST	/policies/check	Evaluate policy for action
GET	/policies/{policy_id}	Get policy
PUT	/policies/{policy_id}	Update policy
DELETE	/policies/{policy_id}	Delete policy

Policy check body:

{
  "agent_id": "uuid",
  "action": "read_data",
  "resource": "customer_pii",
  "context": {"consent": true}
}

Policy check response:

{
  "allowed": true,
  "reason": "GDPR check passed",
  "severity": null,
  "required_approval": false,
  "risk_score": 0.15,
  "risk": {"level": "low"},
  "anomaly": {"is_anomaly": false}
}

List query parameters: active_only, skip, limit

---

Audit

Requires X-API-Key. Export requires Security Analyst+ role.

Method	Endpoint	Description
POST	/audit/log	Create audit log entry
GET	/audit	List audit logs
GET	/audit/{log_id}	Get audit log by ID
GET	/audit/export/csv	Export as CSV
GET	/audit/export/json	Export as JSON
GET	/audit/export	Export with format param
POST	/audit/export/async	Start async export job
GET	/audit/export/status/{job_id}	Check export job status
GET	/audit/export/download/{job_id}	Download export file

Log body:

{
  "agent_id": "uuid",
  "action": "query_database",
  "resource": "customers",
  "input": {},
  "output": {},
  "reasoning": ["step 1", "step 2"],
  "risk_score": 0.2,
  "is_approved": true
}

List query parameters: agent_id, action, skip, limit

---

Anomalies

Requires X-API-Key. Security Analyst+ for read.

Method	Endpoint	Description
GET	/anomalies	List anomaly reports
GET	/anomalies/stats	Anomaly statistics
POST	/anomalies/report	Report anomaly manually
GET	/anomalies/detector/status	Detector status
GET	/anomalies/detector/metrics	Detector metrics
GET	/anomalies/detector/versions	Model versions
POST	/anomalies/detector/train	Train detector
GET	/anomalies/detector/training/status	Current training status
GET	/anomalies/detector/training-status/{task_id}	Training task status
POST	/anomalies/detector/rollback/{version}	Rollback model version
DELETE	/anomalies/detector/cancel	Cancel training

---

HITL

Requires X-API-Key. Approve/reject requires Security Analyst+ role.

Method	Endpoint	Description
POST	/hitl/request	Create approval request
POST	/hitl/approve/{approval_id}	Approve request
POST	/hitl/reject/{approval_id}	Reject request
GET	/hitl/status/{approval_id}	Get request status
GET	/hitl/pending	List pending requests

---

Stats & Status

Method	Endpoint	Auth	Description
GET	/stats	X-API-Key	Dashboard KPI statistics (includes Guard counters)
GET	/status	X-API-Key	Platform health and uptime

---

Prompt Guard

Method	Endpoint	Auth	Description
GET	/guard/health	—	Guard liveness and config
POST	/guard/validate	X-API-Key	Validate a prompt (injection / jailbreak / leakage)
GET	/guard/stats	X-API-Key	In-process Guard metrics
GET	/guard/detector/status	X-API-Key	Per-tenant detector status
GET	/guard/detector/metrics	X-API-Key	Detector precision/recall
GET	/guard/detector/versions	X-API-Key	Model version history
POST	/guard/detector/train	X-API-Key + guard:manage	Start background training
GET	/guard/detector/training/status	—	Training task progress (task_id)
POST	/guard/detector/rollback/{version}	X-API-Key + guard:manage	Roll back model version
DELETE	/guard/detector/cancel	X-API-Key + guard:manage	Cancel training
POST	/guard/detector/feedback	X-API-Key + guard:manage	Manual label (FP / attack)

See Prompt Guard for architecture, thresholds, and SDK usage.

---

Health

No authentication required.

Method	Endpoint	Description
GET	/health	Liveness check
GET	/health/ready	Readiness (DB, Redis, OPA)

---

Integrations

Method	Endpoint	Description
GET	/integrations/langchain/status	LangChain integration status
GET	/integrations/openai/status	OpenAI integration status

---

SIEM (Admin)

Requires Super Admin JWT or X-Admin-Key.

Method	Endpoint	Description
GET	/siem/status	SIEM configuration and transport
POST	/siem/test	Send test event and flush batch

See SIEM Integration.

---

WebSocket

WS /ws?token=<jwt>

Real-time notification channel. Authenticate with JWT access token as query parameter.

Server events: policy.violated, anomaly.detected, hitl.requested, hitl.resolved, system.status

---

Webhooks (outside /api/v1)

Method	Endpoint	Auth	Description
POST	/webhooks/agent	X-Webhook-Signature	Receive agent events

See Webhooks for payload format and signing.

---

Root

Method	Endpoint	Description
GET	/	Platform info and links

{
  "name": "AegisAI Platform",
  "version": "1.0.0",
  "docs": "/docs",
  "dashboard": "/dashboard"
}

Rate Limiting

Rate limiting is not enforced in the default development configuration. Configure at the reverse proxy level for production.

Related Documentation

• Python SDK
• Webhooks
• Architecture