{"openapi":"3.1.0","info":{"title":"Opinly SDK API","version":"1.0.0","description":"Headless content API for the Opinly SDK."},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"PostList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"has_more":{"type":"boolean","example":true},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor; pass as ?cursor= for the next page. null when no more.","example":"MTcwMDAwMDAwMDAwMDoxMjM"}},"required":["data","has_more","next_cursor"]},"Post":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"firstPublishedAt":{"type":"string","example":"2026-01-01T00:00:00.000Z"},"lastPublishedAt":{"type":"string","example":"2026-01-01T00:00:00.000Z"},"image":{"$ref":"#/components/schemas/Image"},"category":{"$ref":"#/components/schemas/PostCategory"},"author":{"$ref":"#/components/schemas/PostAuthor"}},"required":["slug","title","description","firstPublishedAt","lastPublishedAt","image","category","author"]},"Image":{"type":"object","nullable":true,"properties":{"fileKey":{"type":"string","nullable":true},"alt":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"caption":{"type":"string","nullable":true}},"required":["fileKey","alt","title","caption"]},"PostCategory":{"type":"object","nullable":true,"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["slug","name","description"]},"PostAuthor":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"},"fileKey":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true}},"required":["name","slug","fileKey","bio"]},"Problem":{"type":"object","properties":{"type":{"type":"string","example":"https://opinly.ai/docs/reference/errors/not-found"},"title":{"type":"string","example":"Not found"},"status":{"type":"number","example":404},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string","example":"NOT_FOUND"},"request_id":{"type":"string"}},"required":["type","title","status","code"]},"ContentRoutes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["home","post","category","author"],"example":"post"},"slug":{"type":"string","description":"Bare slug — no taxonomy prefix, no nesting. Empty for `home`.","example":"my-post"},"lastModified":{"type":"string","example":"2026-01-01T00:00:00.000Z"}},"required":["type","slug","lastModified"]}},"Categories":{"type":"array","items":{"$ref":"#/components/schemas/CategorySummary"}},"CategorySummary":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}},"required":["slug","title","description","imageUrl","posts"]},"Authors":{"type":"object","properties":{"type":{"type":"string","enum":["authors"]},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"image":{"$ref":"#/components/schemas/Image"},"bio":{"type":"string","nullable":true},"slug":{"type":"string"},"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}},"required":["name","image","bio","slug","posts"]}}},"required":["type","data"]},"AuthorPage":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["not-found"]},"data":{"nullable":true}},"required":["type","data"]},{"type":"object","properties":{"type":{"type":"string","enum":["author"]},"data":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"image":{"$ref":"#/components/schemas/Image"},"bio":{"type":"string","nullable":true},"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}},"required":["name","slug","image","bio","posts"]}},"required":["type","data"]}]},"FullPost":{"type":"object","properties":{"content":{"$ref":"#/components/schemas/ContentNode"},"title":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"metaDescription":{"type":"string","nullable":true},"metaTitle":{"type":"string","nullable":true},"titleFile":{"type":"object","nullable":true,"properties":{"fileKey":{"type":"string","nullable":true},"altText":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"caption":{"type":"string","nullable":true}},"required":["fileKey","altText","title","caption"]},"firstPublishedAt":{"type":"string"},"modifiedAt":{"type":"string"},"images":{"type":"array","items":{"type":"object","properties":{"fileKey":{"type":"string","nullable":true},"altText":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"caption":{"type":"string","nullable":true}},"required":["fileKey","altText","title","caption"]}},"author":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"fileKey":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"slug":{"type":"string"}},"required":["name","fileKey","bio","slug"]},"faqs":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]}},"category":{"$ref":"#/components/schemas/PostCategory"}},"required":["content","title","slug","description","metaDescription","metaTitle","titleFile","firstPublishedAt","modifiedAt","images","author","faqs","category"]},"ContentNode":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{"nullable":true}},"marks":{"type":"array","items":{"$ref":"#/components/schemas/ContentMark"}},"text":{"type":"string"},"content":{"type":"array","items":{"$ref":"#/components/schemas/ContentNode"}}}},"ContentMark":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type"]},"Rss":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"date":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}},"required":["slug","title","date"]}}},"parameters":{}},"paths":{"/v1/content/posts":{"get":{"tags":["Content"],"summary":"List published posts (cursor-paginated, filterable)","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":12,"example":12,"description":"Page size (1–100)."},"required":false,"description":"Page size (1–100).","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from a previous response's next_cursor."},"required":false,"description":"Opaque cursor from a previous response's next_cursor.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"Filter by category slug.","example":"nutrition"},"required":false,"description":"Filter by category slug.","name":"category","in":"query"},{"schema":{"type":"string","description":"Filter by author slug.","example":"jane-doe"},"required":false,"description":"Filter by author slug.","name":"author","in":"query"},{"schema":{"type":"string","enum":["newest","oldest"],"default":"newest","description":"Sort by first-published date."},"required":false,"description":"Sort by first-published date.","name":"sort","in":"query"}],"responses":{"200":{"description":"A cursor-paginated page of published posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostList"}}}},"400":{"description":"Invalid query parameters (e.g. bad limit, sort, or cursor)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/content/routes":{"get":{"tags":["Content"],"summary":"All addressable content routes (sitemap + static generation)","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Typed routes (home, posts, categories, authors) with bare slugs + lastModified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRoutes"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/content/categories":{"get":{"tags":["Content"],"summary":"Categories with sample posts","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Categories, each with up to 5 latest posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Categories"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/content/authors":{"get":{"tags":["Content"],"summary":"All authors with sample posts","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"All authors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Authors"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/content/authors/{slug}":{"get":{"tags":["Content"],"summary":"A single author page","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Author page, or not-found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorPage"}}}},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/content/post":{"get":{"tags":["Content"],"summary":"A single post by slug","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The post's company-unique slug (flat, no category path).","example":"my-post"},"required":true,"description":"The post's company-unique slug (flat, no category path).","name":"slug","in":"query"}],"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullPost"}}}},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No post found at that slug","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/content/rss":{"get":{"tags":["Content"],"summary":"RSS feed items","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"RSS feed items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rss"}}}},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}