---
title: "Add extraction types to an existing document"
method: POST
path: "/api/v1/documents/{document_id}/extractions"
tags: ["Document"]
---

# Add extraction types to an existing document

`POST /api/v1/documents/{document_id}/extractions`

## Request

- Base URL: `https://api.gemina.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemina.co/api/v1/documents/{document_id}/extractions`
- Auth: API key in header `X-API-Key`

Run additional extraction types on a document that is already stored.

No upload: the document's stored artifacts are reused and only the
extraction step runs. Billed per extraction like an upload. Returns the
whole document (all extractions, old and new). When the new extractions
are still running the response is HTTP 202 and ``pollCorrelationId`` /
``Location`` point at the existing results endpoint.

## Path parameters

- `document_id` string, uuid, required

## Request body

- AddExtractionsInDTO: Request body for ``POST /documents/{document_id}/extractions``. No file, external id or end-user id: they belong to the document. FileTag is structurally rejected by ``UploadExtractionTypeModel``.
  - `extractionTypes` UploadExtractionTypeEnum[], required: Extraction types to add to the existing document
  - `modelType` 'gemina' | 'google' | 'openai' | 'velox' | 'praetorian' | 'invictus'
  - `thinking` boolean, nullable: Enable extended reasoning; defaults to the account setting
  - `evaluation` boolean, nullable: Enable self-evaluation of the extracted data; defaults to the account setting
  - `correction` boolean, nullable: Enable self-correction of the extracted data; defaults to the account setting
  - `includeCoordinates` boolean, nullable: Return per-field bounding boxes; defaults to the account setting
  - `templateId` string, uuid, nullable: Custom template to extract with; required by (and only valid with) the custom_template type

## Response `200`

Successful Response

- DocumentAddExtractionsOutDTO: The document view (all extractions, old and new) plus what this call created. ``pollCorrelationId`` is the document's ORIGINAL correlation: the existing ``GET /documents/results/{id}`` / ``get_extraction_result`` report the whole document as done only once every row (including the new ones) is terminal.
  - `status` 'pending' | 'in_process' | 'failed' | 'success' | 'partial' | 'empty', required
  - `meta` DocumentAddExtractionsMetaOutDTO, required: The document-view meta plus the async poll pointer. Extends (never replaces) ``DocumentViewMetaOutDTO`` so the add-on response keeps every meta field a document view carries (``createdAt``, ``contentPurgedAt``, ``processingStatus``, ``documentId``, ...) and only ADDS ``next`` / ``correlationId`` -- the same poll pointer an upload response exposes, so an existing submit-and-wait SDK helper works unchanged.
    - `externalId` string, nullable
    - `documentId` string, uuid, nullable
    - `userId` string, uuid, nullable
    - `endUserId` string, nullable
    - `apiKeyId` string, uuid, nullable
    - `filename` string, nullable
    - `fileSize` integer, nullable
    - `contentType` string, nullable
    - `documentFileType` 'pdf' | 'image' | 'other'
    - `numberOfPages` integer, nullable
    - `normalizedWidth` integer, nullable
    - `normalizedHeight` integer, nullable
    - `normalizedMegapixels` number, nullable
    - `storageLocation` 'israel' | 'europe' | 'united_states' | 'asia'
    - `imageUrl` string, uri, nullable
    - `thumbnailUrl` string, uri, nullable
    - `originalDocumentUrl` string, uri, nullable
    - `processingStatus` 'pending' | 'in_process' | 'failed' | 'success' | 'partial' | 'empty'
    - `createdAt` string, date-time, required
    - `contentPurgedAt` string, date-time, nullable, required
    - `correlationId` string, uuid, nullable
    - `next` string, uri, nullable
  - `data` DocumentDataOutDTO, required
    - `extractions` ExtractionProcessingResultOutDTO[], nullable
      - `status` 'pending' | 'in_process' | 'failed' | 'success' | 'partial' | 'empty', required
      - `meta` ExtractionMetaOutDTO, required
        - `extractionId` string, uuid, nullable
        - `modelType` 'gemina' | 'google' | 'openai' | 'velox' | 'praetorian' | 'invictus', required
        - `thinking` boolean, required
        - `correction` boolean, required
        - `evaluation` boolean, required
        - `includeCoordinates` boolean, required
        - `processorClass` string, required
        - `extractionType` 'ocr' | 'document_details_hebrew' | 'document_line_items_hebrew' | 'invoice_headers' | 'invoice_line_items' | 'custom_template' | 'filetag', required: Defines the type of operation to perform on the uploaded document
        - `latencySeconds` number, nullable
        - `numberOfFields` integer, nullable
        - `purgeAt` string, date-time, nullable, required
        - `purgedAt` string, date-time, nullable, required
        - `purgeReason` 'user_deleted' | 'retention_expired' | 'admin_action', required
        - `validationFeedback` ValidationSchemaModel
          - `validationSchema` string[], required
          - `validationFields` ValidationFieldModel[]
            - `key` string, required
            - `label` string, required
            - `type` 'string' | 'number' | 'integer' | 'boolean' | 'date', required
            - `enum` string[], nullable
            - `format` string, nullable
            - `description` string, nullable
          - `rowMutableTables` RowMutableTableModel[]
            - `pointer` string, required
            - `keyTemplate` string, required
            - `columns` ValidationColumnModel[]
              - …
        - `validated` boolean
      - `values` object, nullable, required
      - `verifiedValues` object, nullable
      - `verifiedDiff` VerifiedDiffEntryOutDTO[], nullable
        - `field` string, required
        - `status` 'corrected' | 'added' | 'removed', required
        - `pointer` string, nullable
        - `original` union
          - string
          - integer
          - number
          - boolean
          - unknown[]
            - unknown
          - object
        - `verified` union
          - string
          - integer
          - number
          - boolean
          - unknown[]
            - unknown
          - object
      - `errors` object[]
  - `errors` object[]
  - `createdAt` string, date-time, nullable
  - `createdAtTimestamp` number, nullable
  - `newExtractionIds` string[]: Ids of the extractions this call created
  - `pollCorrelationId` string, uuid, required: Correlation id to poll for the document's completion

## Other responses

- `202`: The new extractions are still running. Poll `pollCorrelationId` (also in `Location`).
- `404`: The resource does not exist, or is not visible to the caller. Ownership failures are deliberately indistinguishable from a missing resource.
- `409`: The request conflicts with the resource's current state; `errors[0].error_code` says which rule.
- `410`: The resource's content has been purged and cannot be processed again.
- `422`: Request validation failed (`HTTPValidationError`), or the request was understood but cannot be applied — e.g. the extraction is under legal hold or did not complete successfully (`FoundationDTO`).
- `429`: Rate or quota limit exceeded; `errors[0].error_code` says which. Retryable limits (`FILETAG_RATE_LIMIT_EXCEEDED`, burst limits) send a `Retry-After` header: back off and retry after it. `CREDIT_EXHAUSTED` for an account with no active subscription or trial sends no `Retry-After` and is not resolved by waiting: start the free trial (once per account) or choose a plan in the console.

---

[API](https://skmtc.dev/gemina/apis/gemina-api.md) · [All operations](https://skmtc.dev/gemina/apis/gemina-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemina/apis/gemina-api/revisions/152fd3f6f6ec?raw)