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

# Ingest Document

> Ingest a document into a given `Datastore`.

Ingestion is an asynchronous task. Returns a document `id` which can be used to track the status of the ingestion job through calls to the `GET /datastores/{datastore_id}/documents/{document_id}/metadata` API.

This `id` can also be used to delete the document through the `DELETE /datastores/{datastore_id}/documents/{document_id}` API.

`file` must be a PDF, HTML, DOC(X), PPT(X), PNG, JPG, or JPEG file. The filename must end with one of the following extensions: `.pdf`, `.html`, `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`, `.png`, `.jpg`, `.jpeg`.



## OpenAPI

````yaml api-reference/openapi.json post /datastores/{datastore_id}/documents
openapi: 3.1.0
info:
  title: Endpoints
  version: '1.0'
servers:
  - url: https://api.contextual.ai/v1
security:
  - BearerAuth: []
paths:
  /datastores/{datastore_id}/documents:
    post:
      tags:
        - /datastores/{id}/documents
      summary: Ingest Document
      description: >-
        Ingest a document into a given `Datastore`.


        Ingestion is an asynchronous task. Returns a document `id` which can be
        used to track the status of the ingestion job through calls to the `GET
        /datastores/{datastore_id}/documents/{document_id}/metadata` API.


        This `id` can also be used to delete the document through the `DELETE
        /datastores/{datastore_id}/documents/{document_id}` API.


        `file` must be a PDF, HTML, DOC(X), PPT(X), PNG, JPG, or JPEG file. The
        filename must end with one of the following extensions: `.pdf`, `.html`,
        `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`, `.png`, `.jpg`,
        `.jpeg`.
      operationId: ingest_document_datastores__datastore_id__documents_post
      parameters:
        - name: datastore_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Datastore ID of the datastore in which to ingest the document
            title: Datastore Id
          description: Datastore ID of the datastore in which to ingest the document
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_ingest_document_datastores__datastore_id__documents_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_ingest_document_datastores__datastore_id__documents_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: File to ingest.
        metadata:
          type: string
          title: Metadata
          description: >-
            Metadata request in stringified JSON format. `custom_metadata` is a
            flat dictionary containing one or more key-value pairs, where each
            value must be a primitive type (`str`, `bool`, `float`, or `int`).
            The default maximum metadata fields that can be used is 15, contact
            support@contextual.ai if more is needed. The combined size of the
            metadata must not exceed **2 KB** when encoded as JSON. The strings
            with date format must stay in date format or be avoided if not in
            date format. The `custom_metadata.url` or `link` field is
            automatically included in returned attributions during query time,
            if provided.

                        **Example Request Body (as returned by `json.dumps`):**

                        ```json
                        "{{
                        \"custom_metadata\": {{
                            \"topic\": \"science\",
                            \"difficulty\": 3
                        }}
                        }}"
                        ```
          examples:
            - custom_metadata:
                field1: value1
                field2: value2
        configuration:
          type: string
          title: Configuration
          description: >-
            Overrides the datastore's default configuration for this specific
            document. This allows applying optimized settings tailored to the
            document's characteristics without changing the global datastore
            configuration.
          examples:
            - parsing:
                figure_caption_mode: custom
                figure_captioning_prompt: Generate a detailed caption for each figure.
      type: object
      required:
        - file
      title: Body_ingest_document_datastores__datastore_id__documents_post
    IngestionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: ID of the document being ingested
      type: object
      required:
        - id
      title: IngestionResponse
      description: Response body from POST /data/documents
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````