{"openapi":"3.1.0","info":{"title":"Capsules API","version":"2.0.0","description":"REST namespace. Additive; v1 (/api/*) is frozen."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"Authentication required"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}},"required":["error"]},"Publication":{"type":"object","properties":{"storyId":{"type":"string"},"isPublished":{"type":"boolean"},"slug":{"type":"string","nullable":true},"url":{"type":"string","nullable":true,"description":"Public path, e.g. /owner/slug. Null while unpublished."},"publicationMode":{"type":"string"},"unlisted":{"type":"boolean"},"publishedAt":{"type":"string","nullable":true}},"required":["storyId","isPublished","slug","url","publicationMode","unlisted","publishedAt"]},"PublishResult":{"type":"object","properties":{"url":{"type":"string","description":"Public path. Editions shown to readers include ?edition=<slug>."},"slug":{"type":"string"},"isRepublish":{"type":"boolean"},"publicationMode":{"type":"string"},"publishedStoryId":{"type":"string","description":"Set when an edition was published through its capsule (the default edition)."},"edition":{"type":"string","nullable":true}},"required":["url","slug","isRepublish","publicationMode"]},"PublishRequest":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":80,"description":"Public URL slug. Omit to keep the current one."},"publicationMode":{"type":"string","enum":["STANDARD","WHITE_LABEL"]},"unlisted":{"type":"boolean"},"showSocialShare":{"type":"boolean"},"premiereEmailMode":{"type":"string","enum":["FULL","TEASER","OFF"],"description":"First publish only: whether subscribers get the premiere email."}}},"ConnectedApp":{"type":"object","properties":{"id":{"type":"string"},"clientName":{"type":"string","example":"Claude"},"clientUri":{"type":"string","nullable":true},"logoUri":{"type":"string","nullable":true},"workspaceId":{"type":"string","description":"The connection's default workspace"},"workspaceName":{"type":"string"},"workspaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"description":"Every workspace the connection reaches, including the default"},"scopes":{"type":"array","items":{"type":"string"},"example":["capsules:read","capsules:write"]},"createdAt":{"type":"string"},"lastUsedAt":{"type":"string","nullable":true}},"required":["id","clientName","clientUri","logoUri","workspaceId","workspaceName","workspaces","scopes","createdAt","lastUsedAt"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Liveness check (public)","responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}}}}}},"/me":{"get":{"tags":["meta"],"summary":"The authenticated caller","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The authenticated user (from the JWT)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"workspaceId":{"type":"string","nullable":true}},"required":["id","email","name","workspaceId"]}}}},"401":{"description":"No valid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feed":{"get":{"tags":["feed"],"summary":"Public infinite-scroll feed of listed published capsules","description":"Ranked by pin tier (headline > featured) then lifetime views. Card video prefers the short social-preview clip, then the bake hero. Cursor encodes progress through the ranked candidate stream; deep pages may drift slightly as view counts move.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Feed page","headers":{"Cache-Control":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true},"path":{"type":"string","nullable":true},"publishedAt":{"type":"string","nullable":true},"excerpt":{"type":"string","nullable":true},"sceneCount":{"type":"integer","minimum":0},"views":{"type":"integer","minimum":0},"pinTier":{"type":"string","nullable":true,"enum":["headline","featured"]},"coverImageUrl":{"type":"string","nullable":true},"posterVideoUrl":{"type":"string","nullable":true},"author":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"username":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}},"required":["name","username","avatarUrl"]}},"required":["id","title","slug","path","publishedAt","excerpt","sceneCount","views","pinTier","coverImageUrl","posterVideoUrl","author"]}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]}}}},"500":{"description":"Feed query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stories/{id}/publication":{"get":{"tags":["publication"],"summary":"A capsule's publication state","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"d9dda234-b1a7-44aa-b6ac-2fce3adcb8a2"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Publication state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["publication"],"summary":"Publish or republish a capsule","description":"Bakes and publishes the capsule (synchronously). Publishing an edition that is shown to readers publishes its capsule — the default edition — at the shared URL, with that edition switchable.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"d9dda234-b1a7-44aa-b6ac-2fce3adcb8a2"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}}},"responses":{"200":{"description":"Published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishResult"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["publication"],"summary":"Unpublish a capsule","description":"The public URL stops resolving. With releaseSlug=true the slug is freed for another capsule.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"d9dda234-b1a7-44aa-b6ac-2fce3adcb8a2"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"releaseSlug","in":"query"}],"responses":{"200":{"description":"Unpublished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connected-apps":{"get":{"tags":["connected-apps"],"summary":"AI apps (MCP clients) connected to your account","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Live connections, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedApp"}}},"required":["items"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connected-apps/{id}":{"delete":{"tags":["connected-apps"],"summary":"Disconnect an app","description":"Revokes the connection immediately: its access and refresh tokens stop working.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]}},"required":["revoked"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}