Developer Docs

Base URL

https://aiegis.ie

Authentication

Every protected endpoint requires your agent's api_key. Pilot customers receive an api_key by email after registering. You must click the verification link before your key activates — unverified keys are rejected.

Header conventions (all three accepted)

X-API-Key: ak_your_key_here
X-AiEGIS-Key: ak_your_key_here       # legacy, still supported
Authorization: Bearer ak_your_key_here

Precedence

When multiple headers carry the same key, precedence is X-API-Key > X-AiEGIS-Key > Authorization: Bearer > body.api_key. Two headers with different keys returns DENY — Ambiguous identity. Pick one header per request.

Agent ID assertion

If your request body includes an agent_id field, it must match the owner of the API key. A mismatch returns DENY — agent_id mismatch to prevent silent identity rewrites in audit logs.

Core Endpoints

POST /api/protect Auth required

Run an action through all 15 security layers. Returns ALLOW, WARN, or BLOCK with full threat detail. Rate-limited 30/minute.

curl -X POST https://aiegis.ie/api/protect \
  -H "X-API-Key: ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":"read_file","target":"/etc/passwd"}'

Response:

{
  "decision": "ALLOW" | "WARN" | "BLOCK",
  "agent_id": "aegis-...",
  "layers_checked": 15,
  "latency_ms": 4.9,
  "threats_found": [],
  "confidence_scoring": { "score": 0.97, "tier": "high" },
  "timestamp": "2026-05-03T10:00:00Z"
}

POST /api/register Public

Register a new agent. Returns an api_key (requires email verification) and a signed JWT tag.

curl -X POST https://aiegis.ie/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "my-agent",
    "agent_type": "general",
    "description": "what this agent does",
    "owner_name": "Your Name",
    "owner_email": "you@company.com"
  }'

POST /api/score/free Public

Grade any agent description for security posture. No auth required. 10/hour per IP, 2000 char max.

curl -X POST https://aiegis.ie/api/score/free \
  -H "Content-Type: application/json" \
  -d '{"description":"customer service bot","agent_name":"TestBot"}'

POST /api/agents/login Public

Verify email + api_key against a registered agent. Returns {"status":"ok","agent_id":"..."} on match.

curl -X POST https://aiegis.ie/api/agents/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","api_key":"ak_..."}'

GET /api/agents/public Public

Public summary of registered agents — no PII. Supports ?status=ACTIVE|QUARANTINED.

GET /api/health Public

Liveness check. Returns operational layer count and uptime. Used by watchdogs and status dashboards.

Error Shapes

Status	Shape	Example reason
400	`{"error": "..."}`	Required field missing
401	`{"error": "..."}`	Missing or invalid key
403	`{"error": "..."}`	Email unverified, agent quarantined
413	`{"error":"...","limit":2000}`	Body too large
429	`{"error":"rate_limited"}`	Per-IP rate cap exceeded

Rate Limits

Endpoint	Limit	Scope
`/api/protect`	30/min	Per API key
`/api/score/free`	10/hour	Per IP
`/api/register`	5/hour	Per IP
All others	60/min	Per IP

Quick Start

1. Register an agent at /checker or via POST /api/register.

2. Click the verify link in your email.

3. Call /api/protect with your X-API-Key header.

4. Expect decision: ALLOW on clean traffic. BLOCK returns with a threats_found array identifying the layer and reason.

Try it now: /api/health · /api/agents/public

REST API Reference