Gönderilerinizi kodunuzdan ya da yapay zekâ asistanınızdan planlayın.

Sıfırdan yayındaki bir gönderiye beş adım. Örneklerin hepsi curl ile; anahtarınızı bir kez tanımlayın: export POSTYAY_API_KEY=pyk_live_….

1. 1

   Bir API anahtarı oluşturun

   Ayarlar → API anahtarları bölümüne gidin, anahtara bir ad verin (ör. “Zapier” ya da “Claude”) ve kopyalayın. Anahtarı yalnızca bir kez görürsünüz; biz sadece özetini (hash) saklarız.

2. 2

   Bağlı hesaplarınızı listeleyin

   Önce uygulamada TikTok ya da Bluesky hesabınızı bağlayın. Her hesabın id değeri, gönderinin gideceği yerdir; health hesabın yeniden bağlanması gerekip gerekmediğini söyler.

   curl https://postyay.com/api/v1/accounts \
     -H "Authorization: Bearer $POSTYAY_API_KEY"

3. 3

   Bir video ya da fotoğraf yükleyin

   Dosyayı multipart olarak gönderin ya da herkese açık bir URL verin, biz indirelim. Dönen id değerini saklayın. Biçimi her platform için yayın sırasında biz dönüştürürüz.

   curl https://postyay.com/api/v1/media \
     -H "Authorization: Bearer $POSTYAY_API_KEY" \
     -F [email protected]
   
   # or let postyay download it
   curl https://postyay.com/api/v1/media \
     -H "Authorization: Bearer $POSTYAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://example.com/clip.mp4" }'

4. 4

   Gönderiyi planlayın

   Tek gönderi, birden çok hesap. TikTok için settings.privacyLevel zorunlu. schedule; "now", ISO 8601 bir zaman ya da "draft" olabilir. Önce uygulamadaki ön kontrollerin aynısı çalışır; sorun çıkaracak her şey violations olarak döner.

   curl https://postyay.com/api/v1/posts \
     -H "Authorization: Bearer $POSTYAY_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "text": "Behind the scenes of the shoot #bts",
       "mediaIds": ["MEDIA_ID"],
       "targets": [
         { "accountId": "TIKTOK_ACCOUNT_ID",
           "settings": { "privacyLevel": "PUBLIC_TO_EVERYONE", "allowComment": true } },
         { "accountId": "BLUESKY_ACCOUNT_ID",
           "settings": { "altText": { "MEDIA_ID": "A camera crew on set" } } }
       ],
       "schedule": "now"
     }'
   
   # "schedule": "2026-10-01T09:00:00+03:00" schedules it, "draft" only saves it.

5. 5

   Yayına girene kadar takip edin

   Gönderiyi birkaç saniyede bir sorgulayın. status değeri published olduğunda her hedefin canlı url adresi gelir. TikTok videolarının işlenmesi birkaç dakika sürebilir.

   while :; do
     status=$(curl -s https://postyay.com/api/v1/posts/POST_ID \
       -H "Authorization: Bearer $POSTYAY_API_KEY" | jq -r .status)
     echo "$status"
     case "$status" in published|failed|needs_action|canceled) break ;; esac
     sleep 5
   done

   {
     "id": "5b0e…",
     "status": "published",
     "source": "api",
     "targets": [
       { "platform": "tiktok", "status": "published",
         "url": "https://www.tiktok.com/@you/video/7431…" },
       { "platform": "bluesky", "status": "published",
         "url": "https://bsky.app/profile/you.bsky.social/post/3l…" }
     ]
   }

Anahtarı her isteğin Authorization başlığında gönderin: Bearer pyk_live_….

• Anahtar, onu oluşturan üye adına ve o çalışma alanında işlem yapar. Üye çalışma alanından ayrılırsa anahtar çalışmaz olur.
• Anahtarı Ayarlar’dan dilediğiniz an iptal edebilirsiniz; hemen çalışmaz olur. Son kullanım zamanı, artık gerekmeyen anahtarları fark etmenizi kolaylaştırır.
• Anahtarlara parola gibi davranın: sunucunuzda ya da asistanınızın ayarlarında tutun; tarayıcıya, mobil uygulamaya ya da herkese açık bir depoya asla koymayın.

Her hata aynı biçimdedir. requestId ayrıca x-trace-id başlığında da gelir; destekle iletişime geçerken bu değeri paylaşın.

{
  "code": "PREFLIGHT",
  "message": "TikTok allows 2,200 characters — you're 100 over.",
  "requestId": "3f0c9d2e-…",
  "violations": [
    { "accountId": "…", "platform": "tiktok", "code": "text_too_long",
      "message": "TikTok allows 2,200 characters — you're 100 over.",
      "params": { "max": 2200, "over": 100 },
      "fix": { "mode": "manual", "action": "shorten_text" } }
  ]
}

VALIDATION_ERROR hatasına details (hatalı alanlar) eklenir. PREFLIGHT hatasına violations eklenir: her sorun için bir kayıt; hesap, platform ve text_too_long ya da media_required gibi sabit bir code ile.

