Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
List audit eventsGET /api/orgs/{org}/auditread
Verify the audit logGET /api/orgs/{org}/audit/verifyadmin
Export the audit logGET /api/orgs/{org}/audit/exportadmin

#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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
limitintegernoHow many to return, 1 to 200. Default 50.
offsetintegernoHow many to skip from the start. Default 0.
actorstringnoOnly events by exactly this actor, for example dana@acme.example or api-key:CI pipeline.
actionstringnoOnly events whose action starts with this, for example member. or auth..
fromstringnoOnly events at or after this date and time.
tostringnoOnly 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)

FieldTypeAlways presentDescription
itemsarray of AuditEventyesThe matching events, at most limit of them.
totalintegeryesHow 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

StatusCodeWhen
400bad_requestfrom 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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
formatstringnoThe file format. Default csv.
actorstringnoOnly events by exactly this actor, for example dana@acme.example or api-key:CI pipeline.
actionstringnoOnly events whose action starts with this, for example member. or auth..
fromstringnoOnly events at or after this date and time.
tostringnoOnly 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

StatusCodeWhen
400bad_requestformat 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.

FieldTypeAlways presentDescription
idstringyesThe event's id.
atstringyesWhen it happened.
actorstringyesWho did it: an e-mail address, api-key:<name> for an API key, or nullgap for the service itself.
actionstringyesWhat happened, as a dotted name. The part before the dot groups related actions.
targetstring or nullyesWhat it was done to, when there is one.
detailstring or nullyesMore about the change, when there is more to say.
seqintegernoThe event's position in the organisation's tamper-evident chain, starting at 1. Absent on events recorded before chaining existed.
hashstringnoA 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.

FieldTypeAlways presentDescription
okbooleanyesTrue when every chained event links correctly to the one before it and none is missing from the end.
checkedintegeryesHow many events in the chain were checked.
unchainedintegeryesHow many events were recorded before chaining existed. They are not covered by the check.
firstBreakobject or nullyesWhere the chain first fails. Null when it holds.
firstBreak.idstringyesThe id of the first event that does not link correctly, or chain-head when the newest events are missing.
firstBreak.atstringyesWhen that event was recorded.
firstBreak.seqintegeryesIts position in the chain.

Nullgap documentation