Метадані

metadata — це набір ваших власних пар «ключ — значення» в об’єкті: ідентифікатор запису у вашій CRM, команда, відповідальна за нього, запуск синхронізації, що його записав. 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. Щоб знаходити картку за ідентифікатором вашого запису, задайте картці external_id; він унікальний, а значення метаданих — ні.