跳到主要内容
Sursa Developers

GET/v1/folders

获取所有合集的文件夹树

folder_trees

在一个响应中返回用户至少能看到一个对象的所有合集的文件夹树，可见性规则与 GET /v1/collections/{name}/folders 相同，顺序与 GET /v1/collections 相同。没有可见对象的合集不包括在内。除 cards 外，每个文件夹还包含子树合计 cards_total、sensitive_total 和 top_category。使用 updated_since 或 metadata[<key>]= 时，每个合集的 folders 以扁平列表的形式包含符合条件的文件夹（children 为空，parent_id 表示在树中的位置）。使用 updated_since 时，按 updated_at 升序、再按 id 排序；不使用时，按 sort_key 顺序排列。没有符合条件的文件夹的合集不包括在内。

身份验证

在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。

查询参数

  • limitinteger

    每页数量。不传 limit 和 cursor 时返回整个列表；传入时最多返回 limit 项，下一页通过 Link（rel="next"）和 X-Next-Cursor 头给出。

    ≥ 1, ≤ 200

  • cursorstring

    下一页的游标，取自 X-Next-Cursor 或上一个响应（筛选条件相同）的 next_cursor；游标中包含每页数量。与 offset 同时使用时返回 422 validation.failed；属于其他列表、其他筛选条件或格式错误的游标返回 400 api.cursor_invalid。

    length ≤ 512

  • updated_sincestring (date-time)

    只返回 updated_at 不早于此时刻（带时区偏移的 RFC 3339）的对象，用于同步。使用该参数时，列表按 updated_at 升序排列，再按 id 排序，游标也按这个顺序继续。已删除的对象不会列出：删除以事件的形式通知。

    length ≤ 512

  • metadatamap of string

    按 metadata 筛选：metadata[<key>]=<value> 表示精确匹配。最多 3 个条件，且必须全部满足（?metadata[team]=support&metadata[crm_id]=A-1042）。超过 3 个条件或键无效时返回 400 api.metadata_invalid。

响应

200成功响应

响应头

  • Link

    下一页的地址，<…>; rel="next"。没有此头表示当前是最后一页。

  • X-Next-Cursor

    下一页的游标，用于 cursor 参数。没有此头表示当前是最后一页。

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：FolderTreeList

array of FolderTree
  • collection_idinteger必填
  • collection_namestring必填
  • collection_titlestring必填

    用于显示的合集名称。

  • permissionsarray of string必填

    用户对该合集的有效权限。

  • unfiledinteger必填

    用户可访问、但不在任何文件夹中的合集卡片。与默认卡片列表一样，不计入已归档的卡片。

  • foldersarray of FolderNode必填
401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。

响应头

  • Retry-After

    重试请求前需要等待的秒数。

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

错误码

除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← folders · API 参考