Developer Docs


# REST API Reference


Authentication, endpoints, request and response shapes. Every claim on this page is reproducible against the live API at `https://aiegis.ie`.







Getting Started
[Base URL](#base-url)
[Authentication](#auth)
[Quick Start](#quickstart)
Endpoints
[POST /api/protect](#protect)
[POST /api/register](#register)
[POST /api/score/free](#score-free)
[POST /api/score/deep](#score-deep)
[POST /api/agents/login](#login)
[GET /api/agents/public](#agents)
[GET /api/health](#health)
Reference
[Error shapes](#errors)
[Rate limits](#rate-limits)
Manuals
[AIEGIS User Manual](/manual)
[IT Dashboard Manual](/manual/dashboard)







## 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. Designed for real-time verification on customer infrastructure.


```
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
Admin


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/health) · [/api/agents/public](/api/agents/public)