PUT
/
datastores
/
{datastore_id}
/
documents
/
{document_id}
/
metadata
Update Document Metadata
curl --request PUT \
  --url https://api.contextual.ai/v1/datastores/{datastore_id}/documents/{document_id}/metadata \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "custom_metadata": {},
  "custom_metadata_config": {}
}'
{
  "custom_metadata": {},
  "custom_metadata_config": {},
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "pending",
  "created_at": "<string>",
  "updated_at": "<string>",
  "ingestion_config": {},
  "has_access": true
}

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 from which to retrieve the document

document_id
string<uuid>
required

Document ID of the document to retrieve details for

Body

application/json

Metadata request in 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). This function rewrites the metadata you are sending entirely. The strings with date format must stay in date format or be avoided if not in date format. The custom_metadata.url or custom_metadata.link field is automatically included in returned attributions during query time, if provided. 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. metadata_config is an optional dictionary that defines how each metadata field should be used — e.g., whether it's included in chunk reranking (in_chunks, default=False), included in the API response(returned_in_response, default=False), or enabled for filtering (filterable, default=True).

Example Request Body:

{
"custom_metadata": {
"topic": "science",
"difficulty": 3
},
"metadata_config": {
"topic": {
"in_chunks": true,
"returned_in_response": false,
"filterable": true
},
"difficulty": {
"filterable": true
}
}
}
custom_metadata
object

Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed.

custom_metadata_config
object

A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits: - Maximum characters per metadata field (for prompt or rerank): 400 - Maximum number of metadata fields (for prompt or retrieval): 10 Contact support@contextual.ai to request quota increases.

Response

Successful Response

Document description

id
string<uuid>
required

ID of the document that was ingested

name
string
required

User specified name of the document

status
enum<string>
required

Status of this document's ingestion job

Available options:
pending,
processing,
retrying,
completed,
failed,
cancelled
created_at
string
required

Timestamp of when the document was created in ISO format.

custom_metadata
object

Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed.

custom_metadata_config
object

A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits: - Maximum characters per metadata field (for prompt or rerank): 400 - Maximum number of metadata fields (for prompt or retrieval): 10 Contact support@contextual.ai to request quota increases.

updated_at
string

Timestamp of when the document was modified in ISO format.

ingestion_config
object

Ingestion configuration for the document when the document was ingested. It may be different from the current datastore configuration.

has_access
boolean
default:true

Whether the user has access to this document.