Audit trail API | Developer Guides | Docbyte Knowledge Base

You can use the Audit trail API to find out what happened in the archive: who moved a package to the trash, which ingest failed, when someone placed a legal hold. You can search all the records of your tenant, export them as a CSV file, or read the audit trail of one package.

Every call needs the archive-content-manager role, and only returns records of the tenant that you call. Every call also needs the headers in Common headers. To handle errors that any call can return, go to Errors.

Search the audit trail

Returns the audit trail records that match your filters, most recent first. All filters are optional, and you can combine them.

GET /v2/audittrail

Required role: archive-content-manager

Name	Type	Required	Description
`page`	integer, query	No	The page to return, starting at `0`. Default: `0`.
`pageSize`	integer, query	No	The number of records per page. Default: `100`.
`sortBy`	string, query	No	`name`, `user`, `severity`, or `packageId`. Any other value sorts by the time of the event. Without `sortBy`, records are sorted by time, most recent first.
`sortOrder`	string, query	No	`asc` or `desc`. Default: `desc`. Only applies when you set `sortBy`.
`packageId`	string, query	No	Returns the records of this package. Also works for a package whose ingest failed.
`eventName`	string, query	No	Returns the records of this event, for example `aipTrashed`. Exact match. For the events, see Events that you can filter on.
`user`	string, query	No	Returns the records of this user name. Exact match.
`severity`	string, query	No	`INFO`, `WARNING`, or `ERROR`. To ask for more than one, separate them with commas (`severity=WARNING,ERROR`), or repeat the parameter. Not case-sensitive. A record without a severity counts as `INFO`.
`from`	string, query	No	Returns events on or after this moment, as an ISO 8601 date and time with an offset, for example `2026-01-01T00:00:00Z`.
`to`	string, query	No	Returns events on or before this moment, in the same format, for example `2026-01-31T23:59:59Z`.

Bash

curl -G https://archive.example.com/v2/audittrail \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: acme-archive" \
  --data-urlencode "packageId=HR-2019-0042" \
  --data-urlencode "severity=WARNING,ERROR" \
  --data-urlencode "from=2026-09-01T00:00:00Z"

Response: 200 OK with an AuditTrailList object.

JSON

{
  "totalResults": 1,
  "page": 0,
  "pageSize": 100,
  "items": [
    {
      "eventId": "48213",
      "name": "plugin_failed",
      "severity": "WARNING",
      "message": "Plugin pdfa-validation failed: report.pdf is not valid PDF/A",
      "packageId": "HR-2019-0042",
      "user": "jdoe",
      "time": "2026-09-14T13:02:11Z",
      "logDate": "2026-09-14T13:02:12Z",
      "repository": "acme-archive",
      "extendedInfo": {
        "packageId": "HR-2019-0042",
        "severity": "Moderate",
        "message": "Plugin pdfa-validation failed: report.pdf is not valid PDF/A"
      }
    }
  ]
}

400 with INVALID_DATE: from or to isn't an ISO 8601 date and time with an offset.
400 with UNSUPPORTED_VALUE: severity holds a value other than INFO, WARNING, or ERROR.

Export the audit trail as CSV

Creates a CSV file with the records that match your filters, and returns a link to download it. You can use the filters of Search the audit trail: packageId, eventName, user, severity, from, and to. Paging and sorting don't apply.

GET /v2/audittrail/export

Required role: archive-content-manager

The call returns when the file is ready. The file holds at most 10,000 records, the most recent first. To export more, split the export into shorter date ranges with from and to.

The CSV file has a header row and these columns: eventId, name, severity, user, time, packageId, packageType, repository, and message.

Response: 200 OK with an ExportResult object.

JSON

{
  "downloadUrl": "https://downloads.example.com/exports/audittrail/2b7f0c9e.csv?X-Amz-Expires=3600"
}

400 with INVALID_DATE: from or to isn't an ISO 8601 date and time with an offset.
400 with UNSUPPORTED_VALUE: severity holds a value other than INFO, WARNING, or ERROR.

Get a package's audit trail

Returns the audit trail records of one package, most recent first.

GET /v2/archive/{packageId}/audittrail

Required role: archive-content-manager

Name	Type	Required	Description
`packageId`	string, path	Yes	The package ID.
`page`	integer, query	No	The page to return, starting at `0`. Default: `0`.
`pageSize`	integer, query	No	The number of records per page. Default: `100`.

Response: 200 OK with an AuditTrailList object.

