Metadades

metadata és un conjunt de parelles clau-valor pròpies d’un objecte: l’ID de l’element al vostre CRM, l’equip que n’és responsable, l’execució de la sincronització que l’ha escrit. Sursa les desa, les retorna amb l’objecte i als esdeveniments, i us permet filtrar-hi les llistes d’entrades, col·leccions i carpetes. No les interpreta de cap manera.

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

Objectes amb metadata: entrades, col·leccions i carpetes. Un document d’una font personalitzada també porta metadata, que passa a ser el metadata de l’entrada del document.

Límits

Una sol·licitud que supera un límit retorna 400 amb el codi api.metadata_invalid. error.details.key indica la clau, i error.details.reason diu què és incorrecte: too_many_keys, key_invalid, value_too_long, too_large o value_invalid (el valor no és una cadena).

Els valors són cadenes. Deseu també els nombres i les dates com a cadenes, per exemple "2026-10-24".

Definir les metadades

Quan creeu o substituïu un objecte (POST, PUT), metadata es defineix sencer:

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

En una sol·licitud multipart/form-data, com ara una pujada de fitxer, envieu metadata com un camp de formulari amb l’objecte JSON com a valor: metadata={"crm_id":"A-1042"}.

Actualitzar les metadades

PATCH fusiona les claus que envieu amb les existents. Una clau amb el valor "" o null s’elimina; les claus que no envieu es mantenen com eren:

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": {} no canvia res. Per eliminar totes les parelles, envieu cada clau amb null.

Filtrar per metadades

Aquestes llistes accepten metadata[<key>]=<value>:

• entrades: GET /v1/cards i GET /v1/cards/count;
• col·leccions: GET /v1/collections;
• carpetes: GET /v1/folders i GET /v1/collections/{name}/folders.

El filtre coincideix exactament amb el valor. Podeu combinar fins a 3 condicions, i un objecte les ha de complir totes:

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"

Amb un filtre, un arbre de carpetes arriba com una llista plana: el folders de cada col·lecció conté les carpetes que coincideixen, amb children buit, i parent_id indica on és cadascuna. Aleshores GET /v1/folders omet les col·leccions sense carpetes que coincideixin. Més de 3 condicions o una clau no vàlida retorna 400 amb el codi api.metadata_invalid.

Què no són les metadades

• No són contingut. La cerca i les respostes de l’assistent no les fan servir. Poseu el que la gent ha de trobar al text de l’entrada, al seu títol o a les seves etiquetes.
• No són privades. Tothom qui pot veure l’objecte en pot veure les metadades. No hi deseu mai secrets, tokens ni dades personals que no hagin de veure els lectors de l’objecte.
• No substitueixen external_id. Per trobar una entrada per l’ID del vostre element, doneu a l’entrada un external_id: és únic, mentre que els valors de les metadades no ho són.