Siêu dữ liệu

metadata là tập các cặp khóa-giá trị của riêng bạn trên một đối tượng: ID của bản ghi trong CRM của bạn, đội phụ trách nó, lượt đồng bộ đã ghi nó. Sursa lưu trữ, trả về nó cùng đối tượng và trong sự kiện, và cho phép bạn lọc danh sách thẻ, bộ sưu tập và thư mục theo nó. Sursa không diễn giải nó theo bất kỳ cách nào.

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

Các đối tượng có metadata: thẻ, bộ sưu tập và thư mục. Tài liệu của một nguồn tùy chỉnh cũng mang metadata; nó trở thành metadata của thẻ tạo từ tài liệu đó.

Giới hạn

Giới hạn	Giá trị
Số cặp trên mỗi đối tượng	50
Khóa	Từ 1 đến 40 ký tự trong `A-Z`, `a-z`, `0-9`, `_`, `.` và `-`, bắt đầu bằng chữ cái hoặc chữ số
Giá trị	Chuỗi dài tối đa 500 ký tự
Toàn bộ đối tượng	Tối đa 8 KiB dưới dạng JSON

Yêu cầu vượt một giới hạn trả về 400 với mã api.metadata_invalid. error.details.key cho biết khóa, còn error.details.reason cho biết lỗi là gì: too_many_keys, key_invalid, value_too_long, too_large hoặc value_invalid (giá trị không phải chuỗi).

Giá trị là chuỗi. Hãy lưu cả số và ngày dưới dạng chuỗi, ví dụ "2026-10-24".

Đặt siêu dữ liệu

Khi bạn tạo hoặc thay thế một đối tượng (POST, PUT), metadata được đặt toàn bộ:

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

Trong yêu cầu multipart/form-data, chẳng hạn khi tải tệp lên, hãy gửi metadata dưới dạng một trường biểu mẫu có giá trị là đối tượng JSON: metadata={"crm_id":"A-1042"}.

Cập nhật siêu dữ liệu

PATCH gộp các khóa bạn gửi vào các khóa hiện có. Khóa có giá trị "" hoặc null bị xóa; các khóa bạn không gửi giữ nguyên:

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": {} không thay đổi gì. Để xóa mọi cặp, hãy gửi từng khóa với null.

Lọc theo siêu dữ liệu

Các danh sách sau chấp nhận metadata[<key>]=<value>:

thẻ: GET /v1/cards và GET /v1/cards/count;
bộ sưu tập: GET /v1/collections;
thư mục: GET /v1/folders và GET /v1/collections/{name}/folders.

Điều kiện khớp chính xác giá trị. Bạn có thể kết hợp tối đa 3 điều kiện, và đối tượng phải khớp tất cả:

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"

Khi có bộ lọc, cây thư mục được trả về dưới dạng danh sách phẳng: folders của mỗi bộ sưu tập chứa các thư mục khớp với children trống, và parent_id cho biết vị trí của từng thư mục. Khi đó GET /v1/folders bỏ qua các bộ sưu tập không có thư mục nào khớp. Hơn 3 điều kiện hoặc khóa không hợp lệ trả về 400 với mã api.metadata_invalid.

Siêu dữ liệu không phải là gì

Nó không phải nội dung. Tìm kiếm và câu trả lời của trợ lý không dùng nó. Hãy đặt những gì mọi người cần tìm vào nội dung thẻ, tiêu đề hoặc nhãn của thẻ.
Nó không riêng tư. Bất kỳ ai xem được đối tượng đều xem được siêu dữ liệu của nó. Không bao giờ lưu bí mật, token hoặc dữ liệu cá nhân mà người đọc đối tượng không được thấy.
Nó không thay thế được external_id. Để tìm thẻ theo ID bản ghi của bạn, hãy gán cho thẻ một external_id; giá trị này là duy nhất, còn giá trị siêu dữ liệu thì không.