本文へスキップ
Sursa Developers

GET/v1/folders

すべてのコレクションのフォルダーツリーを取得する

folder_trees

ユーザーが1つ以上のオブジェクトにアクセスできるすべてのコレクションのフォルダーツリーを、1つのレスポンスで返します。アクセスの規則は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の暦の上での1分・1日・1か月ごとの組織のクォータです。

  • 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の暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り:"<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目(残りのリクエスト数が最も少ない項目)の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

429リクエストが多すぎる(`api.rate_limited`)、組織の1分・1日・1か月のクォータを使い切った(`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の暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り:"<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目(残りのリクエスト数が最も少ない項目)の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

エラーコード

すべてのリクエストに共通のコードに加えて、このエンドポイントがerror.codeで返すことのあるコード。

レート制限

レスポンスには、RateLimitヘッダーとRateLimit-Policyヘッダー、以前のX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが含まれます。429レスポンスにはRetry-After(秒)が含まれます。その時間だけ待ってから再試行してください。

← folders · APIリファレンス