{"openapi":"3.0.3","info":{"title":"Avatar Manager API","version":"1.1.0","description":"Unity avatar editörünün kaydetme/yükleme sözleşmesiyle uyumlu avatar servisi. Avatar verisi Unity'nin AvatarSaveData JSON'u ile birebir aynıdır; katalog Unity'deki AvatarItemDatabase'in tamamıdır (dosyalar, varyantlar, gövde maskeleri).\n\nÜç yol: (1) tarayıcı oturumu (çerez), (2) Supabase erişim belirteci: Authorization: Bearer <access_token>, (3) sunucudan sunucuya API anahtarı: X-Api-Key + X-External-User-Id (örneğin uygulamanın kullanıcı kimliği). API anahtarı ile gelen her dış kullanıcı için otomatik bir profil açılır. Stüdyo uçları yönetici rolü ister."},"servers":[{"url":"https://avatar.62.83.43.210.sslip.io"}],"tags":[{"name":"Avatars","description":"Kayıt, yükleme ve sürüm geçmişi"},{"name":"Catalog","description":"Kategoriler, parçalar, varyantlar, dosyalar ve maskeler"},{"name":"Studio","description":"Katalog düzenleme (yönetici)"},{"name":"Projects","description":"Hesabın projeleri: katalog seçimi, API anahtarları (oturum ya da Bearer)"},{"name":"Compatibility","description":"Mevcut updateAvatar sözleşmesi"},{"name":"System"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase access token"},"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Server-to-server key; send X-External-User-Id as well"},"externalUser":{"type":"apiKey","in":"header","name":"X-External-User-Id","description":"The caller's own user id (e.g. the app's user id)"}},"schemas":{"AvatarSaveData":{"type":"object","description":"Unity AvatarSaveData (Metaverse.Avatar). Slot types are the AvatarSlotType flag values.","required":["bodyType","equippedItems"],"properties":{"bodyType":{"type":"integer","enum":[0,1],"description":"0 = Female, 1 = Male"},"equippedItems":{"type":"array","items":{"type":"object","required":["slotType","itemId","materialId"],"properties":{"slotType":{"type":"integer","description":"1 EyeRight, 2 EyeLeft, 4 Head, 8 Glasses, 16 Headwear, 32 Hair, 64 Beard, 128 Facewear, 256 OutfitTop, 512 OutfitBottom, 1024 OutfitFootwear, 2048 Body, 4096 Eyebrow"},"itemId":{"type":"string","example":"female_hair_0"},"materialId":{"type":"string","example":"hairColor0"}}}}},"example":{"bodyType":0,"equippedItems":[{"slotType":32,"itemId":"female_hair_0","materialId":"hairColor0"},{"slotType":256,"itemId":"top_female_32","materialId":""}]}},"Avatar":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"name":{"type":"string"},"bodyType":{"type":"integer","enum":[0,1]},"data":{"$ref":"#/components/schemas/AvatarSaveData"},"avatar":{"type":"string","description":"data as the JSON string Unity's JsonUtility reads (same text the app stores for the user)"},"imgUrl":{"type":"string","nullable":true,"description":"Public URL of the uploaded preview photo"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SaveAvatarRequest":{"type":"object","required":["avatar"],"properties":{"avatar":{"description":"AvatarSaveData as a JSON string (exactly what Unity sends today) or as an object","oneOf":[{"type":"string"},{"$ref":"#/components/schemas/AvatarSaveData"}]},"avatarImage":{"type":"string","nullable":true,"description":"Preview photo as base64 PNG/JPEG, with or without the data:image/...;base64, prefix"},"name":{"type":"string","nullable":true,"maxLength":80}},"example":{"avatar":"{\"bodyType\":1,\"equippedItems\":[{\"slotType\":32,\"itemId\":\"male_hair_0\",\"materialId\":\"male_hairColor0\"}]}","avatarImage":"iVBORw0KGgo..."}},"Failure":{"type":"object","properties":{"success":{"type":"integer","enum":[0]},"message":{"type":"string"}}},"CatalogItem":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string","description":"Display name"},"description":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"slotType":{"type":"integer"},"slot":{"type":"string"},"bodyTypes":{"type":"array","items":{"type":"string","enum":["Female","Male"]}},"preview":{"type":"string","nullable":true,"description":"Absolute URL of the preview image"},"meshFile":{"type":"string","nullable":true,"description":"Path of the GLB inside the Unity project"},"glbUrl":{"type":"string","nullable":true,"description":"Absolute URL of the GLB (Wolf3D rig, one skinned mesh)"},"glbSize":{"type":"integer","nullable":true},"glbSha1":{"type":"string","nullable":true},"meshName":{"type":"string","nullable":true,"description":"Mesh to use inside the GLB (e.g. Wolf3D_Outfit_Top)"},"materialName":{"type":"string","nullable":true},"textureCount":{"type":"integer"},"skinned":{"type":"boolean"},"inApp":{"type":"boolean","description":"Listed in the app's AvatarDatabaseSmall"},"active":{"type":"boolean"},"hasBodyMask":{"type":"boolean"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}}},"CatalogItemDetail":{"allOf":[{"$ref":"#/components/schemas/CatalogItem"},{"type":"object","properties":{"bodyMask":{"type":"string","nullable":true,"description":"Clothing only: body vertices under the item as packed bits (numpy packbits, MSB first), base64"},"bodyMaskStats":{"type":"object","nullable":true,"properties":{"coveredVertices":{"type":"integer"},"hiddenFaces":{"type":"integer"},"pokeVertices":{"type":"integer"},"pokeMaxMm":{"type":"number"}}},"meshNames":{"type":"array","items":{"type":"string"}},"materials":{"type":"array","items":{"$ref":"#/components/schemas/CatalogMaterial"}},"categories":{"type":"array","items":{"type":"string"},"description":"Category paths the item is listed under"}}}]},"CatalogMaterial":{"type":"object","properties":{"materialId":{"type":"string"},"name":{"type":"string"},"bodyType":{"type":"integer","enum":[0,1]},"slotType":{"type":"integer"},"slot":{"type":"string"},"itemId":{"type":"string","nullable":true,"description":"Set when the variant only applies to one item"},"preview":{"type":"string","nullable":true},"color":{"type":"object","nullable":true,"properties":{"r":{"type":"number"},"g":{"type":"number"},"b":{"type":"number"},"a":{"type":"number"}}},"textureUrl":{"type":"string","nullable":true},"inApp":{"type":"boolean"}}},"CatalogCategory":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string","example":"Head/Eye"},"preview":{"type":"string","nullable":true},"camera":{"type":"object","nullable":true,"description":"Editor camera preset (mobile)"},"cameraXR":{"type":"object","nullable":true,"description":"Editor camera preset (XR)"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"materials":{"type":"array","items":{"$ref":"#/components/schemas/CatalogMaterial"}},"subCategories":{"type":"array","items":{"$ref":"#/components/schemas/CatalogCategory"}}}},"ItemPatch":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"slot":{"type":"string","description":"Slot name or flag value"},"categoryPath":{"type":"string","nullable":true,"example":"Outfit/Top"},"preview":{"type":"string","nullable":true},"glbPath":{"type":"string","nullable":true,"description":"URL returned by /studio/upload"},"glbSize":{"type":"integer","nullable":true},"glbSha1":{"type":"string","nullable":true},"meshName":{"type":"string","nullable":true},"materialName":{"type":"string","nullable":true},"textureCount":{"type":"integer","nullable":true},"bodyMask":{"type":"string","nullable":true},"inApp":{"type":"boolean"},"active":{"type":"boolean"}}}},"parameters":{"bodyType":{"name":"bodyType","in":"query","required":false,"schema":{"type":"string","enum":["female","male","0","1"]},"description":"Varsayılan female"},"db":{"name":"db","in":"query","required":false,"schema":{"type":"string","enum":["small","full"]},"description":"small = uygulamada yayında olanlar (varsayılan), full = tüm parçalar"},"project":{"name":"project","in":"query","required":false,"schema":{"type":"string"},"description":"Proje kısa adı (slug) ya da id: o projenin katalog görünümü (kapalı parçalar çıkarılır). Projeye bağlı X-Api-Key ile çağrılınca gerekmez."},"projectId":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Proje id ya da kısa adı"}}},"security":[{"bearerAuth":[]},{"apiKey":[],"externalUser":[]}],"paths":{"/api/v1/projects":{"get":{"tags":["Projects"],"summary":"Hesabın projeleri (yönetici: tüm projeler)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Projeler","content":{"application/json":{"example":{"success":1,"projects":[{"id":"…","name":"Lagomya","slug":"lagomya","stats":{"avatars":12,"keys":1,"excluded":40}}]}}}},"401":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"post":{"tags":["Projects"],"summary":"Yeni proje","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":60},"description":{"type":"string","nullable":true}}},"example":{"name":"VRSocial"}}}},"responses":{"201":{"description":"Oluşturuldu"},"401":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"422":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}":{"get":{"tags":["Projects"],"summary":"Proje ayrıntısı, istatistikler ve kapalı parçalar","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"responses":{"200":{"description":"Proje"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"patch":{"tags":["Projects"],"summary":"Ad / açıklama güncelle","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Güncellendi"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"delete":{"tags":["Projects"],"summary":"Projeyi sil","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"responses":{"200":{"description":"Silindi"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}/items":{"get":{"tags":["Projects"],"summary":"Projede kapalı parçalar (\"body|itemId\")","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"responses":{"200":{"description":"Kapalı parçalar","content":{"application/json":{"example":{"success":1,"excluded":["1|male_hair_2","0|female_glasses_7"]}}}}}},"put":{"tags":["Projects"],"summary":"Parçaları kapat / aç","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["itemId","bodyType","enabled"],"properties":{"itemId":{"type":"string"},"bodyType":{"type":"integer","enum":[0,1]},"enabled":{"type":"boolean"}}}}}},"example":{"items":[{"itemId":"male_hair_2","bodyType":1,"enabled":false}]}}}},"responses":{"200":{"description":"Kaydedildi; excluded = kapalı parça sayısı"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"422":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}/keys":{"get":{"tags":["Projects"],"summary":"Projenin API anahtarları (yalnızca ön ek)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"responses":{"200":{"description":"Anahtarlar"}}},"post":{"tags":["Projects"],"summary":"Yeni API anahtarı (düz metin yalnızca bu yanıtta)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Oluşturuldu","content":{"application/json":{"example":{"success":1,"key":"am_…","row":{"id":"…","name":"Unity arka uç"}}}}}}}},"/api/v1/projects/{projectId}/assets":{"get":{"tags":["Projects"],"summary":"Projenin kendi parçaları ve varyantları","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"responses":{"200":{"description":"items, materials"}}},"post":{"tags":["Projects"],"summary":"Yeni parça, çekirdek parçanın kopyası ya da projede onun yerine geçen kendi sürümü","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bodyType"],"properties":{"bodyType":{"type":"integer","enum":[0,1]},"name":{"type":"string"},"slot":{"type":"string"},"itemId":{"type":"string"},"categoryPath":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"fromItemId":{"type":"string","nullable":true,"description":"Kopyalanacak çekirdek parça"},"override":{"type":"boolean","description":"true: aynı itemId ile projede çekirdek sürümün yerine geçer"}}},"example":{"fromItemId":"male_hair_14","bodyType":1,"override":true}}}},"responses":{"201":{"description":"Oluşturuldu (item)"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"409":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"422":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}/assets/{itemId}":{"get":{"tags":["Projects"],"summary":"Projenin parçası (satır)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"responses":{"200":{"description":"Parça"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"patch":{"tags":["Projects"],"summary":"Projenin parçasını güncelle","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPatch"}}}},"responses":{"200":{"description":"Güncellendi"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"delete":{"tags":["Projects"],"summary":"Projenin parçasını sil (kendi sürümü silinince çekirdek sürüm döner)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"responses":{"200":{"description":"Silindi"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}/upload":{"post":{"tags":["Projects"],"summary":"GLB, doku ya da önizleme yükle (projenin parçaları için)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["kind","file"],"properties":{"kind":{"type":"string","enum":["glb","texture","preview"]},"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Yüklendi (url, size, sha1, glb özeti)"},"400":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}/materials/{materialId}":{"put":{"tags":["Projects"],"summary":"Projeye ait renk / doku varyantı oluştur veya güncelle","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"name":"materialId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slot"],"properties":{"slot":{"type":"string"},"name":{"type":"string"},"color":{"type":"object","nullable":true},"preview":{"type":"string","nullable":true},"texturePath":{"type":"string","nullable":true},"itemId":{"type":"string","nullable":true},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Kaydedildi"}}},"delete":{"tags":["Projects"],"summary":"Varyantı sil","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"name":"materialId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"responses":{"200":{"description":"Silindi"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/projects/{projectId}/keys/{keyId}":{"delete":{"tags":["Projects"],"summary":"Anahtarı iptal et","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"İptal edildi"},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/health":{"get":{"tags":["System"],"summary":"Sağlık kontrolü","security":[],"responses":{"200":{"description":"ok","content":{"application/json":{"example":{"ok":true,"version":"1.0.0"}}}}}}},"/api/v1/me":{"get":{"tags":["System"],"summary":"Çağıranın profil bilgisi","responses":{"200":{"description":"Profil","content":{"application/json":{"example":{"success":1,"profileId":"9a3e...","displayName":"murat","via":"bearer"}}}},"401":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/avatars/me":{"get":{"tags":["Avatars"],"summary":"Varsayılan avatarımı getir","responses":{"200":{"description":"Avatar (yoksa avatar null)","content":{"application/json":{"example":{"success":1,"avatar":{"id":"…","avatar":"{\"bodyType\":0,…}","imgUrl":"https://…/avatar-photos/…png"}}}}},"401":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"put":{"tags":["Avatars"],"summary":"Varsayılan avatarımı kaydet (oluştur/değiştir)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveAvatarRequest"}}}},"responses":{"200":{"description":"Kaydedildi","content":{"application/json":{"example":{"success":1,"message":"Avatar başarıyla kaydedildi.","imgUrl":"https://…png","avatar":{"id":"…"}}}}},"422":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/avatars/me/versions":{"get":{"tags":["Avatars"],"summary":"Kayıt geçmişi (en yeni önce)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Sürümler","content":{"application/json":{"example":{"success":1,"versions":[{"id":12,"avatar":"{…}","imgUrl":null,"source":"unity","createdAt":"2026-10-15T09:00:00Z"}]}}}}}}},"/api/v1/avatars/{profileId}":{"get":{"tags":["Avatars"],"summary":"Başka bir profilin avatarı (oda içinde diğer oyuncuları çizmek için)","security":[],"parameters":[{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Avatar","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"integer"},"avatar":{"$ref":"#/components/schemas/Avatar"}}}}}},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/updateAvatar":{"post":{"tags":["Compatibility"],"summary":"Mevcut updateAvatar ile aynı istek/yanıt (Unity bugün bunu gönderiyor)","description":"Gövde: {\"avatar\": \"<AvatarSaveData JSON string>\", \"avatarImage\": \"<base64 png>\"}. Yanıt: {success, message, imgUrl}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveAvatarRequest"}}}},"responses":{"200":{"description":"Uyumlu biçimde yanıt","content":{"application/json":{"example":{"success":1,"message":"Avatar başarıyla kaydedildi.","imgUrl":"https://…png"}}}},"401":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/catalog":{"get":{"tags":["Catalog"],"summary":"Kategori ağacı (parçalar, varyantlar, dosya adresleri, kamera ayarları)","security":[],"parameters":[{"$ref":"#/components/parameters/bodyType"},{"$ref":"#/components/parameters/db"},{"$ref":"#/components/parameters/project"},{"name":"masks","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"1 = her kıyafetin bodyMask alanı da gelir"}],"responses":{"200":{"description":"Katalog","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["database","bundled"]},"version":{"type":"integer"},"db":{"type":"string"},"bodyType":{"type":"integer"},"bodyTypeName":{"type":"string"},"slotTypes":{"type":"object","additionalProperties":{"type":"string"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CatalogCategory"}}}}}}}}}},"/api/v1/catalog/items":{"get":{"tags":["Catalog"],"summary":"Düz parça listesi","security":[],"parameters":[{"$ref":"#/components/parameters/bodyType"},{"$ref":"#/components/parameters/db"},{"$ref":"#/components/parameters/project"},{"name":"slot","in":"query","required":false,"schema":{"type":"string"},"description":"Örn. Hair, OutfitTop ya da sayısal 32"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Ad, itemId, etiket araması"},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Kategori yolu (alt kategoriler dahil)"},{"name":"inApp","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Parçalar ve varyantlar","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"materials":{"type":"array","items":{"$ref":"#/components/schemas/CatalogMaterial"}}}}}}}}}},"/api/v1/catalog/items/{itemId}":{"get":{"tags":["Catalog"],"summary":"Parça ayrıntısı: dosyalar, varyantlar, kategoriler, gövde maskesi","security":[],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"responses":{"200":{"description":"Parça","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"integer"},"item":{"$ref":"#/components/schemas/CatalogItemDetail"}}}}}},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/catalog/materials":{"get":{"tags":["Catalog"],"summary":"Renk / doku varyantları","security":[],"parameters":[{"$ref":"#/components/parameters/bodyType"},{"$ref":"#/components/parameters/db"},{"name":"slot","in":"query","schema":{"type":"string"}},{"name":"itemId","in":"query","schema":{"type":"string"},"description":"Parçaya özel olanlar + slot genelindekiler"}],"responses":{"200":{"description":"Varyantlar","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"materials":{"type":"array","items":{"$ref":"#/components/schemas/CatalogMaterial"}}}}}}}}}},"/api/v1/studio/items":{"post":{"tags":["Studio"],"summary":"Yeni parça oluştur","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["itemId","slot"],"properties":{"itemId":{"type":"string"},"bodyType":{"type":"string"},"name":{"type":"string"},"slot":{"type":"string"},"categoryPath":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"inApp":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Oluşturuldu"},"403":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"409":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/studio/items/{itemId}":{"patch":{"tags":["Studio"],"summary":"Parçayı güncelle","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPatch"}}}},"responses":{"200":{"description":"Güncellendi"},"403":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"404":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"delete":{"tags":["Studio"],"summary":"Parçayı katalogdan kaldır (active = false)","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"responses":{"200":{"description":"Kapatıldı"},"403":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/studio/upload":{"post":{"tags":["Studio"],"summary":"GLB, doku ya da önizleme yükle","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["kind","file"],"properties":{"kind":{"type":"string","enum":["glb","texture","preview"]},"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Yüklendi","content":{"application/json":{"example":{"success":1,"kind":"glb","url":"https://…/catalog-assets/glb/…glb","size":163840,"sha1":"…","glb":{"meshes":["Wolf3D_Outfit_Top"],"materials":["Wolf3D_Outfit_Top"],"images":3,"skinned":true}}}}},"400":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/studio/materials/{materialId}":{"put":{"tags":["Studio"],"summary":"Varyant oluştur / güncelle","parameters":[{"name":"materialId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/bodyType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slot"],"properties":{"slot":{"type":"string"},"name":{"type":"string"},"color":{"type":"object","nullable":true},"preview":{"type":"string","nullable":true},"texturePath":{"type":"string","nullable":true},"itemId":{"type":"string","nullable":true},"inApp":{"type":"boolean"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Kaydedildi"},"403":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/api/v1/studio/changes":{"get":{"tags":["Studio"],"summary":"Son değişiklikler","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":40,"maximum":200}}],"responses":{"200":{"description":"Değişiklikler"},"403":{"description":"Hata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}}}}