メタデータ

metadataは、オブジェクトに付ける独自のキーと値のペアの集まりです。CRMのレコードのID、担当チーム、それを書き込んだ同期の実行などを入れます。Sursaはこれを保存し、オブジェクトやイベントと一緒に返し、カード、コレクション、フォルダーのリストの絞り込みに使えるようにします。内容を解釈することは一切ありません。

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

metadataを持つオブジェクト：カード、コレクション、フォルダー。カスタムソースのドキュメントにもmetadataがあり、それがドキュメントのカードのmetadataになります。

上限

上限を超えるリクエストには、コードapi.metadata_invalidとともに400が返ります。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のリクエストでは、値をJSONオブジェクトにしたフォームのフィールドとしてmetadataを送信します：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つを超える場合や、キーが無効な場合は、コードapi.metadata_invalidとともに400が返ります。

メタデータに向かない用途

• 内容ではありません。検索とアシスタントの回答はメタデータを使いません。見つけてほしい情報は、カードの本文、タイトル、タグに入れてください。
• 非公開ではありません。オブジェクトを参照できる人は全員、そのメタデータも参照できます。シークレット、トークン、オブジェクトの閲覧者に見せてはいけない個人データは決して保存しないでください。
• external_idの代わりにはなりません。自社のレコードのIDでカードを探すには、カードにexternal_idを付けてください。こちらは一意ですが、メタデータの値は一意ではありません。