Métadonnées

metadata est un ensemble de paires clé-valeur qui vous appartiennent, attachées à un objet : l’identifiant de l’enregistrement dans votre CRM, l’équipe qui en est responsable, l’exécution de la synchronisation qui l’a écrit. Sursa les conserve, les renvoie avec l’objet et dans les événements, et vous permet de filtrer selon elles les listes de fiches, de collections et de dossiers. Il ne les interprète d’aucune façon.

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

Objets qui ont des metadata : les fiches, les collections et les dossiers. Un document d’une source personnalisée porte aussi des metadata ; elles deviennent les metadata de la fiche du document.

Limites

Une requête qui dépasse une limite renvoie 400 avec le code api.metadata_invalid. error.details.key nomme la clé et error.details.reason indique le problème : too_many_keys, key_invalid, value_too_long, too_large ou value_invalid (la valeur n’est pas une chaîne).

Les valeurs sont des chaînes. Stockez aussi les nombres et les dates sous forme de chaînes, par exemple "2026-10-24".

Définir les métadonnées

Quand vous créez ou remplacez un objet (POST, PUT), metadata est défini en bloc :

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

Dans une requête multipart/form-data, comme un téléversement de fichier, envoyez metadata dans un champ de formulaire dont la valeur est l’objet JSON : metadata={"crm_id":"A-1042"}.

Modifier les métadonnées

PATCH fusionne les clés que vous envoyez avec les clés existantes. Une clé de valeur "" ou null est supprimée ; les clés que vous n’envoyez pas restent inchangées :

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": {} ne change rien. Pour supprimer toutes les paires, envoyez chaque clé avec null.

Filtrer selon les métadonnées

Les listes suivantes acceptent metadata[<key>]=<value> :

• fiches : GET /v1/cards et GET /v1/cards/count ;
• collections : GET /v1/collections ;
• dossiers : GET /v1/folders et GET /v1/collections/{name}/folders.

La valeur doit correspondre exactement. Vous pouvez combiner jusqu’à 3 conditions, et un objet doit les remplir toutes :

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"

Avec un filtre, une arborescence de dossiers arrive sous forme de liste à plat : folders de chaque collection contient les dossiers correspondants avec des children vides, et parent_id indique où se trouve chacun d’eux. GET /v1/folders omet alors les collections sans dossier correspondant. Plus de 3 conditions ou une clé invalide renvoie 400 avec le code api.metadata_invalid.

Ce que les métadonnées ne sont pas

• Ce n’est pas du contenu. La recherche et les réponses de l’assistant ne les utilisent pas. Placez ce que les gens doivent trouver dans le texte de la fiche, son titre ou ses étiquettes.
• Elles ne sont pas privées. Toute personne qui peut voir l’objet voit ses métadonnées. N’y stockez jamais de secrets, de jetons ni de données personnelles que les lecteurs de l’objet ne doivent pas voir.
• Elles ne remplacent pas external_id. Pour trouver une fiche par l’identifiant de votre enregistrement, donnez-lui un external_id : il est unique, alors que les valeurs des métadonnées ne le sont pas.