{"openapi":"3.0.3","info":{"title":"Publicasta Publishing API","version":"2.0","description":"Explicit v2 contract. V1 remains supported, not deprecated. JSON writes: 20 translations and 2097152 bytes; article: 700 translations. Idempotency keys are scoped to authenticated user and channel; replay must have identical method, path and raw JSON bytes."},"servers":[{"url":"\/api\/v2"}],"security":[{"bearerAuth":[]},{"apiKey":[]}],"paths":{"\/channels":{"get":{"summary":"List channels","operationId":"getchannels","parameters":[],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}}}},"\/channels\/{channel}\/pages":{"get":{"summary":"List article summaries","operationId":"getchannelschannelpages","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"$ref":"#\/components\/schemas\/ArticleSummary"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}}},"post":{"summary":"Create a draft","operationId":"postchannelschannelpages","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"201":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateArticle"}}}}}},"\/channels\/{channel}\/pages\/{article}":{"get":{"summary":"Read article status and progress","operationId":"getchannelschannelpagesarticle","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}}}},"\/channels\/{channel}\/pages\/{article}\/translations":{"get":{"summary":"List translation metadata","operationId":"getchannelschannelpagesarticletranslations","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"type":"object","properties":{"translations":{"type":"array","items":{"$ref":"#\/components\/schemas\/TranslationSummary"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}}},"put":{"summary":"Save a draft batch","operationId":"putchannelschannelpagesarticletranslations","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TranslationBatch"}}}}}},"\/channels\/{channel}\/pages\/{article}\/translations\/{language}":{"get":{"summary":"Read one translation","operationId":"getchannelschannelpagesarticletranslationslanguage","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","schema":{"enum":["current","working"],"default":"current"}},{"name":"formats[]","in":"query","style":"form","explode":true,"schema":{"type":"array","maxItems":2,"items":{"enum":["html","markdown"]}}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"type":"object","properties":{"translation":{"allOf":[{"$ref":"#\/components\/schemas\/TranslationSummary"},{"type":"object","properties":{"view":{"enum":["current","working"]},"content_html":{"type":"string"},"content_markdown":{"type":"string"},"excerpt":{"type":"string","nullable":true},"seo_title":{"type":"string","nullable":true},"seo_description":{"type":"string","nullable":true}}}]}}}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}}},"put":{"summary":"Save one draft translation","operationId":"putchannelschannelpagesarticletranslationslanguage","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TranslationInput"}}}}}},"\/channels\/{channel}\/pages\/{article}\/status":{"patch":{"summary":"Submit the complete article for review","operationId":"patchchannelschannelpagesarticlestatus","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"202":{"description":"Accepted for asynchronous review; not yet published.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"200":{"description":"Already published with no new working revision.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PublishArticle"}}}}}},"\/channels\/{channel}\/pages\/{article}\/review":{"patch":{"summary":"Pause or resume bulk review","operationId":"patchchannelschannelpagesarticlereview","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ReviewControl"}}}}}},"\/channels\/{channel}\/pages\/{article}\/settings":{"patch":{"summary":"Update article settings","operationId":"patchchannelschannelpagesarticlesettings","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"article","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSummary"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ArticleSettings"}}}}}},"\/channels\/{channel}\/media":{"post":{"summary":"Upload page-bound article media","operationId":"postchannelschannelmedia","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"201":{"description":"Success","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required"},"403":{"description":"Permission or plan denied"},"404":{"description":"Not found"},"409":{"description":"Key conflict, language set mismatch, or active review"},"413":{"description":"Request exceeds 20 translations or 2097152 bytes"},"415":{"description":"JSON required"},"422":{"description":"Validation error"},"429":{"description":"Rate limited; honor Retry-After"}},"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"$ref":"#\/components\/schemas\/MediaInput"}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"TranslationInput":{"type":"object","required":["title"],"properties":{"language":{"type":"string","maxLength":16},"title":{"type":"string","maxLength":255},"excerpt":{"type":"string","maxLength":320},"content_html":{"type":"string"},"content_markdown":{"type":"string"},"seo_title":{"type":"string","maxLength":255},"seo_description":{"type":"string","maxLength":2000},"status":{"type":"string","enum":["draft"]}},"anyOf":[{"required":["content_html"]},{"required":["content_markdown"]}]},"TranslationBatch":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","minItems":1,"maxItems":20,"items":{"allOf":[{"$ref":"#\/components\/schemas\/TranslationInput"},{"required":["language"]}]}}}},"CreateArticle":{"allOf":[{"$ref":"#\/components\/schemas\/TranslationBatch"},{"type":"object","required":["slug","default_language"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9_-]{1,160}$"},"default_language":{"type":"string"},"status":{"type":"string","enum":["draft"]},"homepage_mode":{"enum":["inherit","allow","hide"]},"toc_enabled":{"type":"boolean"}}}]},"PublishArticle":{"type":"object","required":["status","expected_languages"],"properties":{"status":{"type":"string","enum":["published","scheduled"]},"expected_languages":{"type":"array","minItems":1,"maxItems":700,"uniqueItems":true,"items":{"type":"string"}},"scheduled_at":{"type":"string","format":"date-time"},"publish_translations":{"type":"boolean","enum":[true]}}},"ReviewControl":{"type":"object","required":["paused"],"properties":{"paused":{"type":"boolean"}}},"ArticleSettings":{"type":"object","properties":{"toc_enabled":{"type":"boolean"},"homepage_mode":{"enum":["inherit","allow","hide"]}},"anyOf":[{"required":["toc_enabled"]},{"required":["homepage_mode"]}]},"MediaInput":{"type":"object","required":["page_slug","image"],"properties":{"page_slug":{"type":"string"},"image":{"type":"string","format":"binary"},"alt":{"type":"string","maxLength":255},"watermark":{"enum":["auto","on","off"]},"purpose":{"enum":["article"]}}},"TranslationSummary":{"type":"object","required":["id","language","status","revision","pending_revision"],"properties":{"id":{"type":"integer"},"language":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"revision":{"type":"integer"},"content_sha256":{"type":"string","nullable":true},"payload_sha256":{"type":"string","nullable":true},"pending_revision":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"status":{"type":"string"},"revision":{"type":"integer"},"content_sha256":{"type":"string"},"payload_sha256":{"type":"string"}}}}},"ArticleSummary":{"type":"object","required":["id","slug","status","translation_status_summary","review","warnings"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"status":{"type":"string"},"default_language":{"type":"string"},"url":{"type":"string","format":"uri"},"edit_url":{"type":"string","format":"uri"},"pending_revision":{"type":"boolean"},"scheduled_at":{"type":"string","nullable":true,"format":"date-time"},"scheduled_paused":{"type":"boolean"},"scheduled_pause_reason":{"type":"string","nullable":true},"translation_status_summary":{"type":"object","properties":{"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}},"pending_revisions":{"type":"integer"}}},"review":{"type":"object","properties":{"operation_id":{"type":"string","nullable":true},"total":{"type":"integer"},"dispatched":{"type":"integer"},"paused":{"type":"boolean"},"completed":{"type":"boolean"},"manual_review_required":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}},"saved_translations":{"type":"array","items":{"$ref":"#\/components\/schemas\/TranslationSummary"}}}},"Pagination":{"type":"object","properties":{"per_page":{"type":"integer"},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}