Analyze retained contract

Explicitly analyze a retained intake against its captured policy and preserve a durable failed or completed outcome.

Access

Requires app_topolo_contracts.workspace:write 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. Honor the action’s explicit confirmation requirement, including for a GET export. Any required JSON confirmation value is separate from transport/client confirmation.

Steps

1. Read the intake, its current version, status, attempts and failure code.
2. Request analysis only for the authorized retained source and current version; an active 180-second analysis lease refuses concurrent execution.
3. Inspect the returned intake status even when HTTP is 200. Read the review only when completed and reviewId is returned.

Identifiers

• Use the id/version returned by intakes.get; the completed review shares the intake id. Do not substitute a freshly uploaded document for a retry.

Request

POST /api/intakes/{intakeId}/analyze

Action: app_topolo_contracts.intakes.analyze.

• intakeId: required, UUID.
• expectedVersion: required, integer.

Response and effects

• Claims a new version and analysis attempt, verifies/decrypts and parses retained source bytes, sends the analysis request through the configured provider, then conditionally persists the result.
• A successful result creates a source-linked review and audit/outbox records. Provider/storage/source failures can persist status failed with an allowlisted error and no review. Failed analysis is not equivalent to failed retention.
• Analysis can consume configured paid model capacity and disclose submitted content to the configured provider; this guide grants no spending or provider-retention guarantee.
• A 200 response can carry intake.status=failed. Read error rather than exposing raw provider details; running/failed/completed are distinct. Historical or uncertain provider effects are not reset by an example.

Examples

Example request and response

Request input:

{
  "intakeId": "11111111-1111-4111-8111-111111111111",
  "expectedVersion": 1
}

Illustrated response:

{
  "intake": {
    "id": "11111111-1111-4111-8111-111111111111",
    "title": "Documentation specimen",
    "counterparty": "Example Beta",
    "contractType": "mutual_nda",
    "filename": "documentation-specimen.docx",
    "sha256": "6ca130ea78e011afbd4384bbe0ee82ea155a8bb65b7cad0f17932c3b402c6174",
    "status": "completed",
    "version": 3,
    "attempts": 1,
    "createdAt": "2026-10-21T00:00:00.000Z",
    "leaseUntil": null,
    "reviewId": "11111111-1111-4111-8111-111111111111",
    "error": null,
    "policyId": "default",
    "policyVersion": 1,
    "policyApprovedBy": "user_documentation_fixture",
    "policyApprovedAt": "2026-10-21T00:00:00.000Z"
  }
}

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

Refusal or dependency failure

If: The retained intake has already advanced to version 2; this request still supplies expectedVersion 1.

Request input:

{
  "intakeId": "11111111-1111-4111-8111-111111111111",
  "expectedVersion": 1
}

Source error-code excerpt (HTTP 409):

{
  "error": "intake_version_conflict"
}

Reload the intake and reconcile the actual prior attempt.

Refusal or dependency failure

If: The action has an otherwise valid authorized context and input, but the source-document storage binding is unavailable. For a review read, the stored review still references a document.

Request input:

{
  "intakeId": "11111111-1111-4111-8111-111111111111",
  "expectedVersion": 1
}

Source error-code excerpt (HTTP 503):

{
  "error": "contracts_documents_unavailable"
}

Restore access to the retained source through its existing owner; do not upload duplicates as a probe.

HTTP success with a retained failed analysis

Request input:

{
  "intakeId": "11111111-1111-4111-8111-111111111111",
  "expectedVersion": 1
}

Illustrated response:

{
  "intake": {
    "id": "11111111-1111-4111-8111-111111111111",
    "title": "Documentation specimen",
    "counterparty": "Example Beta",
    "contractType": "mutual_nda",
    "filename": "documentation-specimen.docx",
    "sha256": "6ca130ea78e011afbd4384bbe0ee82ea155a8bb65b7cad0f17932c3b402c6174",
    "status": "failed",
    "version": 3,
    "attempts": 1,
    "createdAt": "2026-10-21T00:00:00.000Z",
    "leaseUntil": null,
    "reviewId": null,
    "error": "contract_analysis_timeout",
    "policyId": "default",
    "policyVersion": 1,
    "policyApprovedBy": "user_documentation_fixture",
    "policyApprovedAt": "2026-10-21T00:00:00.000Z"
  }
}

HTTP 200 illustration. HTTP 200 carries status failed and contract_analysis_timeout; no completed review is established.

Verify the result

• Confirm completed plus reviewId before reviews.get; for failed, retain its current version, attempts and allowlisted error. Notification outbox creation is not delivery proof.

Recovery

• 409 intake_version_conflict: Reload the intake and reconcile the actual prior attempt.
• 409 intake_analysis_in_progress: Do not launch a parallel attempt while its lease is active.
• 409 intake_already_completed: Read the existing review rather than running analysis again.
• 503 contracts_documents_unavailable: Restore access to the retained source through its existing owner; do not upload duplicates as a probe.
• 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:write 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.

A failed intake may be retried explicitly with its newly observed current version after the cause is resolved. Reconcile an expired/uncertain running attempt and provider effects first; do not replay automatically or replace the captured policy.

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.