Metadata

metadata je sada vašich vlastních dvojic klíč–hodnota u objektu: identifikátor záznamu ve vašem CRM, tým, který objekt spravuje, běh synchronizace, který ho zapsal. Sursa je ukládá, vrací je s objektem i v událostech a umožňuje podle nich filtrovat seznamy karet, kolekcí a složek. Nijak je nevykládá.

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

Objekty s metadata: karty, kolekce a složky. Také dokument vlastního zdroje nese metadata; z nich se stanou metadata karty dokumentu.

Limity

Požadavek, který poruší limit, vrátí 400 s kódem api.metadata_invalid. error.details.key uvádí klíč a error.details.reason říká, co je špatně: too_many_keys, key_invalid, value_too_long, too_large nebo value_invalid (hodnota není řetězec).

Hodnoty jsou řetězce. Čísla a data ukládejte také jako řetězce, například "2026-10-24".

Nastavení metadat

Při vytvoření nebo nahrazení objektu (POST, PUT) se metadata nastaví jako celek:

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

V požadavku multipart/form-data, například při nahrávání souboru, odešlete metadata jako pole formuláře, jehož hodnotou je objekt JSON: metadata={"crm_id":"A-1042"}.

Aktualizace metadat

PATCH sloučí odeslané klíče se stávajícími. Klíč s hodnotou "" nebo null se odstraní; klíče, které neodešlete, zůstanou beze změny:

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": {} nic nezmění. Chcete-li odstranit všechny dvojice, odešlete každý klíč s null.

Filtrování podle metadat

Tyto seznamy přijímají metadata[<key>]=<value>:

• karty: GET /v1/cards a GET /v1/cards/count;
• kolekce: GET /v1/collections;
• složky: GET /v1/folders a GET /v1/collections/{name}/folders.

Hodnota se porovnává přesně. Kombinovat lze až 3 podmínky a objekt musí splnit všechny:

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"

S filtrem přichází strom složek jako plochý seznam: folders každé kolekce obsahuje odpovídající složky s prázdným children a parent_id udává, kde každá z nich leží. GET /v1/folders pak vynechá kolekce bez odpovídajících složek. Více než 3 podmínky nebo neplatný klíč vrátí 400 s kódem api.metadata_invalid.

Čím metadata nejsou

• Nejsou obsahem. Vyhledávání ani odpovědi asistenta je nepoužívají. Co mají lidé najít, patří do textu karty, jejího názvu nebo štítků.
• Nejsou soukromá. Metadata objektu vidí každý, kdo vidí objekt. Nikdy do nich neukládejte tajné klíče, tokeny ani osobní údaje, které čtenáři objektu nemají vidět.
• Nenahrazují external_id. Chcete-li kartu najít podle identifikátoru svého záznamu, přidělte kartě external_id; ten je jedinečný, hodnoty metadat nikoli.