Metatiedot

metadata on objektiin liitetty joukko omia avain–arvo-parejasi: tietueen tunnus CRM-järjestelmässäsi, objektin omistava tiimi, sen kirjoittanut synkronointiajo. Sursa tallentaa metatiedot, palauttaa ne objektin mukana ja tapahtumissa ja antaa suodattaa korttien, kokoelmien ja kansioiden listoja niiden mukaan. Sursa ei tulkitse niitä millään tavalla.

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

Objektit, joilla on metadata: kortit, kokoelmat ja kansiot. Myös mukautetun lähteen asiakirjalla on metadata; siitä tulee asiakirjan kortin metadata.

Rajat

Rajan ylittävä pyyntö palauttaa 400-vastauksen ja koodin api.metadata_invalid. error.details.key kertoo avaimen, ja error.details.reason kertoo, mikä on vialla: too_many_keys, key_invalid, value_too_long, too_large tai value_invalid (arvo ei ole merkkijono).

Arvot ovat merkkijonoja. Tallenna myös luvut ja päivämäärät merkkijonoina, esimerkiksi "2026-10-24".

Metatietojen asettaminen

Kun luot tai korvaat objektin (POST, PUT), metadata asetetaan kokonaisuutena:

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

multipart/form-data-pyynnössä, kuten tiedoston latauksessa, lähetä metadata lomakekenttänä, jonka arvo on JSON-objekti: metadata={"crm_id":"A-1042"}.

Metatietojen päivittäminen

PATCH yhdistää lähettämäsi avaimet olemassa oleviin. Avain, jonka arvo on "" tai null, poistetaan; avaimet, joita et lähetä, pysyvät ennallaan:

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": {} ei muuta mitään. Jos haluat poistaa kaikki parit, lähetä jokainen avain arvolla null.

Suodatus metatietojen mukaan

Seuraavat listat hyväksyvät parametrin metadata[<key>]=<value>:

• kortit: GET /v1/cards ja GET /v1/cards/count;
• kokoelmat: GET /v1/collections;
• kansiot: GET /v1/folders ja GET /v1/collections/{name}/folders.

Se vastaa arvoa täsmälleen. Voit yhdistää enintään 3 ehtoa, ja objektin täytyy täyttää ne kaikki:

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"

Suodattimen kanssa kansiopuu tulee tasaisena listana: kunkin kokoelman folders sisältää vastaavat kansiot tyhjällä children-kentällä, ja parent_id kertoo, missä kukin niistä sijaitsee. GET /v1/folders jättää tällöin pois kokoelmat, joissa ei ole vastaavia kansioita. Yli 3 ehtoa tai virheellinen avain palauttaa 400-vastauksen ja koodin api.metadata_invalid.

Mitä metatiedot eivät ole

• Ne eivät ole sisältöä. Haku ja avustajan vastaukset eivät käytä niitä. Kirjoita se, mitä ihmisten pitää löytää, kortin tekstiin, otsikkoon tai tunnisteisiin.
• Ne eivät ole yksityisiä. Jokainen, joka näkee objektin, näkee myös sen metatiedot. Älä koskaan tallenna niihin salaisuuksia, käyttöoikeustunnuksia tai henkilötietoja, joita objektin lukijoiden ei pidä nähdä.
• Ne eivät korvaa external_id-kenttää. Jos haluat löytää kortin oman tietueesi tunnuksella, anna kortille external_id; se on yksilöllinen, metatietojen arvot eivät ole.