Metadata

metadata er et sett av dine egne nøkkel-verdi-par på et objekt: ID-en til posten i CRM-systemet ditt, teamet som er ansvarlig for den, kjøringen av synkroniseringen som skrev den. Sursa lagrer settet, returnerer det sammen med objektet og i hendelser og lar deg filtrere listene over kort, samlinger og mapper etter det. Sursa tolker det ikke på noen måte.

{
  "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 i en egendefinert kilde har også metadata; det blir metadata for kortet til dokumentet.

Grenser

En forespørsel som bryter en grense, returnerer 400 med koden api.metadata_invalid. error.details.key oppgir nøkkelen, og error.details.reason sier hva som er galt: too_many_keys, key_invalid, value_too_long, too_large eller value_invalid (verdien er ikke en streng).

Verdiene er strenger. Lagre også tall og datoer som strenger, for eksempel "2026-10-24".

Angi metadata

Når du oppretter eller erstatter et objekt (POST, PUT), settes metadata under ett:

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-forespørsel, for eksempel en filopplasting, sender du metadata som et skjemafelt der verdien er JSON-objektet: metadata={"crm_id":"A-1042"}.

Oppdatere metadata

PATCH fletter nøklene du sender, inn i de eksisterende. En nøkkel med verdien "" eller null fjernes; nøkler du ikke sender, forblir som de er:

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": {} endrer ingenting. For å fjerne alle par sender du hver nøkkel med null.

Filtrere etter metadata

Disse listene godtar 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.

Verdien må stemme nøyaktig. Du kan kombinere opptil 3 betingelser, og et objekt må oppfylle 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 mappetre som en flat liste: folders for hver samling inneholder mappene som oppfyller betingelsene, med tom children, og parent_id viser hvor hver av dem ligger. GET /v1/folders utelater da samlingene uten slike mapper. Mer enn 3 betingelser eller en ugyldig nøkkel returnerer 400 med koden api.metadata_invalid.

Hva metadata ikke er

• Metadata er ikke innhold. Søket og assistentens svar bruker dem ikke. Legg det folk skal finne, i teksten på kortet, i tittelen eller i taggene.
• Metadata er ikke private. Alle som kan se objektet, kan se metadataene. Lagre aldri hemmeligheter, tokener eller personopplysninger som objektets lesere ikke skal se.
• Metadata erstatter ikke external_id. For å finne et kort etter ID-en til posten din gir du kortet en external_id; den er unik, mens metadataverdier ikke er det.