POST/v1/sources

Kaynak oluşturma

create_source

Bir kuruluş API anahtarıyla (1.62.0 sürümünden beri) yalnızca özel kaynak (kind: custom) kullanılabilir: anahtarın admin rolüne ve admin kapsamına sahip olması gerekir. Diğer her tür 400 sources.kind_not_allowed_for_key döndürür; hizmet sağlayıcıda oturum açan bağlayıcılar tarayıcıda kurulur. Bağlayıcı alanları herkese açık spesifikasyonda gösterilmez. Özel kaynak name, koleksiyonu (collection_id ya da collection), permissions_mode izin modunu, kartlar için koleksiyon klasörünü (folder_id ve folder_mode) ve seçilen belge klasörlerini (roots) alır. Belgeler /v1/push/sources/{source_id}/* işlemleriyle gönderilir.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Başlık parametreleri

X-View-Asstring
Yalnızca admin rolündeki API anahtarları için. İsteği <profile>[:viewer|verifier|editor] veri profili adına yapar, örneğin employee:viewer. Kurulum anahtarı bu başlığı kullanamaz (403).
Idempotency-Keystring
Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).
length ≥ 1, length ≤ 255

Çerez parametreleri

kb_view_asstring
Bir oturum için “View as” modunun (başka bir kullanıcı gibi görüntüleme) çerezi. POST /auth/view-as bu çerezi ayarlar, DELETE /auth/view-as temizler.

İstek gövdesi

application/json

Nesne: SourceCreate

kindstring
Kaynak türü (bkz. SourceKind); kuruluş API anahtarıyla yalnızca custom.
Varsayılan: "gdrive"
namestringzorunlu
length ≥ 1, length ≤ 120
collectionstring
Kaynağın koleksiyonunun adı; bunun yerine collection_id gönderebilirsiniz (1.62.0 sürümünden beri).
length ≥ 1, length ≤ 64
collection_idinteger
Kimliğe göre kaynağın koleksiyonu (1.62.0 sürümünden beri); ikisi de gönderilirse collection_id geçerli olur.
permissions_modestring
Kaynak kartlarının izin modu (1.62.0 sürümünden beri, update_source_settings içindeki gibi): own koleksiyonun izinlerini kullanır, mirror izinleri belgeden alır (permissions). mirror seçmek için koleksiyonun izinlerini yönetme hakkı gerekir.
Geçerli değerler: ownmirror
default_owner_idinteger | null
verify_interval_daysinteger
Varsayılan: 90≥ 1, ≤ 3650
tagsarray of string
Varsayılan: []
default_categorystring | null
rootsarray of string | null
Kaynağın seçili klasörleri: yalnızca bunların içindeki öğeler karta dönüşür. Özel kaynakta belgelerin klasör yolları (Guides/Billing); bağlayıcılarda sağlayıcının ağacındaki düğümler.
folder_idstring | null
Kaynağın koleksiyonunda kartların yerleştirildiği klasör (null, koleksiyonun kökü anlamına gelir).
folder_modestring
flat her şeyi seçili klasöre koyar; mirror, öğenin kaynaktaki yolunu yineleyen klasörler oluşturur, ancak klasörlerin iç içe geçme sınırından (3 düzey) daha derine inmez; daha derindeki öğeler en yakın klasöre gider.
Geçerli değerler: flatmirror
Varsayılan: "flat"

Yanıtlar

200Başarılı yanıt

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.
Idempotency-Replayed
true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: DataSource

Şunlardan biri

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

404Nesne yok ya da size açık değil. API, erişimi kısıtlı bir nesnenin var olduğunu belli etmez.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

Retry-After
İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.
RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← sources · API başvurusu

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"

Dene

API anahtarı

Anahtar bu sekmenin belleğinde kalır ve yalnızca https://api.sursa.com adresine gönderilir.

İstekler kuruluşunuzun gerçek verileri üzerinde çalışır.

X-View-As header

Idempotency-Key header

Idempotency-Key

Bu alan boş bırakılırsa her istek için yeni bir anahtar oluşturulur.

İstek gövdesi (JSON)