POST/v1/uploads
マルチパートアップロードを開始する
create_upload
大きなファイル（インストール環境のマルチパートアップロードの上限まで。デフォルトは5GB）のアップロードセッションを開きます：名前、コンテンツタイプ、サイズ、そしてアップロードを何に使うかを示すpurposeを指定します：card_file（POST /v1/cards）、archive（POST /v1/cards/archive）、import_attachment（カスタムソースのドキュメントの添付ファイル）。レスポンスにはid（upl_に続く32文字の16進数）、パートのサイズpart_size、パートの数part_countが含まれます。最後のパート以外はすべてちょうどpart_sizeバイト（5〜100MiB）で、最後のパートは残りの部分です。完了していないアップロードは24時間有効です（expires_at）。
ファイル名の拡張子が用途の形式に含まれない場合は415 uploads.unsupported_formatを返します（インポートの添付ファイルは任意の拡張子を受け付けます）。インストール環境の上限、またはプランで決まる組織のストレージの総容量を超えるファイルは413 uploads.too_largeを返します。組織の完了していないアップロードを含めてストレージの残りが足りない場合は402 limits.storageを返します。
パートはSursaを経由し（PUT /v1/uploads/{upload_id}/parts/{n}）、ファイルストレージで組織のキーにより暗号化されます。ストレージへの直接のリンクはありません。アップロードを参照・使用できるのは、それを作成したAPIキーまたはユーザーだけです。1.62.0で追加されました。
認証
AuthorizationヘッダーでAPIキーを送信します：Authorization: Bearer <キー>。
ヘッダーパラメーター
Idempotency-Keystring書き込みを安全に再試行するためのキー：1〜255文字の印字可能なASCII文字で、論理的な操作ごとにUUID v4を使うことを推奨します。同じキーで24時間以内に再試行しても操作は再実行されず、保存済みのレスポンス（ステータス、ヘッダー、ボディ）が
Idempotency-Replayed: trueヘッダー付きで返されます。同じキーでメソッド、パス、Content-Type、ボディのいずれかが異なる場合は409 api.idempotency_mismatchを返し、最初のリクエストがまだ実行中の場合は409 api.idempotency_in_progressをRetry-After: 1付きで返します。5xxまたは429のレスポンスの後はキーが解放され、再試行で操作がもう一度実行されます。キーの有効範囲は、組織と呼び出し元（APIキー、ユーザー、カスタムソースのソースキー）の組み合わせです。length ≥ 1, length ≤ 255
リクエストボディ
application/json
filenamestring必須拡張子付きのファイル名。拡張子で形式が決まります。
length ≥ 1, length ≤ 255
content_typestring申告されたコンテンツタイプ（MIME）。ファイルのシグネチャと照合されます。
length ≤ 255
sizeinteger (int64)必須ファイルのサイズ（バイト）。
≥ 1
sha256stringファイルのSHA-256（事前にわかっている場合）。
completeは、ファイルのチェックサムをこの値と比較します。
レスポンス
201アップロードセッションが作成されました。
レスポンスヘッダー
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
Idempotency-Replayedtrueは、このIdempotency-Keyの保存済みのレスポンスが再送されたことを示します：操作は再実行されていません。
application/json
idstring必須アップロードのID（
upl_の後に16進数32文字）。filenamestring必須ファイル名（フォルダーを含まない）。
content_typestring必須申告されたコンテンツタイプ。申告されていない場合は空。
sizeinteger (int64)必須ファイルのサイズ（バイト）。
sha256string | null必須作成時または
completeで申告されたファイルのSHA-256。まだわからない場合はnull。part_sizeinteger (int64)必須最後のパートを除く各パートのサイズ（5〜100MiB）。
part_countinteger必須パートの数。
≥ 1, ≤ 1000
parts_receivedinteger必須受信したパートの数。
≥ 0
番号ごとの受信済みのパート（
POST /v1/uploadsのレスポンスでは空）。reject_reasonstring | null必須拒否の理由（
rejected）：checksum_mismatch、type_mismatch、unsupported_format、infected、scan_unavailable、unsafe_content。列挙値は増えることがあります。拒否されていない場合はnull。reject_detailsobject | null必須拒否の詳細（拡張子、申告された形式と検出された形式、チェックサム）。拒否されていない場合は
null。created_atstring (date-time)必須アップロードが作成された日時。
expires_atstring (date-time)必須アップロードを完了する期限と、準備ができた後にそれを使用する期限。
completed_atstring (date-time) | null必須検査が終わった日時（
readyまたはrejected）。consumed_atstring (date-time) | null必須アップロードが使用された日時（カード、アーカイブファイル、インポートのいずれかで）。
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
402組織がプランの上限（カード、ストレージ、ユーザー）に達しています。`error.details`には`kind`、`limit`、`used`が含まれます。
レスポンスヘッダー
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
403この操作は許可されていません：ロールの権限が足りない、コレクションやカードへのアクセス権がない、リクエストが「View as」モードで実行されている、または組織が停止中か削除済みです（`detail`は`code: org_suspended | org_deleted`を持つオブジェクト）。
レスポンスヘッダー
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
413リクエストボディが許容サイズを超えています。
レスポンスヘッダー
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
415このファイル形式はサポートされていません。
レスポンスヘッダー
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
422バリデーションエラー：ボディまたはパラメーターがスキーマに一致しない（`detail`はバリデーションエラーのリスト）、またはパラメーターの値が範囲外です（`detail`はメッセージ）。
レスポンスヘッダー
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
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か月ごとの組織のクォータです。RateLimitRateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。X-RateLimit-Remaining最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset最も厳しい制限がリセットされるまでの秒数。
application/json
エラーコード
すべてのリクエストに共通のコードに加えて、このエンドポイントがerror.codeで返すことのあるコード。
安全な再試行
POSTとPATCHのたびにIdempotency-Keyヘッダー（UUIDなど）を送信してください。24時間以内に同じキーで再試行すると、リクエストをもう一度実行せずに、保存済みのレスポンスが返ります。
レート制限
レスポンスには、RateLimitヘッダーとRateLimit-Policyヘッダー、以前のX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが含まれます。429レスポンスにはRetry-After（秒）が含まれます。その時間だけ待ってから再試行してください。