Metadáta

metadata je sada vašich vlastných dvojíc kľúč – hodnota pri objekte: ID záznamu vo vašom CRM, tím, ktorému objekt patrí, beh synchronizácie, ktorý ho zapísal. Sursa ich uloží, vráti ich s objektom aj v udalostiach a umožní podľa nich filtrovať zoznamy kariet, kolekcií a priečinkov. Nijako ich neinterpretuje.

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

Objekty s metadata: karty, kolekcie a priečinky. metadata má aj dokument vlastného zdroja; stanú sa z nich metadata karty dokumentu.

Limity

Požiadavka, ktorá prekročí limit, vráti 400 s kódom api.metadata_invalid. error.details.key uvádza kľúč a error.details.reason hovorí, čo je zle: too_many_keys, key_invalid, value_too_long, too_large alebo value_invalid (hodnota nie je reťazec).

Hodnoty sú reťazce. Aj čísla a dátumy ukladajte ako reťazce, napríklad "2026-10-24".

Nastavenie metadát

Keď objekt vytvárate alebo nahrádzate (POST, PUT), metadata sa nastaví ako celok:

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žiadavke multipart/form-data, napríklad pri nahrávaní súboru, odošlite metadata ako pole formulára, ktorého hodnotou je objekt JSON: metadata={"crm_id":"A-1042"}.

Aktualizácia metadát

PATCH zlúči odoslané kľúče s existujúcimi. Kľúč s hodnotou "" alebo null sa odstráni; kľúče, ktoré neodošlete, zostanú bez zmeny:

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": {} nič nezmení. Ak chcete odstrániť všetky dvojice, odošlite každý kľúč s hodnotou null.

Filtrovanie podľa metadát

Tieto zoznamy prijímajú metadata[<key>]=<value>:

• karty: GET /v1/cards a GET /v1/cards/count;
• kolekcie: GET /v1/collections;
• priečinky: GET /v1/folders a GET /v1/collections/{name}/folders.

Hodnota sa musí zhodovať presne. Môžete skombinovať najviac 3 podmienky a objekt musí spĺňať všetky:

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 filtrom príde strom priečinkov ako plochý zoznam: folders každej kolekcie obsahuje vyhovujúce priečinky s prázdnym children a parent_id hovorí, kde každý z nich leží. GET /v1/folders potom vynechá kolekcie bez vyhovujúcich priečinkov. Viac ako 3 podmienky alebo neplatný kľúč vráti 400 s kódom api.metadata_invalid.

Čím metadáta nie sú

• Nie sú obsahom. Vyhľadávanie ani odpovede asistenta ich nepoužívajú. To, čo majú ľudia nájsť, vložte do textu karty, jej názvu alebo štítkov.
• Nie sú súkromné. Metadáta vidí každý, kto vidí objekt. Nikdy do nich neukladajte tajné kľúče, tokeny ani osobné údaje, ktoré čitatelia objektu nemajú vidieť.
• Nenahrádzajú external_id. Ak chcete nájsť kartu podľa ID svojho záznamu, priraďte karte external_id; ten je jedinečný, hodnoty metadát nie.