{"openapi":"3.1.0","info":{"title":"developers.contentstack.com Public JSON API","version":"1.0.0","description":"Public read-only API for querying content, persons, taxonomies, and detailed markdown content."},"servers":[{"url":"https://developers.contentstack.com"}],"paths":{"/api/content":{"get":{"summary":"Search content across all content types","tags":["Content"],"parameters":[{"name":"types","in":"query","required":false,"description":"Comma-separated content types. Allowed: blogpost,guide,livestream,kickstart,page,person","schema":{"type":"string"},"example":"blogpost,guide"},{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/blogposts":{"get":{"summary":"List and search blog posts","tags":["Blogposts"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/blogposts/{slug}":{"get":{"summary":"Get blog post detail","tags":["Blogposts"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Blog post slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MarkdownDetail"}},"required":["data"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/guides":{"get":{"summary":"List and search guides","tags":["Guides"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/guides/{slug_path}":{"get":{"summary":"Get guide detail","tags":["Guides"],"parameters":[{"name":"slug_path","in":"path","required":true,"description":"Guide path after /guides/, slash-separated for chapters","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MarkdownDetail"}},"required":["data"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/livestreams":{"get":{"summary":"List and search live streams","tags":["Livestreams"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/livestreams/{slug_path}":{"get":{"summary":"Get live stream detail","tags":["Livestreams"],"parameters":[{"name":"slug_path","in":"path","required":true,"description":"Live stream path after /livestreams/","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MarkdownDetail"}},"required":["data"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/kickstarts":{"get":{"summary":"List and search kickstarts","tags":["Kickstarts"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/kickstarts/{slug_path}":{"get":{"summary":"Get kickstart detail","tags":["Kickstarts"],"parameters":[{"name":"slug_path","in":"path","required":true,"description":"Kickstart path after /kickstarts/","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MarkdownDetail"}},"required":["data"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/pages":{"get":{"summary":"List and search pages","tags":["Pages"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/pages/{slug_path}":{"get":{"summary":"Get page detail","tags":["Pages"],"parameters":[{"name":"slug_path","in":"path","required":true,"description":"Page path without leading slash","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PageDetail"}},"required":["data"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/persons":{"get":{"summary":"List and search persons","tags":["Persons"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query","schema":{"type":"string"},"example":"headless cms"},{"name":"subjects","in":"query","required":false,"description":"Comma-separated subject taxonomy term UIDs","schema":{"type":"string"},"example":"headless_cms,ai"},{"name":"technology","in":"query","required":false,"description":"Comma-separated technology taxonomy term UIDs","schema":{"type":"string"},"example":"nextjs,react"},{"name":"authors","in":"query","required":false,"description":"Comma-separated person UIDs","schema":{"type":"string"},"example":"blt1234,blt5678"},{"name":"limit","in":"query","required":false,"description":"Result size (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicContentListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/persons/{name}":{"get":{"summary":"Get person detail and authored content","tags":["Persons"],"parameters":[{"name":"name","in":"path","required":true,"description":"Person path segment from /person/{name}","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PersonDetail"}},"required":["data"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/openapi.json":{"get":{"summary":"Get OpenAPI specification","tags":["Meta"],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"ApiImage":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}},"required":["url","alt"]},"ApiAuthor":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"}},"required":["uid","name"]},"ApiTaxonomies":{"type":"object","properties":{"subjects":{"type":"array","items":{"type":"string"}},"technology":{"type":"array","items":{"type":"string"}}},"required":["subjects","technology"]},"PublicContentSummary":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string","enum":["blogpost","guide","livestream","kickstart","page","person"]},"title":{"type":"string"},"path":{"type":"string"},"url":{"type":"string"},"markdown_url":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"image":{"anyOf":[{"$ref":"#/components/schemas/ApiImage"},{"type":"null"}]},"taxonomies":{"$ref":"#/components/schemas/ApiTaxonomies"},"authors":{"type":"array","items":{"$ref":"#/components/schemas/ApiAuthor"}},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","type","title","path","url","markdown_url","description","image","taxonomies","authors","created_at","updated_at"]},"PublicContentFacets":{"type":"object","properties":{"content_types":{"type":"object","properties":{"blogpost":{"type":"integer"},"guide":{"type":"integer"},"livestream":{"type":"integer"},"kickstart":{"type":"integer"},"page":{"type":"integer"},"person":{"type":"integer"}},"required":["blogpost","guide","livestream","kickstart","page","person"]},"subjects":{"type":"array","items":{"type":"object","properties":{"term_uid":{"type":"string"},"count":{"type":"integer"}},"required":["term_uid","count"]}},"technology":{"type":"array","items":{"type":"object","properties":{"term_uid":{"type":"string"},"count":{"type":"integer"}},"required":["term_uid","count"]}},"authors":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"title":{"type":"string"},"count":{"type":"integer"}},"required":["uid","title","count"]}}},"required":["content_types","subjects","technology","authors"]},"PublicContentListMeta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"},"facets":{"$ref":"#/components/schemas/PublicContentFacets"}},"required":["total","limit","offset","has_more","facets"]},"PublicContentListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicContentSummary"}},"meta":{"$ref":"#/components/schemas/PublicContentListMeta"}},"required":["data","meta"]},"ContentDetailBase":{"allOf":[{"$ref":"#/components/schemas/PublicContentSummary"},{"type":"object","properties":{"canonical_url":{"type":"string","nullable":true}},"required":["canonical_url"]}]},"MarkdownDetail":{"allOf":[{"$ref":"#/components/schemas/ContentDetailBase"},{"type":"object","properties":{"markdown":{"type":"string"}},"required":["markdown"]}]},"PageDetail":{"allOf":[{"$ref":"#/components/schemas/ContentDetailBase"},{"type":"object","properties":{"components":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["components"]}]},"PersonContentGroup":{"type":"object","properties":{"blogs":{"type":"array","items":{"$ref":"#/components/schemas/PublicContentSummary"}},"guides":{"type":"array","items":{"$ref":"#/components/schemas/PublicContentSummary"}},"livestreams":{"type":"array","items":{"$ref":"#/components/schemas/PublicContentSummary"}},"kickstarts":{"type":"array","items":{"$ref":"#/components/schemas/PublicContentSummary"}},"pages":{"type":"array","items":{"$ref":"#/components/schemas/PublicContentSummary"}}},"required":["blogs","guides","livestreams","kickstarts","pages"]},"PersonDetail":{"allOf":[{"$ref":"#/components/schemas/ContentDetailBase"},{"type":"object","properties":{"job":{"type":"string","nullable":true},"bio_markdown":{"type":"string","nullable":true},"content":{"$ref":"#/components/schemas/PersonContentGroup"}},"required":["job","bio_markdown","content"]}]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}