API başvurusu

Medya

Bu gruptaki 4 uç.

Medya kütüphanesini listeler

GET/api/v1/media

En yeni önce; q görünen adda arar. Yönetici yetkisi gerekir. Kapsam: organization:read.

Kapsam
organization:read
SDK metodu
listMedia · list_media
MCP aracı
listMediasalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
qsorgustringhayırGörünen adda arama
limitsorguintegerhayırSayfa boyutu (1–200, varsayılan 50); tam sayı değilse 400val 1–200, default 50
cursorsorgustringhayırÖnceki yanıttaki next_cursor (opak)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/media?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://example.com/hook",
      "path": "string",
      "name": "Hiboty",
      "mime": "string",
      "size": 1,
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Görsel yükler

POST/api/v1/media

En fazla 2 MB; JPG, PNG, WebP ya da GIF (tür dosyanın içeriğinden belirlenir, SVG kabul edilmez). Organizasyon başına en fazla 500 görsel (409 limit_reached); toplam boyut plan depolama kotasını aşamaz (413 storage_quota_exceeded; kullanım getUsage storage alanında); dakikada 30 yükleme (429). Yönetici yetkisi gerekir. Kapsam: organization:write.

Kapsam
organization:write
SDK metodu
uploadMedia · upload_media
MCP aracı
uploadMedia

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
Idempotency-Keybaşlıkstringhayırİsteğe bağlı, 1-255 görünür ASCII karakter. Aynı anahtar ve gövdeyle 24 saat içinde ilk yanıt aynen döner; farklı gövdede 409 idempotency_conflict.len 1–255

Gövde alanları

AdTürZorunluAçıklama
file_namestringevetlen ≤ 255
file_base64stringevetDosyanın base64 içeriği (data: öneki olmadan)

Örnek istek

curl -X POST "https://hiboty.com/api/v1/media" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"logo.png","file_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "path": "string",
    "name": "Hiboty",
    "mime": "string",
    "size": 1,
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.limit_reached
  • 413Plan depolama kotası dolu (storage_quota_exceeded); görsel silin ya da planı yükseltin.storage_quota_exceeded
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Görselin kullanıldığı yerleri getirir

GET/api/v1/media/{id}/usage

Kampanya, planlı gönderi, marka logosu, Mini App, otomasyon ve sohbet geçmişi taranır. Yönetici yetkisi gerekir. Kapsam: organization:read.

Kapsam
organization:read
SDK metodu
getMediaUsage · get_media_usage
MCP aracı
getMediaUsagesalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/media/3fa85f64-5717-4562-b3fc-2c963f66afa6/usage" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "in_use": true,
    "usages": [
      {
        "place": "campaign",
        "count": 1
      }
    ]
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Görseli siler

DELETE/api/v1/media/{id}

Kullanılan görsel silinmez (409 media_in_use). Dosya da kalıcı silinir. Yönetici yetkisi gerekir. Kapsam: organization:write.

Kapsam
organization:write
SDK metodu
deleteMedia · delete_media
MCP aracı
deleteMediageri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/media/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.media_in_use
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.