> ## Documentation Index > Fetch the complete documentation index at: https://cortex-e852fafe-auto-update-openapi-6a9e3873a7492d091ac8c1f.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update Source Metadata > Merge tenant metadata and additional metadata for one existing source without re-ingesting its content. export const Field = ({name, type, required, recommended}) => { const label = required ? 'required' : recommended ? 'recommended' : null; const typeLabel = typeof type === 'string' ? type : null; const ariaParts = [name, typeLabel && `${typeLabel}`, label].filter(Boolean); return {name} {required && *} {recommended && ●} {type && {type}} {label && {label} } ; }; Use this endpoint when you know a source ID and need to update its metadata in place. It updates both the source row and indexed chunk metadata used by query/list filters. ```http theme={null} PATCH /context/{id}/metadata ``` The legacy route `PATCH /context/sources/{source_id}/metadata` still works but is deprecated - migrate to the route above. Both dispatch to the same handler; `source_id` and `id` name the same value. ```bash cURL theme={null} curl -X PATCH 'https://api.hydradb.com/context/policy_main/metadata' \ -H "Authorization: Bearer $HYDRA_DB_API_KEY" \ -H "API-Version: 2" \ -H "Content-Type: application/json" \ -d '{ "database": "acme_corp", "collection": "team_docs", "database_metadata": { "department": "legal", "priority": 7 }, "additional_metadata": { "author": "Legal Team", "doc_version": 3 } }' ``` ```python Python theme={null} import requests response = requests.patch( "https://api.hydradb.com/context/policy_main/metadata", headers={ "Authorization": f"Bearer {HYDRA_DB_API_KEY}", "API-Version": "2", "Content-Type": "application/json", }, json={ "database": "acme_corp", "collection": "team_docs", "database_metadata": { "department": "legal", "priority": 7, }, "additional_metadata": { "author": "Legal Team", "doc_version": 3, }, }, ) ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.hydradb.com/context/policy_main/metadata", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.HYDRA_DB_API_KEY}`, "API-Version": "2", "Content-Type": "application/json", }, body: JSON.stringify({ database: "acme_corp", collection: "team_docs", database_metadata: { department: "legal", priority: 7, }, additional_metadata: { author: "Legal Team", doc_version: 3, }, }), }); ``` ## Request ### Path parameters | Name | Description | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | | Existing source ID to update. This is the `id` you supplied at ingest, or the source ID returned by HydraDB. | ### Body | Name | Description | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Owning database. (deprecated alias: `tenant_id`) | | | Collection that contains the source. This endpoint does not default it. (deprecated alias: `sub_tenant_id`) | | | Schema-backed metadata fields to merge into the source's `metadata`. Keys must satisfy the tenant metadata schema when one exists. (deprecated alias: `tenant_metadata`) | | | Free-form metadata fields to merge into the source's `additional_metadata`. | At least one of `database_metadata` or `additional_metadata` is required. This edit endpoint uses `database_metadata` for schema-backed source metadata (deprecated alias: `tenant_metadata` - still accepted, but the canonical field wins if both are sent). The shorter `metadata` field used by ingestion/list examples is not accepted in this PATCH body. `document_metadata` is also not accepted; use `additional_metadata`. ## Behavior * The update is a **merge/upsert**: * keys present in the request are inserted or overwritten * keys omitted from the request are preserved * The source must already exist. This endpoint does not create sources. * The endpoint edits one source at a time. Bulk metadata edits are not supported. * Updated metadata is visible to [`/query`](/api-reference/v2/endpoint/query) metadata filters and [`/context/list`](/api-reference/v2/endpoint/list-documents) filters. * If an edited tenant metadata field has `enable_dense_embedding` or `enable_sparse_embedding`, HydraDB synchronously refreshes the relevant vector store metadata search lane. * If the edited fields are `enable_match`-only, the edit remains MongoDB-only and `vector_sync_required` is `false`. ## Response ```json Success theme={null} { "success": true, "data": { "id": "policy_main", "tenant_id": "acme_corp", "sub_tenant_id": "team_docs", "updated": true, "database_metadata_keys": ["department", "priority"], "tenant_metadata_keys": ["department", "priority"], "additional_metadata_keys": ["author", "doc_version"], "vector_sync_required": false, "milvus_sync_required": false, "chunk_rows_matched": 4, "chunk_rows_modified": 4 }, "error": null, "meta": { "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d", "latency_ms": 12.3 } } ``` ```json Dense or sparse metadata sync theme={null} { "success": true, "data": { "id": "policy_main", "tenant_id": "acme_corp", "sub_tenant_id": "team_docs", "updated": true, "database_metadata_keys": ["summary_label"], "tenant_metadata_keys": ["summary_label"], "additional_metadata_keys": [], "vector_sync_required": true, "vector_synced": true, "vector_rows_synced": 4, "milvus_sync_required": true, "milvus_synced": true, "milvus_rows_synced": 4, "chunk_rows_matched": 4, "chunk_rows_modified": 4 }, "error": null, "meta": { "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d", "latency_ms": 28.9 } } ``` ```json Failure theme={null} { "success": false, "data": null, "error": { "code": "BAD_REQUEST", "message": "invalid metadata edit: tenant_metadata.department must be of type VARCHAR" }, "meta": { "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d", "latency_ms": 4.8 } } ``` | Field | Description | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | | Updated source ID. | | | Public tenant ID. | | | Sub-tenant that contained the source. | | | `true` when the source metadata was updated. | | | Database metadata keys included in the request. | | | Deprecated alias for `database_metadata_keys`; still emitted for backward compatibility. | | | Additional metadata keys included in the request. | | | `true` when at least one changed tenant metadata field has dense/sparse embedding enabled. | | | Present when sync was required. `true` means the sync completed. | | | Number of chunk rows synced to the vector store when sync was required. | | | Deprecated alias for `vector_sync_required`; still emitted for backward compatibility. | | | Deprecated alias for `vector_synced`; still emitted for backward compatibility. | | | Deprecated alias for `vector_rows_synced`; still emitted for backward compatibility. | | | Number of MongoDB chunk rows matched by the source update. | | | Number of MongoDB chunk rows modified by the source update. | ## Validation and errors | Status | When it happens | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | Missing `database`, missing `collection`, empty metadata payload, `document_metadata` supplied, unknown tenant metadata key when a schema exists, wrong type, reserved key, over-size payload, too-deep nesting, or `null` for a dense/sparse-enabled field. | | `404` | Source does not exist for the `(database, collection, id)` scope. | | `500` | Metadata was written to MongoDB but dense/sparse vector store sync failed. Retry the same idempotent edit to converge. | ### Size limits `database_metadata` (and its still-accepted `tenant_metadata` alias) is capped at **16 KiB**; `additional_metadata` at **1 KiB**. Each cap applies to the whole map, measured on its compact JSON encoding in UTF-8 bytes - keys, quotes and punctuation count toward the budget, so budget in bytes rather than in characters of content. `document_metadata` has no size limit here because it is **not accepted on this endpoint at all** - any non-null value returns `400`, whatever its size. It is a valid alias for `additional_metadata` on [`/context/ingest`](/api-reference/v2/endpoint/ingest-context), but not on this one. Send `additional_metadata`. The cap is checked against the payload in **this** request, before the merge - not against the stored map the merge produces. A small edit to an already-large map is therefore accepted, so treat the cap as a per-request budget rather than a guarantee about the final stored size. Over-cap fails the whole edit with `400` and reports both numbers: ```json theme={null} { "success": false, "data": null, "error": { "code": "INVALID_INPUT", "message": "invalid metadata edit: additional_metadata is too large (1065 bytes when serialized; the maximum is 1024). Reduce the number or size of metadata fields." } } ``` See [Scoping using metadata → Size limits](/essentials/v2/metadata#size-limits). ## Related * [Scoping using metadata](/essentials/v2/metadata) * [Ingest Context](/api-reference/v2/endpoint/ingest-context) * [List Context](/api-reference/v2/endpoint/list-documents) * [Query](/api-reference/v2/endpoint/query) ## OpenAPI ````yaml api-reference/v2/openapi.json PATCH /context/{id}/metadata openapi: 3.1.0 info: contact: email: support@hydradb.com name: HydraDB Support description: >- HydraDB Application API — knowledge ingestion, search, and memory management. license: name: Proprietary title: HydraDB Application API version: 0.1.0 servers: - description: Production server url: https://api.hydradb.com security: [] externalDocs: description: '' url: '' paths: /context/{id}/metadata: patch: tags: - context summary: Update source metadata description: >- Merge/upsert database_metadata and additional_metadata for one source. collection is required. parameters: - description: Source ID in: path name: id required: true schema: example: HydraDoc1234 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/handler.contextMetadataUpdateRequest' description: Metadata update request required: true responses: '200': content: application/json: schema: $ref: >- #/components/schemas/handler.Envelope-github_com_hydradb_hydradb-application_internal_service_MetadataEditResult description: OK '400': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Bad Request '404': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Not Found '500': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Internal Server Error security: - BearerAuth: [] components: schemas: handler.contextMetadataUpdateRequest: properties: acl: description: >- ACL, when present, REPLACES the source's access-control list without re-ingestion (PRO-1684): pass the COMPLETE new allow-list (adding a third user means sending all three), an empty list to make the source private, or ["__public__"] to open it to every identified caller. A pointer so omitted (nil, ACL untouched) is distinguishable from an explicit empty list (private). ACL uses RawMessage so the handler can tell three wire states apart: absent (leave the stored ACL untouched), explicit null (revoke to nobody, JSON-merge-patch semantics), and a list (replace). A plain *[]string cannot: encoding/json leaves the pointer nil for BOTH absent and null, which silently ignored an explicit null revocation. items: type: string type: array uniqueItems: false additional_metadata: additionalProperties: {} description: >- Free-form key-value pairs to merge into the source's `additional_metadata`. The only accepted spelling for document metadata on this endpoint. Capped at 1 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count. example: author: ada doc_version: 3 type: object collection: description: >- Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated). example: team_docs type: string database: description: >- Database/Collection are the canonical v2 names; TenantID/SubTenantID are their deprecated aliases. The TenantAliases middleware reconciles them in the request body before binding, so the handler reads TenantID/SubTenantID. example: acme_corp type: string database_metadata: additionalProperties: {} description: >- Schema-backed metadata fields to merge into the source's `metadata` (database metadata). Canonical name; `tenant_metadata` is a deprecated alias. Capped at 16 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count. example: department: legal priority: 7 type: object document_metadata: additionalProperties: {} deprecated: true description: >- Not accepted on this endpoint. Sending any non-null value returns 400 (`document_metadata is not accepted; use additional_metadata`), regardless of size. Use `additional_metadata` instead. Accepted as an alias on /context/ingest only. type: object x-deprecated: 'true' sub_tenant_id: deprecated: true description: 'deprecated: use collection' example: sub_tenant_4567 type: string x-deprecated: 'true' tenant_id: deprecated: true description: 'deprecated: use database' example: tenant_1234 type: string x-deprecated: 'true' tenant_metadata: additionalProperties: {} deprecated: true description: >- Deprecated alias for `database_metadata`, still accepted here; `database_metadata` wins when both are sent. Capped at 16 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count. example: department: legal priority: 7 type: object x-deprecated: 'true' type: object handler.Envelope-github_com_hydradb_hydradb-application_internal_service_MetadataEditResult: properties: data: $ref: >- #/components/schemas/github_com_hydradb_hydradb-application_internal_service.MetadataEditResult example: acl_drift_recorded: true acl_updated: true chunk_rows_matched: 1 chunk_rows_modified: 1 collection: team_docs database: acme_corp database_metadata_keys: - department - priority id: HydraDoc1234 milvus_rows_synced: 1 milvus_sync_required: true milvus_synced: true sub_tenant_id: sub_tenant_4567 tenant_id: tenant_1234 updated: true vector_acl_synced: true vector_rows_synced: 1 vector_sync_required: true vector_synced: true error: $ref: '#/components/schemas/handler.apiError' description: Error message, empty string on success. example: code: DATABASE_NOT_FOUND message: Database not found meta: $ref: '#/components/schemas/handler.responseMeta' example: collection: team_docs database: acme_corp latency_ms: 12.3 request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d source_type: file sub_tenant_id: sub_tenant_4567 tenant_id: tenant_1234 success: description: Whether the request succeeded. example: true type: boolean type: object handler.ErrorResponse: properties: data: {} detail: $ref: '#/components/schemas/handler.ErrorDetail' description: Structured error detail with code, message, and deprecation hints. example: deprecated: true deprecated_field: tenant_id error_code: VALIDATION_ERROR message: Request validation failed preferred_field: database error: $ref: '#/components/schemas/handler.apiError' description: Error message, empty string on success. example: code: DATABASE_NOT_FOUND message: Database not found meta: $ref: '#/components/schemas/handler.ErrorMeta' example: latency_ms: 12.3 request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d success: description: Whether the request succeeded. example: true type: boolean type: object github_com_hydradb_hydradb-application_internal_service.MetadataEditResult: properties: acl_drift_recorded: description: >- ACLDriftRecorded reports that a failed ACL mirror was durably recorded for reconciliation. Always true when vector_acl_synced is true. False beside acl_updated=true and vector_acl_synced=false is the one state the operator must act on (the error log names the document). example: true type: boolean acl_updated: description: >- ACLUpdated reports that this edit replaced the source's ACL (PRO-1684). example: true type: boolean additional_metadata_keys: description: Additional metadata keys included in the update request. items: type: string type: array uniqueItems: false chunk_rows_matched: description: Number of MongoDB chunk rows matched by the source update. example: 1 type: integer chunk_rows_modified: description: Number of MongoDB chunk rows modified by the source update. example: 1 type: integer collection: description: >- Collection that contained the source. Canonical name; mirrors the deprecated `sub_tenant_id` alias. example: team_docs type: string database: description: >- Owning database. Canonical name; mirrors the deprecated `tenant_id` alias. example: acme_corp type: string database_metadata_keys: description: >- Database metadata keys included in the update request. Canonical name; `tenant_metadata_keys` is a deprecated alias. example: - department - priority items: type: string type: array uniqueItems: false id: description: Unique identifier for this resource. example: HydraDoc1234 type: string milvus_rows_synced: deprecated: true description: 'deprecated: use vector_rows_synced' example: 1 type: integer x-deprecated: 'true' milvus_sync_required: deprecated: true description: >- Deprecated: use vector_sync_required / vector_synced / vector_rows_synced. Retained as additive aliases for existing clients; carry the same values. example: true type: boolean x-deprecated: 'true' milvus_synced: deprecated: true description: 'deprecated: use vector_synced' example: true type: boolean x-deprecated: 'true' partial_commit: description: >- PartialCommit reports that the edit committed in at least one database of a shared deployment but a later write in another failed; the idempotent retry converges the database that fell behind. type: string sub_tenant_id: deprecated: true description: 'deprecated: use collection' example: sub_tenant_4567 type: string x-deprecated: 'true' tenant_id: deprecated: true description: 'deprecated: use database' example: tenant_1234 type: string x-deprecated: 'true' tenant_metadata_keys: deprecated: true description: 'deprecated: use database_metadata_keys' items: type: string type: array uniqueItems: false x-deprecated: 'true' updated: description: Whether the source metadata was updated. example: true type: boolean vector_acl_synced: description: >- VectorACLSynced reports that the ACL edit also reached the vector rows' pushdown columns (PRO-1740). False with ACLUpdated true means the document's own-ACL projection is stale until its next re-index: still enforced correctly from Mongo, but invisible to the pushdown lane for any principal the edit ADDED. Always false for collections created before PRO-1740, which carry no pushdown columns. example: true type: boolean vector_rows_synced: description: >- Number of chunk rows synced to the vector store when sync was required. example: 1 type: integer vector_sync_error: description: |- VectorSyncError explains a vector_synced=false when a sync was required: the authority (Mongo) committed, the vector metadata did not follow; the idempotent retry converges it. type: string vector_sync_required: description: >- Vendor-neutral vector-sync signal (PRO-1185): the canonical field must not name the vector store. The milvus_* fields below are deprecated aliases kept for backward compatibility (additive change, not a rename) and carry the same values; they are slated for removal in a future major version. example: true type: boolean vector_synced: description: >- Whether the vector store metadata sync completed. Present when sync was required. example: true type: boolean type: object handler.apiError: properties: code: description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`). example: DATABASE_NOT_FOUND type: string message: description: Human-readable description of the error. example: Database not found type: string type: object handler.responseMeta: properties: api_version: description: >- APIVersion echoes the version of the API that served the request (PRO-1209), sourced from reqmeta.APIVersion — the same value carried by OpenAPI info.version and /health — so a client always knows which API version produced a response. Always present (no omitempty). type: string collection: description: >- Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated). example: team_docs type: string database: description: >- Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated). example: acme_corp type: string deprecation: description: >- Deprecation lists any migration nudges that apply to this request — the caller used a legacy /tenants route, a legacy tenant_id/sub_tenant_id field, or the deprecated sub_tenant_ids selector. It is a non-breaking signal (the status code is unchanged); omitempty keeps it absent for fully-migrated requests. A list so independent deprecations coexist without clobbering. items: $ref: '#/components/schemas/handler.deprecationNotice' type: array uniqueItems: false latency_ms: description: Server-side processing time in milliseconds. example: 12.3 type: number request_id: description: Unique identifier for this request, useful for support and tracing. example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d type: string source_type: description: Type of the parent source (e.g. `file`, `slack`, `notion`). example: file type: string sub_tenant_id: deprecated: true example: sub_tenant_4567 type: string x-deprecated: 'true' tenant_id: deprecated: true example: tenant_1234 type: string x-deprecated: 'true' type: object handler.ErrorDetail: properties: deprecated: description: Whether this response concerns a deprecated field or route. example: true type: boolean deprecated_field: description: The deprecated field name. example: tenant_id type: string error_code: description: Machine-readable error classification code. example: VALIDATION_ERROR type: string message: description: Human-readable description of the error. example: Request validation failed type: string preferred_field: description: The canonical replacement for the deprecated field. example: database type: string success: deprecated: true description: >- Deprecated for API clients: always false on this path, so it carries no information. To detect a failure read the HTTP status code; for what went wrong read the envelope's error.code and error.message, and meta.request_id when reporting it. The whole `detail` object is deprecated legacy — tagging the field individually so SDK users see it on the property, not just the container (PRO-1208). example: true type: boolean x-deprecated: 'true' type: object handler.ErrorMeta: properties: api_version: type: string latency_ms: example: 12.3 type: number request_id: description: Unique identifier for this request, useful for support and tracing. example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d type: string type: object handler.deprecationNotice: properties: deprecated: description: Whether this response concerns a deprecated field or route. example: true type: boolean deprecated_field: description: The deprecated field name. example: tenant_id type: string deprecated_since: description: API version when the field was deprecated. example: 2.0.1 type: string message: description: Migration guidance message. example: tenant_id is deprecated; use database instead. type: string preferred_field: description: The canonical replacement for the deprecated field. example: database type: string type: object securitySchemes: BearerAuth: bearerFormat: API key description: 'API key sent as a Bearer token: "Bearer prefix.secret"' scheme: bearer type: http ````