Audit actions

The audit log is append-only and kept per application. Every sensitive operation writes one row before it answers; if the row cannot be written, the operation fails. This page lists every action and what a row holds. It is for administrators, for backends that read the log, and for evaluators.

Permission: files.audit.read

A row

{
  "audit_id": "01J9Z7A2B3C4D5E6F7G8H9J0K1", "tenant_id": "fitness-co", "application_id": "fitness-app", "at": "2026-10-22T09:30:00.000Z",
  "actor": { "type": "client", "client_id": "fitness-backend", "acting_user_id": "user-ana" },
  "action": "file.downloaded",
  "target": { "type": "file", "id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "contract.pdf" },
  "ip": "203.0.113.7", "user_agent": "…",
  "metadata": { "version_no": 2, "size": 1048576, "expires_in_seconds": 900 }
}

actor.type is user, client (a backend client, with acting_user_id when it named one) or system (processing, retention).
metadata holds a fixed list of facts per action: never file contents, extracted text, tokens or passwords.
Reading metadata and previews is not logged. Downloads of originals are, one row per minted download URL (not per byte).

Reading the log

Route	Answers
`GET P/audit`	The application’s rows, newest first, filtered by `action`, `actor_user_id`, `actor_client_id`, `target_type`, `target_id`, `from` and `to`; paged
`GET P/audit/export`	The same filters as JSON lines (`application/x-ndjson`), up to 100,000 rows
`GET P/files/:file_id/audit`, `GET P/folders/:folder_id/audit`	One item’s rows: `view` on it plus `files.audit.read`, or `files.manage`

Rows are kept 365 days. A machine client reads the log with files:config.manage.

Some rows belong to the tenant rather than one application (application_id: null): changes to the tenant’s ceilings, and the platform administrators’ reads and exports of the tenant’s log and usage (tenant_audit.read, audit.exported, usage.exported, with the target { type: "tenant", id }). An application’s routes above never show them; platform administrators read them, with every application’s rows, through GET /platform/tenants/:tenant_id/audit and GET /platform/tenants/:tenant_id/audit/export (Platform administration). A tenant’s storage assignment and its moves are tenant rows too (tenant_storage.assigned, storage_migration.*); changes to the storage accounts themselves (storage_account.*) belong to no tenant.

The actions

Actions marked as coming are declared and written once their feature exists.

Files

Action	Written when
`file.created`	An upload completed: the file exists with its first version.
`file.version.created`	A new version was uploaded and became current.
`file.version.deleted`	An old version was deleted.
`file.version.restored`	An old version was copied into a new current version.
`file.renamed`	The file's name changed.
`file.moved`	The file moved to another folder.
`file.copied`	The file was copied (the row is written for the new file).
`file.metadata.updated`	Title, description, category, department, tags, custom metadata or `external_ref` changed.
`file.status.changed`	The approval status changed (`from`, `to`).
`file.visibility.changed`	The visibility changed between `private`, `application` and `public`.
`file.trashed`	The file moved to the trash.
`file.restored`	The file came back from the trash.
`file.purged`	The file and every version were deleted for good (on request, or when the trash retention ended).
`file.downloaded`	A download URL for the original was minted with `disposition=attachment`: one row per URL, not per byte.
`file.quarantined`	Malware scanning found the file infected and quarantined it.
`file.rejected`	Processing refused the file: its detected type did not match, its type is not allowed, or its checksum differed.
`file.owner.changed`	The file was given another owner.
`file.checked_out`	The file was checked out for editing. Coming
`file.checked_in`	A checked-out file was checked in with a new version. Coming
`file.lock.broken`	Someone with `files.manage` broke another user's check-out. Coming

Legal hold

Action	Written when
`hold.placed`	Someone with `files.manage` placed a legal hold on the file (`reason`, `until`).
`hold.updated`	The reason or the end of a legal hold in force changed (`previous_reason`, `previous_until`).
`hold.released`	A legal hold ended: released by someone with `files.manage` (with their optional `reason`), or by the system with `reason: expired` once `until` passed. The row keeps the hold's reason, who placed it, when and its end.

Folders

Action	Written when
`folder.created`	A folder was created.
`folder.renamed`	The folder's name changed.
`folder.moved`	The folder moved under another parent, with its subtree.
`folder.copied`	The folder was copied with its subtree.
`folder.updated`	The folder's description, metadata or owner changed.
`folder.trashed`	The folder moved to the trash with its subtree.
`folder.restored`	The folder came back from the trash with its subtree.
`folder.purged`	The folder and its subtree were deleted for good.
`folder.managed`	A machine client marked the folder application-managed, on creation or later: it and its subtree became read-only for people (`client_id`, `name`).
`folder.unmanaged`	A machine client removed the application-managed mark from the folder (`client_id`, `name` of the removed mark).
`folder.management_released`	The tenant owner released an application-managed folder in an emergency (`reason`, and the `client_id` and `name` of the released mark).

Access entries

Action	Written when
`entry.granted`	An access entry was added to a file or folder.
`entry.revoked`	An access entry was removed.
`inheritance.changed`	A file or folder stopped or started inheriting its parent's entries.

Role matrix

Action	Written when
`permissions.updated`	The role matrix changed: what a role may do in the application.

Action	Written when
`share.created`	A share link was created.
`share.revoked`	A share link was revoked.
`share.accessed`	A share link was opened or downloaded from, with the IP address.
`share.password_failed`	A wrong password was tried on a share link.

Administration

Action	Written when
`settings.updated`	The application's settings changed, with the values before and after.
`quota.updated`	The application's quota changed.
`usage.reconciled`	The stored bytes were counted again and the usage was corrected by more than a small margin.
`taxonomy.updated`	A managed value list (categories or departments) changed.

Platform administration

Action	Written when
`tenant_settings.updated`	A platform administrator changed the tenant's ceilings (quota, sizes, types, visibility, share links, suspension).
`platform_settings.updated`	A platform administrator changed the platform defaults for new tenants.
`tenant_audit.read`	A platform administrator read the tenant's audit log across its applications (the filters and the number of rows).
`audit.exported`	A platform administrator exported the tenant's audit log (the format, the filters and whether the row cap cut it). Written before the first row.
`usage.exported`	A platform administrator exported the tenant's daily usage (the format and the period).

Trash

Action	Written when
`trash.emptied`	Someone with `files.manage` emptied the trash.

Webhooks

Action	Written when
`webhook.updated`	The application's webhook changed.
`webhook.disabled`	The webhook was switched off after repeated failed deliveries.

Storage

Action	Written when
`storage_account.created`	A platform administrator added a storage account; it was probed before it was saved. Credentials are never in the row.
`storage_account.updated`	A storage account was renamed, given new credentials or a new location.
`storage_account.verified`	A storage account was probed again (the outcome).
`storage_account.deleted`	A storage account no tenant used was removed. Its stored bytes are not touched.
`tenant_storage.assigned`	The tenant was assigned to another storage account: its new files go there.
`storage_migration.started`	A move of the tenant's files to another storage account started.
`storage_migration.switched`	Every file of the tenant was copied and verified, and the tenant switched to the target account.
`storage_migration.completed`	The move finished: the copies in the source account were deleted.
`storage_migration.failed`	The move stopped after repeated failures; files already moved stay readable where they are.