POST/v1/sources

Buat sumber

create_source

Dengan kunci API organisasi (sejak 1.62.0), hanya sumber kustom (kind: custom) yang tersedia: kunci memerlukan peran admin dan cakupan admin. Jenis lain mana pun mengembalikan 400 sources.kind_not_allowed_for_key; konektor yang masuk melalui penyedia layanan diatur di peramban. Field konektor tidak ditampilkan dalam spesifikasi publik. Sumber kustom menerima name, koleksi (collection_id atau collection), mode izin permissions_mode, folder koleksi untuk kartu (folder_id dan folder_mode), dan folder dokumen yang dipilih (roots). Dokumen dikirim dengan operasi /v1/push/sources/{source_id}/*.

Autentikasi

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

Parameter header

X-View-Asstring
Hanya untuk kunci API dengan peran admin. Menjalankan permintaan sebagai profil data <profile>[:viewer|verifier|editor], misalnya employee:viewer. Kunci instalasi tidak dapat memakai header ini (403).
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

Parameter cookie

kb_view_asstring
Cookie mode “View as” (Lihat sebagai) untuk sesi. POST /auth/view-as menetapkannya dan DELETE /auth/view-as menghapusnya.

Isi permintaan

application/json

Objek: SourceCreate

kindstring
Jenis sumber (lihat SourceKind); dengan kunci API organisasi, hanya custom.
Default: "gdrive"
namestringwajib
length ≥ 1, length ≤ 120
collectionstring
Nama koleksi sumber; Anda dapat mengirim collection_id sebagai gantinya (sejak 1.62.0).
length ≥ 1, length ≤ 64
collection_idinteger
Koleksi sumber menurut ID (sejak 1.62.0); jika keduanya dikirim, collection_id yang dipakai.
permissions_modestring
Mode izin kartu sumber (sejak 1.62.0, seperti di update_source_settings): own memakai izin koleksi, mirror mengambilnya dari dokumen (permissions). Memilih mirror memerlukan hak untuk mengelola izin koleksi.
Nilai yang diizinkan: ownmirror
default_owner_idinteger | null
verify_interval_daysinteger
Default: 90≥ 1, ≤ 3650
tagsarray of string
Default: []
default_categorystring | null
rootsarray of string | null
Folder sumber yang dipilih: hanya item di dalamnya yang menjadi kartu. Untuk sumber kustom, path folder dokumen (Guides/Billing); untuk konektor, simpul pohon penyedia.
folder_idstring | null
Folder di koleksi sumber tempat kartu diletakkan (null berarti akar koleksi).
folder_modestring
flat meletakkan semuanya di folder yang dipilih; mirror membuat folder yang mengulang path item di sumber, tidak lebih dalam dari batas kedalaman folder (3 tingkat; item yang lebih dalam masuk ke folder terdekat).
Nilai yang diizinkan: flatmirror
Default: "flat"

Respons

200Respons berhasil

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: DataSource

Salah satu dari

400Permintaan tidak valid: nilai parameter atau status objek tidak memungkinkan tindakan ini (`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

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

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

404Objek tidak ada atau tidak tersedia bagi Anda. API tidak mengonfirmasi keberadaan objek yang dibatasi.

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.

← sources · Referensi API

curl -X POST 'https://api.sursa.com/v1/sources' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"custom","name":"Help center import","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Coba

Kunci API

Kunci hanya disimpan di memori tab ini dan hanya dikirim ke https://api.sursa.com.

Permintaan bekerja pada data asli organisasi Anda.

X-View-As header

Idempotency-Key header

Idempotency-Key

Jika kosong, kunci baru dibuat untuk setiap permintaan.

Isi permintaan (JSON)