Inkpilots V1 API Dokümantasyonu

Amaç: Node.js SDK oluşturma için tam endpoint açıklamaları, sorgu parametreleri, kimlik doğrulama, yanıt formatları ve kota sistemi içeren V1 genel API referansı.

İçindekiler

Kimlik Doğrulama
Temel URL ve CORS
API Endpoint'leri
Hata Yönetimi
Kota Sistemi
Yanıt Formatları
Endpoint Özeti

Kimlik Doğrulama

API Anahtarı ile Kimlik Doğrulama

Tüm V1 API endpoint'leri API anahtarı ile kimlik doğrulama gerektirir. API anahtarı istek başlığında gönderilir.

Başlık Formatı:

x-api-key: Bearer <api-anahtarınız>

Örnek:

curl -H "x-api-key: Bearer api_anahtariniz_burada" https://inkpilots.com/api/v1/agents

Doğrulama Akışı

İstemci x-api-key başlığı ile istek gönderir
Sunucu verifyApiKey(apiKeyHeader) fonksiyonunu çağırır
Geçerliyse döndürür:
- isValid: boolean
- workspaceId: string (string olarak MongoDB ObjectId)
Geçersizse { isValid: false } döndürür

Hata Yanıtları

401 Yetkisiz: Geçersiz veya eksik API anahtarı, ya da yetersiz izinler
402 Ödeme Gerekli: Çalışma alanı planı için API erişim kotası aşıldı

Temel URL ve CORS

Temel URL

https://inkpilots.com/api/v1

CORS Başlıkları

Tüm yanıtlar aşağıdaki CORS başlıklarını içerir:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

Not: API çerez kullanmadığından (durumsuz kimlik doğrulama) CORS tüm kaynaklara izin verir.

Ön Kontrol İstekleri

Tüm endpoint'ler CORS ön kontrolü için OPTIONS isteklerini destekler:

curl -X OPTIONS https://inkpilots.com/api/v1/agents

Yanıt: CORS başlıkları ile 204 No Content.

API Endpoint'leri

1. Ajanları Listele

Endpoint: GET /agents

Özet: Ajanları listele

Açıklama: Durum, çalıştırma modu, LLM modeli ile gelişmiş filtreleme ve isim ile prompt üzerinde tam metin arama ile sayfalanmış ajan listesi getirir. x-api-key başlığı ile kimlik doğrulama ve geçerli API kotası gerektirir.

Kimlik Doğrulama: Gerekli (x-api-key)

Etiketler: Ajanlar

Sorgu Parametreleri:

