İçeriğe geç

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

AdYerTürAçıklama
parentIdsorgustring (uuid)
qsorgustring
viewsorgu"mine" | "shared" | "recent" | "pinned" | "trash"mine | shared | recent | pinned | trash
sourceAppsorgu"drive" | "voice" | "katalog" | "api"
sortsorgu"name" | "updated" | "size"
cursorsorgustringÖnceki yanıtın nextCursor değeri
limitsorguinteger

Yanıtlar

GET/nodes/{id}

Tek öğe

Gereken yetki: drive:read.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)

Yanıtlar

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

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Gövde

Yanıtlar

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

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).
permanentsorgu"1"

Yanıtlar

POST/nodes/{id}/restore

Çöpten geri al

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Yanıtlar

POST/folders

Klasör oluştur

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Gövde

Yanıtlar

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

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)

Yanıtlar

GET/files/{id}/preview

Tarayıcıda aç (görsel, ses, video, PDF)

Gereken yetki: drive:read.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)

Yanıtlar

DELETE/trash

Çöp kutusunu boşalt (kalıcı)

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Yanıtlar

GET/usage

Kullanılan alan ve kota

Gereken yetki: drive:read.

Yanıtlar

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

AdYerTürAçıklama
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).
name zorunlusorgustring
parentIdsorgustring (uuid) | null
checksumsorgustring

Gövde

  • application/octet-stream: string
  • multipart/form-data: object

Yanıtlar

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

AdYerTürAçıklama
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Gövde

Yanıtlar

POST/uploads/{id}/parts

Parça adreslerini yenile

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
id zorunluyolstringuploadId

Gövde

Yanıtlar

POST/uploads/{id}/complete

Yüklemeyi tamamla

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
id zorunluyolstringuploadId
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Yanıtlar

DELETE/uploads/{id}

Yüklemeyi iptal et

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
id zorunluyolstringuploadId

Yanıtlar

Paylaşım ve gizlilik

GET/nodes/{id}/shares

Kişiye paylaşımlar

Gereken yetki: drive:share.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)

Yanıtlar

POST/nodes/{id}/shares

Kişiye paylaş

Gereken yetki: drive:share.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).

Gövde

Yanıtlar

PATCH/nodes/{id}/shares

Paylaşımın yetkisini değiştir

Gereken yetki: drive:share.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).
shareId zorunlusorgustring

Gövde

Yanıtlar

DELETE/nodes/{id}/shares

Paylaşımı kaldır

Gereken yetki: drive:share.

Parametreler

AdYerTürAçıklama
id zorunluyolstringÖğenin kimliği (uuid)
Idempotency-Keybaşlıkstring1–200 karakter. Aynı anahtarla 24 saat içinde tekrarlanan istek ilk başarılı yanıtı döner (Idempotent-Replayed: true).
shareId zorunlusorgustring

Yanıtlar

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

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

Yanıtlar

DELETE/keys/{id}

API anahtarını iptal et

Gereken yetki: drive:write.

Parametreler

AdYerTürAçıklama
id zorunluyolstringAnahtarın kimliği (key_…)

Yanıtlar

Hatalar

Bütün hata yanıtlarının gövdesi Error şemasındadır.

  • 400 İstek geçersiz (bad_request)
  • 401 Kimlik yok ya da geçersiz (unauthorized)
  • 403 Yetki yetmiyor (forbidden)
  • 404 Bulunamadı 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)
  • 422 Boyut uyuşmuyor ya da Idempotency-Key başka istekte kullanılmış (size_mismatch, idempotency_mismatch)
  • 429 Hız sınırı (rate_limited); Retry-After başlığına bak

Şemalar

DriveNode

AlanTürAçıklama
id zorunlustring (uuid)
kind zorunlu"FOLDER" | "FILE"
name zorunlustring
parentId zorunlustring (uuid) | null
mimeType zorunlustring | null
sizeBytes zorunlustringBayt; 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 zorunlustring | null
pinned zorunluboolean
trashedAt zorunlustring | null
createdAt zorunlustringISO 8601 zaman, UTC
updatedAt zorunlustringISO 8601 zaman, UTC
role zorunlu"OWNER" | "EDITOR" | "VIEWER"İsteği yapanın bu öğedeki yetkisi
shared zorunlubooleanÖğe başkasına ait (seninle paylaşılmış)
systembooleanUygulama 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)
childCountintegerSadece listede, klasörler için
visibility zorunlu"private" | "link" | "public"
publicUrlstring (uri)Yalnızca visibility = public iken

NodeList

AlanTürAçıklama
items zorunluDriveNode[]
nextCursor zorunlustring | nullSonraki sayfa için ?cursor=; son sayfada null

