Metadati

metadata ir jūsu pašu atslēgas un vērtības pāru kopa objektā: ieraksta ID jūsu CRM sistēmā, komanda, kurai objekts pieder, sinhronizācijas palaišana, kas to ierakstīja. Sursa šos pārus glabā, atgriež kopā ar objektu un notikumos un ļauj pēc tiem filtrēt kartīšu, kolekciju un mapju sarakstus. Sursa tos nekādi neinterpretē.

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

Objekti ar metadata: kartītes, kolekcijas un mapes. Arī pielāgotā avota dokumentam ir metadata; tas kļūst par dokumenta kartītes metadata.

Limiti

Pieprasījums, kas pārkāpj limitu, atgriež 400 ar kodu api.metadata_invalid. error.details.key norāda atslēgu, bet error.details.reason – kas ir nepareizi: too_many_keys, key_invalid, value_too_long, too_large vai value_invalid (vērtība nav virkne).

Vērtības ir virknes. Arī skaitļus un datumus glabājiet kā virknes, piemēram, "2026-10-24".

Metadatu iestatīšana

Kad izveidojat vai aizstājat objektu (POST, PUT), metadata tiek iestatīts kopumā:

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

Pieprasījumā multipart/form-data, piemēram, augšupielādējot failu, nosūtiet metadata kā formas lauku, kura vērtība ir JSON objekts: metadata={"crm_id":"A-1042"}.

Metadatu maiņa

PATCH apvieno nosūtītās atslēgas ar esošajām. Atslēga ar vērtību "" vai null tiek noņemta; atslēgas, kuras nenosūtāt, paliek nemainīgas:

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": {} neko nemaina. Lai noņemtu visus pārus, nosūtiet katru atslēgu ar null.

Filtrēšana pēc metadatiem

Šie saraksti pieņem metadata[<key>]=<value>:

• kartītes: GET /v1/cards un GET /v1/cards/count;
• kolekcijas: GET /v1/collections;
• mapes: GET /v1/folders un GET /v1/collections/{name}/folders.

Vērtībai jāsakrīt precīzi. Var apvienot līdz 3 nosacījumiem, un objektam jāatbilst tiem visiem:

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"

Ar filtru mapju koks tiek atgriezts kā vienkāršs saraksts: katras kolekcijas folders satur atbilstošās mapes ar tukšu children, bet parent_id norāda, kur katra no tām atrodas. GET /v1/folders tad izlaiž kolekcijas bez atbilstošām mapēm. Vairāk nekā 3 nosacījumi vai nederīga atslēga atgriež 400 ar kodu api.metadata_invalid.

Kas metadati nav

• Tie nav saturs. Meklēšana un asistenta atbildes tos neizmanto. To, kas cilvēkiem jāatrod, ierakstiet kartītes tekstā, virsrakstā vai birkās.
• Tie nav privāti. Ikviens, kas var redzēt objektu, var redzēt arī tā metadatus. Nekad neglabājiet tajos noslēpumus, marķierus vai personas datus, kurus objekta lasītājiem nevajadzētu redzēt.
• Tie neaizstāj external_id. Lai atrastu kartīti pēc jūsu ieraksta ID, piešķiriet kartītei external_id; tas ir unikāls, bet metadatu vērtības – nē.