---
title: "Set organization audit capture"
method: PATCH
path: "/v1/audit/settings"
tags: ["Organizations"]
---

# Set organization audit capture

`PATCH /v1/audit/settings`

Fresh organization administrator authorization, literal metadata.capabilities.auditLogs=true and visibility required. Only captureOn and expectedRevision are accepted. Enabling requires Enterprise or explicit installation entitlement and capture rollout availability. A missing policy is initialized with server-owned temporary defaults; expectedRevision=0 is accepted only by the initializing request. Explicit OFF initializes and disables atomically, never publishing intermediate ON. Disabling remains available after entitlement loss while flagged. Revision conflicts require refresh; matching no-ops do not record duplicate events. Changes and immutable lifecycle evidence commit atomically. Existing capacity configuration and retained history are unchanged.

## Request body

- object
  - `captureOn` boolean, required
  - `expectedRevision` integer, required

## Response `200`

Latest audit policy, entitlement and retained usage.

- object
  - `entitlement` object, required
    - `enabled` boolean, required
    - `source` 'enterprise_plan' | 'self_hosted' | 'none', required
  - `captureOn` boolean, required
  - `captureAvailable` boolean, required
  - `policy` object, nullable, required
    - `organizationId` string, required
    - `revision` integer, required
    - `source` 'cloud' | 'operator', required
    - `enabled` boolean, required
    - `categories` string[], required
    - `allowance` integer, required
    - `excessMode` 'delete_oldest' | 'paid_overage' | 'keep_all', required
    - `effectiveAt` string, date-time, required
    - `captureStartedAt` string, date-time, nullable, required
    - `attachmentWindowSeconds` integer, required
  - `captureEnabled` boolean, required
  - `retainedOperations` integer, required
  - `eventCount` integer, required
  - `logicalBytes` integer, required
  - `oldestAvailableAt` string, date-time, nullable, required
  - `measuredAt` string, date-time, nullable, required
  - `billing` 'disabled', required
  - `cleanup` 'dry_run', required
  - `drains` 'not_configured', required

## Other responses

- `400` — Only captureOn and a nonnegative safe expectedRevision are accepted.
- `401` — Authentication required.
- `402` — Enabling capture requires audit availability.
- `403` — Administrator permission, fresh authentication, audit feature and visibility required.
- `404` — Organization or retained operation not found, including foreign-tenant targets.
- `409` — Refresh a changed policy or wait for capture rollout.
- `410` — Cursor expired or retained snapshot anchors/history are no longer available.
- `503` — Audit storage or required access capture unavailable; no audit content is released.

## Changes

- **2026-09-30** `0d10fe7f6aa1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/audit/settings/patch.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) · [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/406852f37cc0?raw)