Metadata

metadata är en uppsättning egna nyckel-värde-par på ett objekt: id:t för posten i ditt CRM, teamet som äger den, synkningskörningen som skrev den. Sursa lagrar paren, returnerar dem med objektet och i händelser och låter dig filtrera listorna över kort, samlingar och mappar efter dem. Den tolkar dem inte på något sätt.

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

Objekt med metadata: kort, samlingar och mappar. Ett dokument från en egen källa har också metadata; det blir metadata för dokumentets kort.

Gränser

Ett anrop som bryter mot en gräns returnerar 400 med koden api.metadata_invalid. error.details.key anger nyckeln, och error.details.reason säger vad som är fel: too_many_keys, key_invalid, value_too_long, too_large eller value_invalid (värdet är inte en sträng).

Värdena är strängar. Lagra även tal och datum som strängar, till exempel "2026-10-24".

Ange metadata

När du skapar eller ersätter ett objekt (POST, PUT) anges metadata i sin helhet:

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 ett multipart/form-data-anrop, till exempel en filuppladdning, skickar du metadata som ett formulärfält vars värde är JSON-objektet: metadata={"crm_id":"A-1042"}.

Uppdatera metadata

PATCH slår ihop nycklarna du skickar med de befintliga. En nyckel med värdet "" eller null tas bort; nycklar du inte skickar lämnas som de är:

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": {} ändrar ingenting. För att ta bort alla par skickar du varje nyckel med null.

Filtrera efter metadata

De här listorna tar emot metadata[<key>]=<value>:

• kort: GET /v1/cards och GET /v1/cards/count;
• samlingar: GET /v1/collections;
• mappar: GET /v1/folders och GET /v1/collections/{name}/folders.

Värdet måste stämma exakt. Du kan kombinera upp till 3 villkor, och ett objekt måste uppfylla alla:

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 ett filter kommer ett mappträd som en platt lista: folders för varje samling innehåller de matchande mapparna med tomma children, och parent_id anger var var och en ligger. GET /v1/folders utelämnar då samlingarna utan matchande mappar. Fler än 3 villkor eller en ogiltig nyckel returnerar 400 med koden api.metadata_invalid.

Vad metadata inte är

• Det är inte innehåll. Sökningen och assistentens svar använder det inte. Lägg det som folk ska hitta i kortets text, rubrik eller taggar.
• Det är inte privat. Alla som kan se objektet kan se dess metadata. Lagra aldrig hemligheter, token eller personuppgifter som objektets läsare inte ska se.
• Det ersätter inte external_id. För att hitta ett kort med id:t för din post ger du kortet ett external_id; det är unikt, medan metadatavärden inte är det.