API: temel bilgiler

VentionDesk API'si, arayüzün kullandığı API'nin ta kendisidir. Otomasyonlar için — Claude, kendi script'lerin, CI — bir API anahtarıyla oturum açarsın. Tüm adresler https://api.ventiondesk.com ile başlar; tüm gövdeler ve yanıtlar UTF-8 kodlu JSON'dur.

API anahtarıyla oturum açma

İşletme sahibi bir anahtarı Ayarlar › API anahtarları › “Yeni anahtar” altında oluşturur. Anahtar tam olarak bir kez düz metin olarak görünür.

Her istek onu bearer token olarak taşır:

curl https://api.ventiondesk.com/v1/tasks?status=todo \
  -H "Authorization: Bearer vd_live_…"

Değiş tokuş için ayrı bir endpoint yoktur: VentionDesk anahtarı önekinden tanır, her istekte kontrol eder (iptal edildi mi? süresi doldu mu?) ve ardından anahtarın hesabı için bir oturumla çalışır. Bu yüzden anahtar için de bir kişi için geçerli olan veritabanı kuralları geçerlidir — yalnızca kapsamının izin verdiğini görür.

Anahtar yerine OAuth ile bağlanmış bir yapay zekâ uygulamasının oturumu da bearer token olarak gelebilir. Bu, kişinin onay sırasında seçtiği izinler ve projelerle bir ajan anahtarı gibi sayılır — asla kişinin kendi izinleriyle değil — ve bağlantı kesildiğinde hemen sona erer.

Bir ajan anahtarı, Ajan rolüne sahip ayrı bir hesaptır. API referansında bir kapsam gösteren endpoint'ler ile GET /v1/me ve ajan çalıştırmaları için tasarlanmıştır. “işletme sahibi” veya “işletme sahibi ve çalışanlar” gerektiren endpoint'lere web arayüzü, oturum açmış bir kişinin oturumuyla hizmet eder; bir API anahtarına 403 ile yanıt verirler.

Kapsamlar

Bir ajan anahtarının neler yapabileceğini kapsamları (scope'lar) belirler:

Bir kapsam tam olarak onu karşılayan endpoint'lerde görünür — API referansı her endpoint için onu belirtir. deployments:read hiçbir endpoint'te görünmez: Yansıtılan commit'lerin, pull request'lerin ve dağıtımların veritabanı kuralları üzerinden etki eder.

Proje bağlaması

Bir anahtar tüm projelerde veya bir seçimde geçerlidir. Bağlı bir anahtar yalnızca projelerinin verilerini görür — ve bilerek projesiz hiçbir şeyi, örneğin henüz hiçbir projeye atanmamış talepleri görmez. API, projeleri dışındaki bir satıra 404 veya 403 ile yanıt verir. Bir giriş anahtarı her zaman tam olarak bir projeye bağlıdır.

Kapsamı değiştirmek yeni bir anahtar gerektirmez. Kapsamları ve projeleri işletme sahibi anahtar listesindeki “İzinler” altında değiştirir; bir sonraki istek yeni kapsamla çalışır. İptal edilmiş veya süresi dolmuş bir anahtar bir sonraki isteğinde reddedilir.

Hatalar

Her hata yanıtı aynı biçimdedir:

{ "ok": false, "error": "Diese Aufgabe gibt es nicht.", "code": "not_found" }

error insanlar için Almanca bir cümle, code programlar için sabit bir İngilizce değerdir. Yaygın yanıtlar:

Her yanıt x-request-id başlığında bir kimlik taşır. Kendin bir tane gönderirsen (en fazla 128 karakter) o kullanılır. Bir şeyler ters giderse onu destek ekibine ver.

İstek sınırları

Dakika başına, anahtar başına veya IP adresi başına sayılır:

Sınırın üzerinde API 429 ve rate_limited ile yanıt verir; RateLimit ve RateLimit-Policy başlıkları güncel sayıyı ve sınırı belirtir.

Listeler ve filtreler

Liste endpoint'leri sorgu parametreleriyle filtreler ve limit ile sınırlar; imleç veya ofsetli sayfalar yoktur. Örnekler:

• GET /v1/tasks?projectSlug=shop&status=todo&claimable=true&limit=20 — şu anda çekilebilecek görevler.
• GET /v1/projects?status=active — aktif projeler.

Bir endpoint'in hangi parametreleri tanıdığı ve hangi alanları döndürdüğü API referansında listelenir — VentionDesk'in isteği kontrol etmek için kullandığı aynı sözleşmeden okunur.

Bir ajanın tipik turu

1. GET /v1/tasks?claimable=true — ne yapılması gerekiyor?
2. POST /v1/tasks/:id/claim — görevi atomik olarak üstlen. İki çalıştırma asla aynı görevi almaz.
3. Çalış; arada hayat belirtisi olarak "state": "arbeitet" ile POST /v1/tasks/:id/result.
4. kontrolle, frage, master, blockiert veya erledigt ile POST /v1/tasks/:id/result — kontrolle ve erledigt ile evidence içinde kanıtla.

Bunu kendin kurmak istemiyorsan Claude ve MCP sayfasını kullan.