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, when a validation rule was added or edited, or when a document is stuck without a settled validation result.

Every call re-evaluates the model's validation rules against the document's current values before dispatching anything, whatever include asks for. Rule evaluation is synchronous and free, so the response already reflects the new rule results and the next read of the document shows them. The rest of the call dispatches the custom lanes you named.

Each call starts a new validation attempt for those lanes: 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.

Validation rules are not a branch and cannot be excluded: they are re-evaluated on every call, including one that dispatches nothing.

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 the rule results and every validation row on the file, so a branch you did not re-run still counts.

The call publishes the event itself in exactly one case: the model has validation rules and the call dispatched nothing — no script batch enqueued and no validator agent run started. Nothing is left to wait for, so the freshly evaluated rules settle the document before the call returns. Whenever a lane was dispatched, the event follows that lane's completion instead. A model with no rules that dispatches nothing publishes no event at all: old results are never replayed.

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"
    ]
  },
  "modelId": "dep_abc123",
  "viaDeploymentId": "dpl_prod01"
}

• 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 custom validation configured for the requested branches. The rules were still re-evaluated — read the document to see their results. On a model with rules that call also settles the document and emits DOCUMENT_VALIDATED; on a model without rules it emits nothing.

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:

• Re-evaluating the validation rules is free. A call that dispatches nothing costs nothing.
• 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"
}

A deployment that is not ACTIVE refuses the call before anything is re-evaluated or dispatched. Address the model instead, or resume the deployment.

{
  "error": "Deployment dpl_prod01 on model dep_abc123 is PAUSED. Resume it before processing documents through it.",
  "code": "DEPLOYMENT_PAUSED",
  "deploymentId": "dpl_prod01",
  "modelId": "dep_abc123",
  "status": "PAUSED"
}

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