Metadata

metadata adalah kumpulan pasangan kunci-nilai milik Anda pada sebuah objek: ID catatan di CRM Anda, tim yang bertanggung jawab atasnya, eksekusi sinkronisasi yang menulisnya. Sursa menyimpannya, mengembalikannya bersama objek dan dalam peristiwa, serta memungkinkan Anda menyaring daftar kartu, koleksi, dan folder menurutnya. Sursa sama sekali tidak menafsirkannya.

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

Objek yang memiliki metadata: kartu, koleksi, dan folder. Dokumen dari sumber kustom juga membawa metadata; nilai itu menjadi metadata kartu dari dokumen tersebut.

Batas

Permintaan yang melanggar batas mengembalikan 400 dengan kode api.metadata_invalid. error.details.key menyebutkan kuncinya, dan error.details.reason menyebutkan masalahnya: too_many_keys, key_invalid, value_too_long, too_large, atau value_invalid (nilainya bukan string).

Nilai berupa string. Simpan juga angka dan tanggal sebagai string, misalnya "2026-10-24".

Menetapkan metadata

Saat Anda membuat atau mengganti objek (POST, PUT), metadata ditetapkan secara utuh:

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

Dalam permintaan multipart/form-data, seperti unggahan file, kirim metadata sebagai field formulir yang nilainya berupa objek JSON: metadata={"crm_id":"A-1042"}.

Memperbarui metadata

PATCH menggabungkan kunci yang Anda kirim ke kunci yang sudah ada. Kunci dengan nilai "" atau null dihapus; kunci yang tidak Anda kirim tetap seperti semula:

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": {} tidak mengubah apa pun. Untuk menghapus semua pasangan, kirim setiap kunci dengan null.

Menyaring menurut metadata

Daftar berikut menerima metadata[<key>]=<value>:

• kartu: GET /v1/cards dan GET /v1/cards/count;
• koleksi: GET /v1/collections;
• folder: GET /v1/folders dan GET /v1/collections/{name}/folders.

Penyaring ini mencocokkan nilai secara persis. Anda dapat menggabungkan hingga 3 syarat, dan objek harus memenuhi semuanya:

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"

Dengan penyaring, pohon folder datang sebagai daftar datar: folders dari setiap koleksi berisi folder yang cocok dengan children kosong, dan parent_id menunjukkan letak masing-masing. GET /v1/folders lalu tidak menyertakan koleksi tanpa folder yang cocok. Lebih dari 3 syarat atau kunci yang tidak valid mengembalikan 400 dengan kode api.metadata_invalid.

Apa yang bukan metadata

• Metadata bukan konten. Pencarian dan jawaban asisten tidak memakainya. Letakkan apa yang perlu ditemukan orang di teks kartu, judulnya, atau tag-nya.
• Metadata tidak privat. Setiap orang yang dapat melihat objek dapat melihat metadatanya. Jangan pernah menyimpan rahasia, token, atau data pribadi yang tidak boleh dilihat oleh pembaca objek itu.
• Metadata bukan pengganti external_id. Untuk menemukan kartu menurut ID catatan Anda, berikan kartu itu external_id; nilai itu unik, sedangkan nilai metadata tidak.