1. Identify the intended work
This reference example processes two documents under documents.intake.v1. The request selects a manifest rather than placing every input directly in the request body. The manifest fixes the expected input set so a run can reconcile its result to a stable collection.
There is no live endpoint behind these examples. In your own implementation, add authentication, authorization, durable acceptance, input validation, and an appropriate storage boundary before exposing a submission route.
{
"process": "documents.intake.v1",
"input_manifest": "manifest-001",
"policy": {
"validation": "required",
"on_ambiguity": "human_review",
"max_attempts": 3
},
"output": {
"include_item_results": true,
"publish_after_validation": true
}
}Download job-request.json. The max_attempts field is an example policy value, not a universal retry recommendation. Your workflow still needs to classify which failures are worth retrying and define its elapsed-time limit.
2. Accept the request durably
The proposed interface uses POST /v1/runs for submission and returns HTTP 202 Accepted only after the accepted intent is recorded. A response should include the stable run identity and the location where an authorized client can observe it. Acceptance is not completion.
Define an idempotency-key scope and retention policy. A repeated submission for the same accepted operation should recover the original run where the contract supports that behavior. Reusing the key with materially different content should produce an explicit conflict, not an unrelated run hidden behind the same identity.
3. Observe a run without changing it
The proposed status operation is GET /v1/runs/{run_id}. It returns the lifecycle state and a bounded summary of progress. Reading status must still enforce object-level authorization. An identifier is not permission to see another account's work.
{
"run_id": "run-example-001",
"process": "documents.intake.v1",
"input_manifest": "manifest-001",
"state": "succeeded",
"progress": {
"total": 2,
"succeeded": 2,
"failed": 0,
"pending": 0
},
"result_manifest": "results-example-001"
}This is an illustrative completed run, not live telemetry. Download run-status.json and compare its totals with the two items in batch-manifest.json.
4. Reconcile the result
A succeeded run has accepted outcomes for every required item under the manifest's delivery rule. The result_manifest connects the run to its per-item output references. Use item identifiers to join the result to the input set; do not assume completion order matches input order.
Download result-manifest.json. Its output paths are logical references that an implementation would resolve under its own access controls. A real design must define how artifacts are retrieved, how long they remain available, and who may publish them.
5. Test the interrupted journey
Repeat an accepted submission, stop a worker between processing and persistence, and delay a dependency's response after it accepts a request. For each test, define the expected business outcome and inspect both local state and external effects.
Continue with the job lifecycle and batch manifest references. The longer API design playbook explains the tradeoffs behind identity, authorization, errors, and compatibility.