Tek bir yapılandırılmış API ile Eyivo üzerinde geliştirin.

1. Genel bakış

Eyivo REST API, yapılandırılmış siteleri programatik olarak yönetmenizi sağlar. HTTPS ve JSON kullanır, /api/v1 altında sürümlendirilir ve kontrol paneliyle aynı sahiplik, plan sınırı, doğrulama ve denetim kurallarını uygular.

Sürümlendirme: sözleşmeyi bozan değişiklikler yeni bir temel sürüm gerektirir. Mevcut JSON nesnelerine yeni alanlar eklenebilir; istemciler tanımadıkları alanları yok saymalıdır.

2. Hızlı başlangıç

1. 1
   Bir API anahtarı oluşturun.

   Uygulamaya giriş yapın, API anahtarlarını açın, gerekli en dar kapsamları seçin ve ey_ ile başlayan gizli anahtarı gösterildiğinde kopyalayın.

2. 2
   Sitelerinizi listeleyin.

   Kimlik doğrulamasını onaylayın ve alt uç noktaların kullandığı sayısal site kimliğini alın.

3. 3
   Yinelenebilir güvenli yazma istekleri gönderin.

   Her POST, PATCH ve DELETE isteğine benzersiz bir Idempotency-Key.

curl --request GET \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token'

Başarılı bir koleksiyon yanıtı kayıtları data içinde sunar:

{
  "data": [
    {
      "id": 42,
      "platform_subdomain_key": "7kr9mp2x",
      "template_key": "corporate-01",
      "status": "active",
      "native_locale": "en",
      "english_enabled": false,
      "content_version": 1,
      "search_visibility": "platform_noindex"
    }
  ]
}

3. Kimlik doğrulama

Her /api/v1 isteği bir bearer token gerektirir:

Authorization: Bearer <token>

PKCE yetkilendirme akışı

1. Yüksek entropili bir code_verifier ve bunun SHA-256 code_challenge değerini oluşturun.
2. Kullanıcıyı response_type=code, herkese açık client_id, kayıtlı tam redirect_uri, boşlukla ayrılmış istenen scope, state, code_challenge ve code_challenge_method=S256 ile /oauth/authorize adresine yönlendirin.
3. Yönlendirme sonrası state değerini doğrulayın; ardından dönen yetkilendirme kodunu özgün code_verifier ile /oauth/token adresinde anahtarla değiştirin.
4. Erişim ve yenileme anahtarlarını güvenle saklayın. Süreleri dolmadan yenileyin ve döndürülen kimlik bilgilerini atomik olarak değiştirin.

4. Kapsamlar

İstekler aşağıda belirtilen tam kapsamı gerektirir. * içeren kişisel anahtar tüm kapsam kontrollerinden geçer; uygulamalar yine de gerekli en dar kapsamları istemelidir.

REST, mcp:use değil uç noktanın kapsamını gerektirir. Medya uç noktaları media:read veya media:write kullanır.

5. Yinelenebilir güvenli yazma işlemleri

Aynı isteği güvenle tekrarlamak için JSON değişikliklerinde Idempotency-Key gönderin. Multipart medya yüklemeleri ve yükleme bileti oluşturma kapsam dışıdır; yeniden denemeden önce aktarım sonucunu kontrol edin.

Idempotency-Key: site-42-page-create-01J7M6Y8RRF3ZE6WB4Z0Y9XJXC

İstek eşleşmesi HTTP yöntemi, istek yolu ve ham istek gövdesinin tam içeriğini kapsar. Yeniden denerken özgün JSON serileştirmesini kullanın.

6. Yanıtlar ve kaynak yapıları

İçerik işlemleri data zarfı döndürür. MCP, structuredContent ve aynı JSON’un metin kopyasını; REST ise JSON döndürür. Kimlik, yayın hazırlığı ve sayfalama için çıktı şemasını okuyun. Blog, medya ve gönderim listelerinde dönen sayfa bilgilerini izleyin.

{ "data": { "id": 42, "status": "active" } }

{ "data": [{ "id": 42 }, { "id": 43 }] }

Koleksiyon yapıları değişebilir. Her uç noktanın sayfalama bilgilerini izleyin; tüm sonuçların düz veya sayfalamasız liste olduğunu varsaymayın.

7. Siteler

Site oluşturma

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: site-create-01J7M6Y8' \
  --data '{
    "display_name": "Northstar Studio",
    "template_key": "corporate-01",
    "native_locale": "en"
  }'

Yanıt: site kaynağıyla birlikte 201 Created. Yerleştirme tamamlanana kadar ilk durumda site etkin görünmeyebilir. Site ve plan sınırları için 422 döner.

Site kaynağı alanları: id, platform_subdomain_key, template_key, status, native_locale, english_enabled, content_version, search_visibility, isteğe bağlı runtime ve zaman damgaları.

8. Sayfalar

Sayfa oluşturma

{
  "type": "page",
  "sort_order": 300,
  "locale": "en",
  "slug": "our-story",
  "title": "Our story",
  "body": "<p>How the company began.</p>",
  "meta_title": "Our story | Northstar Studio",
  "meta_description": "Learn about Northstar Studio."
}

Oluşturma yanıtı: 201. Güncelleme yanıtı: 200. Silme yanıtı: gövdesiz 204.

Taslağı kaydedin, yayın hazırlığını kontrol edin ve kullanıcı değişikliği yayına almak istediğinde ilgili öğeyi ve dili yayınlayın. Diğer taslaklar yayınlanmaz.

9. Katalog öğeleri

Katalog öğesi oluşturma

