POST/v1/uploads/{upload_id}/complete

アップロードを完了する

complete_upload

すべてのパートを受信すると、Sursaはファイルを組み立て、ファイル全体のSHA-256をボディのsha256と比較し、1回のリクエストでのアップロードと同じ検査を行います：内容のシグネチャによる形式の確認とウイルススキャンです。結果はready、またはreject_reason付きのrejectedです（checksum_mismatch、type_mismatch、unsupported_format、infected、scan_unavailable、unsafe_content）。形式の確認またはウイルススキャンによる拒否は、それぞれfile.rejectedとして監査ログに記録されます。

200のレスポンスは結果が出たことを示します。202はファイルをまだ検査中（processing）であることを示し、結果はGET /v1/uploads/{upload_id}で取得します。状態がpendingに戻った場合（APIのインスタンスの再起動で検査が中断された場合）は、もう一度completeを送信してください。結果が出た後にcompleteを繰り返すと、同じ結果が返ります。足りないパートがある場合は409 uploads.incomplete（details.missing）を返します。作成時に宣言したものと異なるsha256、または受信したパートと異なるparts[].etagは422 uploads.checksum_mismatchを返します。準備が完了したアップロードは、使用されなければ24時間有効です。1.62.0で追加されました。

認証

AuthorizationヘッダーでAPIキーを送信します：Authorization: Bearer <キー>。

パスパラメーター

upload_idstring必須
アップロードのID（upl_に続く32文字の16進数）。
length ≤ 64

ヘッダーパラメーター

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

オブジェクト：UploadComplete

sha256string必須
ファイル全体のSHA-256。
partsarray of UploadPartRef
任意のパートの確認：PUT …/parts/{n}が返した各パートのETag。
items ≤ 1000

レスポンス

200結果が出ました：`ready`または`rejected`。

レスポンスヘッダー

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
最も厳しい制限がリセットされるまでの秒数。
Idempotency-Replayed
trueは、このIdempotency-Keyの保存済みのレスポンスが再送されたことを示します：操作は再実行されていません。

application/json

オブジェクト：Upload

idstring必須
アップロードのID（upl_の後に16進数32文字）。
purposeUploadPurpose必須
filenamestring必須
ファイル名（フォルダーを含まない）。
content_typestring必須
申告されたコンテンツタイプ。申告されていない場合は空。
sizeinteger (int64)必須
ファイルのサイズ（バイト）。
sha256string | null必須
作成時またはcompleteで申告されたファイルのSHA-256。まだわからない場合はnull。
statusUploadStatus必須
part_sizeinteger (int64)必須
最後のパートを除く各パートのサイズ（5〜100MiB）。
part_countinteger必須
パートの数。
≥ 1, ≤ 1000
parts_receivedinteger必須
受信したパートの数。
≥ 0
partsarray of UploadPart必須
番号ごとの受信済みのパート（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必須
アップロードが使用された日時（カード、アーカイブファイル、インポートのいずれかで）。

202ファイルはまだ検査中です（`processing`）。

レスポンスヘッダー

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
最も厳しい制限がリセットされるまでの秒数。
Idempotency-Replayed
trueは、このIdempotency-Keyの保存済みのレスポンスが再送されたことを示します：操作は再実行されていません。

application/json

オブジェクト：Upload

idstring必須
アップロードのID（upl_の後に16進数32文字）。
purposeUploadPurpose必須
filenamestring必須
ファイル名（フォルダーを含まない）。
content_typestring必須
申告されたコンテンツタイプ。申告されていない場合は空。
sizeinteger (int64)必須
ファイルのサイズ（バイト）。
sha256string | null必須
作成時またはcompleteで申告されたファイルのSHA-256。まだわからない場合はnull。
statusUploadStatus必須
part_sizeinteger (int64)必須
最後のパートを除く各パートのサイズ（5〜100MiB）。
part_countinteger必須
パートの数。
≥ 1, ≤ 1000
parts_receivedinteger必須
受信したパートの数。
≥ 0
partsarray of UploadPart必須
番号ごとの受信済みのパート（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か月ごとの組織のクォータです。
RateLimit
RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。
X-RateLimit-Remaining
最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset
最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

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か月ごとの組織のクォータです。
RateLimit
RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。
X-RateLimit-Remaining
最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset
最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

404オブジェクトが存在しないか、アクセスできません。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
最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

409オブジェクトの状態により、この操作を実行できません。たとえば、重複している、インデックス作成中である、ジョブがすでに処理済みである場合です。

レスポンスヘッダー

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

オブジェクト：Error

410オブジェクトは存在していましたが、もう利用できません：リンクが使用済みか期限切れである、またはファイルが保持期間の終了時に削除されています。

レスポンスヘッダー

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

オブジェクト：Error

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か月ごとの組織のクォータです。
RateLimit
RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。
X-RateLimit-Remaining
最も厳しい制限での残りのリクエスト数。
X-RateLimit-Reset
最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

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
最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

エラーコード

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

安全な再試行

POSTとPATCHのたびにIdempotency-Keyヘッダー（UUIDなど）を送信してください。24時間以内に同じキーで再試行すると、リクエストをもう一度実行せずに、保存済みのレスポンスが返ります。

レート制限

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

← uploads · APIリファレンス

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

試してみる

APIキー

キーはこのタブのメモリにだけ保持され、https://api.sursa.comにだけ送信されます。

リクエストは組織の実際のデータに対して実行されます。

Idempotency-Key header

upload_id path *

Idempotency-Key

空欄の場合は、リクエストごとに新しいキーが生成されます。

リクエストボディ（JSON）