Sınırlar anahtar başınadır ve bir dakikalık pencerelerle sayılır: dakikada 60 istek, bunların en fazla 10 tanesi gönderi oluşturabilir. MCP araç çağrıları da aynı bütçeden düşer.

Her yanıt nerede olduğunuzu söyler: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (saniye) ve RateLimit-Policy. Sınırı aşınca Retry-After ile birlikte 429 RATE_LIMITED alırsınız.

RateLimit-Policy: 60;w=60, 10;w=60;comment="posts"
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

Gönderiler, uygulamada oluşturulanlar gibi planınızın aylık gönderi sınırına da sayılır. Kullanımınızı GET /api/v1/me gösterir.

Listeler en yeniden eskiye { data, nextCursor } döner. limit (1–100, varsayılan 25) gönderin; sonraki sayfa için cursor=nextCursor ekleyin. Son sayfada nextCursor değeri null olur. GET /api/v1/posts ayrıca status, accountId, from ve to ile süzülebilir.

curl "https://postyay.com/api/v1/posts?status=scheduled&limit=50" \
  -H "Authorization: Bearer $POSTYAY_API_KEY"

# next page
curl "https://postyay.com/api/v1/posts?status=scheduled&limit=50&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $POSTYAY_API_KEY"

Ağ aksaklıkları olur. POST /api/v1/posts isteğine bir Idempotency-Key başlığı (ör. bir UUID) ekleyin ve gönül rahatlığıyla yeniden deneyin: 24 saat boyunca aynı anahtar ve aynı gövde, ikinci bir gönderi oluşturmak yerine ilk sonucu Idempotent-Replayed: true ile döndürür. Aynı anahtar farklı bir gövdeyle gelirse reddedilir.

Bir gönderi bir ya da daha çok hesaba gider; her biri kendi durumu olan bir hedeftir. Gönderinin status değeri, hedeflerinin en acil olanıdır.

draft

Kaydedildi, planlanmadı.

scheduled

Zamanını bekliyor.

queued

Zamanı geldi; yayına alındı.

preparing

Medya platform için dönüştürülüyor.

publishing

Platforma gönderiliyor.

processing

Platform kabul etti ve işliyor.

published

Yayında; hedefin url değeri var.

needs_action

Birinin müdahale etmesi gerekiyor (ör. hesabı yeniden bağlamak); error alanına bakın.

failed

Denemelerden sonra vazgeçildi; error alanına bakın.

canceled

Gönderi yayınlanmadan silindi.

postyay Model Context Protocol’ü destekler; yapay zekâ asistanları gönderilerinizi sizin için planlayabilir: “bu videoyu yarın saat 9’da TikTok ve Bluesky’a gönder”. REST API ile aynı anahtarı, sınırları ve kontrolleri kullanır.

Araçlar

• list_accountsBağlı hesaplar; kimlikleri ve durumlarıyla.
• upload_media_from_urlHerkese açık bir URL’den video, fotoğraf ya da PDF indirir.
• create_postGönderiyi oluşturur ve planlar (hemen, belirli bir zamanda ya da taslak), ön kontrol geri bildirimiyle.
• schedule_postVar olan bir taslağı planlar.
• list_postsDurumlarıyla gönderiler; süzülmüş ve sayfalanmış.
• get_post_statusBir gönderinin yayın zaman çizelgesi ve canlı adresleri.
• reschedule_postGönderiyi yeni bir zamana taşır.
• delete_postGönderiyi siler, yayınlanmamış hedefleri iptal eder.
• get_best_timePaylaşım için bir zaman önerir. Şimdilik sabit bir kural (saat diliminizde yarın 09:00); kitle verisine dayanmaz ve bunu açıkça söyler.

Asistanınızı bağlayın

Claude Code

Tek komut sunucuyu anahtarınızla ekler:

claude mcp add --transport http postyay https://postyay.com/mcp \
  --header "Authorization: Bearer pyk_live_…"

Claude Desktop

Şunu claude_desktop_config.json dosyasına ekleyin (Ayarlar → Geliştirici → Yapılandırmayı düzenle) ve Claude’u yeniden başlatın. mcp-remote uzak sunucuya köprü kurar ve anahtarınızı başlık olarak gönderir.

{
  "mcpServers": {
    "postyay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://postyay.com/mcp",
               "--header", "Authorization:${POSTYAY_API_KEY}"],
      "env": { "POSTYAY_API_KEY": "Bearer pyk_live_…" }
    }
  }
}

Cursor, VS Code ve diğer istemciler

Uzak bir MCP sunucusu için HTTP başlığı tanımlamanıza izin veren her istemci, URL ve başlıkla çalışır:

{
  "mcpServers": {
    "postyay": {
      "url": "https://postyay.com/mcp",
      "headers": { "Authorization": "Bearer pyk_live_…" }
    }
  }
}

API’nin doğrulamada kullandığı şemaların aynısından üretilir. Temel URL: https://postyay.com/api/v1. OpenAPI belgesini Postman’e, Insomnia’ya ya da kod üreticinize aktarabilirsiniz.