Read API

Authentication

Every request carries the organisation key in the Authorization header, as a Bearer token.

Authorization: Bearer alx_live_…

The key starts with alx_live_. Its first 17 characters are the prefix shown in Settings → API. The full key is shown only once, when it is created: Alethexis stores only its SHA-256 fingerprint and cannot show it to you again.

A revoked key stops working on the next request.

A missing, unknown, wrong or revoked key gets the same 401 response: the API does not tell these cases apart.

Quota

Each key allows 120 requests per minute and 10,000 per day.

Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When the quota runs out, the response is 429 with Retry-After, in seconds.

In addition, each IP address allows 60 requests every 10 seconds. Above that, requests are blocked for 10 seconds.

Pagination

List responses return an object with data and next_cursor.

limit ranges from 1 to 200; the default is 50.

For the next page, repeat the request with cursor set to the next_cursor you received. On the last page, next_cursor is null.

The cursor is opaque: do not build or modify it.

Errors

All errors share one shape: an error object with code and message. The message is technical English; the code is stable.

Resources

All of them accept limit, cursor and since (an ISO 8601 date with time zone).

What the API does not return

The API returns no data about people and no hand-written text. Per resource, it leaves out:

• systems: who created or edited the system, the person named in the prohibited-practices check, the purpose and the notes.
• classifications: who classified it and the written justification.
• controls: the assigned owner and approver, the notes and the links to evidence files.
• evidence: the file, its storage path, the title, the description and who uploaded it.
• sections: the review reason and its details.
• approvals: who recorded the act, their roles and the comment.
• audit-log: who acted, the IP address, the browser and the values before and after the change.
• requests: who raised, reviewed or decided it, the purpose, the intended users, the notes on personal data, the decision comment and the comments.

Webhooks

A webhook notifies your system as soon as something happens, without polling the API. The Owner registers them in Settings → Webhooks: an https URL, the events you want and a secret shown only once.

{
  "id": "0f3a…",                 // Alethexis-Event-Id
  "type": "section.closed",
  "created_at": "2026-09-18T09:12:03.412Z",
  "api_version": "v1",
  "data": { "account_id": "…", "section_id": "GOB-2", "status": "complete", "closed_at": "…" }
}

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const [t, v1] = header.split(',').map((part) => part.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(v1, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}

# Python
import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Versions

v1 is a contract: its responses do not change in incompatible ways. An incompatible change ships as a new version, v2.

OpenAPI specification

The OpenAPI 3.1 specification is generated from the same schemas that validate every response: /api/v1/openapi.json

Example

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/systems?limit=50"