Metadane

metadata to zestaw Twoich własnych par klucz–wartość w obiekcie: identyfikator rekordu w Twoim CRM, zespół, do którego obiekt należy, uruchomienie synchronizacji, które go zapisało. Sursa przechowuje te dane, zwraca je razem z obiektem i w zdarzeniach oraz pozwala filtrować według nich listy kart, kolekcji i folderów. W żaden sposób ich nie interpretuje.

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

Obiekty z metadata: karty, kolekcje i foldery. Dokument własnego źródła również ma metadata; stają się one metadata karty tego dokumentu.

Limity

Żądanie, które przekracza limit, zwraca 400 z kodem api.metadata_invalid. error.details.key wskazuje klucz, a error.details.reason mówi, co jest nie tak: too_many_keys, key_invalid, value_too_long, too_large lub value_invalid (wartość nie jest ciągiem znaków).

Wartości są ciągami znaków. Liczby i daty także zapisuj jako ciągi znaków, np. "2026-10-24".

Ustaw metadane

Gdy tworzysz lub zastępujesz obiekt (POST, PUT), metadata jest ustawiane w całości:

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

W żądaniu multipart/form-data, np. przy przesyłaniu pliku, wyślij metadata jako pole formularza, którego wartością jest obiekt JSON: metadata={"crm_id":"A-1042"}.

Zaktualizuj metadane

PATCH scala wysłane klucze z istniejącymi. Klucz z wartością "" lub null jest usuwany; klucze, których nie wyślesz, pozostają bez zmian:

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": {} niczego nie zmienia. Aby usunąć wszystkie pary, wyślij każdy klucz z wartością null.

Filtruj według metadanych

Te listy przyjmują metadata[<key>]=<value>:

• karty: GET /v1/cards i GET /v1/cards/count;
• kolekcje: GET /v1/collections;
• foldery: GET /v1/folders i GET /v1/collections/{name}/folders.

Wartość musi się zgadzać dokładnie. Możesz połączyć do 3 warunków, a obiekt musi spełniać wszystkie:

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"

Z filtrem drzewo folderów przychodzi jako płaska lista: folders każdej kolekcji zawiera pasujące foldery z pustym children, a parent_id wskazuje, gdzie każdy z nich się znajduje. GET /v1/folders pomija wtedy kolekcje bez pasujących folderów. Więcej niż 3 warunki lub nieprawidłowy klucz zwracają 400 z kodem api.metadata_invalid.

Czym metadane nie są

• Nie są treścią. Wyszukiwanie i odpowiedzi asystenta z nich nie korzystają. To, co ludzie mają znaleźć, umieść w tekście karty, jej tytule lub tagach.
• Nie są prywatne. Każdy, kto widzi obiekt, widzi też jego metadane. Nigdy nie przechowuj w nich sekretów, tokenów ani danych osobowych, których czytelnicy obiektu nie powinni widzieć.
• Nie zastępują external_id. Aby znaleźć kartę po identyfikatorze Twojego rekordu, nadaj karcie external_id; jest on unikalny, a wartości metadanych nie są.