API reference
Audit log
Read, export and verify the organisation’s audit log.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| List audit events | GET /api/orgs/{org}/audit | read |
| Verify the audit log | GET /api/orgs/{org}/audit/verify | admin |
| Export the audit log | GET /api/orgs/{org}/audit/export | admin |
#List audit events
GET /api/orgs/{org}/audit
Answers the organisation's audit log, newest first, optionally filtered. Every change to settings, people, keys, integrations and findings is recorded here, with sign-ins. The log is not removed by the retention period or by erasing data.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | How many to return, 1 to 200. Default 50. |
offset | integer | no | How many to skip from the start. Default 0. |
actor | string | no | Only events by exactly this actor, for example dana@acme.example or api-key:CI pipeline. |
action | string | no | Only events whose action starts with this, for example member. or auth.. |
from | string | no | Only events at or after this date and time. |
to | string | no | Only events at or before this date and time. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/audit?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of AuditEvent | yes | The matching events, at most limit of them. |
total | integer | yes | How many match in all, before limit and offset. |
{
"items": [
{
"id": "aud_7b2e90c41f6a",
"at": "2026-11-16T09:30:00.000Z",
"actor": "dana@acme.example",
"action": "member.role",
"target": "sam@acme.example",
"detail": "admin",
"seq": 128,
"hash": "9f2c4e7a1b3d5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8"
}
],
"total": 42
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | from or to is not a date. |
#Verify the audit log
GET /api/orgs/{org}/audit/verify
Walks the whole audit log, oldest first, and checks that each event links to the one before it and that none has been removed from the end. A log that has been altered answers 200 with ok: false and the first place it fails; it is not an error status.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/audit/verify"
Answer (200, application/json)
A AuditVerification object.
{
"ok": true,
"checked": 128,
"unchained": 0,
"firstBreak": {
"id": "aud_7b2e90c41f6a",
"at": "2026-11-16T09:30:00.000Z",
"seq": 97
}
}
#Export the audit log
GET /api/orgs/{org}/audit/export
Downloads the audit log as a file, with the same filters as the list and up to 100,000 events. The default is a CSV file named nullgap-<slug>-audit.csv with the columns seq, at, actor, action, target, detail, hash; cells that a spreadsheet would run as a formula are prefixed with an apostrophe. With format=json it is a JSON file, nullgap-<slug>-audit.json, holding an array of audit events. The export is itself recorded in the audit log.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | string | no | The file format. Default csv. |
actor | string | no | Only events by exactly this actor, for example dana@acme.example or api-key:CI pipeline. |
action | string | no | Only events whose action starts with this, for example member. or auth.. |
from | string | no | Only events at or after this date and time. |
to | string | no | Only events at or before this date and time. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/audit/export"
Answer (200, text/csv)
The file. CSV text with a header row and one line per event, lines ending in CRLF. With format=json, the content type is application/json and the body is an array of AuditEvent.
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | format is neither csv nor json, or from or to is not a date. |
#Objects
The objects the operations above take and return.
#AuditEvent
One entry in the organisation's audit log.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The event's id. |
at | string | yes | When it happened. |
actor | string | yes | Who did it: an e-mail address, api-key:<name> for an API key, or nullgap for the service itself. |
action | string | yes | What happened, as a dotted name. The part before the dot groups related actions. |
target | string or null | yes | What it was done to, when there is one. |
detail | string or null | yes | More about the change, when there is more to say. |
seq | integer | no | The event's position in the organisation's tamper-evident chain, starting at 1. Absent on events recorded before chaining existed. |
hash | string | no | A hash of this event and the one before it. Absent on events recorded before chaining existed. |
#AuditVerification
The outcome of checking the audit log's tamper-evident chain.
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | True when every chained event links correctly to the one before it and none is missing from the end. |
checked | integer | yes | How many events in the chain were checked. |
unchained | integer | yes | How many events were recorded before chaining existed. They are not covered by the check. |
firstBreak | object or null | yes | Where the chain first fails. Null when it holds. |
firstBreak.id | string | yes | The id of the first event that does not link correctly, or chain-head when the newest events are missing. |
firstBreak.at | string | yes | When that event was recorded. |
firstBreak.seq | integer | yes | Its position in the chain. |
Nullgap documentation