NodeDetail

AlanTürAçıklama
id zorunlustring (uuid)
kind zorunlu"FOLDER" | "FILE"
name zorunlustring
parentId zorunlustring (uuid) | null
mimeType zorunlustring | null
sizeBytes zorunlustringBayt; 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 zorunlustring | null
pinned zorunluboolean
trashedAt zorunlustring | null
createdAt zorunlustringISO 8601 zaman, UTC
updatedAt zorunlustringISO 8601 zaman, UTC
role zorunlu"OWNER" | "EDITOR" | "VIEWER"İsteği yapanın bu öğedeki yetkisi
shared zorunlubooleanÖğe başkasına ait (seninle paylaşılmış)
systembooleanUygulama 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)
childCountintegerSadece listede, klasörler için
visibility zorunlu"private" | "link" | "public"
publicUrlstring (uri)Yalnızca visibility = public iken
path zorunluobject[]Kökten ebeveyne, erişilebilen atalar

UploadTicket

  • Seçenek 1
    AlanTürAçıklama
    uploadId zorunlustring (uuid)
    nodeId zorunlustring (uuid)
    mode zorunlu"single"
    url zorunlustring (uri)İmzalı PUT adresi (15 dk)
    headers zorunluRecord<string, string>PUT isteğinde aynen gönderilecek
    expiresAt zorunlustringISO 8601 zaman, UTC
  • Seçenek 2
    AlanTürAçıklama
    uploadId zorunlustring (uuid)
    nodeId zorunlustring (uuid)
    mode zorunlu"multipart"
    partSize zorunluinteger
    partCount zorunluinteger
    parts zorunluobject[]
    expiresAt zorunlustringISO 8601 zaman, UTC

UploadParts

AlanTürAçıklama
parts zorunluobject[]
expiresAt zorunlustringISO 8601 zaman, UTC

Usage

AlanTürAçıklama
usedBytes zorunlustringBayt; büyük sayılar kaybolmasın diye metin olarak
reservedBytes zorunlustringBayt; büyük sayılar kaybolmasın diye metin olarak
limitBytes zorunlustringBayt; büyük sayılar kaybolmasın diye metin olarak
byApp zorunluRecord<"drive" | "voice" | "katalog" | "api", string>

ShareEntry

AlanTürAçıklama
id zorunlustring (uuid)
granteeUserId zorunlustring | null
granteeEmail zorunlustring | null
role zorunlu"VIEWER" | "EDITOR"
createdAt zorunlustringISO 8601 zaman, UTC
displayNamestring | null
displayEmailstring | null
pendingboolean

LinkInfo

AlanTürAçıklama
tokenstringYalnızca oluşturma yanıtında, bir kez
urlstring (uri)Yalnızca oluşturma yanıtında, bir kez
expiresAt zorunlustringISO 8601 zaman, UTC

ApiKey

AlanTürAçıklama
id zorunlustring
name zorunlustring
prefix zorunlustring"kvd_" + ilk 8 karakter
scopes zorunlu"drive:read" | "drive:write" | "drive:share"[]
folderId zorunlustring (uuid) | null
folderNamestring | null
expiresAt zorunlustring | null
lastUsedAt zorunlustring | null
createdAt zorunlustringISO 8601 zaman, UTC
expired zorunluboolean

CreatedApiKey

AlanTürAçıklama
key zorunluApiKey
token zorunlustringDüz anahtar (kvd_…). YALNIZCA bu yanıtta, bir kez

Error

AlanTürAçıklama
error zorunluobject

CreateFolderInput

AlanTürAçıklama
name zorunlustring
parentIdstring (uuid) | null

UpdateNodeInput

AlanTürAçıklama
namestring
parentIdstring (uuid) | null
pinnedboolean
visibility"private" | "link" | "public"

StartUploadInput

AlanTürAçıklama
name zorunlustring
sizeBytes zorunluinteger | string
mimeTypestring
parentIdstring (uuid) | null
sourceApp"drive" | "voice" | "katalog" | "api"
sourceRefstring
checksumstring

RefreshPartsInput

AlanTürAçıklama
partNumbers zorunluinteger[]

AddShareInput

AlanTürAçıklama
email zorunlustring (email)
role zorunlu"VIEWER" | "EDITOR"

UpdateShareInput

AlanTürAçıklama
role zorunlu"VIEWER" | "EDITOR"

CreateLinkInput

AlanTürAçıklama
days zorunlu1 | 7 | 30

CreateApiKeyInput

AlanTürAçıklama
name zorunlustring
scopes zorunlu"drive:read" | "drive:write" | "drive:share"[]
folderIdstring (uuid) | null
expiresInDays30 | 90 | 365 | null