APIでフォルダーを作成して親を確認する

フォルダーの作成では、単一の名前または階層化されたパスを指定できます。レスポンスでは、存在する末尾フォルダーと、このリクエストで実際に追加されたパスの各部分を区別します。

アクセスの要件

REST APIを利用できるフルアクセスキーを使用してください。同じ認証情報で作成と読み取りができます。アップロードのみは作成ルートを呼び出せますが、確認用のGETは実行できません。キーの対象をワークスペースに限定できますが、フォルダーアンカーを追加するとRESTは使用できません。

変更にはcreate_folders、子フォルダーの一覧表示にはaccess_filesがメンバーのロールに必要です。

手順

1. 表示できる親フォルダーを選び、fld_…識別子をコピーしてください。ワークスペースのルートに作成する場合はparent_idを省略します。
2. 期待されるcreated_countを明確にするため、100文字以内の一意な1階層のテスト名を選んでください。
3. POST /api/foldersを{ "workspace_id":"wks_…", "parent_id":"fld_…", "name":"API verification" }とともに送信してください。
4. HTTP 201を確認し、レスポンスのfolder.id、folder.parent_id、created_count、created_folders配列を記録してください。
5. GET /api/folders/children?workspace_id=wks_…&parent_id=fld_…を呼び出してください。選択した親がワークスペースのルートの場合に限りparent_idを省略します。
6. 返されたフォルダーのうちIDがfolder.idと一致するものがちょうど1件あることを確認し、名前と親を照合してからテストフォルダーを残すかゴミ箱に移動してください。

パスの動作

作成ルートはパスを/と\の両方で分割するため、Reports/2026/Octoberで複数階層を1回のリクエストで作成できます。パス全体は500文字以内、各部分は100文字以内です。既存の部分は再利用されます。再試行が成功してcreated_count:0が返る場合や、既存部分を含むパスで作成数が部分の数より少なくなる場合があります。

201の本文には末尾フォルダーがfolder:{id,name,parent_id,workspace_id}として含まれます。created_foldersにはそのリクエストで追加された行のみが含まれます。作成するとワークスペースのツリーはすぐに変わります。後でテストを削除するには別の変更操作が必要です。

期待される結果

作成レスポンスの末尾フォルダーの識別子が、指定した親の直下の子フォルダーとして表示されます。一意の1階層のテストではcreated_count:1と、created_folders内の1件の項目が返ります。

トラブルシューティング

workspace_id is requiredまたはFolder name is requiredは本文が不完全であることを示します。メンバーシップやロールの問題はNot a member of this workspaceまたはYou don't have permission to create foldersと表示されます。存在しない親フォルダーやロックされた親フォルダーではParent folder not foundまたは構造化されたfolder_lockedレスポンスが返ります。競合により409 A folder named "<part>" already exists hereが発生する場合は、親の一覧を取得してから再試行を判断してください。

関連ガイド

• フォルダー操作を使用する
• REST APIクイックスタート