Langsung ke konten
Sursa Developers

POST/v1/uploads

Mulai unggahan multibagian

create_upload

Membuka sesi unggahan untuk file besar (hingga batas instalasi untuk unggahan multibagian, secara default 5 GB): nama, jenis konten, ukuran, dan purpose, yang menyatakan apa yang akan memakai unggahan: card_file (POST /v1/cards), archive (POST /v1/cards/archive), atau import_attachment (lampiran dokumen sumber kustom). Respons berisi id (upl_ diikuti 32 karakter heksadesimal), ukuran bagian part_size, dan jumlah bagian part_count. Setiap bagian kecuali yang terakhir berukuran tepat part_size byte (dari 5 hingga 100 MiB), dan bagian terakhir adalah sisanya. Unggahan yang belum selesai berlaku selama 24 jam (expires_at).

Ekstensi nama file di luar format untuk tujuan tersebut mengembalikan 415 uploads.unsupported_format (lampiran impor menerima ekstensi apa pun). File yang lebih besar dari batas instalasi atau dari total penyimpanan organisasi menurut paketnya mengembalikan 413 uploads.too_large. Sisa penyimpanan yang tidak cukup, dengan memperhitungkan unggahan organisasi yang belum selesai, mengembalikan 402 limits.storage.

Bagian-bagian melewati Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) dan dienkripsi dengan kunci organisasi di penyimpanan file; tidak ada tautan langsung ke penyimpanan. Hanya kunci API atau pengguna yang membuat unggahan yang dapat melihat dan memakainya. Ditambahkan di 1.62.0.

Autentikasi

Kirim kunci API di header Authorization: Authorization: Bearer <kunci>.

Parameter header

  • Idempotency-Keystring

    Kunci untuk percobaan ulang penulisan yang aman: 1 hingga 255 karakter ASCII yang dapat dicetak; disarankan satu UUID v4 per operasi logis. Percobaan ulang dengan kunci yang sama dalam 24 jam tidak menjalankan operasi lagi: yang dikembalikan adalah respons tersimpan (status, header, dan isi) dengan header Idempotency-Replayed: true. Kunci yang sama dengan metode, path, Content-Type, atau isi yang berbeda mengembalikan 409 api.idempotency_mismatch; selama permintaan pertama masih berjalan, 409 api.idempotency_in_progress dengan Retry-After: 1. Setelah respons 5xx atau 429, kunci dilepaskan, dan percobaan ulang menjalankan operasi lagi. Kunci berlaku dalam lingkup organisasi dan pemanggil (kunci API, pengguna, atau kunci sumber kustom).

    length ≥ 1, length ≤ 255

Isi permintaan

application/json

Objek: UploadCreate

  • filenamestringwajib

    Nama file beserta ekstensinya; ekstensi menentukan format.

    length ≥ 1, length ≤ 255

  • content_typestring

    Jenis konten yang dinyatakan (MIME); dibandingkan dengan tanda tangan file.

    length ≤ 255

  • sizeinteger (int64)wajib

    Ukuran file dalam byte.

    ≥ 1

  • purposeUploadPurposewajib
  • sha256string

    SHA-256 file, jika sudah diketahui sebelumnya; complete membandingkan checksum file dengan nilai ini.

Respons

201Sesi unggahan dibuat.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

  • Idempotency-Replayed

    true berarti respons ini dikirim ulang dari respons tersimpan untuk Idempotency-Key ini: operasi tidak dijalankan lagi.

application/json

Objek: Upload

  • idstringwajib

    ID unggahan (upl_ diikuti 32 karakter heksadesimal).

  • purposeUploadPurposewajib
  • filenamestringwajib

    Nama file (tanpa folder).

  • content_typestringwajib

    Jenis konten yang dinyatakan; kosong jika tidak dinyatakan.

  • sizeinteger (int64)wajib

    Ukuran file dalam byte.

  • sha256string | nullwajib

    SHA-256 file, yang dinyatakan saat pembuatan atau saat complete; null jika belum diketahui.

  • statusUploadStatuswajib
  • part_sizeinteger (int64)wajib

    Ukuran setiap bagian kecuali yang terakhir (dari 5 hingga 100 MiB).

  • part_countintegerwajib

    Jumlah bagian.

    ≥ 1, ≤ 1000

  • parts_receivedintegerwajib

    Jumlah bagian yang sudah diterima.

    ≥ 0

  • partsarray of UploadPartwajib

    Bagian yang sudah diterima menurut nomor (kosong dalam respons POST /v1/uploads).

  • reject_reasonstring | nullwajib

    Alasan penolakan (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Enum dapat bertambah; null jika tidak ditolak.

  • reject_detailsobject | nullwajib

    Detail penolakan (ekstensi, format yang dinyatakan dan yang terdeteksi, checksum); null jika tidak ditolak.

  • created_atstring (date-time)wajib

    Kapan unggahan dibuat.

  • expires_atstring (date-time)wajib

    Tenggat untuk menyelesaikan unggahan dan, setelah siap, untuk memakainya.

  • completed_atstring (date-time) | nullwajib

    Kapan pemeriksaan selesai (ready atau rejected).

  • consumed_atstring (date-time) | nullwajib

    Kapan unggahan dipakai (oleh kartu, arsip, atau impor).

401Kredensial tidak dikirim (baik cookie sesi maupun kunci API), atau kunci tidak ditemukan.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

402Organisasi telah mencapai batas paket (kartu, penyimpanan, atau pengguna). `error.details` berisi `kind`, `limit`, dan `used`.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

403Tindakan tidak diizinkan: peran tidak memadai, tidak ada akses ke koleksi atau kartu, permintaan berjalan dalam mode “View as”, atau organisasi ditangguhkan atau dihapus (`detail` adalah objek dengan `code: org_suspended | org_deleted`).

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

413Isi permintaan melebihi ukuran yang diizinkan.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

415Format file tidak didukung.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

422Error validasi: isi atau parameter tidak sesuai dengan skema (`detail` berisi daftar error validasi), atau nilai parameter berada di luar rentang (`detail` berisi pesan).

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

429Terlalu banyak permintaan (`api.rate_limited`), kuota organisasi untuk menit, hari, atau bulan sudah habis (`api.quota_exceeded`; `error.details` berisi `quota`, `limit`, dan `reset_at`), batas organisasi tercapai, atau layanan jawaban sedang sibuk (`answers.engine_busy`). Tunggu selama waktu di header `Retry-After`.

Header respons

  • Retry-After

    Jumlah detik yang perlu ditunggu sebelum Anda mencoba ulang permintaan.

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

Kode error

Kode yang dapat dikembalikan endpoint ini di error.code, selain kode umum yang berlaku untuk setiap permintaan.

Percobaan ulang yang aman

Kirim header Idempotency-Key (misalnya UUID) bersama setiap POST dan PATCH. Percobaan ulang dengan kunci yang sama dalam 24 jam mengembalikan respons yang tersimpan alih-alih menjalankan permintaan lagi.

Batas laju

Respons berisi header RateLimit dan RateLimit-Policy serta header lama X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Respons 429 berisi Retry-After dalam detik: tunggu, lalu coba lagi.

← uploads · Referensi API