ログイン無料で始める

ファイル API リファレンス

プロジェクトの共有ファイル、フォルダ、リビジョン履歴を操作する API です。

ℹ️

認証・エラー形式・ロールは REST API リファレンスの共通仕様 を参照してください。このページの auth 列は、読む = 全 project member、書く = owner / admin / member、admin = owner / admin を表します。

前提

  • project でファイル機能が有効であること。無効な project への呼び出しは 404 です。
  • {projectId}、{fileId}、{folderId} は UUID、{revision} は 1 始まりの整数です。
  • フォルダは最大 5 階層です。フォルダを自分自身や子孫の下へ移動することはできません。
  • 同じフォルダへ同名のファイルをアップロードすると、新しいファイルではなく新しいリビジョンになります。名前は大文字小文字を区別する完全一致で比較します。
  • リビジョンはファイルごとに直近 10 版を保持します。古い版と対応する添付は自動的に削除対象になります。
  • ストレージ容量は課題・Wiki の添付と共用です。現在の上限は Free が project ごとに 100 MB、Pro が 10 GB です。上限超過は添付のアップロード開始時に 402 plan_limit となります。

アップロードの流れ

  1. 添付 API の POST /api/projects/{projectId}/attachments で presigned PUT URL を取得します。
  2. 取得した URL へファイルを PUT し、POST /api/projects/{projectId}/attachments/{attachmentId}/complete で添付を ready にします。
  3. POST /api/projects/{projectId}/files に attachmentId を渡します。

指定できるのは、認証ユーザー自身がアップロードした、未紐付けかつ ready の添付だけです。

ツリー

GET/api/projects/{projectId}/files/tree読む

project のフォルダ、各ファイルの最新リビジョン、ストレージ使用量を一括で返します。

{
  "folders": [
    {
      "id": "folder-uuid",
      "parentId": null,
      "name": "設計資料",
      "updatedAt": "2026-08-31T01:23:45.678Z"
    }
  ],
  "files": [
    {
      "id": "file-uuid",
      "folderId": "folder-uuid",
      "name": "要件定義.pdf",
      "currentRevision": 2,
      "size": 2048,
      "mime": "application/pdf",
      "createdBy": { "id": "user-uuid", "displayName": "山田" },
      "updatedBy": { "id": "user-uuid", "displayName": "山田" },
      "updatedAt": "2026-08-31T02:00:00.000Z"
    }
  ],
  "usage": {
    "usedBytes": 4096,
    "limitBytes": 104857600
  }
}

createdBy と updatedBy はユーザーを解決できない場合 null です。usedBytes は project の pending または ready の添付が予約・使用している合計バイト数です。limitBytes はプランの上限バイト数で、上限なしのプラン設定では null になり得ます。

status意味
200{ folders, files, usage }
403project を読む権限がない
404project が見つからない、またはファイル機能が無効

ファイル

POST/api/projects/{projectId}/files書く

upload 完了済みの添付を共有ファイルとして登録します。同じフォルダに同名ファイルがあれば、新しいリビジョンを追加します。

{
  "attachmentId": "attachment-uuid",
  "folderId": "folder-uuid",
  "name": "要件定義.pdf"
}
field条件
attachmentId必須。自分がアップロードした未紐付けの ready 添付 UUID
folderId同じ project のフォルダ UUID。省略または null はルート
name省略時は添付の filename。1〜255 文字
{
  "file": {
    "id": "file-uuid",
    "folderId": "folder-uuid",
    "name": "要件定義.pdf",
    "currentRevision": 2,
    "size": 2048,
    "mime": "application/pdf",
    "createdBy": { "id": "user-uuid", "displayName": "山田" },
    "updatedBy": { "id": "user-uuid", "displayName": "山田" },
    "updatedAt": "2026-08-31T02:00:00.000Z"
  },
  "revision": 2
}
statuserror意味
201—{ "file": ProjectFile, "revision": number }
400入力エラー文添付、名前、UUID が不正
403権限エラー文owner / admin / member ではない
404folder_not_found指定フォルダが見つからない
409file_conflict同名アップロードが同時実行され競合した
GET/api/projects/{projectId}/files/{fileId}読む

ファイルの最新メタ情報と、リビジョンを新しい順で返します。

{
  "file": {
    "id": "file-uuid",
    "folderId": null,
    "name": "要件定義.pdf",
    "currentRevision": 2,
    "size": 2048,
    "mime": "application/pdf",
    "createdBy": { "id": "user-uuid", "displayName": "山田" },
    "updatedBy": { "id": "user-uuid", "displayName": "佐藤" },
    "updatedAt": "2026-08-31T02:00:00.000Z",
    "revisions": [
      {
        "revision": 2,
        "size": 2048,
        "mime": "application/pdf",
        "uploadedBy": { "id": "user-uuid", "displayName": "佐藤" },
        "createdAt": "2026-08-31T02:00:00.000Z"
      }
    ]
  }
}

