Audits

import { Aside } from ‘@astrojs/starlight/components’;

List audits (organization)

GET /v1/organizations/:orgId/audits

Required role: Member.

Returns a paginated list of audits across all non-archived products in the organization, including productName and productSlug fields.

Query parameters:

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`).
`pageSize`	`integer`	Results per page (default: `20`, max: `100`).
`status`	`"in_progress" \| "completed"`	Filter by status. Comma-separated for multiple values.
`type`	`"full" \| "re_audit" \| "small_scope"`	Filter by audit type. Comma-separated for multiple values.
`productId`	`string`	Filter to a specific product.
`sortField`	`"createdAt" \| "startedAt" \| "completedAt"`	Field to sort by (default: `"createdAt"`).
`sortDirection`	`"asc" \| "desc"`	Sort direction (default: `"desc"`).

Response:

{
  "audits": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 42,
    "totalPages": 3
  }
}

Future audit schedule

GET /v1/organizations/:orgId/future-audits

Required role: Member.

Returns a computed list of upcoming audit dates for all active products that have an audit frequency configured and no full audit currently in progress.

Response:

{
  "futureAudits": [
    {
      "productId": "...",
      "productName": "My Product",
      "productSlug": "my-product",
      "nextAuditDate": "2025-06-01T00:00:00.000Z",
      "isOverdue": false,
      "auditFrequency": 12,
      "lastAuditDate": "2024-06-01T00:00:00.000Z",
      "lastAuditNumber": 3
    }
  ]
}

nextAuditDate is calculated from the most recent completed full audit’s completedAt date plus the effective frequency. If no completed full audit exists, the product’s createdAt date is used.
isOverdue is true when nextAuditDate is in the past.
Products with an in-progress full audit are excluded.
Results are sorted by nextAuditDate ascending.

List audits (product)

GET /v1/organizations/:orgId/products/:productSlug/audits

Required role: Member.

Same query parameters as the organization-level list, except productId (fixed by the URL).

Response: Same shape as the organization-level list.

Create an audit

POST /v1/organizations/:orgId/products/:productSlug/audits

Required role: Member.

Cannot create an audit for an archived product — returns 409 Conflict.

Request body:

Field	Type	Default	Description
`type`	`"full" \| "re_audit" \| "small_scope"`	`"full"`	Audit type.
`title`	`string \| null`	—	Optional title (max 200 characters).
`description`	`string \| null`	—	Optional description (max 2000 characters).
`status`	`"in_progress" \| "completed"`	`"in_progress"`	Initial status.

startedAt is set to the current time automatically. If status is "completed", completedAt is also set to now. The standardId and conformanceLevel are inherited from the product (or organization defaults if the product has none).

Audit numbers are sequential per product, assigned atomically.

Returns 201 Created with a Location header.

Get an audit

GET /v1/organizations/:orgId/products/:productSlug/audits/:auditNumber

Required role: Member.

:auditNumber is the sequential integer audit number, not a UUID.

Update an audit

PATCH /v1/organizations/:orgId/products/:productSlug/audits/:auditNumber

Required role: Member.

Request body (all fields optional):

Field	Type	Description
`type`	`"full" \| "re_audit" \| "small_scope"`	Audit type.
`title`	`string \| null`	Title.
`description`	`string \| null`	Description.
`status`	`"in_progress" \| "completed"`	Transitioning to `"completed"` auto-sets `completedAt` if not already set. Transitioning to `"in_progress"` auto-sets `startedAt` if not already set.
`startedAt`	`string (ISO 8601) \| null`	Override the start date.
`completedAt`	`string (ISO 8601) \| null`	Override the completion date.
`standardId`	`string \| null`	Override the standard for this audit.
`conformanceLevel`	`string \| null`	Override the conformance level. Must be valid for the given standard.

Delete an audit

DELETE /v1/organizations/:orgId/products/:productSlug/audits/:auditNumber

Required role: Admin or owner.

Returns 204 No Content.

List issues for an audit

GET /v1/organizations/:orgId/products/:productSlug/audits/:auditNumber/issues

Required role: Member.

Returns all issues linked to the specified audit.