> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Sources

> Create or join a durable sources computation. Located finds printed answers; cited also seeks supporting inputs. Background requests return immediately; synchronous requests wait up to 20 seconds before returning 202 with a version-pinned Location. Repeated requests reuse work and never bill twice. Processing completion does not guarantee evidence for every field. A cited request during a located-only computation returns 409; retry after that computation finishes.

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.

<RequestExample>
  ```python Python theme={null}
  from retab import Retab

  client = Retab()
  result = client.extractions.create_extraction_source(
      "extr_123", mode="located", background=True
  )
  print(result.job)
  ```

  ```typescript TypeScript theme={null}
  import { Retab } from "@retab/node";

  const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
  const result = await client.extractions.create_extraction_source(
    "extr_123", true, undefined, "located"
  );
  console.log(result.job);
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      retab "github.com/retab-dev/retab/clients/go"
  )

  func main() {
      client, err := retab.NewClient("")
      if err != nil { log.Fatal(err) }
      background := true
      mode := retab.CreateSourcesRequestModeLocated
      result, err := client.Extractions.CreateSource(context.Background(), "extr_123",
          &retab.ExtractionsCreateSourceParams{Background: &background, Mode: &mode})
      if err != nil { log.Fatal(err) }
      fmt.Println(result.Job)
  }
  ```

  ```java Java theme={null}
  import com.retab.RetabClient;
  import com.retab.models.CreateSourcesRequest;
  import com.retab.types.CreateSourcesRequestMode;

  public final class Example {
    public static void main(String[] args) throws Exception {
      RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
      var result = client.extractions().createSource("extr_123",
          new CreateSourcesRequest(true, null, CreateSourcesRequestMode.LOCATED, false));
      System.out.println(result.getJob());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require 'retab'

  client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
  result = client.extractions.create_extraction_source(
    extraction_id: 'extr_123', mode: 'located', background: true
  )
  puts result
  ```

  ```rust Rust theme={null}
  use retab::{Retab, enums::CreateSourcesRequestMode, models::CreateSourcesRequest};
  use retab::resources::extractions::CreateExtractionSourceParams;

  #[tokio::main]
  async fn main() -> Result<(), Box<dyn std::error::Error>> {
      let client = Retab::new(std::env::var("RETAB_API_KEY")?);
      let result = client.extractions().create_extraction_source("extr_123",
          CreateExtractionSourceParams::new(CreateSourcesRequest {
              mode: Some(CreateSourcesRequestMode::Located),
              background: Some(true),
              ..Default::default()
          })).await?;
      println!("{:?}", result.job);
      Ok(())
  }
  ```

  ```csharp C# theme={null}
  using Retab;
  using RetabClient = Retab.Retab;

  var client = new RetabClient(Environment.GetEnvironmentVariable("RETAB_API_KEY")!);
  var result = await client.Extractions.CreateSourceAsync("extr_123",
      new ExtractionsCreateSourceOptions {
          Mode = CreateSourcesRequestMode.Located, Background = true
      });
  Console.WriteLine(result.Job);
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Retab\Client;
  use Retab\Resource\SourceJobMode;

  $client = new Client(apiKey: getenv('RETAB_API_KEY'));
  $result = $client->extractions()->createExtractionSource(
      extractionId: 'extr_123', background: true, mode: SourceJobMode::Located,
  );
  print_r($result);
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://api.retab.com/v1/extractions/extr_123/sources' \
    -H "Authorization: Bearer $RETAB_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"mode":"located","background":true}'
  ```
</RequestExample>

