GET/v1/folders
Lấy cây thư mục của mọi bộ sưu tập
folder_trees
Trả về, trong một phản hồi, cây thư mục của mọi bộ sưu tập mà người dùng nhìn thấy ít nhất một đối tượng, với cùng quy tắc hiển thị như GET /v1/collections/{name}/folders và theo thứ tự của GET /v1/collections. Bộ sưu tập không có đối tượng nào hiển thị được bỏ qua. Ngoài cards, mỗi thư mục có các tổng của cây con cards_total, sensitive_total và top_category. Với updated_since hoặc metadata[<key>]=, folders của mỗi bộ sưu tập chứa các thư mục khớp dưới dạng danh sách phẳng (children trống, còn parent_id cho biết vị trí trong cây). Với updated_since, chúng được sắp xếp theo updated_at tăng dần, rồi theo id; khi không có nó, theo thứ tự sort_key. Bộ sưu tập không có thư mục nào khớp được bỏ qua.
Xác thực
Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.
Tham số truy vấn
limitintegerKích thước trang. Khi không có
limitvàcursor, toàn bộ danh sách được trả về; khi có, trả về tối đalimitphần tử, và trang tiếp theo được cho trong các headerLink(rel="next") vàX-Next-Cursor.≥ 1, ≤ 200
cursorstringCon trỏ của trang tiếp theo, lấy từ
X-Next-Cursorhoặcnext_cursorcủa phản hồi trước với cùng bộ lọc; con trỏ mang theo kích thước trang. Dùng cùng vớioffset:422 validation.failed; con trỏ của danh sách khác, của bộ lọc khác hoặc sai định dạng:400 api.cursor_invalid.length ≤ 512
updated_sincestring (date-time)Chỉ các đối tượng có
updated_attại hoặc sau thời điểm này (RFC 3339 có độ lệch múi giờ), dùng để đồng bộ. Khi có tham số này, danh sách được sắp xếp theoupdated_attăng dần, rồi theoid, và con trỏ tiếp tục theo thứ tự đó. Đối tượng đã bị xóa không được liệt kê: thao tác xóa được báo bằng sự kiện.length ≤ 512
metadatamap of stringLọc theo
metadata:metadata[<key>]=<value>so khớp chính xác. Tối đa 3 điều kiện, và mọi điều kiện đều phải khớp (?metadata[team]=support&metadata[crm_id]=A-1042). Quá 3 điều kiện hoặc khóa không hợp lệ trả về400 api.metadata_invalid.
Phản hồi
200Phản hồi thành công
Header phản hồi
LinkĐịa chỉ của trang tiếp theo,
<…>; rel="next". Không có header nghĩa là đây là trang cuối.X-Next-CursorCon trỏ của trang tiếp theo cho tham số
cursor. Không có header nghĩa là đây là trang cuối.RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
collection_idintegerbắt buộccollection_namestringbắt buộccollection_titlestringbắt buộcTên bộ sưu tập để hiển thị.
permissionsarray of stringbắt buộcQuyền hiệu lực của người dùng trên bộ sưu tập.
unfiledintegerbắt buộcCác thẻ của bộ sưu tập mà người dùng truy cập được nhưng không nằm trong thư mục nào. Thẻ đã lưu trữ không được tính, như trong danh sách thẻ mặc định.
401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.
Header phản hồi
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.
Header phản hồi
Retry-AfterSố giây cần chờ trước khi thử lại yêu cầu.
RateLimit-PolicyCác giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF
draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy"<name>";q=<quota>;w=<window in seconds>.keylà tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên làuser, khi không có thông tin xác thực làip);minute,dayvàmonthlà hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.RateLimitPhần còn lại của mỗi giới hạn trong
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitGiới hạn của mục chặt nhất trong
RateLimit-Policy(mục còn ít yêu cầu nhất).X-RateLimit-RemainingSố yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-ResetSố giây cho đến khi giới hạn chặt nhất được đặt lại.
application/json
Mã lỗi
Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.
Giới hạn tốc độ
Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.