Remediation APICopy Anchor Link

These endpoints are additive to existing API v1 contracts and are designed to mirror the same remediation workflow available in the console UI and CLI.

Get Working DraftCopy Anchor Link

GET /api/v1/documents/{documentId}/working-draft

Returns editable working-copy spans derived from digitized content.

ResponseCopy Anchor Link

{
  "documentId": "uuid",
  "fileName": "sample-lease.pdf",
  "utility": "duke-energy",
  "state": "NC",
  "spans": [
    {
      "id": "uuid",
      "spanId": "span_4_12_abc123",
      "pageNumber": 4,
      "lineNumber": 12,
      "charStart": 1421,
      "charEnd": 1472,
      "originalText": "Lease shall remain in effect for twenty years",
      "currentText": "Lease shall remain in effect for twenty-five years",
      "normalizedText": "lease shall remain in effect for twenty five years",
      "lineHint": null,
      "isEdited": true,
      "editedAt": "2026-03-05T16:20:00.000Z"
    }
  ],
  "stats": {
    "total": 530,
    "edited": 4
  }
}

Patch Working Draft SpanCopy Anchor Link

PATCH /api/v1/documents/{documentId}/working-draft/spans/{spanId}

Updates a single working span and records remediation audit metadata.

spanId accepts either:

• the span row UUID (spans[].id), or
• the stable span token (spans[].spanId, e.g. span_4_12_abc123)

BodyCopy Anchor Link

{
  "text": "Lease shall remain in effect for twenty-five years",
  "deficiencyId": "optional-deficiency-uuid"
}

Create Remediation Export BundleCopy Anchor Link

POST /api/v1/remediation/exports

Creates clean/redline/evidence artifacts and returns a poll handle.

BodyCopy Anchor Link

{
  "documentId": "uuid",
  "format": "bundle",
  "sessionId": "optional-session-uuid"
}

sessionId is optional and links the export to an application or validation session when available.

At creation time, the export manifest records the source document ID, content hash, and version number. Those values are immutable for that export.

ResponseCopy Anchor Link

{
  "exportId": "uuid",
  "status": "processing",
  "pollUrl": "/api/v1/remediation/exports/uuid",
  "export": {
    "id": "uuid",
    "documentId": "uuid",
    "format": "bundle",
    "status": "processing",
    "cleanDocumentUrl": null,
    "redlineDocumentUrl": null,
    "evidencePacketUrl": null
  }
}

Get Remediation ExportCopy Anchor Link

GET /api/v1/remediation/exports/{exportId}

Fetches status and generated artifact links.

Possible status values:

• pending
• processing
• complete
• failed

When complete, the payload includes:

• cleanDocumentUrl
• redlineDocumentUrl
• evidencePacketUrl

Completion and promotion use the stored source identity, not the document's later current identity. If the project link or source generation has changed, the operation returns the canonical stale-export failure and commits no artifact attachment, promoted document, link change, version, or manifest change.

Exporting a working copy does not grant permission to replace source-owned packet evidence. Promotion refuses a Salesforce-owned packet before rendering and checks again under the packet lock before writing. Correct the record or files in Salesforce; the separate connector capture workflow remains planned and disabled.

The remediation routes are always on: the environment feature gates that once returned FEATURE_DISABLED were removed on 2026-08-26 after being hardcoded enabled, so generated clients no longer need to handle that code on these routes. The routes are included in the complete authenticated partner OpenAPI document so generated clients match the live REST surface. That document is built by lib/api/v1/full-openapi.ts and shared by both authenticated copies. The remediation routes are intentionally absent from the curated agent specification, which lists only active partner packet operations whose REST and hosted-MCP bindings are both available.

The shared OpenAPI document now also includes native-DWG intake routes under /api/v1/packets. Those routes do not alter remediation drafts or exports; CAD intake is documented in Partner Packets.

Related EndpointsCopy Anchor Link

• GET /api/v1/deficiency-reports returns normalized workingAnchor and sourceAnchor, plus findingState (open, resolved, or superseded). Use findingState=open for findings that still need review resolution.
• locationStatus filters anchor quality (exact, approximate, unresolved, or pending). remediationStatus filters the applicant's fix progress; setting it to resolved does not close a finding. Only a review closes a finding.
• The legacy status alias accepts all three families. open, resolved, and superseded select finding state; use the explicit remediationStatus parameter to filter fix progress by open or resolved.

CLI EquivalentsCopy Anchor Link

The same operations are available in the CLI:

• gridwonk remediation draft get --document-id <id>
• gridwonk remediation draft patch --document-id <id> --span-id <id> --text "<value>"
• gridwonk remediation export create --document-id <id> --format bundle
• gridwonk remediation export get --export-id <id>