Parametre	Tür	Varsayılan	Açıklama	Örnek
skip	number	0	Sayfalama için atlanacak ajan sayısı (offset)	0
limit	number	10	Sayfa başına döndürülecek maksimum ajan sayısı (maksimum 100)	20
sortBy	string	createdAt	Ajanların sıralanacağı alan (örn: name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Sıralama yönü (artan veya azalan)	desc
status	enum	isteğe bağlı	Ajanları duruma göre filtrele (active veya inactive)	active
executionMode	enum	isteğe bağlı	Ajanları çalıştırma moduna göre filtrele (scheduled veya batched)	scheduled
model	string	isteğe bağlı	Ajanları LLM model adına göre filtrele	llama-2-70b-chat
search	string	isteğe bağlı	Ajan adı ve prompt'ta tam metin arama (büyük/küçük harf duyarsız)	blog yazarı

Yanıt Şeması (200 OK):

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Teknoloji Blog Yazarı",
      "description": "Haftalık programla teknoloji makaleleri üretir",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "tr",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Hata Yanıtları:

400 Hatalı İstek: Geçersiz sorgu parametreleri
401 Yetkisiz: Geçersiz API anahtarı
402 Ödeme Gerekli: API kotası aşıldı
404 Bulunamadı: Çalışma alanı bulunamadı
500 Sunucu Hatası: Sunucu hatası

Örnek İstek:

curl -H "x-api-key: Bearer api_anahtariniz" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. ID ile Ajan Getir

Endpoint: GET /agents/{agentId}

Özet: ID ile ajan getir

Açıklama: Tek bir ajanın tam yapılandırma ve meta verilerini getirir. x-api-key başlığı ile kimlik doğrulama ve geçerli API kotası gerektirir.

Kimlik Doğrulama: Gerekli (x-api-key)

Etiketler: Ajanlar

Yol Parametreleri:

Parametre	Tür	Açıklama	Örnek
agentId	string	Getirilecek ajanın MongoDB ObjectId'si	507f1f77bcf86cd799439011

Yanıt Şeması (200 OK):

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Teknoloji Blog Yazarı",
    "description": "Haftalık programla teknoloji makaleleri üretir",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "tr",
    "prompt": "Şu konu hakkında makale yaz: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Hata Yanıtları:

400 Hatalı İstek: Geçersiz ajan ID formatı
401 Yetkisiz: Geçersiz API anahtarı
402 Ödeme Gerekli: API kotası aşıldı
404 Bulunamadı: Ajan veya çalışma alanı bulunamadı
500 Sunucu Hatası: Sunucu hatası

Örnek İstek:

curl -H "x-api-key: Bearer api_anahtariniz" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. Makaleleri Listele

Endpoint: GET /articles

Özet: Makaleleri listele

Açıklama: Ajan, durum, dil, etiketler ile gelişmiş filtreleme ve başlık, açıklama, anahtar kelimeler üzerinde tam metin arama ile sayfalanmış makale listesi getirir. x-api-key başlığı ile kimlik doğrulama ve geçerli API kotası gerektirir.

Kimlik Doğrulama: Gerekli (x-api-key)

Etiketler: Makaleler

Sorgu Parametreleri:

Parametre	Tür	Varsayılan	Açıklama	Örnek
skip	number	0	Sayfalama için atlanacak makale sayısı (offset)	0
limit	number	10	Sayfa başına döndürülecek maksimum makale sayısı (maksimum 100)	20
sortBy	string	createdAt	Makalelerin sıralanacağı alan (örn: title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Sıralama yönü (artan veya azalan)	desc
agentId	string	isteğe bağlı	Makaleleri kaynak ajan ID'sine göre filtrele (MongoDB ObjectId)	507f1f77bcf86cd799439011
status	enum	isteğe bağlı	Makaleleri yayın durumuna göre filtrele (draft, published, archived)	published
slug	string	isteğe bağlı	Makaleleri verilen slug'a göre filtrele	generic-article-slug-as-example
language	string	isteğe bağlı	Makaleleri dil koduna göre filtrele (örn: en, tr, de)	tr
model	string	isteğe bağlı	Makaleleri üretimde kullanılan LLM modeline göre filtrele	llama-2-70b-chat
tags	string	isteğe bağlı	Etiketlere göre filtrele (virgülle ayrılmış, herhangi bir etikete eşleşir)	öne-çıkan,trend,teknoloji
search	string	isteğe bağlı	Başlık, açıklama, anahtar kelimeler ve etiketlerde tam metin arama (büyük/küçük harf duyarsız)	yapay zeka

Yanıt Şeması (200 OK):

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Next.js 14 ile Başlangıç",
      "slug": "nextjs-14-ile-baslangic",
      "description": "Next.js 14 ile modern web uygulamaları nasıl oluşturulur öğrenin",
      "status": "published",
      "language": "tr",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-gelistirme"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Hata Yanıtları:

400 Hatalı İstek: Geçersiz sorgu parametreleri
401 Yetkisiz: Geçersiz API anahtarı
402 Ödeme Gerekli: API kotası aşıldı
404 Bulunamadı: Çalışma alanı bulunamadı
500 Sunucu Hatası: Sunucu hatası

Örnek İstek:

curl -H "x-api-key: Bearer api_anahtariniz" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=tr&tags=one-cikan,trend&search=yapay+zeka"

4. ID ile Makale Getir

Endpoint: GET /articles/{articleId}

Özet: ID ile makale getir

Açıklama: Tam içerik ve yapılandırılmış bloklarla tek bir makaleyi ID'sine göre getirir. x-api-key başlığı ile kimlik doğrulama ve geçerli API kotası gerektirir.

Kimlik Doğrulama: Gerekli (x-api-key)

Etiketler: Makaleler

Yol Parametreleri:

Parametre	Tür	Açıklama	Örnek
articleId	string	Getirilecek makalenin MongoDB ObjectId'si	607f1f77bcf86cd799439012

Yanıt Şeması (200 OK):

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Next.js 14 ile Başlangıç",
    "slug": "nextjs-14-ile-baslangic",
    "description": "Next.js 14 ile modern web uygulamaları nasıl oluşturulur öğrenin",
    "content": "Tam makale markdown/metin içeriği burada...",
    "status": "published",
    "language": "tr",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-gelistirme"],
    "blocks": [
      {
        "type": "header",
        "content": "Next.js 14 ile Başlangıç",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 yeni özellikler sunuyor..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logosu"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web geliştirme",
      "description": "Next.js 14 ile modern web uygulamaları nasıl oluşturulur öğrenin",
      "tags": ["nextjs", "react", "web-gelistirme"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Blok Türleri:

text: Düz metin paragrafı

{"type": "text", "content": "Paragraf metni"}

header: Başlık (1-6 seviye)

{"type": "header", "content": "Başlık", "level": 1}

image: İsteğe bağlı açıklamalı görsel

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Açıklama"}

list: Sıralı veya sırasız liste

{"type": "list", "items": ["madde1", "madde2"], "ordered": false}

code: Dil belirtilmiş kod bloğu

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video: Video yerleştirme

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video başlığı"}

Hata Yanıtları:

400 Hatalı İstek: Geçersiz makale ID formatı
401 Yetkisiz: Geçersiz API anahtarı
402 Ödeme Gerekli: API kotası aşıldı
404 Bulunamadı: Makale veya çalışma alanı bulunamadı
500 Sunucu Hatası: Sunucu hatası

Örnek İstek:

curl -H "x-api-key: Bearer api_anahtariniz" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. Ajan Makalelerini Getir

Endpoint: GET /agents/{agentId}/articles

Özet: Belirli ajandan makaleleri getir

Açıklama: Belirli bir ajan tarafından oluşturulan tüm makaleleri filtreleme ve sayfalama ile getirir. Makaleleri en yeniden en eskiye sıralar. x-api-key başlığı ile kimlik doğrulama ve geçerli API kotası gerektirir.

Kimlik Doğrulama: Gerekli (x-api-key)

Etiketler: Ajanlar

Yol Parametreleri:

Parametre	Tür	Açıklama	Örnek
agentId	string	Ajanın MongoDB ObjectId'si	507f1f77bcf86cd799439011

Sorgu Parametreleri:

Parametre	Tür	Varsayılan	Açıklama	Örnek
limit	number	50	Döndürülecek maksimum makale sayısı	30
skip	number	0	Sayfalama için atlanacak kayıt sayısı	0
status	string	isteğe bağlı	Makale durumuna göre filtrele (draft, published, archived)	published
sort	string	createdAt	Sıralanacak alan	createdAt
order	enum	desc	Sıralama yönü (asc veya desc)	desc
slug	string	isteğe bağlı	Makaleleri URL dostu slug'a göre filtrele	nextjs-ile-baslangic

Yanıt Şeması (200 OK):

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Next.js ile Başlangıç",
      "slug": "nextjs-ile-baslangic",
      "description": "Next.js için kapsamlı bir rehber",
      "status": "published",
      "language": "tr",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-gelistirme"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Hata Yanıtları:

400 Hatalı İstek: Geçersiz ajan ID formatı
401 Yetkisiz: Geçersiz API anahtarı
402 Ödeme Gerekli: API kotası aşıldı
404 Bulunamadı: Ajan veya çalışma alanı bulunamadı
500 Sunucu Hatası: Sunucu hatası

Örnek İstek:

curl -H "x-api-key: Bearer api_anahtariniz" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. Çalışma Alanı Verilerini Getir

Endpoint: GET /workspaces/{workspaceId}

Özet: Çalışma alanı verilerini getir

Açıklama: Çalışma alanı meta verileri, tüm ajanlar ve tam içerikli yayınlanmış makaleler dahil tam çalışma alanı verilerini getirir. Çalışma alanı içerik yapısına kolay erişim için makalelerle birlikte iç içe ajanlar döndürür. Çalışma alanı ID'si ile eşleşen API anahtarı kimlik doğrulaması gerektirir.

Kimlik Doğrulama: Gerekli (x-api-key) - Erişilen çalışma alanı ile eşleşmeli

Etiketler: Çalışma Alanları

Yol Parametreleri:

Parametre	Tür	Açıklama	Örnek
workspaceId	string	Getirilecek çalışma alanının MongoDB ObjectId'si	507f1f77bcf86cd799439010

Yanıt Şeması (200 OK):

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "İçerik Stüdyom",
    "description": "Yapay zeka destekli içerik üretim çalışma alanı",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Teknoloji İçerik Ajanı",
      "description": "Teknik makaleler ve öğreticiler üretir",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "tr",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Next.js ile Başlangıç",
          "slug": "nextjs-ile-baslangic",
          "description": "Next.js için kapsamlı bir rehber",
          "status": "published",
          "language": "tr",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

Hata Yanıtları:

400 Hatalı İstek: Geçersiz çalışma alanı ID formatı
401 Yetkisiz: Geçersiz API anahtarı veya çalışma alanı uyumsuzluğu
402 Ödeme Gerekli: API kotası aşıldı
404 Bulunamadı: Çalışma alanı bulunamadı
500 Sunucu Hatası: Sunucu hatası

Örnek İstek:

curl -H "x-api-key: Bearer api_anahtariniz" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

Hata Yönetimi

Tüm endpoint'ler HTTP durum kodları ile standartlaştırılmış hata yanıtları döndürür:

Hata Yanıt Formatı

{
  "error": "Hata türü",
  "details": "Detaylı hata mesajı"
}

HTTP Durum Kodları

Durum	Açıklama
200	Başarılı - İstek başarıyla tamamlandı
400	Hatalı İstek - Geçersiz sorgu parametreleri veya yol formatı
401	Yetkisiz - Geçersiz veya eksik API anahtarı
402	Ödeme Gerekli - Çalışma alanı planı için API kotası aşıldı
404	Bulunamadı - Kaynak mevcut değil
500	Sunucu Hatası - Sunucu tarafı hatası oluştu

Kota Sistemi

Her çalışma alanının abonelik planına dayalı bir API çağrı kotası vardır. Kota aylık olarak sıfırlanır ve her istekte uygulanır.

Plan Limitleri

Ücretsiz: Aylık 0 API çağrısı
Başlangıç: Aylık 0 API çağrısı
Pro: Aylık 10.000 API çağrısı
Ajans: ~ API çağrısı/ay
Kurumsal: Sınırsız

Kota Uygulaması

Her API isteği aylık kotaya karşı 1 çağrı olarak sayılır. Kota aşıldığında:

HTTP Durumu: 402 Ödeme Gerekli
Yanıt: { error: "API erişim kotası aşıldı" }

Yanıt Formatları

Başarılı Yanıt

Tüm başarılı yanıtlar JSON verisi ile 200 durum kodu döndürür:

{
  "data": [...],
  "pagination": {...}
}

Sayfalama Formatı

Tüm liste endpoint'leri tutarlı sayfalama meta verileri kullanır:

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Hata Yanıtı

Tüm hata yanıtları error ve details alanlarını içerir:

{
  "error": "Yetkisiz",
  "details": "Geçersiz veya eksik API anahtarı"
}

Endpoint Özeti

Metot	Endpoint	Açıklama
GET	/agents	Sayfalama ve filtrelerle ajanları listele
GET	/agents/{agentId}	ID ile tek ajan getir
GET	/articles	Sayfalama ve gelişmiş filtrelerle makaleleri listele
GET	/articles/{articleId}	Tam içerikle ID ile tek makale getir
GET	/agents/{agentId}/articles	Belirli ajandan makaleleri getir
GET	/workspaces/{workspaceId}	Tüm ajanlar ve makalelerle çalışma alanını getir
OPTIONS	/*	CORS ön kontrol desteği

En İyi Uygulamalar

Sayfalama

Zaman aşımlarını önlemek için liste endpoint'lerinde her zaman sayfalama kullanın
skip: 0 ve limit: 25-50 ile başlayın
Daha fazla sonuç olup olmadığını belirlemek için hasNextPage kullanın
Başarısız istekler için üstel geri çekilme uygulayın

Filtreleme

Yanıt boyutunu azaltmak için belirli filtreler kullanın
Sonuçları daraltmak için status ve language ile filtreleyin
Tüm kayıtları getirmek yerine tam metin araması için search kullanın

Hata Yönetimi

Her zaman 401 (kimlik doğrulama) ve 402 (kota) hatalarını kontrol edin
Üstel geri çekilme ile yeniden deneme mantığı uygulayın
Hata ayıklama için hata detaylarını günlüğe kaydedin
4xx hatalarını istemci sorunları, 5xx hatalarını sunucu sorunları olarak ele alın

Performans

API çağrılarını azaltmak için sonuçları 5-10 dakika önbelleğe alın
Optimum performans için limit=50 kullanın
Sonuç kümesi boyutunu minimize etmek için filtreleri birleştirin
Kota limitlerine göre sayfalama toplu iş boyutunu değerlendirin

Doküman Sürümü: 2.0 Son Güncelleme: Ocak 2026 API Sürümü: v1 Durum: SDK Oluşturma için Üretime Hazır