404 with PACKAGE_NOT_FOUND: no package that you can see has this ID. To find the records of a package whose ingest failed, use Search the audit trail with the packageId filter.

Get one audit trail record

Returns one record of a package's audit trail.

GET /v2/archive/{packageId}/audittrail/{eventId}

Required role: archive-content-manager

Name	Type	Required	Description
`packageId`	string, path	Yes	The package ID.
`eventId`	string, path	Yes	The record's `eventId`, from a search or from the package's audit trail.

Response: 200 OK with an AuditTrailRecord object.

404 with AUDIT_EVENT_NOT_FOUND: this package has no record with this eventId.

Events that you can filter on

Use these names in the eventName filter. Some of them also carry a severity.

Event	When it's recorded	Severity
`ingest_failed`	An ingest failed.	`ERROR`
`sip_create_failed`	The archive couldn't create or read a SIP, for example because it isn't valid.	`ERROR`
`aip_create_failed`	The archive couldn't create or find the package for a SIP.	`ERROR`
`virus_found`	The virus scan found a virus.	`ERROR`
`plugin_failed`	A preservation action failed.	`WARNING`
`plugin_warning`	A preservation action finished with a warning.	`INFO`
`updateSubmissionCreated`	Someone updated a package's metadata, and the archive created an update SIP.	None
`renditionsDeleted`	Someone deleted a package's renditions.	None
`aipTrashed`	Someone moved a package to the trash.	None
`aipRestored`	Someone restored a package from the trash.	None
`aipPermanentlyDeleted`	Someone deleted a package permanently.	None
`aipTransferred`	Someone transferred a package to another tenant. The target tenant is in `extendedInfo.targetRepo`.	None
`afterSetLegalHold`	Someone placed a legal hold.	None
`afterRemoveLegalHold`	Someone lifted a legal hold.	None
`afterSetRetention`	A package's retention date was set.	None
`afterExtendRetention`	A package's retention date was extended.	None
`deletionListRecordAdded`	A package was added to a deletion list after its retention period ended.	None
`deletionListRecordRemoved`	A package was removed from a deletion list, for example because its retention was extended or it was placed on legal hold.	None
`deletionListReviewInitiated`	Someone started the review of a deletion list.	None
`deletionListReviewApproved`	A reviewer approved a deletion list.	None
`deletionListReviewRejected`	A reviewer rejected a deletion list.	None
`deletionListApproved`	All the reviewers approved a deletion list.	None
`deletionListRemoved`	The archive ran the end action of an approved deletion list on its packages.	None
`deletion_list_end_action_failed`	The end action of an approved deletion list couldn't run on a package, because the action failed on that package.	`ERROR`

The events from deletionListReviewInitiated to deletionListRemoved are recorded on the deletion list, not on a package. You find them in a search without the packageId filter, but not in a package's audit trail.

Schemas

AuditTrailList

Field	Type	Description
`totalResults`	number	The number of records that match, on all pages.
`page`	number	The page in this response.
`pageSize`	number	The page size in this response.
`items`	array of AuditTrailRecord	The records on this page.

AuditTrailRecord

Field	Type	Description
`eventId`	string	The record's ID. Use it to get one audit trail record.
`name`	string	The event name, for example `aipTrashed`.
`category`	string	The event category.
`severity`	string	`INFO`, `WARNING`, or `ERROR`. Missing when the event has no severity.
`message`	string	A readable description of what happened. When the event has no message of its own, it holds the event's comment.
`packageId`	string	The package that the event is about. When the event doesn't record one, it's the package ID in your request, or it's missing.
`packageType`	string	The type of package, for example `SIP`, when the event records it.
`user`	string	The user who triggered the event.
`time`	string (date-time)	When the event happened.
`logDate`	string (date-time)	When the archive recorded the event.
`repository`	string	The tenant where the event happened.
`docPath`	string	The path of the package, SIP, or deletion list that the event is about, at the time of the event.
`docType`	string	The type of what the event is about, for example `AIP` for a package or `SIP` for a SIP.
`docLifeCycle`	string	Its lifecycle state at the time of the event, for example `approved` for a package.
`comment`	string	A comment on the event, when there is one.
`extendedInfo`	object	More details as key and value pairs, for example `title`, `targetRepo`, or `reason`. All values are strings.

ExportResult

Field	Type	Description
`downloadUrl`	string	The link to download the CSV file. By default, it's valid for 60 minutes.