Revalidate Document

Re-runs validation for a document that has already been extracted. Use it when a validation script changed, when a validation agent run died, or when a document is stuck without a settled validation result.

Each call starts a new validation attempt: the affected CustomValidationResult rows are reset to PENDING under a freshly minted validationAttemptId, and a DOCUMENT_VALIDATION_STARTED event is emitted for every branch that actually dispatched. The attempt settles as usual with DOCUMENT_VALIDATED, or with DOCUMENT_VALIDATION_FAILED if it dies first.

Parameters

The request body is optional — an empty body re-runs both branches.

• STATIC — re-enqueues the deployment's enabled validation scripts as one batch.
• AGENT — creates and enqueues a run for every active validator agent routed to the deployment.

Only the requested branches are reset. Asking for STATIC alone leaves an in-flight agent validation untouched, and asking for AGENT alone leaves the script results untouched, so the branch you did not ask for never ends up stuck at PENDING.

Partial Revalidation and Settlement

DOCUMENT_VALIDATED is emitted when the document settles, not when a branch settles. Settlement aggregates every validation row on the file, so a branch you did not re-run still counts.

The consequence is deliberate. If you call {"include": ["STATIC"]} on a document whose validator agent is still in flight, the static batch will finish and write its results, but no DOCUMENT_VALIDATED is emitted while the agent-validator row is still PENDING — the document is not validated yet, and the event would be saying something untrue if it fired. The same holds in reverse for {"include": ["AGENT"]} while a static batch is running.

What that costs you in latency:

• The agent run finishes normally. The document settles as soon as the agent submits, and DOCUMENT_VALIDATED carries both branches. This is the common case and adds no delay beyond the run itself.
• The agent run dies. The failure is bridged to the document — the agent-validator row flips to ERROR, DOCUMENT_VALIDATION_FAILED is emitted with reason: "AGENT_RUN_FAILED", and the document settles immediately.
• The agent run hangs, or was never dispatched. The validation watchdog picks it up. It runs inside the stale-job cron every 10 minutes, considers a row stalled after 15 minutes without progress, and hard-fails any attempt still unsettled 60 minutes after it started. Worst case is therefore roughly an hour before DOCUMENT_VALIDATED arrives with status: "error".

The attempt ids in the settled payload tell you which branch is which: data.validationAttemptId is the newest attempt, while each entry of data.results carries its own validationAttemptId, so a result from the lane you did not re-run keeps its older id. See DOCUMENT_VALIDATED.

If you want a settled event promptly and do not care about preserving the other lane's in-flight work, re-run both branches — the default empty body — which resets every row onto one fresh attempt.

Request

const res = await fetch(
"https://app.limai.io/api/v1/deployments/dep_abc123/documents/file_001/revalidate",
{
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ include: ["AGENT"] }),
}
);
const result = await res.json();

Response

{
  "fileId": "file_001",
  "static": {
    "enqueued": true,
    "scriptCount": 2
  },
  "agent": {
    "runIds": [
      "run_abc123"
    ]
  }
}

• static.scriptCount — how many enabled validation scripts the batch covers.
• static.enqueued — whether the static batch was actually enqueued. false with scriptCount: 0 when the deployment has no enabled scripts, or when STATIC was not requested.
• agent.runIds — the validator agent runs now responsible for the document. Empty when AGENT was not requested or no validator agent routes to the deployment.

Nothing is hidden: a call that dispatched nothing returns {"static": {"enqueued": false, "scriptCount": 0}, "agent": {"runIds": []}} with a 200, which means the deployment has no validation configured for the requested branches.

Idempotency

The only deduplication is at the agent-run level. If a validator agent already has a non-terminal run for the same document, that run is returned in runIds and is not enqueued a second time. Wait for it to finish (or for DOCUMENT_VALIDATED) before retrying. Static batches are not deduplicated — every call re-enqueues them.

Billing

Every dispatch is billed through the normal usage paths, and only a dispatch is billed:

• A static batch is charged on every enqueue, so each STATIC call costs the same as the first validation.
• An agent branch is charged only when it creates a new run. When an active validator run is reused (see Idempotency), nothing is enqueued and nothing extra is charged.

So a repeated request does not always cost the same — it costs what it actually dispatched.

Errors

A body that is present but not valid JSON is rejected — it is never treated as an empty body, so a malformed request never dispatches anything.

{
  "error": "Invalid JSON body"
}

{
  "error": "Validation failed"
}

{
  "error": "Authentication required"
}

{
  "error": "Unauthorized: No access to this deployment"
}

{
  "error": "Document not found"
}

{
  "error": "Failed to enqueue custom validation job"
}