* `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](/api-reference/extractions/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.


## OpenAPI

````yaml POST /v1/extractions/{extraction_id}/sources
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.retab.com
security: []
paths:
  /v1/extractions/{extraction_id}/sources:
    post:
      tags:
        - Extractions
      summary: Create Extraction Sources
      description: >-
        Create or join a durable sources computation. Located finds printed
        answers; cited also seeks supporting inputs. Background requests return
        immediately; synchronous requests wait up to 20 seconds before returning
        202 with a version-pinned Location. Repeated requests reuse work and
        never bill twice. Processing completion does not guarantee evidence for
        every field. A cited request during a located-only computation returns
        409; retry after that computation finishes.
      operationId: create_extraction_sources
      parameters:
        - in: path
          name: extraction_id
          required: true
          schema:
            type: string
            title: Extraction Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourcesRequest'
        required: true
      responses:
        '200':
          description: Requested computation is terminal; inspect job.status and evidence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionSources'
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionSources'
          headers:
            Access-Control-Expose-Headers:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
            ETag:
              schema:
                type: string
            Location:
              schema:
                type: string
            Retry-After:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateSourcesRequest:
      properties:
        background:
          type: boolean
          title: Background
          description: >-
            Return immediately when true. Otherwise wait up to 20 seconds, then
            return 202 with Location while the same durable job continues.
          default: false
        job_id:
          type: string
          title: Job Id
          description: >-
            Optional expected sources job identity. Returns 409 if the
            extraction changed.
        mode:
          type: string
          enum:
            - located
            - cited
          title: Mode
          default: located
        retry:
          type: boolean
          title: Retry
          description: >-
            Retry a terminal failed or incomplete computation. Concurrent
            requests join the current attempt; billing remains once per
            extraction.
      type: object
      title: CreateSourcesRequest
    ExtractionSources:
      properties:
        object:
          type: string
          const: extraction.sources
          title: Object
          default: extraction.sources
        extraction_id:
          type: string
          title: Extraction Id
          description: ID of the extraction
        document_type:
          type: string
          enum:
            - pdf
            - image
            - csv
            - xlsx
            - docx
            - txt
          title: Document Type
          description: Detected document type of the source file
        file:
          $ref: '#/components/schemas/FileRef'
          description: Source file metadata (id, filename, mime_type).
        extraction:
          additionalProperties: true
          type: object
          title: Extraction
          description: Original extraction output
        sources:
          additionalProperties: true
          type: object
          title: Sources
          description: >-
            Same shape as extraction but leaves are {value, source} objects.
            Non-null source entries include file_id.
        evidence:
          additionalProperties:
            $ref: '#/components/schemas/SourcesFieldEvidence'
          type: object
          title: Evidence
          default: {}
        job:
          $ref: '#/components/schemas/SourcesJob'
      type: object
      required:
        - document_type
        - extraction
        - extraction_id
        - file
        - sources
      title: ExtractionSources
      description: >-
        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).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          default: []
      type: object
      title: HTTPValidationError
    FileRef:
      properties:
        id:
          type: string
          title: Id
          description: ID of the file
        filename:
          type: string
          title: Filename
          description: Filename of the file
        mime_type:
          type: string
          title: Mime Type
          description: MIME type of the file
      type: object
      required:
        - filename
        - id
        - mime_type
      title: FileRef
      description: Public/shared file reference used across SDK and customer-facing APIs.
    SourcesFieldEvidence:
      properties:
        kind:
          type: string
          enum:
            - direct
            - supporting
            - unavailable
          title: Kind
        sources:
          anyOf:
            - items:
                $ref: '#/components/schemas/EvidenceSource'
              type: array
            - type: 'null'
          title: Sources
          description: >-
            Printed answer locations and supporting inputs. Supporting evidence
            does not establish that an inferred answer is correct.
        status:
          type: string
          enum:
            - pending
            - matched
            - partial
            - missing
            - ambiguous
            - unsupported
            - error
          title: Status
      type: object
      required:
        - kind
        - sources
        - status
      title: SourcesFieldEvidence
    SourcesJob:
      properties:
        error:
          $ref: '#/components/schemas/SourcesJobError'
        id:
          type: string
          title: Id
        is_partial:
          type: boolean
          title: Is Partial
          description: >-
            Processing stopped before all requested work finished. A missing
            match alone is not a processing failure.
        mode:
          type: string
          enum:
            - located
            - cited
          title: Mode
        object:
          type: string
          const: extraction.sources.job
          title: Object
        revision:
          type: integer
          title: Revision
        status:
          type: string
          enum:
            - pending
            - running
            - completed
            - error
          title: Status
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - is_partial
        - mode
        - object
        - revision
        - status
        - updated_at
      title: SourcesJob
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
          default: null
        ctx:
          type: object
          title: Context
          default: {}
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    EvidenceSource:
      properties:
        anchor:
          $ref: '#/components/schemas/EvidenceAnchor'
        content:
          type: string
          title: Content
        file_id:
          type: string
          title: File Id
        qualification:
          type: string
          enum:
            - direct
            - partial
            - legacy
          title: Qualification
        role:
          type: string
          enum:
            - answer
            - input
            - comparison
          title: Role
      type: object
      required:
        - anchor
        - content
        - file_id
        - qualification
        - role
      title: EvidenceSource
    SourcesJobError:
      properties:
        code:
          type: string
          title: Code
        is_retryable:
          type: boolean
          title: Is Retryable
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - is_retryable
        - message
      title: SourcesJobError
    EvidenceAnchor:
      properties:
        char_end:
          type: integer
          title: Char End
        char_start:
          type: integer
          title: Char Start
        column:
          anyOf:
            - type: string
            - type: integer
          title: Column
        coordinate:
          type: string
          title: Coordinate
        height:
          type: number
          title: Height
        kind:
          type: string
          enum:
            - pdf_bbox
            - image_bbox
            - text_span
            - spreadsheet_cell
            - csv_cell
            - docx_text_span
            - docx_table_cell
          title: Kind
        left:
          type: number
          title: Left
        line_end:
          type: integer
          title: Line End
        line_start:
          type: integer
          title: Line Start
        page:
          type: integer
          title: Page
        paragraph:
          type: integer
          title: Paragraph
        row:
          type: integer
          title: Row
        sheet_index:
          type: integer
          title: Sheet Index
        sheet_name:
          type: string
          title: Sheet Name
        table:
          type: integer
          title: Table
        top:
          type: number
          title: Top
        width:
          type: number
          title: Width
      type: object
      required:
        - kind
      title: EvidenceAnchor
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.