POST /v1/files/{file_id}/processing-runs

← API referenceFile intelligence · API access unavailable

API REFERENCE / FILE INTELLIGENCE

`POST` /v1/files/{file_id}/processing-runs

Start or rerun selected enabled processors for one immutable version.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Header	`Content-Type`	string (media type)	Yes	application/json.
Path	`file_id`	string	Yes	Stable Atom file ID.
Header	`Idempotency-Key`	string	Yes	Stable retry identity; retrying must return the same run.
Body	`version_id`	string	Yes	Immutable source version to process.
Body	`outputs`	string (extensible)	Yes	Specific enabled output kinds to produce or regenerate. Examples · extensible`thumbnailpage_ocrtranscriptdocument_summary`

Request example

Example request

POST /v1/files/file_789/processing-runs
Authorization: Bearer <analysis-manage token>
Idempotency-Key: run-8427
Content-Type: application/json

{
  "version_id": "ver_012",
  "outputs": [
    "page_ocr",
    "document_summary"
  ]
}

HTTP status codes

Status	Meaning
`202 Accepted`	Success response shown below.
`400 Bad Request`	Invalid source version or output kinds.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`404 Not Found`	File or version is not visible to this caller.
`409 Conflict`	Requested output is disabled or the idempotency key was reused with different input.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`run_id`	string	run_123
`file_id`	string	file_789
`version_id`	string	ver_012
`status`	string (enum)	queued Allowed values · closed enum`queuedrunningcancellation_requestedcompletedpartially_completedfailedcancelled`
`status_url`	string	/v1/processing-runs/run_123

Response example

Example response

202 Accepted
Content-Type: application/json

{
  "run_id": "run_123",
  "file_id": "file_789",
  "version_id": "ver_012",
  "status": "queued",
  "status_url": "/v1/processing-runs/run_123"
}

How it works

This creates a retry-safe run, not a new file version. A disabled processor cannot be started through this endpoint. Regenerated artifacts receive new IDs and retain provenance; an old result is not overwritten in place.