Метаданные

metadata — набор ваших собственных пар «ключ — значение» у объекта: идентификатор записи в вашей CRM, команда, которая за неё отвечает, запуск синхронизации, который её записал. 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: он уникален, а значения метаданных — нет.