Skip to main content

Ledger API Reference

All Ledger endpoints are served under the /api/v1/ledger prefix via the gateway.

Endpoints​

MethodPathDescription
GET/api/v1/ledger/eventsList audit events
POST/api/v1/ledger/eventsEmit audit event
GET/api/v1/ledger/policiesList retention policies
POST/api/v1/ledger/policiesCreate policy
GET/api/v1/ledger/classifications?service=<id>List field classifications
POST/api/v1/ledger/classificationsClassify a field

Examples​

Emit an Audit Event​

curl -X POST http://localhost:3000/api/v1/ledger/events \
  -H "Content-Type: application/json" \
  -d '{
    "action": "service.deployed",
    "actor": "ci-pipeline",
    "resource": "payment-api",
    "metadata": {"version": "1.2.3", "environment": "production"}
  }'

Response:

{
  "success": true,
  "data": {
    "id": "l1m2n3o4",
    "action": "service.deployed",
    "actor": "ci-pipeline",
    "resource": "payment-api",
    "metadata": {"version": "1.2.3", "environment": "production"},
    "timestamp": "2026-03-05T12:00:00.000Z"
  }
}

List Audit Events​

curl http://localhost:3000/api/v1/ledger/events

Response:

{
  "success": true,
  "data": [
    {
      "id": "l1m2n3o4",
      "action": "service.deployed",
      "actor": "ci-pipeline",
      "resource": "payment-api",
      "metadata": {"version": "1.2.3", "environment": "production"},
      "timestamp": "2026-03-05T12:00:00.000Z"
    }
  ]
}

Create a Retention Policy​

curl -X POST http://localhost:3000/api/v1/ledger/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "audit-events-90d",
    "retentionDays": 90,
    "scope": "ledger.events"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "r1s2t3u4",
    "name": "audit-events-90d",
    "retentionDays": 90,
    "scope": "ledger.events",
    "createdAt": "2026-03-05T12:00:00.000Z"
  }
}

List Retention Policies​

curl http://localhost:3000/api/v1/ledger/policies

Classify a Field​

curl -X POST http://localhost:3000/api/v1/ledger/classifications \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "a1b2c3d4",
    "field": "user.email",
    "level": "pii",
    "justification": "Contains personally identifiable information"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "c1d2e3f4",
    "serviceId": "a1b2c3d4",
    "field": "user.email",
    "level": "pii",
    "justification": "Contains personally identifiable information",
    "createdAt": "2026-03-05T12:00:00.000Z"
  }
}

List Classifications for a Service​

curl "http://localhost:3000/api/v1/ledger/classifications?service=a1b2c3d4"

Response:

{
  "success": true,
  "data": [
    {
      "id": "c1d2e3f4",
      "serviceId": "a1b2c3d4",
      "field": "user.email",
      "level": "pii",
      "justification": "Contains personally identifiable information",
      "createdAt": "2026-03-05T12:00:00.000Z"
    }
  ]
}

Response Envelope​

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Action field is required"
  }
}