Runs and Reprocessing

Create a processing run during upload or apply a new configuration to a document that is already stored.

Start processing during upload

Provide either:

• processing_config_id for a saved configuration
• pipeline_config for one-time custom settings

The accepted document includes latest_run with the new run identifier and initial pending status.

Omit both fields when the file should be stored without processing. See Uploading Documents for multipart, base64, and direct upload examples.

Process existing documents in Shipwell

1. Open Document AI .
2. Select one or more stored documents.
3. Choose the processing action.
4. Select an enabled named configuration or custom processing settings.
5. Confirm the request.

Process existing documents through the API

Create one new run for each accepted document:

curl -X POST "https://sandbox-api.shipwell.com/document-store/runs" \
  -H "Authorization: Token <user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": [
      "<document-id-1>",
      "<document-id-2>"
    ],
    "processing_config_id": "<processing-config-id>"
  }'

import requests

response = requests.post(
    "https://sandbox-api.shipwell.com/document-store/runs",
    headers={"Authorization": "Token <user-token>"},
    json={
        "document_ids": ["<document-id-1>", "<document-id-2>"],
        "processing_config_id": "<processing-config-id>",
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()

Exactly one of processing_config_id or pipeline_config is required. Document identifiers must be unique within the request.

The endpoint returns 202 Accepted:

{
  "runs": [
    {
      "document_id": "<document-id-1>",
      "id": "<run-id>"
    }
  ],
  "skipped": [
    {
      "document_id": "<document-id-2>",
      "decision": "skipped",
      "reason": "<eligibility-reason>"
    }
  ]
}

Keep every returned run id for monitoring. A skipped document does not receive a run.

View run history

Use GET /document-store/documents/{id}/runs to retrieve a document's runs, newest first.

Use run history to:

• Compare results after a configuration change
• Audit the configuration snapshot used for an attempt
• Diagnose a failed attempt without losing a prior successful result
• Retrieve results for a specific historical run

Reprocessing behavior

Reprocessing creates a new run; it does not replace prior runs.

If the new run completes:

• The document's latest results point to the new output.
• Auto-description can replace the document's current description.
• Previous runs and results remain available through run history.

Store the relevant run_id when your integration requires historical reproducibility.

When to reprocess

Create a new run when:

• You changed an extraction schema.
• You need to apply a different platform-managed configuration.
• A previous run failed because of a corrected input or configuration.
• You enabled splitting, descriptions, or semantic search for an existing document.

Do not create duplicate runs only because an accepted run is still pending or processing. Monitor it using How Processing Works.