Metadata

metadata is een set eigen sleutel-waardeparen op een object: de ID van het record in je CRM, het team dat er eigenaar van is, de synchronisatierun die het heeft geschreven. Sursa slaat de paren op, geeft ze terug met het object en in events, en laat je de lijsten van kaarten, collecties en mappen erop filteren. Verder doet het er niets mee.

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

Objecten met metadata: kaarten, collecties en mappen. Ook een document van een eigen bron heeft metadata; die wordt de metadata van de kaart van het document.

Limieten

Een request dat een limiet overschrijdt, geeft 400 met de code api.metadata_invalid. error.details.key noemt de sleutel en error.details.reason zegt wat er mis is: too_many_keys, key_invalid, value_too_long, too_large of value_invalid (de waarde is geen string).

Waarden zijn strings. Sla ook getallen en datums op als strings, bijvoorbeeld "2026-10-24".

Metadata instellen

Wanneer je een object maakt of vervangt (POST, PUT), wordt metadata in zijn geheel ingesteld:

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 een multipart/form-data-request, zoals het uploaden van een bestand, stuur je metadata als formulierveld waarvan de waarde het JSON-object is: metadata={"crm_id":"A-1042"}.

Metadata bijwerken

PATCH voegt de sleutels die je stuurt samen met de bestaande. Een sleutel met de waarde "" of null wordt verwijderd; sleutels die je niet stuurt, blijven zoals ze zijn:

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": {} verandert niets. Om alle paren te verwijderen, stuur je elke sleutel met null.

Filteren op metadata

Deze lijsten accepteren metadata[<key>]=<value>:

• kaarten: GET /v1/cards en GET /v1/cards/count;
• collecties: GET /v1/collections;
• mappen: GET /v1/folders en GET /v1/collections/{name}/folders.

Daarbij moet de waarde exact overeenkomen. Je kunt maximaal 3 voorwaarden combineren, en een object moet aan alle voorwaarden voldoen:

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"

Met een filter komt een mappenboom als platte lijst: folders van elke collectie bevat de overeenkomende mappen met lege children, en parent_id geeft aan waar elke map staat. GET /v1/folders laat dan de collecties zonder overeenkomende mappen weg. Meer dan 3 voorwaarden of een ongeldige sleutel geeft 400 met de code api.metadata_invalid.

Wat metadata niet is

• Het is geen inhoud. Het zoeken en de antwoorden van de assistent gebruiken het niet. Zet wat mensen moeten vinden in de tekst van de kaart, de titel of de tags.
• Het is niet privé. Iedereen die het object kan zien, ziet ook de metadata. Sla nooit geheimen, tokens of persoonsgegevens op die de lezers van het object niet mogen zien.
• Het is geen vervanging voor external_id. Om een kaart te vinden op de ID van je record, geef je de kaart een external_id; die is uniek, metadatawaarden niet.