{ "openapi": "3.1.1", "info": { "title": "Postlip Metrics Content API", "version": "1.0.0", "description": "Sitelerin ve uygulamaların blogu kendi tasarımıyla çizmek için okuduğu API: yalnız YAYINDAKİ yazılar (taslak, onaydaki sürüm ya da yayından kaldırılmış yazı hiç dönmez; çalışma sürümü yalnız editörlerin verdiği önizleme belirteciyle). Kimlik: organizasyonun panelden oluşturduğu API anahtarı, kapsam `content:read` (yalnız bu kapsamlı anahtar uygulamanın «içerik anahtarı»dır), `Authorization: Bearer mk_…` — yalnız sunucu tarafında. Önbellek: `ETag` / `Last-Modified`, `If-None-Match` / `If-Modified-Since` ile 304; değişiklikler imzalı yayın webhook'uyla (`content.post.published|updated|unpublished`, `Metrics-Signature`) duyurulur, site önbelleğini uzun tutup webhook'ta yeniler. İçerik HTML değil blok belgesidir; `html` alanı Postlip Metrics'in kaçışlayarak çizdiği güvenli HTML'dir. Hata gövdesi `{ \"error\": { \"code\", \"message\", \"traceId\" } }`, `message` isteğin dilinde (`Accept-Language`: tr, en)." }, "servers": [ { "url": "https://api.metrics.example", "description": "Content API" } ], "tags": [ { "name": "İçerik (blog)", "description": "Yazılar (blok içerik, SEO, kapak, kategori, etiket, yazarlar), iş akışı (onaya gönderme, onay, dört göz, zamanlama, yayın, yayından kaldırma, arşiv), sürümler ve farkları, zaman çizelgesi, yorumlar, süreli önizleme bağlantıları, yasaklı ifadeler, ayarlar; siteler için İçerik API’si (yalnız yayındaki yazılar) ve yayın webhook’ları." } ], "paths": { "/v1/content/apps/{appId}/assets/{assetId}": { "get": { "tags": [ "İçerik (blog)" ], "summary": "Görselin dosyası", "description": "Yayındaki bir yazının (ya da yazarının) gösterdiği görselin baytları — görselleri kendi sunucusunda tutan siteler için; kütüphanenin geri kalanı bu anahtarla okunamaz. Sürüm: `original` (metadata temizlenmiş), `jpg`, `medium` (1080 px WebP), `thumb` (320 px WebP).\n\nManagement API anahtarı gerekir (`Authorization: Bearer mk_…`); işlem anahtarın organizasyonunda ve uygulama kapsamında tek bir RLS işleminde çalışır.\n\nGerekli kapsam: `content:read`.", "operationId": "contentApi.asset", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "Uygulamanın kimliği.", "schema": { "type": "string", "format": "uuid" } }, { "name": "assetId", "in": "path", "required": true, "description": "Dosyanın kimliği.", "schema": { "type": "string", "format": "uuid" } }, { "name": "variant", "in": "query", "required": false, "schema": { "default": "original", "type": "string", "enum": [ "original", "jpg", "medium", "thumb" ] } } ], "responses": { "200": { "description": "Görsel dosyası.", "headers": { "Content-Disposition": { "description": "attachment; filename=\"…\"", "schema": { "type": "string" } } }, "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-access": "api_key", "x-scopes": [ "content:read" ] } }, "/v1/content/apps/{appId}/authors": { "get": { "tags": [ "İçerik (blog)" ], "summary": "Yazarlar", "description": "Etkin ya da yayında yazısı olan yazarlar, profilleriyle. Önbellek: `ETag` (gövdenin özeti) ve `Last-Modified` (uygulamanın sunulan içeriğinin son değişikliği; imzalı görsel bağlantıları saatte bir yenilendiği için en eski bu saatin başı); `If-None-Match` ya da `If-Modified-Since` eşleşirse 304, gövdesiz. `Cache-Control: private, max-age=60`, `Vary: Authorization`.\n\nManagement API anahtarı gerekir (`Authorization: Bearer mk_…`); işlem anahtarın organizasyonunda ve uygulama kapsamında tek bir RLS işleminde çalışır.\n\nGerekli kapsam: `content:read`.", "operationId": "contentApi.authors", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "Uygulamanın kimliği.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Başarılı.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentApiAuthorList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-access": "api_key", "x-scopes": [ "content:read" ] } }, "/v1/content/apps/{appId}/categories": { "get": { "tags": [ "İçerik (blog)" ], "summary": "Kategoriler", "description": "Yayındaki yazı sayılarıyla. Önbellek: `ETag` (gövdenin özeti) ve `Last-Modified` (uygulamanın sunulan içeriğinin son değişikliği; imzalı görsel bağlantıları saatte bir yenilendiği için en eski bu saatin başı); `If-None-Match` ya da `If-Modified-Since` eşleşirse 304, gövdesiz. `Cache-Control: private, max-age=60`, `Vary: Authorization`.\n\nManagement API anahtarı gerekir (`Authorization: Bearer mk_…`); işlem anahtarın organizasyonunda ve uygulama kapsamında tek bir RLS işleminde çalışır.\n\nGerekli kapsam: `content:read`.", "operationId": "contentApi.categories", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "Uygulamanın kimliği.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Başarılı.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentApiCategoryList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-access": "api_key", "x-scopes": [ "content:read" ] } }, "/v1/content/apps/{appId}/posts": { "get": { "tags": [ "İçerik (blog)" ], "summary": "Yayındaki yazılar", "description": "Yalnız YAYINDAKİ yazılar: taslak, onaydaki sürüm ya da yayından kaldırılmış yazı bu uçlardan hiç dönmez (yalnız önizleme belirteciyle). Filtreler: dil, kategori (adres), etiket, yazar (adres), yayın yeri (`web` site, `app` uygulama içi akış), arama, `updatedSince` (artımlı eşitleme); sıralama ilk yayın ya da son güncelleme; imleç sayfalama (en çok 100). Önbellek: `ETag` (gövdenin özeti) ve `Last-Modified` (uygulamanın sunulan içeriğinin son değişikliği; imzalı görsel bağlantıları saatte bir yenilendiği için en eski bu saatin başı); `If-None-Match` ya da `If-Modified-Since` eşleşirse 304, gövdesiz. `Cache-Control: private, max-age=60`, `Vary: Authorization`.\n\nManagement API anahtarı gerekir (`Authorization: Bearer mk_…`); işlem anahtarın organizasyonunda ve uygulama kapsamında tek bir RLS işleminde çalışır.\n\nGerekli kapsam: `content:read`.", "operationId": "contentApi.posts", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "Uygulamanın kimliği.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,512}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 5, "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "author", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "feed", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "web", "app" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "sort", "in": "query", "required": false, "schema": { "default": "published", "type": "string", "enum": [ "published", "updated" ] } } ], "responses": { "200": { "description": "Başarılı.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentApiPostPage" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-access": "api_key", "x-scopes": [ "content:read" ] } }, "/v1/content/apps/{appId}/posts/{slug}": { "get": { "tags": [ "İçerik (blog)" ], "summary": "Yazı (adresiyle)", "description": "Yazının belgesi: blok içerik, Postlip Metrics'in kaçışlayarak çizdiği HTML (sabit etiket seti; betik, stil, satır içi HTML yok), düz metin, içindekiler, okuma süresi, yazarlar ve profilleri, SEO (başlık, açıklama, kanonik adres, noindex, OG görseli), schema.org JSON-LD (`structuredData` ve `