{
  "sort_order": 100,
  "locale": "en",
  "slug": "strategy-advisory",
  "title": "Strategy advisory",
  "summary": "Focused advice for consequential decisions.",
  "body": "Talk to our senior advisory team."
}

Taslağı kaydedin, yayın hazırlığını kontrol edin ve kullanıcı değişikliği yayına almak istediğinde ilgili öğeyi ve dili yayınlayın. Diğer taslaklar yayınlanmaz.

Bunlar içerik ailesine göre örneklerdir. Tüm girdi/çıktı şemalarını ve gerekli kapsamları tools/list veya OpenAPI belgesinden keşfedin. Aşağıdaki REST yolları /api/v1/sites/{site} adresine göredir.

Yetenekler ve içerik düzenleme sözleşmesi

Bir site seçip yeteneklerini okuyun: etkin diller, tema alanları, bileşen şemaları, menü konumları ve kurulu eklenti panelleri. Yazmadan önce content-workflow kaynağını okuyun. Kaynakları desteklemeyen istemciler get-site-capabilities-tool kullanabilir. Keşif tamamlanana kadar tools/list nextCursor değerini izleyin.

GET /api/v1/sites/{site}/capabilities
GET /api/v1/sites/{site}/pages/{page_id}/components/schema?locale=en

İstenen dili ve güncel version veya revision değerini kullanın. Blog kaydı belgenin tamamını değiştirir ve zamanlamasını iptal eder. Menü düzenlemeleri sayısal revision, içerik atamaları ayrı bir menu_revision özeti kullanır. Değiştirilen dizilerdeki mevcut öğeleri koruyun. Çakışmada yeniden okuyup değişiklikleri birleştirin.

Ana gezinme otomatik kalır. Ek menülerin taslakları ve yayınları ayrıdır. İçerik kaydı menü atamalarını hazırlar; ilgili içeriği yayınlamak diğer menü taslaklarını yayınlamadan bu atamaları uygular. Menü yayınlamak bağlantılı içeriği yayınlamaz. Sayfadaki source_hash eski kaynak metne dayanan çevirileri reddeder.

Sayfa gövdesi ve temanın richtext alanları temizlenmiş HTML kabul eder. Yayınlandığında ziyaretçinin dilinde çözümlenen kalıcı /__eyivo/pages/{id} bağlantıları için list-page-links-tool kullanın. Bloglar body_html yerine aynı siteye ait media_id ve sayfa/yazı hedefleri içeren yapılandırılmış document JSON kullanır.

{
  "type": "doc",
  "content": [{
    "type": "paragraph",
    "content": [{ "type": "text", "text": "Our story" }]
  }]
}

Görsel ve video yükleme

upload-media-tool, Claude gibi MCP Apps istemcilerinde dosya seçici açar. ChatGPT ayrıca kendi ek referansını sağlayabilir; Claude sohbet eki OpenAI dosya referansı değildir. İndirme adresi uydurmayın ve araç argümanlarında base64 dosya göndermeyin.

Codex ve Claude Code, prepare-media-upload-tool çağırıp dosyayı beş dakika içinde dönen upload_url adresine tek kullanımlık upload_token ile multipart olarak gönderebilir. Bu anahtarı gizli tutun. REST istemcileri kendi media:write anahtarlarını kullanabilir. İçerikte kullanılacak medya kimliği yalnızca tamamlanan yüklemede döner; bilet oluşturmak dosyayı yüklemez.

POST /api/v1/sites/{site}/media
Authorization: Bearer <media:write token>
Content-Type: multipart/form-data; boundary=<generated by HTTP client>

file: <original file bytes>

10. Özel alan adları

Alan adı isteme

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites/42/domains \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: domain-request-example-com' \
  --data '{"domain":"www.example.com"}'

Bekleyen alan adı kaynağı verification_token içerir. Alan adınız için döndürülen değeri kullanarak gerekli DNS sahiplik kaydını ekleyin, DNS yayılımını bekleyin ve etkinleştirme uç noktasını çağırın. Etkinleştikten sonra birincil genel adres olacaksa birincil uç noktasını çağırın.

Alan adı kaynağı alanları: id, domain, site_id, is_primary, status, koşullu verification_token ve zaman damgaları. Özel alan adı plan sınırları ile alan adı doğrulama hataları 422 döndürür.

11. Hatalar

Doğrulama yanıtı

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

Kimlik doğrulama veya yetkilendirme yanıtı

{
  "message": "Missing required scope [content:write]."
}

12. Geçerli sınırlar ve entegrasyon kontrol listesi

REST v1, Eyivo özelliklerinin belirli bir bölümünü sunar. Bir uç noktanın bulunmaması, dahili API’leri çağırma izni değil sözleşmenin sınırıdır.

Üretim ortamına geçmeden önce

• HTTPS kullanın ve beklenen app.eyivo.com ana makinesini doğrulayın.
• Bearer anahtarlarını sunucu tarafında tutun ve günlüklerde yetkilendirme başlıklarını gizleyin.
• Yalnızca gerekli kapsamları isteyin ve mümkün olduğunda siteyle sınırlı kişisel anahtarları tercih edin.
• Her mantıksal yazma işlemi için benzersiz bir yinelenebilir işlem anahtarı kullanın ve yeniden denemelerde aynı anahtarı koruyun.
• Temel istek veya kimlik bilgisi değişmedikçe 401, 403, 404 ve 422 yanıtlarını geçici hata saymayın.
• Geçici hatalar için rastgele sapmalı üstel gecikme kullanın ve gelecekte dönebilecek Retry-After başlığına uyun.
• Koleksiyon yapıları değişebilir. Her uç noktanın sayfalama bilgilerini izleyin; tüm sonuçların düz veya sayfalamasız liste olduğunu varsaymayın.