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 deep_validate=false \
  --form 'configuration=<string>' \
  --form file_id=FILE_ID_123
{
  "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
        }}
        }}"
        ```
​
deep_validate
boolean
default:false
Whether to perform deep validations on the ingestion result after completion of the ingestion job. If this feature is disabled, basic validations will still be performed which confirm that all expected chunk IDs are present in the VectorDB. If enabled, full equality checks are performed between the expected chunks and the actual chunks present in the VectorDB.

        These full equality checks are computationally expensive and should only be used during tests or debugging.
​
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.

​
file_id
string | null

Unique identifier for the file to be ingested.

Example:

"FILE_ID_123"

Response

Successful Response

Response body from POST /data/documents

​
id
string<uuid>
required

ID of the document being ingested