元数据

metadata 是对象上一组由您定义的键值对：CRM 中记录的 ID、负责该对象的团队、写入该对象的同步批次。Sursa 保存元数据，随对象一起返回，也会放进事件中，还可以用它筛选卡片、合集和文件夹的列表。Sursa 不会以任何方式解读元数据。

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

带有 metadata 的对象：卡片、合集和文件夹。自定义数据源的文档也带有 metadata，它会成为该文档所对应卡片的 metadata。

限制

超出限制的请求返回 400，错误码为 api.metadata_invalid。error.details.key 指出是哪个键，error.details.reason 说明问题所在：too_many_keys、key_invalid、value_too_long、too_large 或 value_invalid（值不是字符串）。

值都是字符串。数字和日期也以字符串形式保存，例如 "2026-10-24"。

设置元数据

创建或替换对象时（POST、PUT），metadata 整体设置：

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

在 multipart/form-data 请求中（例如上传文件），把 metadata 作为表单字段发送，值为 JSON 对象：metadata={"crm_id":"A-1042"}。

更新元数据

PATCH 把您发送的键合并到已有的键中。值为 "" 或 null 的键会被删除；未发送的键保持不变：

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

"metadata": {} 不会更改任何内容。要删除所有键值对，请把每个键都设为 null 发送。

按元数据筛选

以下列表接受 metadata[<key>]=<value>：

• 卡片：GET /v1/cards 和 GET /v1/cards/count；
• 合集：GET /v1/collections；
• 文件夹：GET /v1/folders 和 GET /v1/collections/{name}/folders。

按值精确匹配。最多可以组合 3 个条件，对象必须满足所有条件：

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

使用筛选条件时，文件夹树以扁平列表的形式返回：每个合集的 folders 包含符合条件的文件夹，其 children 为空，parent_id 表示每个文件夹所在的位置。此时 GET /v1/folders 不返回没有符合条件的文件夹的合集。条件超过 3 个或键无效时，返回 400，错误码为 api.metadata_invalid。

元数据不是什么

• 元数据不是内容。搜索和助手的回答都不使用元数据。希望别人找到的内容，请写进卡片的正文、标题或标签。
• 元数据不是私密的。能看到对象的人都能看到它的元数据。不要在其中保存密钥、令牌，或不应让对象读者看到的个人数据。
• 元数据不能代替 external_id。要按您的记录 ID 查找卡片，请给卡片设置 external_id；它是唯一的，而元数据的值不是。