Referans · sürüm 1.0.0
API referansı
Temel adres https://drive.kivilio.com/api/v1. Bütün istekler Authorization: Bearer kvd_… ister. Bu sayfa openapi.json (OpenAPI 3.1) belgesinden üretilir; kendi araçlarına (Postman, kod üreticiler) bu dosyayı verebilirsin.
Dosyalar ve klasörler
GET/nodes
Listele ya da ara
parentId verilmezse Drive'ım kökü (klasörle sınırlı anahtarda anahtarın klasörü). q ile ad araması (ilk limit sonuç, sayfalama yok). Sayfalama imleçle: yanıttaki nextCursor'ı cursor olarak gönder.
Gereken yetki: drive:read.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
parentId | sorgu | string (uuid) | |
q | sorgu | string | |
view | sorgu | "mine" | "shared" | "recent" | "pinned" | "trash" | mine | shared | recent | pinned | trash |
sourceApp | sorgu | "drive" | "voice" | "katalog" | "api" | |
sort | sorgu | "name" | "updated" | "size" | |
cursor | sorgu | string | Önceki yanıtın nextCursor değeri |
limit | sorgu | integer |
Yanıtlar
200Liste →NodeList400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
GET/nodes/{id}
Tek öğe
Gereken yetki: drive:read.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Yanıtlar
200Öğe ve yolu →NodeDetail400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
PATCH/nodes/{id}
Yeniden adlandır, taşı, sabitle, gizlilik
visibility ayrıca drive:share ister ve yalnızca dosyanın sahibi değiştirebilir. Uygulama klasörlerindeki öğeler yeniden adlandırılamaz ve taşınamaz.
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
Gövde
application/json:UpdateNodeInput
Yanıtlar
200Güncel öğe →DriveNode400Hata (400)401Hata (401)403Hata (403)404Hata (404)409Hata (409)429Hata (429)
DELETE/nodes/{id}
Çöpe at ya da kalıcı sil
Varsayılan: çöp kutusuna (30 gün). ?permanent=1: kalıcı siler; öğe önce çöpte olmalı, yalnızca sahibi.
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
permanent | sorgu | "1" |
Yanıtlar
204Silindi400Hata (400)401Hata (401)403Hata (403)404Hata (404)409Hata (409)429Hata (429)
POST/nodes/{id}/restore
Çöpten geri al
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
Yanıtlar
200Geri alınan öğe →DriveNode400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
POST/folders
Klasör oluştur
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
Gövde
application/json:CreateFolderInput
Yanıtlar
201Klasör →DriveNode400Hata (400)401Hata (401)403Hata (403)404Hata (404)409Hata (409)429Hata (429)
GET/files/{id}/download
İndir
5 dakikalık imzalı depolama adresine 302. Range başlığını yönlendirilen adrese gönder.
Gereken yetki: drive:read.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Yanıtlar
302İmzalı adres (Location)400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
GET/files/{id}/preview
Tarayıcıda aç (görsel, ses, video, PDF)
Gereken yetki: drive:read.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Yanıtlar
302İmzalı adres (Location)400Hata (400)401Hata (401)403Hata (403)404Hata (404)415Hata (415)429Hata (429)
DELETE/trash
Çöp kutusunu boşalt (kalıcı)
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
Yanıtlar
200Silinen öğe sayısı →object400Hata (400)401Hata (401)403Hata (403)429Hata (429)
GET/usage
Kullanılan alan ve kota
Gereken yetki: drive:read.
Yanıtlar
200Kullanım →Usage400Hata (400)401Hata (401)403Hata (403)429Hata (429)
Yükleme
POST/files
Basit yükleme (tek istek)
Küçük dosyalar için (varsayılan en fazla 50 MB). Ham gövde: Content-Type dosyanın türü, Content-Length zorunlu, ad sorgu dizesinde. Ya da multipart/form-data (file, name, parentId). Büyük dosyalar: POST /uploads.
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
name zorunlu | sorgu | string | |
parentId | sorgu | string (uuid) | null | |
checksum | sorgu | string |
Gövde
application/octet-stream:stringmultipart/form-data:object
Yanıtlar
201Yüklenen dosya →DriveNode400Hata (400)401Hata (401)403Hata (403)404Hata (404)409Hata (409)413Hata (413)422Hata (422)429Hata (429)
POST/uploads
Parçalı yüklemeyi başlat
Küçük dosyada tek imzalı PUT adresi (mode: single), büyükte parça adresleri (mode: multipart). Dosya doğrudan depolamaya (storage.kivilio.com) gönderilir, sonra POST /uploads/{id}/complete.
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
Gövde
application/json:StartUploadInput
Yanıtlar
201Yükleme bileti →UploadTicket400Hata (400)401Hata (401)403Hata (403)404Hata (404)409Hata (409)413Hata (413)429Hata (429)
POST/uploads/{id}/parts
Parça adreslerini yenile
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | uploadId |
Gövde
application/json:RefreshPartsInput
Yanıtlar
200Yeni adresler →UploadParts400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
POST/uploads/{id}/complete
Yüklemeyi tamamla
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | uploadId |
Idempotency-Key | başlık | string | 1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true). |
Yanıtlar
200Hazır dosya →DriveNode400Hata (400)401Hata (401)403Hata (403)404Hata (404)422Hata (422)429Hata (429)
DELETE/uploads/{id}
Yüklemeyi iptal et
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | uploadId |
Yanıtlar
204İptal edildi400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
Paylaşım ve gizlilik
GET/nodes/{id}/link
Etkin süreli bağlantı
Gereken yetki: drive:share.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Yanıtlar
200Bağlantı (token'sız) ya da null →object400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
POST/nodes/{id}/link
Süreli bağlantı oluştur
Önceki bağlantı iptal olur. Düz token yalnızca bu yanıtta döner. Idempotency-Key desteklenmez.
Gereken yetki: drive:share.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Gövde
application/json:CreateLinkInput
Yanıtlar
201Bağlantı →LinkInfo400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
DELETE/nodes/{id}/link
Bağlantıyı iptal et
Gereken yetki: drive:share.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Öğenin kimliği (uuid) |
Yanıtlar
204İptal edildi400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
API anahtarları
GET/keys
API anahtarlarım
Yalnızca Drive arayüzünden ya da kendi Logto token'ınla; bir API anahtarıyla çağrılamaz.
Gereken yetki: drive:read.
Yanıtlar
200Anahtarlar →object400Hata (400)401Hata (401)403Hata (403)429Hata (429)
POST/keys
API anahtarı oluştur
Düz anahtar yalnızca bu yanıtta, bir kez döner. En fazla 20 etkin anahtar.
Gereken yetki: drive:write.
Gövde
application/json:CreateApiKeyInput
Yanıtlar
201Anahtar →CreatedApiKey400Hata (400)401Hata (401)403Hata (403)404Hata (404)409Hata (409)429Hata (429)
DELETE/keys/{id}
API anahtarını iptal et
Gereken yetki: drive:write.
Parametreler
| Ad | Yer | Tür | Açıklama |
|---|---|---|---|
id zorunlu | yol | string | Anahtarın kimliği (key_…) |
Yanıtlar
204İptal edildi400Hata (400)401Hata (401)403Hata (403)404Hata (404)429Hata (429)
Hatalar
Bütün hata yanıtlarının gövdesi Error şemasındadır.
400İstek geçersiz (bad_request)401Kimlik yok ya da geçersiz (unauthorized)403Yetki yetmiyor (forbidden)404Bulunamadı ya da erişimin yok (not_found)409Çakışma (conflict,name_conflict)413Çok büyük ya da kota dolu (too_large,quota_exceeded)415Önizlenemeyen tür (unsupported_media)422Boyut uyuşmuyor ya da Idempotency-Key başka istekte kullanılmış (size_mismatch,idempotency_mismatch)429Hız sınırı (rate_limited);Retry-Afterbaşlığına bak
Şemalar
DriveNode
| Alan | Tür | Açıklama |
|---|---|---|
id zorunlu | string (uuid) | |
kind zorunlu | "FOLDER" | "FILE" | |
name zorunlu | string | |
parentId zorunlu | string (uuid) | null | |
mimeType zorunlu | string | null | |
sizeBytes zorunlu | string | Bayt; büyük sayılar kaybolmasın diye metin olarak |
status zorunlu | "PENDING" | "READY" | |
sourceApp zorunlu | "drive" | "voice" | "katalog" | "api" | Öğeyi kim yükledi: arayüz, uygulama ya da API |
sourceRef zorunlu | string | null | |
pinned zorunlu | boolean | |
trashedAt zorunlu | string | null | |
createdAt zorunlu | string | ISO 8601 zaman, UTC |
updatedAt zorunlu | string | ISO 8601 zaman, UTC |
role zorunlu | "OWNER" | "EDITOR" | "VIEWER" | İsteği yapanın bu öğedeki yetkisi |
shared zorunlu | boolean | Öğe başkasına ait (seninle paylaşılmış) |
system | boolean | Uygulama klasörü (ör. Voice kayıtları) |
managedBy | "voice" | "katalog" | Uygulama alanında: salt okunur (yükleme, klasör açma, taşıma yok; silme var) |
childCount | integer | Sadece listede, klasörler için |
visibility zorunlu | "private" | "link" | "public" | |
publicUrl | string (uri) | Yalnızca visibility = public iken |
NodeList
| Alan | Tür | Açıklama |
|---|---|---|
items zorunlu | DriveNode[] | |
nextCursor zorunlu | string | null | Sonraki sayfa için ?cursor=; son sayfada null |
NodeDetail
| Alan | Tür | Açıklama |
|---|---|---|
id zorunlu | string (uuid) | |
kind zorunlu | "FOLDER" | "FILE" | |
name zorunlu | string | |
parentId zorunlu | string (uuid) | null | |
mimeType zorunlu | string | null | |
sizeBytes zorunlu | string | Bayt; büyük sayılar kaybolmasın diye metin olarak |
status zorunlu | "PENDING" | "READY" | |
sourceApp zorunlu | "drive" | "voice" | "katalog" | "api" | Öğeyi kim yükledi: arayüz, uygulama ya da API |
sourceRef zorunlu | string | null | |
pinned zorunlu | boolean | |
trashedAt zorunlu | string | null | |
createdAt zorunlu | string | ISO 8601 zaman, UTC |
updatedAt zorunlu | string | ISO 8601 zaman, UTC |
role zorunlu | "OWNER" | "EDITOR" | "VIEWER" | İsteği yapanın bu öğedeki yetkisi |
shared zorunlu | boolean | Öğe başkasına ait (seninle paylaşılmış) |
system | boolean | Uygulama klasörü (ör. Voice kayıtları) |
managedBy | "voice" | "katalog" | Uygulama alanında: salt okunur (yükleme, klasör açma, taşıma yok; silme var) |
childCount | integer | Sadece listede, klasörler için |
visibility zorunlu | "private" | "link" | "public" | |
publicUrl | string (uri) | Yalnızca visibility = public iken |
path zorunlu | object[] | Kökten ebeveyne, erişilebilen atalar |
UploadTicket
- Seçenek 1
Alan Tür Açıklama uploadIdzorunlustring (uuid)nodeIdzorunlustring (uuid)modezorunlu"single"urlzorunlustring (uri)İmzalı PUT adresi (15 dk) headerszorunluRecord<string, string>PUT isteğinde aynen gönderilecek expiresAtzorunlustringISO 8601 zaman, UTC - Seçenek 2
Alan Tür Açıklama uploadIdzorunlustring (uuid)nodeIdzorunlustring (uuid)modezorunlu"multipart"partSizezorunluintegerpartCountzorunluintegerpartszorunluobject[]expiresAtzorunlustringISO 8601 zaman, UTC
UploadParts
| Alan | Tür | Açıklama |
|---|---|---|
parts zorunlu | object[] | |
expiresAt zorunlu | string | ISO 8601 zaman, UTC |
Usage
| Alan | Tür | Açıklama |
|---|---|---|
usedBytes zorunlu | string | Bayt; büyük sayılar kaybolmasın diye metin olarak |
reservedBytes zorunlu | string | Bayt; büyük sayılar kaybolmasın diye metin olarak |
limitBytes zorunlu | string | Bayt; büyük sayılar kaybolmasın diye metin olarak |
byApp zorunlu | Record<"drive" | "voice" | "katalog" | "api", string> |
LinkInfo
| Alan | Tür | Açıklama |
|---|---|---|
token | string | Yalnızca oluşturma yanıtında, bir kez |
url | string (uri) | Yalnızca oluşturma yanıtında, bir kez |
expiresAt zorunlu | string | ISO 8601 zaman, UTC |
ApiKey
| Alan | Tür | Açıklama |
|---|---|---|
id zorunlu | string | |
name zorunlu | string | |
prefix zorunlu | string | "kvd_" + ilk 8 karakter |
scopes zorunlu | "drive:read" | "drive:write" | "drive:share"[] | |
folderId zorunlu | string (uuid) | null | |
folderName | string | null | |
expiresAt zorunlu | string | null | |
lastUsedAt zorunlu | string | null | |
createdAt zorunlu | string | ISO 8601 zaman, UTC |
expired zorunlu | boolean |
CreatedApiKey
| Alan | Tür | Açıklama |
|---|---|---|
key zorunlu | ApiKey | |
token zorunlu | string | Düz anahtar (kvd_…). YALNIZCA bu yanıtta, bir kez |
Error
| Alan | Tür | Açıklama |
|---|---|---|
error zorunlu | object |
CreateFolderInput
| Alan | Tür | Açıklama |
|---|---|---|
name zorunlu | string | |
parentId | string (uuid) | null |
UpdateNodeInput
| Alan | Tür | Açıklama |
|---|---|---|
name | string | |
parentId | string (uuid) | null | |
pinned | boolean | |
visibility | "private" | "link" | "public" |
StartUploadInput
| Alan | Tür | Açıklama |
|---|---|---|
name zorunlu | string | |
sizeBytes zorunlu | integer | string | |
mimeType | string | |
parentId | string (uuid) | null | |
sourceApp | "drive" | "voice" | "katalog" | "api" | |
sourceRef | string | |
checksum | string |
RefreshPartsInput
| Alan | Tür | Açıklama |
|---|---|---|
partNumbers zorunlu | integer[] |
CreateLinkInput
| Alan | Tür | Açıklama |
|---|---|---|
days zorunlu | 1 | 7 | 30 |
CreateApiKeyInput
| Alan | Tür | Açıklama |
|---|---|---|
name zorunlu | string | |
scopes zorunlu | "drive:read" | "drive:write" | "drive:share"[] | |
folderId | string (uuid) | null | |
expiresInDays | 30 | 90 | 365 | null |