File のアップロード

Description

Uploads file content and creates a File.

パス

POST /api/v1/forward/files

リクエストヘッダー

ヘッダー	必須	説明
`Authorization`	はい	`Bearer <PAT または SAT>`
`Idempotency-Key`	いいえ	作成リクエスト用の任意の冪等性キーです。同じキーは同一リクエストにのみ再利用できます。省略した場合、ローカルの冪等リプレイ保護は提供されません。
`Content-Type`	はい	`multipart/form-data`

Query parameters

Parameter	Type	Required	Description
`identity_id`	string	No	For Identity-owned resources only. PATs may supply this query parameter; omitting it uses the administrator scope. SAT ownership is determined by the credential; any SAT (including Admin SAT) explicitly supplying this parameter, even with an empty value, receives HTTP 400. See Identity ownership.

Form フィールド

フィールド	型	必須	説明
`file`	file	はい	アップロードするファイルの内容です。最大サイズは 500 MiB です。対応する形式については、アップロード可能なファイル形式を参照してください。
`name`	string	いいえ	表示ファイル名。既定値は multipart のファイル名です。正規化後の長さは 1〜255 バイトである必要があります。
`metadata`	JSON string	No	Metadata object. `created_by` is reserved and must not be supplied (supplying it returns 400).

リクエスト例

curl -X POST "https://api.qoder.com/api/v1/forward/files" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Idempotency-Key: create-file-001" \
  -F "file=@report.pdf;type=application/pdf" \
  -F "name=report.pdf" \
  -F 'metadata={"source":"console"}'

レスポンス例

HTTP 201 Created

{
  "id": "file_xxx",
  "type": "file",
  "filename": "report.pdf",
  "size_bytes": 1024,
  "mime_type": "application/pdf",
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T10:00:00Z",
  "downloadable": false,
  "scope": null,
  "metadata": {
    "source": "console"
  },
  "identity_id": null
}

レスポンスフィールド

フィールド	型	説明
`id`	string	File ID。
`type`	string	固定値 `file`。
`filename`	string	ファイル名。
`size_bytes`	integer	バイト単位のファイルサイズ。
`mime_type`	string	MIME タイプ。
`created_at`	string	RFC 3339 形式の作成日時。
`updated_at`	string	RFC 3339 形式の最終更新日時。
`downloadable`	boolean	File をダウンロードできるかどうか。
`scope`	object/null	Resource scope associated with the File, such as a Session.
`metadata`	object	File メタデータ。
`identity_id`	string/null	Forward の所有 Identity。

エラー

HTTP	Type	発生条件
400	`invalid_request_error`	The request body, path parameters, query parameters, or multipart fields are invalid, including any SAT explicitly supplying query `identity_id` (even with an empty value).
400	`invalid_request_error`	ファイルの内容が 500 MiB を超えています。
400	`invalid_request_error`	The file type is unsupported. See Supported upload file types.
400	`invalid_request_error`	If the reserved key `created_by` is supplied, `message` is `metadata key "created_by" is reserved`, identifying the invalid field.
401	`authentication_error`	認証トークンがないか、無効です。
403	`permission_error`	管理者 Scope で Owner mismatch が発生したか、下流サービスがアクセスを拒否しました。
404	`not_found_error`	PAT で指定した Identity が存在しない、無効化または削除されている、あるいは呼び出し元に属していません。
409	`conflict_error`	リソース状態、参照関係、または冪等性キーが競合しています。
429	`rate_limit_error`	アップロード容量が不足しています。
500/502/503	`api_error`	Forward または依存サービスでエラーが発生しました。

​Description

​パス

​リクエストヘッダー

​Query parameters

​Form フィールド

​リクエスト例

​レスポンス例

​レスポンスフィールド

​エラー

Description

パス

リクエストヘッダー

Query parameters

Form フィールド

リクエスト例

レスポンス例

レスポンスフィールド

エラー