uploadedBy はユーザーを解決できない場合 null です。

status意味
200{ "file": ProjectFileDetail }
403project を読む権限がない
404ファイルが見つからない、project が見つからない、または機能が無効
PATCH/api/projects/{projectId}/files/{fileId}書く

ファイルをリネーム、または別のフォルダへ移動します。1 項目以上を指定してください。

{
  "name": "要件定義（確定版）.pdf",
  "folderId": null
}

folderId: null はルートへの移動です。成功時は { "file": ProjectFile } を返します。

statuserror意味
200—更新したファイル
400入力エラー文変更項目がない、または名前・UUID が不正
403権限エラー文ファイルを更新する権限がない
404folder_not_found またはエラー文ファイルまたは移動先フォルダが見つからない
409file_name_taken移動先に同名ファイルがある
DELETE/api/projects/{projectId}/files/{fileId}本人 / admin

ファイルとすべてのリビジョンを削除します。復元はできません。member は自分がアップロードしたファイルだけを削除できます。

status意味
204削除済み。レスポンス body なし
403ファイルを削除する権限がない
404ファイルが見つからない、project が見つからない、または機能が無効

ダウンロード

GET/api/projects/{projectId}/files/{fileId}/download?revision={revision}&redirect=1読む

指定リビジョンをダウンロードする presigned URL を発行します。revision を省略すると最新版です。

redirect=1 を省略した場合は、5 分間有効な URL を JSON で返します。

{
  "url": "https://storage.example.com/presigned-url",
  "expiresAt": "2026-08-31T02:05:00.000Z"
}

redirect=1 の場合は presigned URL へ 302 リダイレクトし、cache-control: private, no-store を付けます。ダウンロード時のファイル名は、最新版では現在のファイル名、旧版ではそのリビジョンのアップロード時 filename です。

statuserror意味
200—{ url, expiresAt }
302—redirect=1 のリダイレクト
400エラー文revision が不正
403権限エラー文project を読む権限がない
404エラー文ファイルまたはリビジョンが見つからない
503storage_unavailable添付ストレージが設定されていない

フォルダ

POST/api/projects/{projectId}/folders書く

フォルダを作成します。

{
  "name": "設計資料",
  "parentId": null
}

成功時は 201 で次の形式を返します。

{
  "folder": {
    "id": "folder-uuid",
    "parentId": null,
    "name": "設計資料",
    "updatedAt": "2026-08-31T01:23:45.678Z"
  }
}
statuserror意味
201—{ "folder": ProjectFolder }
400入力エラー文名前または UUID が不正
403権限エラー文フォルダを作成する権限がない
404folder_not_found親フォルダが見つからない
409folder_name_taken同じ場所に同名フォルダがある
422folder_too_deep5 階層を超える
PATCH/api/projects/{projectId}/folders/{folderId}書く

フォルダをリネーム、または別の親フォルダへ移動します。1 項目以上を指定してください。

{
  "name": "設計・仕様",
  "parentId": "parent-folder-uuid"
}

parentId: null はルートへの移動です。成功時は { "folder": ProjectFolder } を返します。

statuserror意味
200—更新したフォルダ
400入力エラー文変更項目がない、または名前・UUID が不正
403権限エラー文フォルダを更新する権限がない
404folder_not_found またはエラー文対象または移動先フォルダが見つからない
409folder_name_taken移動先に同名フォルダがある
422folder_cycle自分自身または子孫の下への移動
422folder_too_deep移動後に 5 階層を超える
DELETE/api/projects/{projectId}/folders/{folderId}admin

フォルダを削除します。子フォルダ、ファイル、リビジョンも削除され、復元はできません。

status意味
204削除済み。レスポンス body なし
403owner / admin ではない
404フォルダが見つからない、project が見つからない、または機能が無効

名前とエラー形式

ファイル名とフォルダ名は 1〜255 文字です。/ を含む名前と、. または .. だけの名前は 400 になります。前後の空白は取り除かれます。

ルートや入力検証で返すエラーは、次の形式です。

{ "error": "名前を入力してください。" }

FilesError に対応するエラーは、機械判定用の error と表示用の message を返します。専用コードがない場合は、両方に同じメッセージが入ります。

{
  "error": "folder_name_taken",
  "message": "同じ場所に同名のフォルダがあります。"
}

現行実装では、未認証は 401、project の操作権限がない場合は 403 です。形式が不正な UUID、存在しないリソース、ファイル機能が無効な project は 404 で返します。

ファイル API リファレンス | Nolto