> ## 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. # Update Document Metadata > Post details of a given document that will enrich the chunk and be added to the context or just for filtering. If Just for filtering, start with "_" in the key. ## OpenAPI ````yaml api-reference/openapi.json put /datastores/{datastore_id}/documents/{document_id}/metadata openapi: 3.1.0 info: title: Endpoints version: '1.0' servers: - url: https://api.contextual.ai/v1 security: - BearerAuth: [] paths: /datastores/{datastore_id}/documents/{document_id}/metadata: put: tags: - /datastores/{id}/documents summary: Update Document Metadata description: >- Post details of a given document that will enrich the chunk and be added to the context or just for filtering. If Just for filtering, start with "_" in the key. operationId: >- update_document_metadata_datastores__datastore_id__documents__document_id__metadata_put parameters: - name: datastore_id in: path required: true schema: type: string format: uuid description: Datastore ID of the datastore from which to retrieve the document title: Datastore Id description: Datastore ID of the datastore from which to retrieve the document - name: document_id in: path required: true schema: type: string format: uuid description: Document ID of the document to retrieve details for title: Document Id description: Document ID of the document to retrieve details for requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MetadataRequest' description: >- 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:** ```json { "custom_metadata": { "topic": "science", "difficulty": 3 }, "metadata_config": { "topic": { "in_chunks": true, "returned_in_response": false, "filterable": true }, "difficulty": { "filterable": true } } } ``` responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentDescription' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: MetadataRequest: properties: custom_metadata: additionalProperties: anyOf: - type: boolean - type: number - type: integer - type: string - items: type: number type: array type: object title: Custom Metadata description: >- 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: additionalProperties: $ref: '#/components/schemas/MetadataFieldConfig' type: object title: Custom Metadata Config description: >- 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. additionalProperties: false type: object title: MetadataRequest description: >- This class contains all queries associated with metadata request for a doc. DocumentDescription: properties: custom_metadata: additionalProperties: anyOf: - type: boolean - type: number - type: integer - type: string - items: type: number type: array type: object title: Custom Metadata description: >- 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: additionalProperties: $ref: '#/components/schemas/MetadataFieldConfig' type: object title: Custom Metadata Config description: >- 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. id: type: string format: uuid title: Id description: ID of the document that was ingested name: type: string title: Name description: User specified name of the document status: $ref: '#/components/schemas/DocumentStatusEnum' description: Status of this document's ingestion job created_at: type: string title: Created At description: Timestamp of when the document was created in ISO format. updated_at: type: string title: Updated At description: Timestamp of when the document was modified in ISO format. ingestion_config: title: Ingestion Config description: >- Ingestion configuration for the document when the document was ingested. It may be different from the current datastore configuration. has_access: type: boolean title: Has Access description: Whether the user has access to this document. default: true type: object required: - id - name - status - created_at title: DocumentDescription description: Document description HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError MetadataFieldConfig: properties: in_chunks: type: boolean title: In Chunks description: >- Whether to add in chunks. Defaults to True. The maximum amount of characters per metadata field that can be added to the prompt or rerank is 400. The maximum amount of metadata fields that can be added for prompt or retrieval is 10. Contact support@contextual.ai to request quota increases. default: true returned_in_response: type: boolean title: Returned In Response description: Whether to add in response. Defaults to False default: false filterable: type: boolean title: Filterable description: Whether to use in filtering. Defaults to True default: true type: object title: MetadataFieldConfig DocumentStatusEnum: type: string enum: - pending - processing - retrying - completed - failed - cancelled title: DocumentStatusEnum 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 ````