Metadata

metadata er et sæt af dine egne nøgle-værdi-par på et objekt: id’et på posten i dit CRM, det team, der ejer den, den synkroniseringskørsel, der skrev den. Sursa gemmer dem, returnerer dem sammen med objektet og i hændelser og lader dig filtrere listerne over kort, samlinger og mapper efter dem. Sursa fortolker dem ikke på nogen måde.

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

Objekter med metadata: kort, samlinger og mapper. Et dokument fra en brugerdefineret kilde har også metadata; de bliver til metadata for dokumentets kort.

Grænser

En anmodning, der overskrider en grænse, returnerer 400 med koden api.metadata_invalid. error.details.key angiver nøglen, og error.details.reason fortæller, hvad der er galt: too_many_keys, key_invalid, value_too_long, too_large eller value_invalid (værdien er ikke en streng).

Værdier er strenge. Gem også tal og datoer som strenge, fx "2026-10-24".

Angivelse af metadata

Når du opretter eller erstatter et objekt (POST, PUT), angives metadata som en helhed:

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

I en multipart/form-data-anmodning, fx en filupload, sender du metadata som et formularfelt, hvis værdi er JSON-objektet: metadata={"crm_id":"A-1042"}.

Opdatering af metadata

PATCH fletter de nøgler, du sender, ind i de eksisterende. En nøgle med værdien "" eller null fjernes; nøgler, du ikke sender, forbliver uændrede:

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": {} ændrer ingenting. Vil du fjerne alle par, så send hver nøgle med null.

Filtrering efter metadata

Disse lister accepterer metadata[<key>]=<value>:

• kort: GET /v1/cards og GET /v1/cards/count;
• samlinger: GET /v1/collections;
• mapper: GET /v1/folders og GET /v1/collections/{name}/folders.

Værdien skal matche nøjagtigt. Du kan kombinere op til 3 betingelser, og et objekt skal opfylde dem alle:

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"

Med et filter kommer et mappetræ som en flad liste: folders for hver samling indeholder de matchende mapper med tom children, og parent_id fortæller, hvor hver mappe ligger. GET /v1/folders udelader så de samlinger, der ikke har matchende mapper. Mere end 3 betingelser eller en ugyldig nøgle returnerer 400 med koden api.metadata_invalid.

Hvad metadata ikke er

• Metadata er ikke indhold. Søgningen og assistentens svar bruger dem ikke. Læg det, som folk skal kunne finde, i kortets tekst, titel eller tags.
• Metadata er ikke private. Alle, der kan se objektet, kan se dets metadata. Gem aldrig hemmeligheder, tokens eller personoplysninger, som objektets læsere ikke må se.
• Metadata erstatter ikke external_id. Vil du finde et kort ud fra id’et på din post, så giv kortet et external_id; det er unikt, mens metadataværdier ikke er det.