{"openapi":"3.1.0","info":{"title":"Planable Public API","version":"1.0.0","description":"REST API for managing Planable companies, workspaces, pages, posts and more."},"servers":[{"url":"https://api.planable.io/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pln_*"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","RATE_LIMITED","POST_ALREADY_PUBLISHED","PUBLISHING_IN_PROGRESS","WORKSPACE_LIMIT_REACHED","INTERNAL"]},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["code","message","requestId"]}},"required":["error"]}},"parameters":{}},"paths":{"/ping":{"get":{"tags":["System"],"summary":"Health check","description":"Returns 200 if the token is valid and has the read scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"tokenId":{"type":"string"},"companyId":{"type":"string"}},"required":["ok","tokenId","companyId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts":{"get":{"tags":["Posts"],"summary":"List posts","description":"Returns posts for a workspace with pagination. Each item includes the same post detail fields as GET /posts/{id}.","parameters":[{"name":"workspaceId","in":"query","required":true,"schema":{"type":"string"}},{"name":"pageId","in":"query","required":false,"schema":{"type":"string"}},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by campaign ID, or `no-campaign` for posts not assigned to any campaign"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of post details with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"pageId":{"type":"string"},"type":{"type":"string"},"classification":{"type":"string"},"plainText":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"gridPosition":{"type":"number"},"campaignId":{"type":["string","null"]},"media":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs."},"scheduledAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}},"approval":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","NEVER_SENT","PENDING","PARTIALLY_APPROVED","FULLY_APPROVED"]},"approved":{"type":"boolean"},"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED","MULTIPLE"]},"completedLevels":{"type":"integer","minimum":0},"totalLevels":{"type":"integer","minimum":0},"currentLevelId":{"type":"string"},"levels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}}},"required":["id","label","approved","approvedBy"]}}},"required":["status","approved","type","completedLevels","totalLevels","levels"]},"published":{"type":"boolean"},"scheduledSet":{"type":"boolean"},"teamOnly":{"type":"boolean"},"archived":{"type":"boolean"},"modifiedAt":{"type":"string","format":"date-time"},"mediaType":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"text":{"type":"string"},"color":{"type":"string"}},"required":["uuid","text","color"]}},"commentsCounter":{"type":"number"},"notesCounter":{"type":"number"},"publicShareLink":{"type":"string","format":"uri"},"publishedPostLink":{"type":"string","format":"uri"},"groupId":{"type":"string"},"groupPageIds":{"type":"array","items":{"type":"string"}},"groupSync":{"type":"boolean"},"pinterest":{"type":"object","properties":{"boardId":{"type":"string"},"boardName":{"type":"string"},"title":{"type":["string","null"]},"link":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["boardId","boardName","title","link","description"]}},"required":["id","workspaceId","pageId","type","classification","plainText","createdAt","campaignId","media","scheduledAt","status","approved","approval","published","scheduledSet","teamOnly","archived","commentsCounter","notesCounter"]}},"pagination":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["offset","limit","hasMore"]}},"required":["data","pagination"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Posts"],"summary":"Create a new post","description":"Creates a post in the specified workspace and page. Use `pageId` for a single post or `pageIds` to create grouped cross-page posts. Set `notify` to `false` to suppress external notifications (email, in-app push) for this post creation; internal activity feed entries are always recorded. The `media` field: Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","minLength":1},"pageId":{"type":"string","minLength":1},"pageIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":20},"text":{"type":"string","maxLength":25000,"default":""},"gridPosition":{"type":"integer","minimum":0},"scheduledAt":{"type":"string","format":"date-time"},"labels":{"type":"array","items":{"type":"string"},"default":[]},"media":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"default":[],"description":"Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs."},"teamOnly":{"type":"boolean"},"approved":{"type":"boolean"},"approvedBy":{"type":"string","minLength":1},"publishAtScheduledDate":{"type":"boolean","default":false},"firstComment":{"type":"string","maxLength":8000},"internalNote":{"type":"string","maxLength":8000},"youtubeTitle":{"type":"string","maxLength":100},"linkedinPdfTitle":{"type":"string","maxLength":150},"linkedinVideoTitle":{"type":"string","maxLength":150},"notify":{"type":"boolean","default":true},"pinterest":{"type":"object","properties":{"boardId":{"type":"string","minLength":1},"title":{"type":"string","maxLength":100},"link":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":500}},"required":["boardId"]},"campaignId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"},{"type":"null"}]}},"required":["workspaceId"]}}}},"responses":{"201":{"description":"Post created","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"pageId":{"type":"string"},"type":{"type":"string"},"classification":{"type":"string"},"plainText":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"gridPosition":{"type":"number"},"campaignId":{"type":["string","null"]},"media":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs."},"scheduledAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}},"approval":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","NEVER_SENT","PENDING","PARTIALLY_APPROVED","FULLY_APPROVED"]},"approved":{"type":"boolean"},"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED","MULTIPLE"]},"completedLevels":{"type":"integer","minimum":0},"totalLevels":{"type":"integer","minimum":0},"currentLevelId":{"type":"string"},"levels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}}},"required":["id","label","approved","approvedBy"]}}},"required":["status","approved","type","completedLevels","totalLevels","levels"]},"published":{"type":"boolean"},"scheduledSet":{"type":"boolean"},"teamOnly":{"type":"boolean"},"archived":{"type":"boolean"},"modifiedAt":{"type":"string","format":"date-time"},"mediaType":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"text":{"type":"string"},"color":{"type":"string"}},"required":["uuid","text","color"]}},"commentsCounter":{"type":"number"},"notesCounter":{"type":"number"},"publicShareLink":{"type":"string","format":"uri"},"publishedPostLink":{"type":"string","format":"uri"},"groupId":{"type":"string"},"groupPageIds":{"type":"array","items":{"type":"string"}},"groupSync":{"type":"boolean"},"pinterest":{"type":"object","properties":{"boardId":{"type":"string"},"boardName":{"type":"string"},"title":{"type":["string","null"]},"link":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["boardId","boardName","title","link","description"]}},"required":["id","workspaceId","pageId","type","classification","plainText","createdAt","campaignId","media","scheduledAt","status","approved","approval","published","scheduledSet","teamOnly","archived","commentsCounter","notesCounter"]}}},"required":["posts"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workspace or page not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/{id}":{"get":{"tags":["Posts"],"summary":"Get post detail","description":"Returns a single post by ID including media URLs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Post detail with media","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"pageId":{"type":"string"},"type":{"type":"string"},"classification":{"type":"string"},"plainText":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"gridPosition":{"type":"number"},"campaignId":{"type":["string","null"]},"media":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs."},"scheduledAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}},"approval":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","NEVER_SENT","PENDING","PARTIALLY_APPROVED","FULLY_APPROVED"]},"approved":{"type":"boolean"},"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED","MULTIPLE"]},"completedLevels":{"type":"integer","minimum":0},"totalLevels":{"type":"integer","minimum":0},"currentLevelId":{"type":"string"},"levels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}}},"required":["id","label","approved","approvedBy"]}}},"required":["status","approved","type","completedLevels","totalLevels","levels"]},"published":{"type":"boolean"},"scheduledSet":{"type":"boolean"},"teamOnly":{"type":"boolean"},"archived":{"type":"boolean"},"modifiedAt":{"type":"string","format":"date-time"},"mediaType":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"text":{"type":"string"},"color":{"type":"string"}},"required":["uuid","text","color"]}},"commentsCounter":{"type":"number"},"notesCounter":{"type":"number"},"publicShareLink":{"type":"string","format":"uri"},"publishedPostLink":{"type":"string","format":"uri"},"groupId":{"type":"string"},"groupPageIds":{"type":"array","items":{"type":"string"}},"groupSync":{"type":"boolean"},"pinterest":{"type":"object","properties":{"boardId":{"type":"string"},"boardName":{"type":"string"},"title":{"type":["string","null"]},"link":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["boardId","boardName","title","link","description"]}},"required":["id","workspaceId","pageId","type","classification","plainText","createdAt","campaignId","media","scheduledAt","status","approved","approval","published","scheduledSet","teamOnly","archived","commentsCounter","notesCounter"]}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Posts"],"summary":"Delete a post","description":"Deletes a post in a workspace accessible to the calling token.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Post deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Posts"],"summary":"Update a post","description":"Updates a post. Published posts are immutable and will return 400. The `media` field: Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs. Pass an empty array to clear media. Stories support a single, non-GIF media item; submitting multiple media URLs or a GIF for a story returns 400. Set `archived` to `true` to archive a post or `false` to restore it; archiving removes any active schedule.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":25000},"scheduledAt":{"type":["string","null"],"format":"date-time"},"labels":{"type":"array","items":{"type":"string"}},"media":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs."},"teamOnly":{"type":"boolean"},"approved":{"type":"boolean"},"approvedBy":{"type":"string","minLength":1},"linkedinPdfTitle":{"type":"string","maxLength":150},"linkedinVideoTitle":{"type":"string","maxLength":150},"pinterest":{"type":"object","properties":{"boardId":{"type":"string","minLength":1},"title":{"type":"string","maxLength":100},"link":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":500}}},"publishAtScheduledDate":{"type":"boolean"},"archived":{"type":"boolean"},"campaignId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Updated post detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"pageId":{"type":"string"},"type":{"type":"string"},"classification":{"type":"string"},"plainText":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"gridPosition":{"type":"number"},"campaignId":{"type":["string","null"]},"media":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from the provided URLs."},"scheduledAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}},"approval":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","NEVER_SENT","PENDING","PARTIALLY_APPROVED","FULLY_APPROVED"]},"approved":{"type":"boolean"},"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED","MULTIPLE"]},"completedLevels":{"type":"integer","minimum":0},"totalLevels":{"type":"integer","minimum":0},"currentLevelId":{"type":"string"},"levels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"},"levelId":{"type":"string"}},"required":["userId","approvedAt"]}}},"required":["id","label","approved","approvedBy"]}}},"required":["status","approved","type","completedLevels","totalLevels","levels"]},"published":{"type":"boolean"},"scheduledSet":{"type":"boolean"},"teamOnly":{"type":"boolean"},"archived":{"type":"boolean"},"modifiedAt":{"type":"string","format":"date-time"},"mediaType":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"text":{"type":"string"},"color":{"type":"string"}},"required":["uuid","text","color"]}},"commentsCounter":{"type":"number"},"notesCounter":{"type":"number"},"publicShareLink":{"type":"string","format":"uri"},"publishedPostLink":{"type":"string","format":"uri"},"groupId":{"type":"string"},"groupPageIds":{"type":"array","items":{"type":"string"}},"groupSync":{"type":"boolean"},"pinterest":{"type":"object","properties":{"boardId":{"type":"string"},"boardName":{"type":"string"},"title":{"type":["string","null"]},"link":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["boardId","boardName","title","link","description"]}},"required":["id","workspaceId","pageId","type","classification","plainText","createdAt","campaignId","media","scheduledAt","status","approved","approval","published","scheduledSet","teamOnly","archived","commentsCounter","notesCounter"]}},"required":["data"]}}}},"400":{"description":"Validation error or post is already published"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/{id}/metrics":{"get":{"tags":["Posts"],"summary":"Get post metrics","description":"Returns the latest metrics snapshot for a published post.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Latest metrics snapshot for the post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"postId":{"type":"string"},"pageId":{"type":"string"},"pageType":{"type":"string"},"fetchedAt":{"type":"string","format":"date-time"},"impressions":{"type":"number"},"engagement":{"type":"number"},"reactions":{"type":"number"},"facebook":{"type":"object","properties":{}},"instagram":{"type":"object","properties":{}},"linkedin":{"type":"object","properties":{}},"tiktok":{"type":"object","properties":{}},"threads":{"type":"object","properties":{}},"youtube":{"type":"object","properties":{}}},"required":["postId","pageId","pageType","fetchedAt","impressions","engagement","reactions"]}},"required":["data"]}}}},"400":{"description":"Post is not published"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found or metrics missing"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/{id}/sync":{"post":{"tags":["Posts"],"summary":"Trigger post metrics sync","description":"Triggers a fresh metrics sync for a published post.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post metrics sync queued or deduplicated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"postId":{"type":"string"},"started":{"type":"boolean"},"message":{"type":"string"}},"required":["postId","started","message"]}},"required":["data"]}}}},"400":{"description":"Post is not published"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/{id}/sync-status":{"get":{"tags":["Posts"],"summary":"Get post metrics sync status","description":"Returns whether a post metrics sync is in progress and when metrics last synced.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Post metrics sync status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"postId":{"type":"string"},"syncInProgress":{"type":"boolean"},"lastSyncedAt":{"type":["string","null"],"format":"date-time"}},"required":["postId","syncInProgress","lastSyncedAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/reorder":{"patch":{"tags":["Posts"],"summary":"Reorder posts in the grid","description":"Sets zero-based grid positions for posts using the order of `postIds`. The first ID receives `gridPosition: 0`, the second receives `gridPosition: 1`, and so on.","security":[{"bearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","minLength":1},"postIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":500}},"required":["workspaceId","postIds"]}}}},"responses":{"200":{"description":"Posts reordered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"gridPosition":{"type":"number"}},"required":["id","gridPosition"]}}},"required":["posts"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workspace or post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/count":{"get":{"tags":["Posts"],"summary":"Get total posts count","description":"Returns the total number of posts across all workspaces the token has access to.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Total posts count and per-workspace breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"number"},"workspaces":{"type":"array","items":{"type":"object","properties":{"workspaceId":{"type":"string"},"count":{"type":"number"}},"required":["workspaceId","count"]}}},"required":["total","workspaces"]}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns":{"get":{"tags":["Campaigns"],"summary":"List campaigns","description":"Returns campaigns for a workspace with pagination, optionally filtered by status.","parameters":[{"name":"workspaceId","in":"query","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","archived","paused","planned","completed"]}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of campaigns with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","archived","paused","planned","completed"]},"icon":{"type":"string","enum":["star","bulb","calendar","apple","gift","christmasTree","glass","eggCracked","archive","ghost","cross","candle","home","briefcase","school","camera","bike","bell","barbell","barrier","paint","bolt","heart","babyCarriage","trophy","award","paw","bone","creditCard","discount","shield","tag","thumbUp","thumbDown","umbrella","flag","sun","campfire","seeding","leaf","cherry","macro","clover","pumpkin","flame","cactus","globe","stack","basketball","baseball","ball","gasPump","car","balloon","mug","location","analyze","chartPie","chartDots","cards","mail","headphones","microphone","key"]},"color":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","name","status","icon","color","startedAt","endedAt","links","createdAt"]}},"pagination":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["offset","limit","hasMore"]}},"required":["data","pagination"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Campaigns"],"summary":"Create a campaign","description":"Creates a campaign in a workspace. `description` is supplied as plain text and stored as rich text. Subject to the workspace campaign plan limit.","security":[{"bearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":80},"status":{"type":"string","enum":["active","archived","paused","planned","completed"],"default":"planned"},"icon":{"type":"string","enum":["star","bulb","calendar","apple","gift","christmasTree","glass","eggCracked","archive","ghost","cross","candle","home","briefcase","school","camera","bike","bell","barbell","barrier","paint","bolt","heart","babyCarriage","trophy","award","paw","bone","creditCard","discount","shield","tag","thumbUp","thumbDown","umbrella","flag","sun","campfire","seeding","leaf","cherry","macro","clover","pumpkin","flame","cactus","globe","stack","basketball","baseball","ball","gasPump","car","balloon","mug","location","analyze","chartPie","chartDots","cards","mail","headphones","microphone","key"]},"color":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["url"]}}},"required":["workspaceId","name"]}}}},"responses":{"201":{"description":"Campaign created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","archived","paused","planned","completed"]},"icon":{"type":"string","enum":["star","bulb","calendar","apple","gift","christmasTree","glass","eggCracked","archive","ghost","cross","candle","home","briefcase","school","camera","bike","bell","barbell","barrier","paint","bolt","heart","babyCarriage","trophy","award","paw","bone","creditCard","discount","shield","tag","thumbUp","thumbDown","umbrella","flag","sun","campfire","seeding","leaf","cherry","macro","clover","pumpkin","flame","cactus","globe","stack","basketball","baseball","ball","gasPump","car","balloon","mug","location","analyze","chartPie","chartDots","cards","mail","headphones","microphone","key"]},"color":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","name","status","icon","color","startedAt","endedAt","links","createdAt"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Campaign limit reached or insufficient permissions"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get campaign detail","description":"Returns a single campaign by ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Campaign detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","archived","paused","planned","completed"]},"icon":{"type":"string","enum":["star","bulb","calendar","apple","gift","christmasTree","glass","eggCracked","archive","ghost","cross","candle","home","briefcase","school","camera","bike","bell","barbell","barrier","paint","bolt","heart","babyCarriage","trophy","award","paw","bone","creditCard","discount","shield","tag","thumbUp","thumbDown","umbrella","flag","sun","campfire","seeding","leaf","cherry","macro","clover","pumpkin","flame","cactus","globe","stack","basketball","baseball","ball","gasPump","car","balloon","mug","location","analyze","chartPie","chartDots","cards","mail","headphones","microphone","key"]},"color":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","name","status","icon","color","startedAt","endedAt","links","createdAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Campaign not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Campaigns"],"summary":"Update a campaign","description":"Partially updates a campaign. Any subset of the create fields may be provided.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"status":{"type":"string","enum":["active","archived","paused","planned","completed"]},"icon":{"type":"string","enum":["star","bulb","calendar","apple","gift","christmasTree","glass","eggCracked","archive","ghost","cross","candle","home","briefcase","school","camera","bike","bell","barbell","barrier","paint","bolt","heart","babyCarriage","trophy","award","paw","bone","creditCard","discount","shield","tag","thumbUp","thumbDown","umbrella","flag","sun","campfire","seeding","leaf","cherry","macro","clover","pumpkin","flame","cactus","globe","stack","basketball","baseball","ball","gasPump","car","balloon","mug","location","analyze","chartPie","chartDots","cards","mail","headphones","microphone","key"]},"color":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["url"]}}}}}}},"responses":{"200":{"description":"Campaign updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","archived","paused","planned","completed"]},"icon":{"type":"string","enum":["star","bulb","calendar","apple","gift","christmasTree","glass","eggCracked","archive","ghost","cross","candle","home","briefcase","school","camera","bike","bell","barbell","barrier","paint","bolt","heart","babyCarriage","trophy","award","paw","bone","creditCard","discount","shield","tag","thumbUp","thumbDown","umbrella","flag","sun","campfire","seeding","leaf","cherry","macro","clover","pumpkin","flame","cactus","globe","stack","basketball","baseball","ball","gasPump","car","balloon","mug","location","analyze","chartPie","chartDots","cards","mail","headphones","microphone","key"]},"color":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","name","status","icon","color","startedAt","endedAt","links","createdAt"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Campaign not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Campaigns"],"summary":"Delete a campaign","description":"Deletes a campaign and detaches it from its posts. Posts are kept; only the `campaignId` link is removed.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Campaign deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Campaign not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/labels":{"get":{"tags":["Labels"],"summary":"List labels","description":"Returns all labels for a workspace.","parameters":[{"name":"workspaceId","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of labels","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"color":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","color","name"]}}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Labels"],"summary":"Create a label","description":"Creates a new label in a workspace.","security":[{"bearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","minLength":1},"text":{"type":"string","minLength":1},"color":{"type":"string","enum":["pattens-blue","feta","pink-lace","pippin","peach-cream","fog","half-and-half","lime-flurish","snowy-mint","blue-chalk","mabel","silver-sand"]}},"required":["workspaceId","text","color"]}}}},"responses":{"201":{"description":"Label created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"color":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","color","name"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/media":{"get":{"tags":["Media"],"summary":"List media uploads","description":"Returns media uploads for a workspace with pagination.","parameters":[{"name":"workspaceId","in":"query","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of media uploads with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"type":{"type":"string","enum":["image","video","gif"]},"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"},"thumbnailUrl":{"type":["string","null"],"format":"uri"},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"size":{"type":"number"},"mimeType":{"type":"string"},"status":{"type":"string","enum":["uploading","processing","error","success"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","type","name","url","thumbnailUrl","width","height","size","mimeType","status","createdAt"]}},"pagination":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["offset","limit","hasMore"]}},"required":["data","pagination"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Media"],"summary":"Upload media from URLs","description":"Accepts 1 to 20 public image or video URLs (each max 100MB) for async download and processing. Returns 202 immediately with processing status for each item.","security":[{"bearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","minLength":1},"mediaUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":20,"description":"Array of 1 to 20 public image/video URLs to upload to the workspace media library. Each file max ~100MB."}},"required":["workspaceId","mediaUrls"]}}}},"responses":{"202":{"description":"Media upload accepted for processing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing"]}},"required":["id","status"]}}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/media/{id}":{"get":{"tags":["Media"],"summary":"Get media upload","description":"Returns a single media upload by ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Media upload detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"type":{"type":"string","enum":["image","video","gif"]},"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"},"thumbnailUrl":{"type":["string","null"],"format":"uri"},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"size":{"type":"number"},"mimeType":{"type":"string"},"status":{"type":"string","enum":["uploading","processing","error","success"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","type","name","url","thumbnailUrl","width","height","size","mimeType","status","createdAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Media not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pages/{id}/sync":{"post":{"tags":["Pages"],"summary":"Trigger page metrics sync","description":"Triggers a fresh analytics metrics sync for a page.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Page metrics sync queued or deduplicated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"pageId":{"type":"string"},"started":{"type":"boolean"},"message":{"type":"string"}},"required":["pageId","started","message"]}},"required":["data"]}}}},"400":{"description":"Page type does not support analytics sync"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Page not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pages/{id}/sync-status":{"get":{"tags":["Pages"],"summary":"Get page metrics sync status","description":"Returns whether a page metrics sync is in progress and when metrics last synced.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Page metrics sync status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"pageId":{"type":"string"},"syncInProgress":{"type":"boolean"},"lastSyncedAt":{"type":["string","null"],"format":"date-time"}},"required":["pageId","syncInProgress","lastSyncedAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Page not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pages":{"get":{"tags":["Pages"],"summary":"List pages","description":"Returns pages (social channels) the token has access to, with pagination.","parameters":[{"name":"workspaceId","in":"query","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of pages with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string"},"workspaceId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time"},"isConnected":{"type":"boolean"},"profilePicture":{"type":["string","null"]},"link":{"type":["string","null"]}},"required":["id","name","platform","workspaceId","createdAt","isConnected","profilePicture","link"]}},"pagination":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["offset","limit","hasMore"]}},"required":["data","pagination"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pages/{id}/metrics":{"get":{"tags":["Pages"],"summary":"Get page metrics","description":"Returns paginated raw page metrics snapshots for a date range.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Paginated page metrics snapshots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string"},"pageType":{"type":"string"},"fetchedAt":{"type":"string","format":"date-time"},"partial":{"type":"boolean"},"facebook":{"type":"object","properties":{"followers":{"type":"number"},"gainedFollowers":{"type":"number"},"posts":{"type":"number"},"engagement":{"type":"number"},"reactions":{"type":"number"},"pageViews":{"type":"number"},"unFollows":{"type":"number"},"views":{"type":"number"},"totalFollowers":{"type":"number"}},"required":["followers","gainedFollowers","posts","engagement","reactions","pageViews","unFollows","views"]},"instagram":{"type":"object","properties":{"gainedFollowers":{"type":"number"},"unFollows":{"type":"number"},"totalFollowers":{"type":"number"},"followersIncomplete":{"type":"boolean"},"impressions":{"type":"number"},"views":{"type":"number"},"reach":{"type":"number"},"accountsReachBreakdown":{"type":"object","properties":{"followers":{"type":"number"},"nonFollowers":{"type":"number"},"total":{"type":"number"}},"required":["followers","nonFollowers","total"]},"profileViews":{"type":"number"},"posts":{"type":"number"},"engagement":{"type":"number"},"engagementBreakdown":{"type":"object","properties":{"post":{"type":"number"},"reel":{"type":"number"},"ad":{"type":"number"},"story":{"type":"number"},"carousel":{"type":"number"}}},"reachBreakdown":{"type":"object","properties":{"post":{"type":"object","properties":{"total":{"type":"number"},"followers":{"type":"number"},"nonFollowers":{"type":"number"}},"required":["total","followers","nonFollowers"]},"reel":{"type":"object","properties":{"total":{"type":"number"},"followers":{"type":"number"},"nonFollowers":{"type":"number"}},"required":["total","followers","nonFollowers"]},"story":{"type":"object","properties":{"total":{"type":"number"},"followers":{"type":"number"},"nonFollowers":{"type":"number"}},"required":["total","followers","nonFollowers"]}},"required":["post","reel","story"]}},"required":["gainedFollowers","unFollows","reach","posts","engagement"]},"linkedin":{"type":"object","properties":{"followers":{"type":"number"},"totalFollowers":{"type":"number"},"impressions":{"type":"number"},"engagement":{"type":"number"},"pageInsights":{"type":"number"},"pageViews":{"type":"number"},"posts":{"type":"number"},"reshares":{"type":"number"},"reactions":{"type":"number"},"comments":{"type":"number"},"shareStats":{"type":"object","properties":{"uniqueImpressionsCount":{"type":"number"},"clickCount":{"type":"number"},"engagement":{"type":"number"},"likeCount":{"type":"number"},"commentCount":{"type":"number"},"shareCount":{"type":"number"},"impressionCount":{"type":"number"},"commentMentionsCount":{"type":"number"},"shareMentionsCount":{"type":"number"}},"required":["uniqueImpressionsCount","clickCount","engagement","likeCount","commentCount","shareCount","impressionCount"]}},"required":["followers","impressions"]},"tiktok":{"type":"object","properties":{"profile_views":{"type":"number"},"video_views":{"type":"number"},"likes":{"type":"number"},"comments":{"type":"number"},"shares":{"type":"number"},"followers_count":{"type":"number"},"engagement":{"type":"number"},"videos":{"type":"number"}},"required":["profile_views","video_views","likes","comments","shares","followers_count","engagement","videos"]},"threads":{"type":"object","properties":{"views":{"type":"number"},"likes":{"type":"number"},"replies":{"type":"number"},"reposts":{"type":"number"},"quotes":{"type":"number"}},"required":["views","likes","replies","reposts","quotes"]},"googleMyBusiness":{"type":"object","properties":{"posts":{"type":"number"},"callClicks":{"type":"number"},"websiteClicks":{"type":"number"},"impressions":{"type":"number"},"engagement":{"type":"number"},"businessConversations":{"type":"number"},"businessImpressionsMobileSearch":{"type":"number"},"businessImpressionsDesktopMaps":{"type":"number"},"businessImpressionsDesktopSearch":{"type":"number"},"businessImpressionsMobileMaps":{"type":"number"},"businessDirectionRequests":{"type":"number"},"businessBookings":{"type":"number"},"businessFoodOrders":{"type":"number"}},"required":["posts","callClicks","websiteClicks","impressions","engagement","businessConversations","businessImpressionsMobileSearch","businessImpressionsDesktopMaps","businessImpressionsDesktopSearch","businessImpressionsMobileMaps","businessDirectionRequests","businessBookings","businessFoodOrders"]},"youtube":{"type":"object","properties":{"subscribers":{"type":"number"},"totalSubscribers":{"type":"number"},"subscribersGained":{"type":"number"},"subscribersLost":{"type":"number"},"videos":{"type":"number"},"views":{"type":"number"},"estimatedMinutesWatched":{"type":"number"},"comments":{"type":"number"},"likes":{"type":"number"},"dislikes":{"type":"number"},"shares":{"type":"number"},"engagement":{"type":"number"},"averageViewDuration":{"type":"number"}},"required":["subscribers","subscribersGained","subscribersLost","videos","views","estimatedMinutesWatched","comments","likes","dislikes","shares","engagement","averageViewDuration"]}},"required":["pageId","pageType","fetchedAt","partial"]}},"pagination":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["offset","limit","hasMore"]}},"required":["data","pagination"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Page not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stories":{"post":{"tags":["Stories"],"summary":"Create an Instagram story","description":"Creates a single-media Instagram story. GIFs and non-Instagram pages are not supported. Set `notify` to `false` to suppress external notifications; internal activity feed entries are always recorded.","security":[{"bearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","minLength":1},"pageId":{"type":"string","minLength":1},"media":{"type":"string","format":"uri"},"stickers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","location","link","music","mention","hashtags","questions","notes","other"]},"value":{"type":"string"}},"required":["type","value"]},"default":[]},"scheduledAt":{"type":"string","format":"date-time"},"labels":{"type":"array","items":{"type":"string"},"default":[]},"teamOnly":{"type":"boolean"},"approved":{"type":"boolean"},"approvedBy":{"type":"string","minLength":1},"publishAtScheduledDate":{"type":"boolean","default":false},"notify":{"type":"boolean","default":true},"internalNote":{"type":"string","maxLength":8000}},"required":["workspaceId","pageId","media"]}}}},"responses":{"201":{"description":"Story created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"pageId":{"type":"string"},"type":{"type":"string"},"classification":{"type":"string","enum":["story"]},"media":{"type":["string","null"],"format":"uri"},"scheduledAt":{"type":["string","null"],"format":"date-time"},"scheduledSet":{"type":"boolean"},"status":{"type":"string"},"approved":{"type":"boolean"},"approvedBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"}},"required":["userId","approvedAt"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","workspaceId","pageId","type","classification","media","scheduledAt","scheduledSet","status","approved","createdAt"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workspace or page not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/posts/{id}/comments":{"get":{"tags":["Posts"],"summary":"List comments on a post","description":"Returns comments for a post with pagination.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}},{"name":"teamOnly","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of comments with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"postId":{"type":"string"},"text":{"type":"string"},"authorId":{"type":"string"},"teamOnly":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","postId","text","authorId","teamOnly","createdAt"]}},"pagination":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["offset","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Posts"],"summary":"Add a comment to a post","description":"Creates a new comment on a post.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1},"teamOnly":{"type":"boolean","default":false}},"required":["text"]}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"postId":{"type":"string"},"text":{"type":"string"},"authorId":{"type":"string"},"teamOnly":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","postId","text","authorId","teamOnly","createdAt"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/workspaces":{"get":{"tags":["Workspaces"],"summary":"List workspaces","description":"Returns all workspaces the token has access to.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of workspaces","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"companyId":{"type":"string"},"timezone":{"type":"string"},"websiteUrl":{"type":["string","null"]},"approvalSettings":{"anyOf":[{"allOf":[{"type":"object","properties":{"autoSchedule":{"type":"boolean"},"autoLock":{"type":"boolean"},"sendReminders":{"type":"boolean"}},"required":["autoSchedule","autoLock"]},{"type":"object","properties":{"type":{"type":"string","enum":["MULTIPLE"]},"approvalLevels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approversIds":{"type":"array","items":{"type":"string"}}},"required":["id","label","approversIds"]}}},"required":["type"]}]},{"allOf":[{"type":"object","properties":{"autoSchedule":{"type":"boolean"},"autoLock":{"type":"boolean"},"sendReminders":{"type":"boolean"}},"required":["autoSchedule","autoLock"]},{"type":"object","properties":{"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED"]}},"required":["type"]}]}]},"defaultTeamOnlyPosts":{"type":"boolean"},"hideEmailsFromClients":{"type":"boolean"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"color":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","color","name"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","companyId","timezone","websiteUrl","approvalSettings","defaultTeamOnlyPosts","hideEmailsFromClients","labels","createdAt","updatedAt"]}}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Workspaces"],"summary":"Create a workspace","description":"Creates a new workspace in the calling token's company.","security":[{"bearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"timezone":{"type":"string"},"approvalSettings":{"anyOf":[{"allOf":[{"type":"object","properties":{"autoSchedule":{"type":"boolean"},"autoLock":{"type":"boolean"},"sendReminders":{"type":"boolean"}},"required":["autoSchedule","autoLock"]},{"type":"object","properties":{"type":{"type":"string","enum":["MULTIPLE"]},"approvalLevels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approversIds":{"type":"array","items":{"type":"string"}}},"required":["id","label","approversIds"]}}},"required":["type"]}]},{"allOf":[{"type":"object","properties":{"autoSchedule":{"type":"boolean"},"autoLock":{"type":"boolean"},"sendReminders":{"type":"boolean"}},"required":["autoSchedule","autoLock"]},{"type":"object","properties":{"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED"]}},"required":["type"]}]}]},"websiteUrl":{"type":"string","maxLength":2048}},"required":["name","timezone","approvalSettings"]}}}},"responses":{"201":{"description":"Workspace created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"companyId":{"type":"string"},"websiteUrl":{"type":["string","null"]},"approvalSettings":{"anyOf":[{"allOf":[{"type":"object","properties":{"autoSchedule":{"type":"boolean"},"autoLock":{"type":"boolean"},"sendReminders":{"type":"boolean"}},"required":["autoSchedule","autoLock"]},{"type":"object","properties":{"type":{"type":"string","enum":["MULTIPLE"]},"approvalLevels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"approversIds":{"type":"array","items":{"type":"string"}}},"required":["id","label","approversIds"]}}},"required":["type"]}]},{"allOf":[{"type":"object","properties":{"autoSchedule":{"type":"boolean"},"autoLock":{"type":"boolean"},"sendReminders":{"type":"boolean"}},"required":["autoSchedule","autoLock"]},{"type":"object","properties":{"type":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED"]}},"required":["type"]}]}]},"defaultTeamOnlyPosts":{"type":"boolean"},"hideEmailsFromClients":{"type":"boolean"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"color":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","color","name"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","timezone","companyId","websiteUrl","approvalSettings","defaultTeamOnlyPosts","hideEmailsFromClients","labels","createdAt"]}},"required":["data"]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Workspace limit reached or insufficient permissions"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/workspaces/{id}":{"delete":{"tags":["Workspaces"],"summary":"Delete a workspace","description":"Deletes a workspace in the company associated with the calling token.","security":[{"bearerAuth":["write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Workspace deleted"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Workspace not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}