Metadati

metadata è un insieme di coppie chiave-valore tue su un oggetto: l’ID del record nel tuo CRM, il team che ne è responsabile, l’esecuzione della sincronizzazione che lo ha scritto. Sursa lo conserva, lo restituisce con l’oggetto e negli eventi e ti permette di filtrare in base a esso gli elenchi di schede, raccolte e cartelle. Non lo interpreta in alcun modo.

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

Oggetti con metadata: schede, raccolte e cartelle. Anche un documento di una fonte personalizzata porta metadata, che diventa il metadata della scheda del documento.

Limiti

Una richiesta che supera un limite restituisce 400 con il codice api.metadata_invalid. error.details.key indica la chiave ed error.details.reason dice cosa non va: too_many_keys, key_invalid, value_too_long, too_large o value_invalid (il valore non è una stringa).

I valori sono stringhe. Conserva come stringhe anche numeri e date, per esempio "2026-10-24".

Impostare i metadati

Quando crei o sostituisci un oggetto (POST, PUT), metadata viene impostato per intero:

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

In una richiesta multipart/form-data, come il caricamento di un file, invia metadata come campo del modulo il cui valore è l’oggetto JSON: metadata={"crm_id":"A-1042"}.

Aggiornare i metadati

PATCH unisce le chiavi che invii a quelle esistenti. Una chiave con il valore "" o null viene rimossa; le chiavi che non invii restano come sono:

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": {} non cambia nulla. Per rimuovere tutte le coppie, invia ogni chiave con null.

Filtrare per metadati

Questi elenchi accettano metadata[<key>]=<value>:

• schede: GET /v1/cards e GET /v1/cards/count;
• raccolte: GET /v1/collections;
• cartelle: GET /v1/folders e GET /v1/collections/{name}/folders.

La corrispondenza con il valore è esatta. Puoi combinare fino a 3 condizioni, e un oggetto deve soddisfarle tutte:

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"

Con un filtro, un albero di cartelle arriva come elenco piatto: folders di ogni raccolta contiene le cartelle corrispondenti con children vuoto, e parent_id indica dove si trova ciascuna. GET /v1/folders in questo caso omette le raccolte senza cartelle corrispondenti. Più di 3 condizioni o una chiave non valida restituiscono 400 con il codice api.metadata_invalid.

Cosa non sono i metadati

• Non sono contenuto. La ricerca e le risposte dell’assistente non li usano. Ciò che le persone devono trovare va nel testo della scheda, nel titolo o nei tag.
• Non sono privati. Chiunque può vedere l’oggetto può vederne i metadati. Non conservare mai segreti, token o dati personali che i lettori dell’oggetto non devono vedere.
• Non sostituiscono external_id. Per trovare una scheda in base all’ID del tuo record, assegna alla scheda un external_id; è univoco, mentre i valori dei metadati non lo sono.