POST
/
datastores
/
{datastore_id}
/
documents
/
{document_id}
/
metadata
curl --request POST \
  --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": {},
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "pending",
  "created_at": "<string>",
  "updated_at": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
datastore_id
string
required

Datastore ID of the datastore from which to retrieve the document

​
document_id
string
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). 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
    }
  }
}

Response

200
application/json

Successful Response

Document description

POST
/
datastores
/
{datastore_id}
/
documents
/
{document_id}
/
metadata
curl --request POST \
  --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": {},
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "pending",
  "created_at": "<string>",
  "updated_at": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
datastore_id
string
required

Datastore ID of the datastore from which to retrieve the document

​
document_id
string
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). 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
    }
  }
}

Response

200
application/json

Successful Response

Document description