List contract reviews

Read the protected review queue for the selected organization and workspace.

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 intended authorized workspace and read its review queue.
2. Inspect stable review ids, status, route and captured policy versions; distinguish ready, in_review, escalated and approved.
3. Read a specific review before any version-sensitive write or document export.

Identifiers

• Use returned review ids; a title/counterparty is descriptive and not a unique authorization binding.

Request

GET /api/reviews

Action: app_topolo_contracts.reviews.list.

Use the empty object {}. Resource/workspace selection belongs outside the action input; do not add undeclared fields.

Response and effects

• Reads/decrypts all scoped stored review records ordered by creation time descending and removes private document object keys. It does not load and parse every original DOCX like reviews.get.
• The source exposes no pagination fields here. List metadata is not a live verification of every original document or provider/notification outcome.
• Approved reviews are completed workflow decisions, not signed agreements. An empty queue differs from storage/protection unavailability.

Examples

Example request and response

Request input:

{}

Illustrated response:

{
  "reviews": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "title": "Documentation specimen",
      "counterparty": "Example Beta",
      "contractType": "Mutual NDA",
      "owner": "Legal review",
      "route": "review",
      "status": "in_review",
      "submittedAt": "2026-10-21T00:00:00.000Z",
      "dueAt": "Not set",
      "policyPack": "Workspace mutual NDA",
      "policyVersion": "1",
      "policyApproval": {
        "policyId": "default",
        "contractType": "mutual_nda",
        "version": 1,
        "confidentialityYears": 3,
        "governingLaw": "England and Wales",
        "approvedBy": "user_documentation_fixture",
        "approvedAt": "2026-10-21T00:00:00.000Z"
      },
      "version": 1,
      "recommendation": "Human review is required before approval.",
      "coverage": {
        "missingClauses": [
          "Confidentiality period",
          "Governing law"
        ],
        "unverifiedQuotes": 0,
        "sourceInventoryVersion": 1
      },
      "findings": [
        {
          "id": "44444444-4444-4444-8444-444444444444",
          "clause": "Other",
          "severity": "review",
          "summary": "Illustrative human check required.",
          "aiExplanation": "Illustrative human check required.",
          "evidence": "Synthetic documentation specimen for Example Alpha and Example Beta. This main-body paragraph demonstrates source retention and a human review workflow. It forms no agreement, provides no approved legal terms and asserts no actual approval.",
          "policy": "Any unclassified contractual deviation requires human review.",
          "confidence": 0.5,
          "source": "model",
          "paragraph": 0,
          "suggestedText": "Synthetic documentation specimen for Example Alpha and Example Beta. This main-body paragraph demonstrates source retention and a human review workflow. It forms no agreement, provides no approved legal terms and asserts no actual approval. Human check remains required.",
          "resolution": "pending"
        }
      ],
      "sourceParagraphs": [
        {
          "index": 0,
          "text": "Synthetic documentation specimen for Example Alpha and Example Beta. This main-body paragraph demonstrates source retention and a human review workflow. It forms no agreement, provides no approved legal terms and asserts no actual approval.",
          "originalText": "Synthetic documentation specimen for Example Alpha and Example Beta. This main-body paragraph demonstrates source retention and a human review workflow. It forms no agreement, provides no approved legal terms and asserts no actual approval."
        }
      ],
      "document": {
        "filename": "documentation-specimen.docx",
        "sha256": "6ca130ea78e011afbd4384bbe0ee82ea155a8bb65b7cad0f17932c3b402c6174",
        "redlines": []
      }
    }
  ]
}

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

Refusal or dependency failure

If: Authentication succeeded, but the verified principal has no organization id. The empty action input does not itself cause this; the source refuses before workspace resolution.

Request input:

{}

Source error-code excerpt (HTTP 403):

{
  "error": "organization_context_required"
}

Keep the intended organization/workspace context; do not guess ids across tenants.

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; do not report zero reviews from a refusal.

Verified empty review queue

Request input:

{}

Illustrated response:

{
  "reviews": []
}

HTTP 200 illustration. A successful scoped empty list does not establish absence in another workspace.

Verify the result

• Open reviews.get for the intended id and confirm its current version and source before acting. Use audit.list for decision history.

Recovery

• 403 organization_context_required: Keep the intended organization/workspace context; do not guess ids across tenants.
• 503 contracts_protection_unavailable: Restore protection readiness; do not report zero reviews from a refusal.
• 401 authentication_required: Outer authentication/authorization contract: Authenticate again with an entitled Contracts credential. Reconcile uncertain earlier write effects before any retry.
• 403 permission_denied: Outer authentication/authorization contract: Grant workspace:read without changing the organization context. 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 only after the failed read dependency recovers, with the same authorized scope.

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.