API Dokümantasyonu

Mosaic Public API · v1

Mosaic Public API, kurumunuzun sosyal medya verilerini (takipçi sayıları, geçmiş trend, paylaşımlar ve özet metrikler) kendi web sitenize veya dashboard'unuza entegre etmenizi sağlar. API salt-okunurdur ve yalnızca size verilen API key'in ait olduğu kurumun verisini döndürür.

Temel URL

https://www.mosaic.net.tr/api/public/v1

Kimlik Doğrulama

Her istekte kurumunuza özel API key'i göndermeniz gerekir. Key'i panelden Kurumlar → (kurum) → Düzenle → Public API bölümünden üretebilir, yenileyebilir veya iptal edebilirsiniz. Üç yöntemden biriyle gönderebilirsiniz (önerilen: X-Api-Key header):

# 1) X-Api-Key header (önerilen)
curl https://www.mosaic.net.tr/api/public/v1/overview -H "X-Api-Key: msk_xxxxxxxx"

# 2) Authorization: Bearer
curl https://www.mosaic.net.tr/api/public/v1/overview -H "Authorization: Bearer msk_xxxxxxxx"

# 3) Query parametresi (sadece test için — URL'de görünür)
curl "https://www.mosaic.net.tr/api/public/v1/overview?api_key=msk_xxxxxxxx"

⚠️ API key'i gizli tutun. Sızdığını düşünüyorsanız panelden Yeniden Üret ile anında iptal edebilirsiniz.

Endpoint'ler

GET/overview

Kurum bilgisi, her platformun güncel takipçi sayısı ve birleşik özet (toplam takipçi, 7 günlük büyüme).

{
  "organization": { "name": "Radyo C", "slug": "radyo-c", "description": "..." },
  "summary": {
    "total_followers": 123487,
    "platform_count": 6,
    "growth_7d": 540,
    "growth_7d_percent": 0.44
  },
  "platforms": [
    {
      "platform": "instagram",
      "platform_label": "Instagram",
      "platform_color": "#e1306c",
      "account_name": "@radyoc",
      "followers": 22303,
      "snapshot_date": "2026-06-19"
    }
  ],
  "updated_at": "2026-06-19"
}

GET/followers

Her platformun en güncel takipçi sayısı (rozet/kart göstermek için ideal).

{
  "data": [
    {
      "platform": "youtube",
      "platform_label": "YouTube",
      "platform_color": "#ff0000",
      "account_name": "@radyoc",
      "followers": 47441,
      "snapshot_date": "2026-06-19"
    }
  ]
}

GET/followers/history

Tarih bazlı takipçi serisi — trend grafiği çizmek için.

Parametre	Tip	Açıklama
`platform`	string	İsteğe bağlı. Tek platform (ör. `instagram`). Boşsa tüm platformlar.
`days`	int	İsteğe bağlı. Kaç günlük geçmiş (varsayılan 30, en fazla 365).

GET https://www.mosaic.net.tr/api/public/v1/followers/history?platform=instagram&days=30

{
  "data": [
    {
      "platform": "instagram",
      "platform_label": "Instagram",
      "account_name": "@radyoc",
      "points": [
        { "date": "2026-06-18", "followers": 22290, "following": 120, "posts": 540 },
        { "date": "2026-06-19", "followers": 22303, "following": 121, "posts": 541 }
      ]
    }
  ]
}

GET/posts

Çekilen son paylaşımlar ve etkileşim metrikleri.

Parametre	Tip	Açıklama
`platform`	string	İsteğe bağlı. Tek platforma filtrele.
`limit`	int	İsteğe bağlı. Maksimum post sayısı (varsayılan 20, en fazla 50).

{
  "data": [
    {
      "platform": "instagram",
      "content": "Yeni çalma listemiz yayında! 🎵",
      "post_type": "image",
      "url": "https://instagram.com/p/...",
      "published_at": "2026-06-18T19:30:00+03:00",
      "metrics": { "likes": 312, "comments": 18, "shares": 4, "views": 0, "impressions": 8200 }
    }
  ]
}

Hata Kodları

Kod	Anlamı
`401`	API key eksik veya geçersiz.
`403`	Kurum pasif.

Tarayıcıdan Kullanım (CORS)

Public API uçları tüm origin'lere açıktır (read-only). Sitenizin frontend'inden doğrudan fetch ile çağırabilirsiniz:

const res = await fetch("https://www.mosaic.net.tr/api/public/v1/overview", {
  headers: { "X-Api-Key": "msk_xxxxxxxx" }
});
const data = await res.json();
document.querySelector("#followers").textContent =
  data.summary.total_followers.toLocaleString("tr-TR");

Not: Frontend'de kullandığınızda key herkese görünür olur. Yalnızca salt-okunur veri döndüğü için bu çoğu durumda kabul edilebilir; daha sıkı kontrol isterseniz çağrıyı kendi sunucunuz üzerinden proxy'leyin.