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 12 enforced security layers. Returns ALLOW, WARN, or BLOCK with full threat detail. Rate-limited 30/minute. Sub-15ms p95 on customer infrastructure (loopback).

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": 12,
  "latency_ms": 6.1,
  "threats_found": [],
  "confidence_scoring": { "score": 0.97, "tier": "high" },
  "timestamp": "2026-05-08T10:00:00Z"
}

POST /api/agent/issue Auth required

Mint an Ed25519-signed agent passport binding agent → operator → jurisdiction → policy bundle. Identity layer (v1.0 ship-gate, 2026-05-06).

curl -X POST https://aiegis.ie/api/agent/issue \
  -H "X-API-Key: ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"...","operator":"...","jurisdiction":"EU"}'

POST /registry/revoke Auth required

Revoke a previously-issued passport. Propagates through the SQLite revocation store; subsequent verifies fail immediately.

curl -X POST https://aiegis.ie/registry/revoke \
  -H "X-API-Key: ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"...","reason":"compromised"}'

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

Free-tier agent description scoring (capped grade). No auth required. Description must be at least 20 characters.

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

POST /api/score/deep Auth required

Paid-tier 5-layer deep audit. Rate-limited 30/hour per API key. Returns full grade up to A.

curl -X POST https://aiegis.ie/api/score/deep \
  -H "X-API-Key: ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"description":"customer service bot for retail returns","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`	—	Public, capped grade
`/api/score/deep`	30/hour	Per API key
`/api/agents/login`	5/min	Per IP
`/api/register`	5/hour	Per IP
All others	60/min	Per IP

Quick Start

1. Register an agent 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