API reference

Find every operation of the Aegis API, see which ones an API key may call, and read how authentication, paging, errors and rate limits work.

At a glance

Where	`Settings → API Keys` links `API reference: operations usable with API keys` and `Full API reference`; both open in a new tab. The addresses are `/api/docs?view=api-keys` and `/api/docs`.
Who can open it	Administrators, on a plan with API access. The reference describes the whole internal API, so other roles are sent back to the dashboard.
Machine-readable spec	`/api/openapi` (JSON) and `/api/docs/spec` (YAML), OpenAPI 3.1, behind the same check. `/api/openapi?view=api-keys` returns only the operations a key may call.
Base address	Your own Aegis address, for example `https://<your-domain>/api/risks`. The reference fills it in for the instance you opened it on.

Good to know

The view of operations usable with API keys keeps only the operations marked x-api-key-level (read, write or admin). Where a per-module scope applies, x-api-key-module names the module. The opening text links back to the full reference, and the full reference links to this view.
Every operation lists its parameters, request body, the statuses it answers with and an example request you can copy. The Test Request panel sends a real request to your instance: a write changes real records.
Some operations never accept a key, whatever its access, for example data subject requests and user management. API Keys lists them.

Authenticate

Send the key's secret as Authorization: Bearer aegis_… — aegis_ followed by 64 lowercase hexadecimal characters. The x-api-key header is not supported. A request from a script looks like this:

curl -H "Authorization: Bearer $API_KEY" \
     "https://<your-domain>/api/risks?page=1&limit=50"

Page through a list

List operations take page (starting at 1) and limit (20 by default, at most 100 unless the operation says otherwise). Next to the array of items the answer carries total, page, limit, totalPages, hasNext and hasPrev. Keep asking for the next page while hasNext is true. The name of the array differs per operation (for example risks or data); the reference shows it.

Read an error

An error is JSON with an error message and sometimes details:

{ "error": "Validation failed", "details": { "title": "Required" } }

Status	Meaning
`400`	The input is invalid; `details` names the fields.
`401`	No credential, or an unknown, expired, revoked or inactive key.
`403`	Refused: the key level or module scope is too low, the owner lacks the permission, the IP address is not allowed, or the module is not on your plan.
`404`	The record does not exist or was deleted.
`409`	The change conflicts with the record's current state.
`429`	A rate limit or the key's hourly limit is reached; wait for `Retry-After` seconds.
`503`	A service Aegis depends on is unavailable; try again later.

When Aegis refuses an API key, the answer carries a code instead of details. Branch on code, not on the message:

{ "error": "API key hourly limit reached", "code": "API_KEY_RATE_LIMIT" }

Status	Code	Meaning
`401`	`INVALID_API_KEY`	The key is unknown, expired, revoked or inactive.
`401`	`UNSUPPORTED_API_CREDENTIAL`	The key was not sent as `Authorization: Bearer aegis_...`, for example in an `X-API-Key` header.
`403`	`API_KEY_FORBIDDEN`	The key level, module scope, IP allowlist or the owner's permission does not allow the call.
`403`	`MFA_ENROLLMENT_REQUIRED`	The key's owner has not enrolled in multi-factor authentication.
`403`	`MFA_ENFORCEMENT_CHECK_FAILED`	Aegis could not check the owner's multi-factor authentication.
`429`	`API_KEY_RATE_LIMIT`	The key's hourly limit is reached; wait for `Retry-After` seconds.
`503`	`API_KEY_UNAVAILABLE`	Key checks are unavailable for a moment; try again later.
`400`	`INVALID_API_KEY_CONFIGURATION`	Creating or changing a key: the settings are invalid.
`400`	`ADMIN_KEY_REQUIRES_ALLOWLIST`	Creating or changing a key: an admin key needs at least one allowed IP address.
`400`	`IP_ALLOWLIST_UNAVAILABLE`	Creating or changing a key: IP restrictions need a verified ingress set-up.
`400`	`MODULE_SCOPE_UNAVAILABLE`	Creating or changing a key: that module has no operations usable with keys yet.

Stay within the limits

Each route allows a number of requests per minute per client IP address (100 on most routes, 60 shared by search and list routes), and each key has its own hourly limit. Over a limit Aegis answers 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The full table is in API Keys.

Where this connects

Create and manage keys in API Keys. To be told when something changes instead of asking, use Webhooks. The integrations that pull data in are listed in Connectors, each with its own page in this part.