Skip to main content
POST
Start or join a durable sources job for a completed extraction. The job belongs to the extraction’s output, schema, and file version. Repeated requests reuse current work. Disconnecting from the request does not cancel the job.
  • located finds printed answers without paid citation calls. It supports the existing PDF, image, CSV, spreadsheet, Word, and text source formats.
  • cited also searches for supporting inputs for inferred answers. It supports PDF and images, is subject to citation availability and plan limits, and uses existing citation billing. Retries do not bill the extraction a second time.
With background: true, an unfinished job returns 202 immediately. Otherwise the request waits up to 20 seconds; unfinished work then returns 202 and continues on the server. Terminal snapshots return 200. Follow Location to poll, respecting Retry-After. Both responses contain the extraction, available sources, field evidence, and the job lifecycle described by Get Sources. An explicit job_id guards a create or retry against an extraction edit. A mismatch returns 409. Located and cited have distinct identities. A located request can use the first snapshot of a cited job; a cited request while a located-only job is running returns 409. Retry that cited request after the located job finishes. Set retry: true to retry terminal failed or incomplete work. Concurrent requests join the active attempt. Processing limits may prevent further citation work; inspect job.error.is_retryable. Available evidence is retained on failure. To prevent automatic citations when creating an extraction or workflow run, include "sources": {"mode": "located"} in the creation request. Omit it to inherit the organization policy. "sources": {"mode": "cited"} requests automatic citations, subject to deployment policy. A later explicit sources request can still request cited evidence after a located extraction. Processing completion does not guarantee that all fields have matches. An unavailable source is not evidence that an extracted value is correct or incorrect.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

extraction_id
string
required

Body

application/json
background
boolean
default:false

Return immediately when true. Otherwise wait up to 20 seconds, then return 202 with Location while the same durable job continues.

job_id
string

Optional expected sources job identity. Returns 409 if the extraction changed.

mode
enum<string>
default:located
Available options:
located,
cited
retry
boolean

Retry a terminal failed or incomplete computation. Concurrent requests join the current attempt; billing remains once per extraction.

Response

Requested computation is terminal; inspect job.status and evidence.

An extraction's output annotated with the source that backs each value.

Returned when fetching the sources for an extraction. Carries the source file and its detected document_type, the original extraction output, and a parallel sources tree where each leaf is a {value, source} object locating the value in the document (a page region for PDFs, a cell for spreadsheets, a text span for plain text, and so on).

extraction_id
string
required

ID of the extraction

document_type
enum<string>
required

Detected document type of the source file

Available options:
pdf,
image,
csv,
xlsx,
docx,
txt
file
FileRef · object
required

Source file metadata (id, filename, mime_type).

extraction
Extraction · object
required

Original extraction output

sources
Sources · object
required

Same shape as extraction but leaves are {value, source} objects. Non-null source entries include file_id.

object
string
default:extraction.sources
Allowed value: "extraction.sources"
evidence
Evidence · object
job
SourcesJob · object