{"openapi":"3.1.0","info":{"title":"CometCOS Public Content API","version":"1.0.0","description":"A stable, versioned, **read-only** REST API for pulling your published CometCOS content into any website, static-site generator, app, or automation. Authoring stays inside CometCOS — this is a consumption layer only.\n\nCreate a read-only API key in **Settings → Integrations**, then send it as a Bearer token on every request. Each key is scoped to a single tenant and can only ever read that tenant's published content."},"servers":[{"url":"https://cos.uipirate.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Content","description":"Published posts."},{"name":"Discovery","description":"Metadata and debugging helpers."}],"paths":{"/api/cometCOS/v1/content":{"get":{"tags":["Content"],"summary":"List published posts","description":"Paginated list of published posts for the authenticated tenant. The heavy `content` field is excluded by default — request it explicitly with `fields=content` (or any explicit `fields` set).","operationId":"listContent","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Items per page."},{"name":"tag","in":"query","schema":{"type":"string"},"description":"Only posts carrying this tag."},{"name":"postType","in":"query","schema":{"type":"string"},"description":"Filter by content type, e.g. `blog`, `case-study`."},{"name":"updatedSince","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO-8601 timestamp. Return only posts updated after it — ideal for incremental static builds."},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated allow-list, e.g. `slug,title,excerpt`. `id` is always included. Add `content` to opt into the HTML body.","example":"slug,title,excerpt"},{"name":"sort","in":"query","schema":{"type":"string","enum":["publishedAt","-publishedAt","updatedAt","-updatedAt"],"default":"-publishedAt"},"description":"Sort order."}],"responses":{"200":{"description":"A page of published posts.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicPost"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded — see `Retry-After`.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cometCOS/v1/content/{slug}":{"get":{"tags":["Content"],"summary":"Get a published post by slug","description":"Returns a single published post. Supports `ETag` / `If-None-Match` for cheap `304 Not Modified` revalidation.","operationId":"getContentBySlug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"my-first-post"},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"A previously returned `ETag`. Yields `304` when unchanged."}],"responses":{"200":{"description":"The published post.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/PublicPost"}}}}}},"304":{"description":"Not modified — the `ETag` you sent still matches."},"401":{"description":"Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No published post matches this slug.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded — see `Retry-After`.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cometCOS/v1/content/id/{id}":{"get":{"tags":["Content"],"summary":"Get a published post by id","description":"Same as the slug endpoint but keyed by the stable MongoDB id — use it for permalinks that must survive a slug change.","operationId":"getContentById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"65a0000000000000000000001"},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The published post.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/PublicPost"}}}}}},"304":{"description":"Not modified."},"401":{"description":"Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No published post matches this id.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded — see `Retry-After`.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cometCOS/v1/tags":{"get":{"tags":["Discovery"],"summary":"List tags with counts","description":"Distinct tags across the tenant's published posts, most-used first.","operationId":"listTags","responses":{"200":{"description":"Tags and how many published posts carry each.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"product"},"count":{"type":"integer","example":12}},"required":["tag","count"]}}}}}}},"401":{"description":"Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded — see `Retry-After`.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cometCOS/v1/me":{"get":{"tags":["Discovery"],"summary":"Inspect the current key","description":"Echoes the authenticated key's tenant, name, scopes, and current rate-limit budget. Useful for debugging auth.","operationId":"getMe","responses":{"200":{"description":"Key and rate-limit info.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"tenantId":{"type":"string"},"keyName":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"example":["read"]},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer"},"reset":{"type":"integer"}}}}}}}}}},"401":{"description":"Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded — see `Retry-After`.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request budget per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"uip_<keyId>_<secret>","description":"A read-only API key from Settings → Integrations. Send as `Authorization: Bearer uip_<keyId>_<secret>`."}},"schemas":{"PublicPost":{"type":"object","description":"The only shape a post takes on a public response. Internal fields (tenant ids, author emails, AI workspace history, approval workflow, bot/duplicate view counts, distribution records) are never included.","properties":{"id":{"type":"string","example":"65a0000000000000000000001"},"slug":{"type":"string","example":"my-first-post"},"title":{"type":"string","example":"My First Post"},"excerpt":{"type":"string","example":"A short summary of the post."},"content":{"type":"string","description":"Rendered HTML body. Omitted from list responses unless `fields=content` is requested.\n\n**Diagrams:** each diagram is published in the form its author chose. By default (**image**) it arrives as `<figure><img src=\"…\" alt=\"Diagram\" /></figure>`, a hosted PNG that needs nothing on your side. If the author chose **Mermaid code** it arrives as `<pre data-out=\"code\" data-bg=\"…\" data-cfg=\"…\"><code class=\"language-mermaid\">…source…</code></pre>`. Render it client-side with [mermaid](https://mermaid.js.org): `mermaid.initialize({ startOnLoad: false }); mermaid.run({ querySelector: \"code.language-mermaid\" });` (replace the `<pre>` with the returned SVG if you want the diagram without the code). `data-cfg` is optional JSON with the editor's style choices (preset, colors, text size, width) and `data-bg` the background preset; you can ignore both. A diagram that has not been published with an image yet (older posts) also arrives in the code form. Without mermaid on your site the block degrades to a readable code block.","example":"<p>HTML body</p>"},"featuredImage":{"type":"string","format":"uri"},"bannerImage":{"type":"string","format":"uri"},"tags":{"type":"array","items":{"type":"string"},"example":["product","launch"]},"postType":{"type":"string","example":"blog"},"author":{"type":"object","properties":{"name":{"type":"string","example":"Jane"}},"required":["name"],"description":"Author display name only. Emails are never exposed."},"readTime":{"type":"integer","example":3},"views":{"type":"integer","description":"Unique human views only.","example":128},"client":{"type":"string","description":"Case-study only (`postType: case-study`)."},"clientLogo":{"type":"string","format":"uri"},"region":{"type":"string"},"technologies":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}},"externalUrl":{"type":"string","format":"uri"},"seo":{"type":"object","properties":{"metaTitle":{"type":"string"},"metaDescription":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"ogTitle":{"type":"string"},"ogDescription":{"type":"string"},"ogImage":{"type":"string","format":"uri"},"canonicalUrl":{"type":"string","format":"uri"},"noIndex":{"type":"boolean"}}},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","slug","title","content","tags","postType","author","updatedAt"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":10},"total":{"type":"integer","example":42},"pages":{"type":"integer","example":5}},"required":["page","limit","total","pages"]},"Error":{"type":"object","description":"Machine-readable error envelope. Branch on `error.code`, never on the message.","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","not_found","rate_limited","internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}}