Update Source Metadata

curl -X PATCH 'https://api.hydradb.com/context/sources/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",
    "tenant_metadata": {
      "department": "legal",
      "priority": 7
    },
    "additional_metadata": {
      "author": "Legal Team",
      "doc_version": 3
    }
  }'

import requests

response = requests.patch(
    "https://api.hydradb.com/context/sources/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",
        "tenant_metadata": {
            "department": "legal",
            "priority": 7,
        },
        "additional_metadata": {
            "author": "Legal Team",
            "doc_version": 3,
        },
    },
)

const response = await fetch("https://api.hydradb.com/context/sources/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",
    tenant_metadata: {
      department: "legal",
      priority: 7,
    },
    additional_metadata: {
      author: "Legal Team",
      doc_version: 3,
    },
  }),
});

{
  "success": true,
  "data": {
    "id": "policy_main",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "team_docs",
    "updated": true,
    "tenant_metadata_keys": ["department", "priority"],
    "additional_metadata_keys": ["author", "doc_version"],
    "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
  }
}

{
  "success": true,
  "data": {
    "id": "policy_main",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "team_docs",
    "updated": true,
    "tenant_metadata_keys": ["summary_label"],
    "additional_metadata_keys": [],
    "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
  }
}

{
  "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
  }
}

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.

PATCH /context/sources/{source_id}/metadata

curl -X PATCH 'https://api.hydradb.com/context/sources/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",
    "tenant_metadata": {
      "department": "legal",
      "priority": 7
    },
    "additional_metadata": {
      "author": "Legal Team",
      "doc_version": 3
    }
  }'

import requests

response = requests.patch(
    "https://api.hydradb.com/context/sources/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",
        "tenant_metadata": {
            "department": "legal",
            "priority": 7,
        },
        "additional_metadata": {
            "author": "Legal Team",
            "doc_version": 3,
        },
    },
)

const response = await fetch("https://api.hydradb.com/context/sources/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",
    tenant_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.
	Free-form metadata fields to merge into the source’s `additional_metadata`.

At least one of tenant_metadata or additional_metadata is required.

This edit endpoint intentionally uses tenant_metadata for schema-backed source metadata. 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 metadata filters and /context/list filters.
If an edited tenant metadata field has enable_dense_embedding or enable_sparse_embedding, HydraDB synchronously refreshes the relevant Milvus metadata search lane.
If the edited fields are enable_match-only, the edit remains MongoDB-only and milvus_sync_required is false.

Response

{
  "success": true,
  "data": {
    "id": "policy_main",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "team_docs",
    "updated": true,
    "tenant_metadata_keys": ["department", "priority"],
    "additional_metadata_keys": ["author", "doc_version"],
    "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
  }
}

{
  "success": true,
  "data": {
    "id": "policy_main",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "team_docs",
    "updated": true,
    "tenant_metadata_keys": ["summary_label"],
    "additional_metadata_keys": [],
    "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
  }
}

{
  "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.
	Tenant metadata keys included in the request.
	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 Milvus when sync was required.
	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 `tenant_id`, missing `sub_tenant_id`, empty metadata payload, `document_metadata` supplied, unknown tenant metadata key when a schema exists, wrong type, reserved key, over-size value, too-deep nesting, or `null` for a dense/sparse-enabled field.
`404`	Source does not exist for the `(tenant_id, sub_tenant_id, source_id)` scope.
`500`	Metadata was written to MongoDB but dense/sparse Milvus sync failed. Retry the same idempotent edit to converge.

List Context Delete Context

⌘I

​Request

​Path parameters

​Body

​Behavior

​Response

​Validation and errors

​Related

Request

Path parameters

Body

Behavior

Response

Validation and errors

Related