Topolo Docs Topolo Platform
Open workspace

List contract audit events

Inspect retained review and intake history in the selected workspace, using a stable two-part cursor for older events.

Inspect retained review and intake history in the selected workspace, using a stable two-part cursor for older events.

Access

Requires app_topolo_contracts.workspace:read and the intended authenticated organization and workspace. Select the permitted workspace through the supported resource-binding flow; do not add a workspace id to strict action input.

Steps

  1. Select the authorized organization and workspace, then optionally narrow to a discovered reviewId.
  2. Read up to 100 events. When nextCursor is non-null, pass both recordedAt as beforeRecordedAt and id as beforeId.
  3. Keep the same scope and review filter across pages; stop when nextCursor is null.

Identifiers

  • Use review identifiers returned by reviews.list or intakes.list. A cursor must come from the prior authorized response, not a guessed timestamp.

Request

GET /api/audit

Action: app_topolo_contracts.audit.list.

Optionally provide reviewId. To read an older page, supply both beforeRecordedAt (a UTC timestamp) and beforeId from the previous response cursor; either cursor field alone is invalid.

Response and effects

  • Reads and decrypts the scoped union of review_events and intake_events. Intake events use their intake identifier in the reviewId field and carry empty evidence.
  • Orders by recordedAt descending, then id descending; the worker reads 101 rows and returns the first 100 plus a cursor only when more exist.
  • A history page is not an independent legal decision or proof of notification delivery. Empty results can mean no events in this filter, not no reviews anywhere.
  • History erased by contract deletion or outside this workspace cannot be reconstructed by this endpoint.

Examples

Example request and response

Request input:

{}

Illustrated response:

{
  "events": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "reviewId": "11111111-1111-4111-8111-111111111111",
      "event": "Document retained",
      "evidence": "",
      "actor": "user_documentation_fixture",
      "recordedAt": "2026-10-21T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}

HTTP 200 illustration. Hypothetical authorized operation only; inspect the action-specific fields and boundaries below.

Invalid input: stop before sending

beforeRecordedAt is supplied without the required beforeId cursor partner.

{
  "beforeRecordedAt": "2026-10-21T00:00:00.000Z"
}

The action input schema rejects this incomplete cursor before a request is sent. The reviewed raw GET handler would return 400 invalid_audit_query for this invalid query if the client-side schema were bypassed. No raw request or carrier is verified.

Refusal or dependency failure

If: The workspace grant and storage binding are present, but protection readiness or protected-database initialization fails before the action handler runs.

Request input:

{}

Source error-code excerpt (HTTP 503):

{
  "error": "contracts_protection_unavailable"
}

Restore protection readiness through its existing owner; never interpret the refusal as an empty audit page.

Older page with no further events

Request input:

{
  "reviewId": "11111111-1111-4111-8111-111111111111",
  "beforeRecordedAt": "2026-10-21T00:00:00.000Z",
  "beforeId": "22222222-2222-4222-8222-222222222222"
}

Illustrated response:

{
  "events": [],
  "nextCursor": null
}

HTTP 200 illustration. This hypothetical earlier page is empty for the same scoped filter.

Verify the result

  • Check reviewId/actor/event and the two-part cursor; compare a discovered review in the same workspace when investigating a specific decision.

Recovery

  • 400 invalid_audit_query: Supply both cursor fields together and use a valid UTC timestamp.
  • 503 contracts_protection_unavailable: Restore protection readiness through its existing owner; never interpret the refusal as an empty audit page.
  • 401 authentication_required: Outer authentication/authorization contract: Authenticate again or provide a valid Topolo API key. Reconcile uncertain earlier write effects before any retry.
  • 403 permission_denied: Outer authentication/authorization contract: Grant the credential permission workspace:read and the required resource binding. Reconcile uncertain earlier write effects before any retry.
  • 429 rate_limited: Outer authentication/authorization contract: Wait for Retry-After when present, then retry without parallel duplicate calls. Reconcile uncertain earlier write effects before any retry.

Read-only: retry a failed page only after the dependency recovers, retaining the exact scope and cursor. Do not record a new decision to test history.

Source and example limits — 21 October 2026: based on reviewed Contracts source 4bfd49a; current serving association is unverified. All requests, responses, approvals and document specimens shown are fictional and unrun. Offline schema/ZIP/XML checks do not prove application acceptance, legal completeness, provider outcomes or human approval.