Skip to main content
POST
/
datastores
/
{datastore_id}
/
documents
Ingest Document
curl --request POST \
  --url https://api.contextual.ai/v1/datastores/{datastore_id}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'metadata=<string>' \
  --form 'configuration=<string>'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
datastore_id
string<uuid>
required

Datastore ID of the datastore in which to ingest the document

Body

multipart/form-data
​
file
file
required

File to ingest.

​
metadata
string

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 [email protected] 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
        }}
        }}"
        ```
Example:
{
  "custom_metadata": { "field1": "value1", "field2": "value2" }
}
​
configuration
string

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.

Example:
{
  "parsing": {
    "figure_caption_mode": "custom",
    "figure_captioning_prompt": "Generate a detailed caption for each figure."
  }
}

Response

Successful Response

Response body from POST /data/documents

​
id
string<uuid>
required

ID of the document being ingested