POST/v1/cards

ファイルをカードとしてアップロードする

upload_card

ドキュメントはmultipart/form-dataフォームのfileフィールドで送信してください。保存の前に、Sursaはファイル名の拡張子、パートで宣言されたContent-Type、内容のシグネチャが一致することを確認します：
- PDF。
- DOCX、XLSX、XLSM、PPTX：宣言されたメインドキュメントの種類を持つZIP。
- ODS：mimetypeエントリーを持つZIP。
- XLS：ブックのストリームを持つOLE2ドキュメント。
- TXT、MD、CSV、TSV、HTML、AsciiDoc、EML：UTF-8またはシングルバイトのエンコーディングで書かれたnullバイトを含まないテキスト。メールの場合は先頭にヘッダーがあること。
- PNG、JPEG、TIFF、WebP、BMP：シグネチャで判定。

一致しない場合は415 files.type_mismatch、対応形式の一覧にない拡張子は415 cards.unsupported_formatを返します。インストール環境のアップロード上限、またはプランで決まる組織のストレージの総容量を超えるファイルは413 files.too_largeを返します。ウイルススキャンが有効な場合、感染したファイルは422 files.infectedを返し、「reject」ポリシーでスキャナーが利用できないときは、リクエストは503 files.scan_unavailableを返します。拒否はそれぞれfile.rejectedとして監査ログに記録されます。

フォームの代わりにapplication/jsonボディ（CardUploadFromUpload、1.62.0以降）を送ることもできます：ファイルは完了済みのマルチパートアップロードupload_id（card_file用途のPOST /v1/uploads）、フィールドはフォームと同じで、tagsは文字列のリストです。アップロードのファイルはcompleteの時点で検査済み（形式、ウイルススキャン）で、サイズの上限は1回のリクエストでのアップロードの上限ではなく、マルチパートアップロードの上限です。アップロードは、カードを作成するのと同じトランザクションの中で一度だけ使われます：使用済みのアップロードは409 uploads.already_used、まだ準備ができていないものは409 uploads.not_ready、拒否されたものは422 uploads.rejected、用途が異なるものは422 uploads.purpose_mismatch、期限切れのものは410 uploads.expired、別の呼び出し元のものや不明なアップロードは404 uploads.not_foundを返します。カードの検査（コレクション、カテゴリ、上限）に失敗した場合、アップロードは消費されません。

認証

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
X-View-Asstring
adminロールのAPIキー専用です。データプロファイル<profile>[:viewer|verifier|editor]（例：employee:viewer）としてリクエストを実行します。インストールキーではこのヘッダーを使えません（403）。

Cookieパラメーター

kb_view_asstring
セッションの「View as」モードのCookie。POST /auth/view-asで設定し、DELETE /auth/view-asで解除します。

リクエストボディ

multipart/form-data

オブジェクト：CardUploadForm

filestring (application/octet-stream)必須
collectionstring
デフォルト："default"
tagsstring
デフォルト：""
forceboolean
デフォルト：false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
デフォルト：false
reviewboolean
デフォルト：false
folder_idstring | null
新しいカードを入れるcollectionのフォルダー。ほかのコレクションのフォルダーでは400 folders.card_collection_mismatch、存在しないフォルダーでは404 folders.not_found、フォルダーに対するCOLLECTION_EDIT_CARDS権限がない場合は403 authz.forbiddenが返ります。この確認はファイルの保存前に行われます。すでにアップロード済みのファイルの重複（skipped）は、フォルダーに移動されません。
length ≤ 64
collection_idinteger | null
IDで指定するコレクション。collectionも渡した場合は、collection_idが優先されます。組織に存在しない、または参照できないコレクションでは404 collections.not_foundが返ります。
external_idstring | null
新しいカードのexternal_id。これを指定すると、コレクションに同じファイルがすでにあってもカードが作成されます。組織のほかのカードがこの値を使っている場合、リクエストは409 cards.external_id_takenを返します。external_idでカードを作成または置換するには、PUT /v1/cards-by-external-id/{external_id}を使用してください。
length ≤ 512
metadatastring | null
新しいカードのmetadata：フォームフィールドの値として渡すJSONオブジェクト。規則はMetadataPatchと同じです。

application/json

オブジェクト：CardUploadFromUpload

upload_idstring必須
card_file用途の準備済み（ready）のアップロード。一度だけ使用されます。
collectionstring
デフォルト："default"
collection_idinteger | null
IDで指定するコレクション。collectionも渡した場合はcollection_idが優先されます。組織に存在しないコレクション、参照できないコレクション、キーのコレクションの外にあるコレクションは404 collections.not_foundを返します。
tagsarray of string
items ≤ 30
forceboolean
デフォルト：false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
デフォルト：false
reviewboolean
デフォルト：false
folder_idstring | null
length ≤ 64
external_idstring | null
新しいカードのexternal_id。フォームのフィールドと同じです。指定すると、コレクションに同じファイルがすでにあってもカードが作成されます。組織の別のカードがこの値を使っている場合、リクエストは409 cards.external_id_takenを返します。
length ≤ 512
metadataMetadataPatch

レスポンス

200`queued`（非同期）、`skipped`（重複）、`ready`または`error`（同期）。

レスポンスヘッダー

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

オブジェクト：UploadResult

statusstring必須
指定できる値: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchangedまたはan identical file is already indexed。
tablesinteger
timingsobject
フィールド
- total_snumber
errorstring

400リクエストが無効です：パラメーターの値またはオブジェクトの状態により、この操作を実行できません（`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

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

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か月ごとの組織のクォータです。
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

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

application/json

オブジェクト：Error

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か月ごとの組織のクォータです。
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

503このリクエストが依存するサービスが一時的に利用できません。しばらくしてから再試行してください。

レスポンスヘッダー

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（秒）が含まれます。その時間だけ待ってから再試行してください。

← cards · APIリファレンス

curl -X POST 'https://api.sursa.com/v1/cards' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_0123456789abcdef0123456789abcdef"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

試してみる

APIキー

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

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

Idempotency-Key header

X-View-As header

Idempotency-Key

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

リクエストボディ（JSON）