{"openapi":"3.1.0","info":{"title":"Publicasta Public Content API","version":"1.0","description":"Read-only discovery and full-text access for published Publicasta content. No API key is required. Use opaque cursors, conditional requests, and Retry-After when rate limited."},"externalDocs":{"description":"Reading Publicasta with AI agents","url":"https://publicasta.com/api-docs#reading-publicasta"},"security":[],"servers":[{"url":"https://publicasta.com/api/public/v1"}],"paths":{"/channels":{"get":{"summary":"List public channels","operationId":"listPublicChannels","parameters":[{"name":"lang","in":"query","required":false,"description":"Exact published BCP 47 language code. Missing translations return 404.","schema":{"type":"string","maxLength":16}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Public channel collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelCollection"}}}},"422":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/{channel_slug}":{"get":{"summary":"Get a public channel","operationId":"getPublicChannel","parameters":[{"$ref":"#/components/parameters/ChannelSlug"},{"name":"lang","in":"query","required":false,"description":"Exact published BCP 47 language code. Missing translations return 404.","schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"Public channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/{channel_slug}/articles":{"get":{"summary":"List published articles in a channel","operationId":"listPublicArticles","parameters":[{"$ref":"#/components/parameters/ChannelSlug"},{"name":"lang","in":"query","required":false,"description":"Exact published BCP 47 language code. Missing translations return 404.","schema":{"type":"string","maxLength":16}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Published article collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleCollection"}}}},"404":{"description":"Channel not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/{channel_slug}/articles/{article_slug}":{"get":{"summary":"Get a published article as JSON with full Markdown","operationId":"getPublicArticle","parameters":[{"$ref":"#/components/parameters/ChannelSlug"},{"$ref":"#/components/parameters/ArticleSlug"},{"name":"lang","in":"query","required":false,"description":"Exact published BCP 47 language code. Missing translations return 404.","schema":{"type":"string","maxLength":16}},{"name":"include","in":"query","required":false,"description":"Set to html to include canonical rendered content_html.","schema":{"type":"string","enum":["html"]}}],"responses":{"200":{"description":"Published article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"304":{"description":"Not modified."},"404":{"description":"Article or translation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/{channel_slug}/articles/{article_slug}.md":{"get":{"summary":"Get a full standalone Markdown document","operationId":"getPublicArticleMarkdown","parameters":[{"$ref":"#/components/parameters/ChannelSlug"},{"$ref":"#/components/parameters/ArticleSlug"},{"name":"lang","in":"query","required":false,"description":"Exact published BCP 47 language code. Missing translations return 404.","schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"Standalone Markdown with YAML front matter.","content":{"text/markdown":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Article or translation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"summary":"Search published article translations","operationId":"searchPublicArticles","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":160}},{"name":"language","in":"query","required":false,"schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"422":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Search unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"parameters":{"ChannelSlug":{"name":"channel_slug","in":"path","required":true,"schema":{"type":"string"}},"ArticleSlug":{"name":"article_slug","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"Links":{"type":"object","additionalProperties":{"type":["string","null"],"format":"uri"}},"TranslationLink":{"type":"object","required":["language","html_url","markdown_url","json_url"],"properties":{"language":{"type":"string"},"title":{"type":"string"},"html_url":{"type":"string","format":"uri"},"markdown_url":{"type":"string","format":"uri"},"json_url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"}}},"ArticleSummary":{"type":"object","required":["id","slug","title","language","html_url","markdown_url","json_url"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":["string","null"]},"language":{"type":"string"},"default_language":{"type":"string"},"html_url":{"type":"string","format":"uri"},"markdown_url":{"type":"string","format":"uri"},"json_url":{"type":"string","format":"uri"}}},"Article":{"type":"object","required":["schema_version","id","slug","title","language","default_language","canonical_url","publisher","content_markdown","available_translations","_links"],"properties":{"schema_version":{"type":"string"},"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":["string","null"]},"language":{"type":"string"},"default_language":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"image":{"type":["object","null"],"properties":{"url":{"type":"string","format":"uri"},"alt":{"type":"string"}}},"publisher":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"}}},"author":{"type":"object","properties":{"name":{"type":"string"}}},"published_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"content_markdown":{"type":"string"},"content_html":{"type":"string"},"available_translations":{"type":"array","items":{"$ref":"#/components/schemas/TranslationLink"}},"_links":{"$ref":"#/components/schemas/Links"}}},"Channel":{"type":"object","required":["schema_version","id","slug","title","default_language","_links"],"properties":{"schema_version":{"type":"string"},"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"language":{"type":"string"},"default_language":{"type":"string"},"available_languages":{"type":"array","items":{"type":"string"}},"canonical_url":{"type":"string","format":"uri"},"_links":{"$ref":"#/components/schemas/Links"}}},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}},"ChannelCollection":{"type":"object","properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"_links":{"$ref":"#/components/schemas/Links"}}},"ArticleCollection":{"type":"object","properties":{"articles":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"_links":{"$ref":"#/components/schemas/Links"}}},"SearchResults":{"type":"object","properties":{"query":{"type":"string"},"returned_count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"_links":{"$ref":"#/components/schemas/Links"}}},"Error":{"type":"object","required":["schema_version","error"],"properties":{"schema_version":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}}}}}