{"openapi":"3.0.3","info":{"title":"RedRover API","version":"v1","description":"Schedule and manage Reddit content, read results and track AI search visibility. Every request is limited to 120 per minute per key.","contact":{"name":"RedRover","url":"https://docs.tryredrover.com"}},"servers":[{"url":"https://app.tryredrover.com/api/public/v1"}],"tags":[{"name":"Workspaces","description":"The workspaces you can reach, each one's company profile and its credits."},{"name":"Posts","description":"List, schedule, edit, approve and cancel Reddit posts."},{"name":"Comments","description":"List, schedule, edit, approve and cancel Reddit comments."},{"name":"Review Notes","description":"Read and leave notes on content waiting for your approval."},{"name":"Review Batches","description":"The batches of content our team writes for you to review, and links to share them."},{"name":"Analytics","description":"Reddit results and AI search visibility."},{"name":"Knowledge Base","description":"Your company information and the subreddits your content must avoid."},{"name":"Keywords","description":"The keywords you target and the AI assistant questions you want to show up for."},{"name":"Webhooks","description":"Endpoints we push signed events to when your content changes."},{"name":"Reports","description":"The weekly gameplans, weekly summaries and performance reports shared with you."},{"name":"Mentions","description":"Reddit posts and comments that mention you, your competitors or your topic."},{"name":"Activity","description":"What recently happened to your content: posted, failed, cancelled or replied to."},{"name":"Strategy","description":"Your campaign strategy and blog campaigns."},{"name":"Agency Partners","description":"For agencies: manage every client with one partner key, and get every client's events in one place."},{"name":"Content Tools","description":"Check a draft against our writing rules, or have our AI rewrite it."},{"name":"Status","description":"Check that the API is up, with no credential."}],"paths":{"/workspaces":{"get":{"operationId":"listWorkspaces","summary":"List Workspaces","description":"Lists the workspaces your key or connected app can act on. This is the one endpoint that needs no X-Workspace-Id.","tags":["Workspaces"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of workspaces, by name","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Workspace ID (UUID). Send it as X-Workspace-Id"},"name":{"type":"string","description":"Workspace name"}},"required":["id","name"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/workspace/profile":{"get":{"operationId":"getWorkspaceProfile","summary":"Get Workspace Profile","description":"Reads the workspace's company profile: website, description, keywords, subreddits, competitors and brand names.","tags":["Workspaces"],"security":[{"bearerAuth":["workspace:read"]}],"x-required-scope":"workspace:read","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Workspace ID"},"name":{"type":"string","description":"Company or workspace name"},"website":{"type":"string","nullable":true,"description":"Company website"},"description":{"type":"string","nullable":true,"description":"What the company does"},"keywords":{"type":"array","items":{"type":"string"},"description":"Target keywords"},"subreddits":{"type":"array","items":{"type":"string"},"description":"Subreddits to focus on, as bare names"},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"website":{"type":"string"}},"required":["name","website"],"additionalProperties":false},"description":"Tracked competitors"},"brandNames":{"type":"array","items":{"type":"string"},"description":"Brand names our checks accept in content"}},"required":["id","name","website","description","keywords","subreddits","competitors","brandNames"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics","website":"https://acme.example","description":"Product analytics for small SaaS teams.","keywords":["product analytics","saas metrics"],"subreddits":["startups","SaaS"],"competitors":[{"name":"Example Metrics","website":"https://metrics.example"}],"brandNames":["Acme","Acme Analytics"]}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"updateWorkspaceProfile","summary":"Update Workspace Profile","description":"Changes the company profile. Send only the fields to change; lists replace the stored list.","tags":["Workspaces"],"security":[{"bearerAuth":["workspace:write"]}],"x-required-scope":"workspace:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"website":{"type":"string","maxLength":500,"description":"Company website, like example.com"},"description":{"type":"string","maxLength":5000,"description":"What the company does, up to 5,000 characters"},"keywords":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":200,"description":"Target keywords. Replaces the whole list"},"subreddits":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":200,"description":"Subreddits to focus on, with or without r/. Replaces the whole list"},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"website":{"type":"string","maxLength":500}},"required":["name","website"],"additionalProperties":false},"maxItems":25,"description":"Competitors as { name, website }. Replaces the whole list"},"brandNames":{"type":"array","items":{"type":"string"},"description":"Brand names our checks should accept. Replaces the whole list"}},"additionalProperties":false},"example":{"keywords":["product analytics","saas metrics","churn"]}}}},"responses":{"200":{"description":"The profile after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Workspace ID"},"name":{"type":"string","description":"Company or workspace name"},"website":{"type":"string","nullable":true,"description":"Company website"},"description":{"type":"string","nullable":true,"description":"What the company does"},"keywords":{"type":"array","items":{"type":"string"},"description":"Target keywords"},"subreddits":{"type":"array","items":{"type":"string"},"description":"Subreddits to focus on, as bare names"},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"website":{"type":"string"}},"required":["name","website"],"additionalProperties":false},"description":"Tracked competitors"},"brandNames":{"type":"array","items":{"type":"string"},"description":"Brand names our checks accept in content"}},"required":["id","name","website","description","keywords","subreddits","competitors","brandNames"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics","website":"https://acme.example","description":"Product analytics for small SaaS teams.","keywords":["product analytics","saas metrics","churn"],"subreddits":["startups","SaaS"],"competitors":[{"name":"Example Metrics","website":"https://metrics.example"}],"brandNames":["Acme","Acme Analytics"]}}}}},"400":{"description":"No field was sent, or a field is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/credits":{"get":{"operationId":"getCredits","summary":"Get Credits","description":"Reads the workspace's credits: the balance, credits expiring soon, what posts and comments cost, 30 days of usage and a link to top up.\n\nScheduling a post or comment takes its credits right away, soonest-expiring credits first, and cancelling it before it goes live gives them back. Credits expire 60 days after they are added.\n\nWhen the balance can't cover new content, scheduling answers 402 with payment_required and a message that includes topUpUrl.\n\npaysWithCredits is false for workspaces billed by invoice: their content costs no credits and is never blocked.","tags":["Workspaces"],"security":[{"bearerAuth":["workspace:read"]}],"x-required-scope":"workspace:read","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The workspace's credits","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"paysWithCredits":{"type":"boolean","description":"False when the workspace is billed by invoice, so posts and comments cost no credits"},"balance":{"type":"integer","description":"Credits available to spend now"},"expiringSoon":{"type":"object","properties":{"credits":{"type":"integer","description":"Credits that expire in the next 7 days"},"expiresAt":{"type":"string","description":"When the first of them expire"}},"required":["credits","expiresAt"],"additionalProperties":false,"nullable":true,"description":"Credits expiring in the next 7 days, or null"},"prices":{"type":"object","properties":{"post":{"type":"integer","description":"Credits a post costs"},"comment":{"type":"integer","description":"Credits a comment costs"}},"required":["post","comment"],"additionalProperties":false},"usage":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"The day, YYYY-MM-DD in UTC"},"spent":{"type":"integer","description":"Credits taken by content scheduled that day"},"refunded":{"type":"integer","description":"Credits given back that day for cancelled content"}},"required":["date","spent","refunded"],"additionalProperties":false},"description":"The last 30 days, oldest first"},"topUpUrl":{"type":"string","description":"Where to buy more credits"}},"required":["paysWithCredits","balance","expiringSoon","prices","usage","topUpUrl"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"paysWithCredits":true,"balance":184,"expiringSoon":{"credits":40,"expiresAt":"2026-11-20T00:00:00.000Z"},"prices":{"post":32,"comment":8},"usage":[{"date":"2026-11-13","spent":48,"refunded":0},{"date":"2026-11-14","spent":0,"refunded":0},{"date":"2026-11-15","spent":72,"refunded":8}],"topUpUrl":"https://app.tryredrover.com/settings?tab=billing"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/posts":{"get":{"operationId":"listPosts","summary":"List Posts","description":"Lists the workspace's posts with their status. Content waiting for your approval comes first, then the rest by schedule, newest first.","tags":["Posts"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Only return content with this status: draft, pending_approval, scheduled, posted, failed or cancelled","schema":{"type":"string","enum":["draft","pending_approval","scheduled","posted","failed","cancelled"]}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of posts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"status, limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createPost","summary":"Schedule a Post","description":"Schedules a new post in a subreddit at least 5 minutes ahead.\n\nOur team handles publishing, so the post goes live on or shortly after scheduledFor. See Scheduling for the rules.\n\nA post costs 32 credits, taken when it is scheduled. Cancelling it before it goes live gives them back. Check the balance with Get Credits.","tags":["Posts"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"description":"The post title, up to 300 characters"},"body":{"type":"string","minLength":1,"maxLength":40000,"description":"The post text, up to 40,000 characters"},"subreddit":{"type":"string","minLength":1,"maxLength":50,"pattern":"^\\/?(?:r\\/)?[A-Za-z0-9_]{2,24}\\/?$","description":"The subreddit, with or without r/"},"flair":{"type":"string","minLength":1,"maxLength":64,"description":"Post flair, when the subreddit asks for one"},"scheduledFor":{"type":"string","format":"date-time","description":"When it should go live, as an ISO 8601 datetime at least 5 minutes from now"}},"required":["title","body","subreddit","scheduledFor"],"additionalProperties":false},"example":{"title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"r/startups","flair":"Lessons Learned","scheduledFor":"2026-12-01T15:00:00Z"}}}},"responses":{"201":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"400":{"description":"A field is missing or invalid, or scheduledFor is less than 5 minutes away","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"402":{"description":"The workspace doesn't have enough credits. The message says how many it needs and where to top up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payment_required","message":"You're out of credits. This needs 32 credits and the workspace has 10. Top up at https://app.tryredrover.com/settings?tab=billing"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/posts/{id}":{"get":{"operationId":"getPost","summary":"Get Post","description":"Reads one post: its text, subreddit, status, schedule, live link and results once posted.","tags":["Posts"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"id","in":"path","required":true,"description":"The post ID from List Posts. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"48213"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"updatePost","summary":"Edit or Reschedule a Post","description":"Changes the text or timing of a post you can still change. Send only the fields to change.\n\nA post can be changed while canChange is true: until it is 5 minutes from going live.","tags":["Posts"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The post ID from List Posts. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"48213"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"description":"New title"},"body":{"type":"string","minLength":1,"maxLength":40000,"description":"New text"},"subreddit":{"type":"string","minLength":1,"maxLength":50,"pattern":"^\\/?(?:r\\/)?[A-Za-z0-9_]{2,24}\\/?$","description":"New subreddit, with or without r/"},"flair":{"type":"string","minLength":1,"maxLength":64,"nullable":true,"description":"New flair, or null to clear it"},"scheduledFor":{"type":"string","format":"date-time","description":"New time, at least 5 minutes from now"}},"additionalProperties":false},"example":{"scheduledFor":"2026-12-02T15:00:00Z"}}}},"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-02T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"400":{"description":"No field was sent, or a field is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The post goes live in under 5 minutes, or has already posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"delete":{"operationId":"cancelPost","summary":"Cancel a Post","description":"Cancels a scheduled post before it goes live. The post stays in the list with status cancelled.\n\nThe credits the post cost go back to the workspace, unless they have expired since.","tags":["Posts"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The post ID from List Posts. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"48213"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"48213","type":"post","status":"cancelled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The post is waiting for approval (leave a review note instead), is too close to going live, or has already posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/posts/{id}/approve":{"post":{"operationId":"approvePost","summary":"Approve a Post","description":"Approves a post our team wrote and sent for your review. Approved content goes onto the schedule.","tags":["Posts"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The post ID from List Posts. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14","type":"post","status":"approved","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":null,"postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The post is not waiting for approval, or is already approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/comments":{"get":{"operationId":"listComments","summary":"List Comments","description":"Lists the workspace's comments with their status. Content waiting for your approval comes first, then the rest by schedule, newest first.","tags":["Comments"],"security":[{"bearerAuth":["comments:read"]}],"x-required-scope":"comments:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Only return content with this status: draft, pending_approval, scheduled, posted, failed or cancelled","schema":{"type":"string","enum":["draft","pending_approval","scheduled","posted","failed","cancelled"]}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of comments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"91574","type":"comment","status":"scheduled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"status, limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createComment","summary":"Schedule a Comment","description":"Schedules a comment on a Reddit thread at least 5 minutes ahead.\n\nA comment costs 8 credits, taken when it is scheduled. Cancelling it before it goes live gives them back. Check the balance with Get Credits.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"threadUrl":{"type":"string","pattern":"^https:\\/\\/(?:(?:www|old|new|np)\\.)?reddit\\.com\\/r\\/[\\w-]+\\/comments\\/[a-z0-9]+(?:[/?#]|$)","description":"Link to the Reddit thread to reply in"},"body":{"type":"string","minLength":1,"maxLength":10000,"description":"The comment text, up to 10,000 characters"},"scheduledFor":{"type":"string","format":"date-time","description":"When it should go live, as an ISO 8601 datetime at least 5 minutes from now"}},"required":["threadUrl","body","scheduledFor"],"additionalProperties":false},"example":{"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","scheduledFor":"2026-12-01T15:00:00Z"}}}},"responses":{"201":{"description":"The comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"91574","type":"comment","status":"scheduled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"400":{"description":"A field is missing or invalid, or scheduledFor is less than 5 minutes away","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"402":{"description":"The workspace doesn't have enough credits. The message says how many it needs and where to top up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payment_required","message":"You're out of credits. This needs 32 credits and the workspace has 10. Top up at https://app.tryredrover.com/settings?tab=billing"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/comments/{id}":{"get":{"operationId":"getComment","summary":"Get Comment","description":"Reads one comment: its text, subreddit, status, schedule, live link and results once posted.","tags":["Comments"],"security":[{"bearerAuth":["comments:read"]}],"x-required-scope":"comments:read","parameters":[{"name":"id","in":"path","required":true,"description":"The comment ID from List Comments. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"91574"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"91574","type":"comment","status":"posted","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-11-10T17:30:00Z","postedAt":"2026-11-10T17:31:12Z","url":"https://www.reddit.com/r/startups/comments/1abcde2/comment/kx9z1p0/","upvotes":14,"commentCount":2,"failureReason":null,"canChange":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"updateComment","summary":"Edit or Reschedule a Comment","description":"Changes the text or timing of a comment you can still change. Send only the fields to change.\n\nA comment can be changed while canChange is true: until it is 5 minutes from going live.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"id","in":"path","required":true,"description":"The comment ID from List Comments. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"91574"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000,"description":"New text"},"scheduledFor":{"type":"string","format":"date-time","description":"New time, at least 5 minutes from now"}},"additionalProperties":false},"example":{"scheduledFor":"2026-12-02T15:00:00Z"}}}},"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"91574","type":"comment","status":"scheduled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-02T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"400":{"description":"No field was sent, or a field is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The comment goes live in under 5 minutes, or has already posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"delete":{"operationId":"cancelComment","summary":"Cancel a Comment","description":"Cancels a scheduled comment before it goes live. The comment stays in the list with status cancelled.\n\nThe credits the comment cost go back to the workspace, unless they have expired since.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"id","in":"path","required":true,"description":"The comment ID from List Comments. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"91574"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"91574","type":"comment","status":"cancelled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The comment is waiting for approval (leave a review note instead), is too close to going live, or has already posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/comments/{id}/approve":{"post":{"operationId":"approveComment","summary":"Approve a Comment","description":"Approves a comment our team wrote and sent for your review. Approved content goes onto the schedule.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"id","in":"path","required":true,"description":"The comment ID from List Comments. Content waiting for approval has a UUID; scheduled content has a number.","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14","type":"comment","status":"approved","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":null,"postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The comment is not waiting for approval, or is already approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/posts/{id}/review-notes":{"get":{"operationId":"listPostReviewNotes","summary":"List Post Review Notes","description":"Lists the review notes on a post waiting for your approval, with our team's replies.","tags":["Review Notes"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"id","in":"path","required":true,"description":"The ID (UUID) of a post waiting for approval","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The notes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contentId":{"type":"string","description":"The post or comment the notes are on"},"openCount":{"type":"integer","description":"Notes not yet resolved"},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Note ID (UUID)"},"onReply":{"type":"boolean","description":"True when the note is on a reply under the post, not the post itself"},"replyTo":{"type":"string","nullable":true,"description":"The note this one answers, for our team's replies"},"body":{"type":"string","description":"The note"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"resolved":{"type":"boolean","description":"Whether the note is resolved"},"resolvedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"resolvedBy":{"type":"string","nullable":true,"description":"Who resolved it"}},"required":["id","onReply","replyTo","body","createdAt","resolved","resolvedAt","resolvedBy"],"additionalProperties":false}}},"required":["contentId","openCount","notes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"contentId":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14","openCount":1,"notes":[{"id":"b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d","onReply":false,"replyTo":null,"body":"Can we make the title shorter?","createdAt":"2026-11-14T10:02:00Z","resolved":false,"resolvedAt":null,"resolvedBy":null}]}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The post is not waiting for approval, so it has no review notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"addPostReviewNote","summary":"Add a Post Review Note","description":"Leaves a note on a post waiting for approval, asking our team for a change.","tags":["Review Notes"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The ID (UUID) of a post waiting for approval","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000,"description":"The note, up to 5,000 characters"}},"required":["body"],"additionalProperties":false},"example":{"body":"Can we make the title shorter?"}}}},"responses":{"201":{"description":"The new note","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Note ID (UUID)"},"onReply":{"type":"boolean","description":"True when the note is on a reply under the post, not the post itself"},"replyTo":{"type":"string","nullable":true,"description":"The note this one answers, for our team's replies"},"body":{"type":"string","description":"The note"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"resolved":{"type":"boolean","description":"Whether the note is resolved"},"resolvedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"resolvedBy":{"type":"string","nullable":true,"description":"Who resolved it"}},"required":["id","onReply","replyTo","body","createdAt","resolved","resolvedAt","resolvedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d","onReply":false,"replyTo":null,"body":"Can we make the title shorter?","createdAt":"2026-11-14T10:02:00Z","resolved":false,"resolvedAt":null,"resolvedBy":null}}}}},"400":{"description":"body is missing or too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The post is not waiting for approval, so it has no review notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"resolvePostReviewNotes","summary":"Resolve Post Review Notes","description":"Marks review notes resolved, or reopens them.","tags":["Review Notes"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The ID (UUID) of a post waiting for approval","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"noteIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"description":"Up to 50 note IDs from the list endpoint"},"resolved":{"type":"boolean","description":"true to resolve, false to reopen"}},"required":["noteIds","resolved"],"additionalProperties":false},"example":{"noteIds":["b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d"],"resolved":true}}}},"responses":{"200":{"description":"Every note on the content, after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contentId":{"type":"string","description":"The post or comment the notes are on"},"openCount":{"type":"integer","description":"Notes not yet resolved"},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Note ID (UUID)"},"onReply":{"type":"boolean","description":"True when the note is on a reply under the post, not the post itself"},"replyTo":{"type":"string","nullable":true,"description":"The note this one answers, for our team's replies"},"body":{"type":"string","description":"The note"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"resolved":{"type":"boolean","description":"Whether the note is resolved"},"resolvedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"resolvedBy":{"type":"string","nullable":true,"description":"Who resolved it"}},"required":["id","onReply","replyTo","body","createdAt","resolved","resolvedAt","resolvedBy"],"additionalProperties":false}}},"required":["contentId","openCount","notes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"contentId":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14","openCount":0,"notes":[{"id":"b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d","onReply":false,"replyTo":null,"body":"Can we make the title shorter?","createdAt":"2026-11-14T10:02:00Z","resolved":true,"resolvedAt":"2026-11-15T09:00:00Z","resolvedBy":"Jordan"}]}}}}},"400":{"description":"noteIds is empty or holds an unknown ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No post with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The post is not waiting for approval, so it has no review notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/comments/{id}/review-notes":{"get":{"operationId":"listCommentReviewNotes","summary":"List Comment Review Notes","description":"Lists the review notes on a comment waiting for your approval, with our team's replies.","tags":["Review Notes"],"security":[{"bearerAuth":["comments:read"]}],"x-required-scope":"comments:read","parameters":[{"name":"id","in":"path","required":true,"description":"The ID (UUID) of a comment waiting for approval","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The notes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contentId":{"type":"string","description":"The post or comment the notes are on"},"openCount":{"type":"integer","description":"Notes not yet resolved"},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Note ID (UUID)"},"onReply":{"type":"boolean","description":"True when the note is on a reply under the post, not the post itself"},"replyTo":{"type":"string","nullable":true,"description":"The note this one answers, for our team's replies"},"body":{"type":"string","description":"The note"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"resolved":{"type":"boolean","description":"Whether the note is resolved"},"resolvedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"resolvedBy":{"type":"string","nullable":true,"description":"Who resolved it"}},"required":["id","onReply","replyTo","body","createdAt","resolved","resolvedAt","resolvedBy"],"additionalProperties":false}}},"required":["contentId","openCount","notes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"contentId":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14","openCount":1,"notes":[{"id":"b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d","onReply":false,"replyTo":null,"body":"Can we make the title shorter?","createdAt":"2026-11-14T10:02:00Z","resolved":false,"resolvedAt":null,"resolvedBy":null}]}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The comment is not waiting for approval, so it has no review notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"addCommentReviewNote","summary":"Add a Comment Review Note","description":"Leaves a note on a comment waiting for approval, asking our team for a change.","tags":["Review Notes"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"id","in":"path","required":true,"description":"The ID (UUID) of a comment waiting for approval","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000,"description":"The note, up to 5,000 characters"}},"required":["body"],"additionalProperties":false},"example":{"body":"Can we make the title shorter?"}}}},"responses":{"201":{"description":"The new note","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Note ID (UUID)"},"onReply":{"type":"boolean","description":"True when the note is on a reply under the post, not the post itself"},"replyTo":{"type":"string","nullable":true,"description":"The note this one answers, for our team's replies"},"body":{"type":"string","description":"The note"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"resolved":{"type":"boolean","description":"Whether the note is resolved"},"resolvedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"resolvedBy":{"type":"string","nullable":true,"description":"Who resolved it"}},"required":["id","onReply","replyTo","body","createdAt","resolved","resolvedAt","resolvedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d","onReply":false,"replyTo":null,"body":"Can we make the title shorter?","createdAt":"2026-11-14T10:02:00Z","resolved":false,"resolvedAt":null,"resolvedBy":null}}}}},"400":{"description":"body is missing or too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The comment is not waiting for approval, so it has no review notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"resolveCommentReviewNotes","summary":"Resolve Comment Review Notes","description":"Marks review notes resolved, or reopens them.","tags":["Review Notes"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"id","in":"path","required":true,"description":"The ID (UUID) of a comment waiting for approval","schema":{"type":"string"},"example":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"noteIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"description":"Up to 50 note IDs from the list endpoint"},"resolved":{"type":"boolean","description":"true to resolve, false to reopen"}},"required":["noteIds","resolved"],"additionalProperties":false},"example":{"noteIds":["b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d"],"resolved":true}}}},"responses":{"200":{"description":"Every note on the content, after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contentId":{"type":"string","description":"The post or comment the notes are on"},"openCount":{"type":"integer","description":"Notes not yet resolved"},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Note ID (UUID)"},"onReply":{"type":"boolean","description":"True when the note is on a reply under the post, not the post itself"},"replyTo":{"type":"string","nullable":true,"description":"The note this one answers, for our team's replies"},"body":{"type":"string","description":"The note"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"resolved":{"type":"boolean","description":"Whether the note is resolved"},"resolvedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"resolvedBy":{"type":"string","nullable":true,"description":"Who resolved it"}},"required":["id","onReply","replyTo","body","createdAt","resolved","resolvedAt","resolvedBy"],"additionalProperties":false}}},"required":["contentId","openCount","notes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"contentId":"3c9a1f2e-7b4d-4e8a-9f61-2d5c8b7a0e14","openCount":0,"notes":[{"id":"b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d","onReply":false,"replyTo":null,"body":"Can we make the title shorter?","createdAt":"2026-11-14T10:02:00Z","resolved":true,"resolvedAt":"2026-11-15T09:00:00Z","resolvedBy":"Jordan"}]}}}}},"400":{"description":"noteIds is empty or holds an unknown ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No comment with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The comment is not waiting for approval, so it has no review notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/review-batches":{"get":{"operationId":"listReviewBatches","summary":"List Review Batches","description":"Lists the batches of posts and comments our team wrote for you to review, newest first.","tags":["Review Batches"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of review batches","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Review batch ID"},"name":{"type":"string","description":"The batch's name"},"month":{"type":"string","description":"The month the batch is for, YYYY-MM-DD"},"status":{"type":"string","enum":["open","approved"],"description":"open while it is being reviewed, approved once signed off"},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"When it was approved"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"}},"required":["id","name","month","status","approvedAt","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01","name":"December Content","month":"2026-12-01","status":"open","approvedAt":null,"createdAt":"2026-11-20T15:00:00Z"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/review-batches/{id}":{"get":{"operationId":"getReviewBatch","summary":"Get a Review Batch","description":"Returns one review batch with every post and comment, how many notes are open on each, and the batch feedback.","tags":["Review Batches"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"id","in":"path","required":true,"description":"The review batch ID from List Review Batches","schema":{"type":"string"},"example":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The batch","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Review batch ID"},"name":{"type":"string","description":"The batch's name"},"month":{"type":"string","description":"The month the batch is for, YYYY-MM-DD"},"status":{"type":"string","enum":["open","approved"],"description":"open while it is being reviewed, approved once signed off"},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"When it was approved"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Item ID"},"kind":{"type":"string","enum":["post","comment"],"description":"post or comment"},"parentId":{"type":"string","format":"uuid","nullable":true,"description":"For a comment, the item it replies to"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair"},"status":{"type":"string","enum":["pending","approved","approvedWithChanges"],"description":"pending, approved, or approvedWithChanges (approved once the requested edits are made)"},"openNotes":{"type":"integer","description":"Review notes on this item that are not resolved yet"}},"required":["id","kind","parentId","title","body","subreddit","flair","status","openNotes"],"additionalProperties":false},"description":"Every post and comment, posts first with their comments after"},"feedback":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Feedback ID"},"body":{"type":"string","description":"The feedback"},"createdAt":{"type":"string","format":"date-time","description":"When it was left"},"resolved":{"type":"boolean","description":"True once our team has addressed it"}},"required":["id","body","createdAt","resolved"],"additionalProperties":false},"description":"Feedback on the batch as a whole, oldest first"}},"required":["id","name","month","status","approvedAt","createdAt","items","feedback"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01","name":"December Content","month":"2026-12-01","status":"open","approvedAt":null,"createdAt":"2026-11-20T15:00:00Z","items":[{"id":"3f1e2d3c-4b5a-4968-8776-655443322110","kind":"post","parentId":null,"title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":null,"status":"pending","openNotes":1}],"feedback":[{"id":"9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a","body":"Lean more on the pricing angle this month.","createdAt":"2026-11-21T10:00:00Z","resolved":false}]}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No review batch with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/review-batches/{id}/approve":{"post":{"operationId":"approveReviewBatch","summary":"Approve a Review Batch","description":"Approves the whole batch, or only the items you list and their comments. Approved content goes on the schedule.","tags":["Review Batches"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The review batch ID from List Review Batches","schema":{"type":"string"},"example":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"description":"Approve only these items and their comments. Leave out to approve the whole batch"}},"additionalProperties":false},"example":{"itemIds":["3f1e2d3c-4b5a-4968-8776-655443322110"]}}}},"responses":{"200":{"description":"What was approved and the batch's status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"approvedItemIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Items approved by this call"},"batchStatus":{"type":"string","enum":["open","approved"],"description":"The batch's status afterwards"}},"required":["approvedItemIds","batchStatus"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"approvedItemIds":["3f1e2d3c-4b5a-4968-8776-655443322110"],"batchStatus":"open"}}}}},"400":{"description":"An item ID is not in this batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No review batch with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The batch is being rewritten, or changed while you were approving it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/review-batches/{id}/feedback":{"post":{"operationId":"addBatchFeedback","summary":"Leave Batch Feedback","description":"Leaves feedback on the batch as a whole, for changes that span many posts. Our team sees it on the review page.","tags":["Review Batches"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The review batch ID from List Review Batches","schema":{"type":"string"},"example":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000,"description":"The feedback, up to 5,000 characters"}},"required":["body"],"additionalProperties":false},"example":{"body":"Lean more on the pricing angle this month."}}}},"responses":{"201":{"description":"The feedback as saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Feedback ID"},"body":{"type":"string","description":"The feedback"},"createdAt":{"type":"string","format":"date-time","description":"When it was left"},"resolved":{"type":"boolean","description":"True once our team has addressed it"}},"required":["id","body","createdAt","resolved"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a","body":"Lean more on the pricing angle this month.","createdAt":"2026-11-21T10:00:00Z","resolved":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No review batch with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"The batch is being rewritten","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/review-batches/{id}/share-link":{"get":{"operationId":"getReviewLink","summary":"Get a Review Link","description":"Returns the batch's review page link to share with your team. Anyone with the link can read the batch and leave notes, without signing in.","tags":["Review Batches"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"id","in":"path","required":true,"description":"The review batch ID from List Review Batches","schema":{"type":"string"},"example":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The review link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"batchId":{"type":"string","format":"uuid","description":"Review batch ID"},"url":{"type":"string","format":"uri","description":"The review page. Anyone with this link can read the batch and leave notes, without signing in"}},"required":["batchId","url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"batchId":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01","url":"https://app.tryredrover.com/share/review/8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01?token=Qm9vc3RjYW1wUmV2aWV3TGluaw"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No review batch with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"resetReviewLink","summary":"Reset a Review Link","description":"Replaces the batch's review link with a new one. Every earlier link stops working, including any our team sent.","tags":["Review Batches"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"id","in":"path","required":true,"description":"The review batch ID from List Review Batches","schema":{"type":"string"},"example":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The new review link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"batchId":{"type":"string","format":"uuid","description":"Review batch ID"},"url":{"type":"string","format":"uri","description":"The review page. Anyone with this link can read the batch and leave notes, without signing in"}},"required":["batchId","url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"batchId":"8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01","url":"https://app.tryredrover.com/share/review/8d0f6a52-3c1e-4b7a-9e2f-5a6b7c8d9e01?token=Qm9vc3RjYW1wUmV2aWV3TGluaw"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No review batch with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/analytics/reddit":{"get":{"operationId":"getRedditPerformance","summary":"Get Reddit Performance","description":"Reddit results for a window: totals, a daily series and the top posts and comments.\n\nSend days for a rolling window ending today, or startDate and endDate for calendar dates (both inclusive, UTC). Windows run up to 365 days; the default is the last 30.","tags":["Analytics"],"security":[{"bearerAuth":["analytics:read"]}],"x-required-scope":"analytics:read","parameters":[{"name":"days","in":"query","required":false,"description":"A rolling window of 1 to 365 days ending today","schema":{"type":"integer","minimum":1,"maximum":365}},{"name":"startDate","in":"query","required":false,"description":"First day, like 2026-10-01. Send with endDate","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"endDate","in":"query","required":false,"description":"Last day, like 2026-10-31. Send with startDate","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Results for the window","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"window":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["startDate","endDate"],"additionalProperties":false,"description":"The window reported on"},"totals":{"type":"object","properties":{"posts":{"type":"number"},"comments":{"type":"number"},"upvotes":{"type":"number"},"impressions":{"type":"number"},"repliesOnPosts":{"type":"number"}},"required":["posts","comments","upvotes","impressions","repliesOnPosts"],"additionalProperties":false},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"posts":{"type":"number"},"comments":{"type":"number"},"upvotes":{"type":"number"},"impressions":{"type":"number"}},"required":["date","posts","comments","upvotes","impressions"],"additionalProperties":false}},"topContent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Same ID the posts and comments endpoints use"},"type":{"type":"string","enum":["post","comment"]},"subreddit":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"excerpt":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"upvotes":{"type":"number"},"replies":{"type":"number"},"postedAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"}},"required":["id","type","subreddit","title","excerpt","url","upvotes","replies","postedAt"],"additionalProperties":false}}},"required":["window","totals","daily","topContent"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"window":{"startDate":"2026-10-17","endDate":"2026-11-15"},"totals":{"posts":12,"comments":48,"upvotes":1310,"impressions":86200,"repliesOnPosts":97},"daily":[{"date":"2026-11-14","posts":1,"comments":2,"upvotes":64,"impressions":4100}],"topContent":[{"id":"48213","type":"post","subreddit":"startups","title":"What we learned shipping a weekly changelog for a year","excerpt":"We started writing a public changelog every Friday...","url":"https://www.reddit.com/r/startups/comments/1abcde2/","upvotes":412,"replies":58,"postedAt":"2026-11-02T15:00:04Z"}]}}}}},"400":{"description":"The window is invalid or longer than allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/analytics/ai-visibility":{"get":{"operationId":"getAiVisibility","summary":"Get AI Search Visibility","description":"How often AI assistants mention and cite your brand: scores, per-platform results, competitors, a trend and the top prompts checked.","tags":["Analytics"],"security":[{"bearerAuth":["analytics:read"]}],"x-required-scope":"analytics:read","parameters":[{"name":"days","in":"query","required":false,"description":"How many days back to report on, 1 to 365 (default 30)","schema":{"type":"integer","minimum":1,"maximum":365,"default":30}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Visibility for the window","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"hasData":{"type":"boolean","description":"False until the workspace's first AI search check has run"},"lastUpdated":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"scores":{"type":"object","properties":{"overall":{"type":"number","description":"Overall visibility score, 0 to 100"},"mentionRate":{"type":"number","description":"Share of answers naming the brand"},"citationRate":{"type":"number","nullable":true},"ownedCitationRate":{"type":"number","nullable":true},"earnedCitationRate":{"type":"number","nullable":true},"shareOfVoice":{"type":"number","nullable":true},"aiSearchVolume":{"type":"number","nullable":true}},"required":["overall","mentionRate","citationRate","ownedCitationRate","earnedCitationRate","shareOfVoice","aiSearchVolume"],"additionalProperties":false},"totals":{"type":"object","properties":{"mentions":{"type":"number"},"promptsChecked":{"type":"number"}},"required":["mentions","promptsChecked"],"additionalProperties":false},"sentiment":{"type":"object","properties":{"score":{"type":"number"},"positive":{"type":"number"},"neutral":{"type":"number"},"negative":{"type":"number"}},"required":["score","positive","neutral","negative"],"additionalProperties":false},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["chatgpt","claude","perplexity","gemini","copilot","google"],"description":"The AI assistant or search engine checked"},"mentioned":{"type":"boolean"},"mentionCount":{"type":"number"},"averagePosition":{"type":"number","nullable":true},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"nullable":true}},"required":["platform","mentioned","mentionCount","averagePosition","sentiment"],"additionalProperties":false}},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"mentionRate":{"type":"number"},"averagePosition":{"type":"number","nullable":true}},"required":["name","mentionRate","averagePosition"],"additionalProperties":false}},"trend":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"overallScore":{"type":"number"},"mentionRate":{"type":"number"},"shareOfVoice":{"type":"number"}},"required":["date","overallScore","mentionRate","shareOfVoice"],"additionalProperties":false}},"topPrompts":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string"},"platform":{"type":"string","enum":["chatgpt","claude","perplexity","gemini","copilot","google"],"description":"The AI assistant or search engine checked"},"mentioned":{"type":"boolean"},"position":{"type":"number","nullable":true},"checkedAt":{"type":"string","description":"ISO 8601 datetime"},"searchVolume":{"type":"number"},"topSources":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"url":{"type":"string"}},"required":["domain","url"],"additionalProperties":false}}},"required":["prompt","platform","mentioned","position","checkedAt","searchVolume","topSources"],"additionalProperties":false}}},"required":["hasData","lastUpdated","scores","totals","sentiment","platforms","competitors","trend","topPrompts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"hasData":true,"lastUpdated":"2026-11-15T06:00:00Z","scores":{"overall":62,"mentionRate":41,"citationRate":18,"ownedCitationRate":7,"earnedCitationRate":11,"shareOfVoice":23,"aiSearchVolume":5400},"totals":{"mentions":37,"promptsChecked":90},"sentiment":{"score":72,"positive":24,"neutral":11,"negative":2},"platforms":[{"platform":"chatgpt","mentioned":true,"mentionCount":14,"averagePosition":2.3,"sentiment":"positive"}],"competitors":[{"name":"Example Metrics","mentionRate":55,"averagePosition":1.8}],"trend":[{"date":"2026-11-15","overallScore":62,"mentionRate":41,"shareOfVoice":23}],"topPrompts":[{"prompt":"best product analytics tool for a small saas","platform":"chatgpt","mentioned":true,"position":2,"checkedAt":"2026-11-15T06:00:00Z","searchVolume":880,"topSources":[{"domain":"reddit.com","url":"https://www.reddit.com/r/SaaS/"}]}]}}}}},"400":{"description":"days is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"AI search tracking is not set up for this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/knowledge-documents/{slug}":{"get":{"operationId":"getKnowledgeDocument","summary":"Get Company Information","description":"Reads a knowledge document our team and our AI work from, like your company information.","tags":["Knowledge Base"],"security":[{"bearerAuth":["workspace:read"]}],"x-required-scope":"workspace:read","parameters":[{"name":"slug","in":"path","required":true,"description":"The document. Available today: company-information.","schema":{"type":"string"},"example":"company-information"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The current version of the document","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"slug":{"type":"string","description":"The document, like company-information"},"title":{"type":"string","description":"The document's name"},"content":{"type":"string","description":"The document text, in Markdown"},"version":{"type":"integer","description":"The current version. 0 until the document is first saved"},"updatedAt":{"type":"string","nullable":true,"description":"When it was last saved"}},"required":["slug","title","content","version","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"slug":"company-information","title":"Company Information","content":"# Acme Analytics\n\nProduct analytics for small SaaS teams. We help founders see which features drive retention...","version":4,"updatedAt":"2026-11-14T16:20:00Z"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"The slug is not one of company-information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"put":{"operationId":"updateKnowledgeDocument","summary":"Update Company Information","description":"Replaces a knowledge document's content, saved as a new version. Earlier versions are kept.\n\nSend the version you read as expectedVersion. If someone saved a newer version since, the request fails with 409 instead of overwriting it: read the document again, merge, and save.","tags":["Knowledge Base"],"security":[{"bearerAuth":["knowledge:write"]}],"x-required-scope":"knowledge:write","parameters":[{"name":"slug","in":"path","required":true,"description":"The document. Available today: company-information.","schema":{"type":"string"},"example":"company-information"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":200000,"description":"The whole document, in Markdown. Replaces the current text"},"expectedVersion":{"type":"integer","minimum":0,"description":"The version you read. The save is refused if a newer one exists"}},"required":["content"],"additionalProperties":false},"example":{"content":"# Acme Analytics\n\nProduct analytics for small SaaS teams. We help founders see which features drive retention...","expectedVersion":4}}}},"responses":{"200":{"description":"The document after the save","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"slug":{"type":"string","description":"The document, like company-information"},"title":{"type":"string","description":"The document's name"},"content":{"type":"string","description":"The document text, in Markdown"},"version":{"type":"integer","description":"The current version. 0 until the document is first saved"},"updatedAt":{"type":"string","nullable":true,"description":"When it was last saved"},"status":{"type":"string","enum":["saved","unchanged"],"description":"unchanged when the content matched the current version, so no version was added"}},"required":["slug","title","content","version","updatedAt","status"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"slug":"company-information","title":"Company Information","content":"# Acme Analytics\n\nProduct analytics for small SaaS teams. We help founders see which features drive retention...","version":5,"updatedAt":"2026-11-14T16:20:00Z","status":"saved"}}}}},"400":{"description":"content is empty or too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"The slug is not one of company-information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"A newer version was saved after expectedVersion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/knowledge-documents/{slug}/versions":{"get":{"operationId":"listKnowledgeDocumentVersions","summary":"List Document Versions","description":"Lists a knowledge document's saved versions, newest first.","tags":["Knowledge Base"],"security":[{"bearerAuth":["workspace:read"]}],"x-required-scope":"workspace:read","parameters":[{"name":"slug","in":"path","required":true,"description":"The document. Available today: company-information.","schema":{"type":"string"},"example":"company-information"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The versions, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"versionNumber":{"type":"integer"},"name":{"type":"string","nullable":true,"description":"The version's name, when it has one"},"savedAt":{"type":"string","description":"ISO 8601 datetime"},"restoredFromVersion":{"type":"integer","nullable":true,"description":"The version it was restored from, when it was a restore"}},"required":["versionNumber","name","savedAt","restoredFromVersion"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"versionNumber":4,"name":null,"savedAt":"2026-11-14T16:20:00Z","restoredFromVersion":null},{"versionNumber":3,"name":"Before rebrand","savedAt":"2026-10-30T09:05:00Z","restoredFromVersion":null}]}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"The slug is not one of company-information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/subreddit-bans":{"get":{"operationId":"listBannedSubreddits","summary":"List Banned Subreddits","description":"Lists the subreddits your content must never go to.","tags":["Knowledge Base"],"security":[{"bearerAuth":["workspace:read"]}],"x-required-scope":"workspace:read","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The banned subreddits","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"banned":{"type":"array","items":{"type":"string"},"description":"Subreddits your content must never go to, like r/example"}},"required":["banned"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"banned":["r/Entrepreneur","r/marketing"]}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"409":{"description":"The list can't be read right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"put":{"operationId":"setSubredditBan","summary":"Ban or Unban a Subreddit","description":"Bans a subreddit so none of your content goes there, or lifts the ban.","tags":["Knowledge Base"],"security":[{"bearerAuth":["knowledge:write"]}],"x-required-scope":"knowledge:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subreddit":{"type":"string","minLength":1,"maxLength":60,"description":"The subreddit, with or without r/. Letters, digits and underscores"},"banned":{"type":"boolean","description":"true to ban, false to lift the ban"}},"required":["subreddit","banned"],"additionalProperties":false},"example":{"subreddit":"r/marketing","banned":true}}}},"responses":{"200":{"description":"The banned list after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"banned":{"type":"array","items":{"type":"string"},"description":"Subreddits your content must never go to, like r/example"}},"required":["banned"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"banned":["r/Entrepreneur","r/marketing"]}}}}},"400":{"description":"subreddit is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"409":{"description":"The list can't be changed right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/keywords":{"get":{"operationId":"listKeywords","summary":"List Keywords","description":"Lists the keywords your campaign targets, with topic, cluster, search volume, difficulty and intent.","tags":["Keywords"],"security":[{"bearerAuth":["keywords:read"]}],"x-required-scope":"keywords:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of keywords","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Keyword ID (UUID)"},"keyword":{"type":"string"},"topic":{"type":"string","nullable":true,"description":"The topic it belongs to"},"cluster":{"type":"string","nullable":true,"description":"The keyword cluster"},"searchVolume":{"type":"number","nullable":true,"description":"Monthly search volume"},"difficulty":{"type":"number","nullable":true,"description":"Ranking difficulty, 0 to 100"},"intent":{"type":"string","nullable":true,"description":"Search intent"},"funnelStage":{"type":"string","nullable":true},"createdAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","keyword","topic","cluster","searchVolume","difficulty","intent","funnelStage","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"0b7e3f5a-2c4d-4e6f-9a1b-3c5d7e9f1a2b","keyword":"product analytics for startups","topic":"Product Analytics","cluster":"Analytics Tools","searchVolume":1900,"difficulty":38,"intent":"commercial","funnelStage":"consideration","createdAt":"2026-10-02T12:00:00Z"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/target-prompts":{"get":{"operationId":"listTargetPrompts","summary":"List Target Prompts","description":"Lists the questions people ask AI assistants that you want to show up for, with each one's visibility over the last 30 days.","tags":["Keywords"],"security":[{"bearerAuth":["keywords:read"]}],"x-required-scope":"keywords:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of target prompts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prompt ID (UUID)"},"prompt":{"type":"string","description":"The question people ask AI assistants"},"keyword":{"type":"string","nullable":true,"description":"The keyword it is grouped under; null while unassigned"},"funnelStage":{"type":"string","nullable":true},"branded":{"type":"boolean","description":"Whether the prompt names your brand"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"visibility":{"type":"object","properties":{"checks":{"type":"number","description":"AI assistant answers checked in the last 30 days"},"mentionRate":{"type":"number","nullable":true,"description":"Share of answers that mention your brand, 0 to 1"},"citationRate":{"type":"number","nullable":true,"description":"Share of answers that cite your site, 0 to 1"},"averagePosition":{"type":"number","nullable":true,"description":"Average position of your citation among the sources"}},"required":["checks","mentionRate","citationRate","averagePosition"],"additionalProperties":false}},"required":["id","prompt","keyword","funnelStage","branded","createdAt","visibility"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"5d2c8e41-9a7b-4f3e-8c6d-1b0a2e4f6c8d","prompt":"What is the best product analytics tool for a small SaaS?","keyword":"product analytics for startups","funnelStage":"consideration","branded":false,"createdAt":"2026-10-02T12:00:00Z","visibility":{"checks":42,"mentionRate":0.38,"citationRate":0.12,"averagePosition":2.4}}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"addTargetPrompts","summary":"Add Target Prompts","description":"Adds up to 20 prompts to track. We start checking them across AI assistants right away.\n\nPrompts the workspace already tracks are skipped and counted in duplicates. First results show up in List Target Prompts once the checks finish.","tags":["Keywords"],"security":[{"bearerAuth":["keywords:write"]}],"x-required-scope":"keywords:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"type":"string","minLength":3,"maxLength":500},"minItems":1,"maxItems":20,"description":"1 to 20 prompts, each 3 to 500 characters"}},"required":["prompts"],"additionalProperties":false},"example":{"prompts":["What is the best product analytics tool for a small SaaS?","How do I measure feature adoption?"]}}}},"responses":{"201":{"description":"What was saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"added":{"type":"integer","description":"Prompts saved"},"duplicates":{"type":"integer","description":"Prompts left out because the workspace already tracks them"},"promptIds":{"type":"array","items":{"type":"string"},"description":"IDs of the prompts saved"}},"required":["added","duplicates","promptIds"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"added":1,"duplicates":1,"promptIds":["5d2c8e41-9a7b-4f3e-8c6d-1b0a2e4f6c8d"]}}}}},"400":{"description":"prompts is empty, too long, or holds more than allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/target-prompts/{id}":{"delete":{"operationId":"retireTargetPrompt","summary":"Retire a Target Prompt","description":"Stops tracking a prompt. Its past results are kept.","tags":["Keywords"],"security":[{"bearerAuth":["keywords:write"]}],"x-required-scope":"keywords:write","parameters":[{"name":"id","in":"path","required":true,"description":"The prompt ID (UUID) from List Target Prompts","schema":{"type":"string"},"example":"5d2c8e41-9a7b-4f3e-8c6d-1b0a2e4f6c8d"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The retired prompt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"retired":{"type":"boolean","enum":[true]}},"required":["id","retired"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2c8e41-9a7b-4f3e-8c6d-1b0a2e4f6c8d","retired":true}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No tracked prompt with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/reports":{"get":{"operationId":"listReports","summary":"List Reports","description":"Lists the reports shared with you, newest first.","tags":["Reports"],"security":[{"bearerAuth":["reports:read"]}],"x-required-scope":"reports:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"type","in":"query","required":false,"description":"Only this kind: week-gameplan, weekly-summary, monthly-report or performance-report","schema":{"type":"string","enum":["week-gameplan","weekly-summary","monthly-report","performance-report"]}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of reports","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Report ID"},"type":{"type":"string","enum":["week-gameplan","weekly-summary","monthly-report","performance-report"],"description":"week-gameplan (the plan for a week), weekly-summary (what a week earned), monthly-report or performance-report"},"periodStart":{"type":"string","description":"First day the report covers, YYYY-MM-DD"},"periodEnd":{"type":"string","description":"Last day the report covers, YYYY-MM-DD"},"createdAt":{"type":"string","format":"date-time","description":"When the report was made"}},"required":["id","type","periodStart","periodEnd","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"4b7c1e2a-9d3f-4a5b-8c6d-7e8f9a0b1c2d","type":"weekly-summary","periodStart":"2026-11-09","periodEnd":"2026-11-15","createdAt":"2026-11-15T14:00:00Z"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"type, limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/reports/{id}":{"get":{"operationId":"getReport","summary":"Get a Report","description":"Returns one shared report with its sections.","tags":["Reports"],"security":[{"bearerAuth":["reports:read"]}],"x-required-scope":"reports:read","parameters":[{"name":"id","in":"path","required":true,"description":"The report ID from List Reports","schema":{"type":"string"},"example":"4b7c1e2a-9d3f-4a5b-8c6d-7e8f9a0b1c2d"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Report ID"},"type":{"type":"string","enum":["week-gameplan","weekly-summary","monthly-report","performance-report"],"description":"week-gameplan (the plan for a week), weekly-summary (what a week earned), monthly-report or performance-report"},"periodStart":{"type":"string","description":"First day the report covers, YYYY-MM-DD"},"periodEnd":{"type":"string","description":"Last day the report covers, YYYY-MM-DD"},"createdAt":{"type":"string","format":"date-time","description":"When the report was made"},"content":{"type":"object","additionalProperties":{},"description":"The report's sections, as stored when it was shared with you: the plan, highlights, wins, figures and so on"}},"required":["id","type","periodStart","periodEnd","createdAt","content"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"4b7c1e2a-9d3f-4a5b-8c6d-7e8f9a0b1c2d","type":"weekly-summary","periodStart":"2026-11-09","periodEnd":"2026-11-15","createdAt":"2026-11-15T14:00:00Z","content":{"fridayUpdate":{"highlights":["Two posts reached the top of r/startups this week"],"closingThought":"Next week we lean into the pricing questions."}}}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No shared report with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/mentions":{"get":{"operationId":"listMentions","summary":"List Mentions","description":"Lists Reddit posts and comments that mention you, your competitors or your topic, newest first.","tags":["Mentions"],"security":[{"bearerAuth":["mentions:read"]}],"x-required-scope":"mentions:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"days","in":"query","required":false,"description":"How many days back to look, 1 to 90 (default 30)","schema":{"type":"integer","minimum":1,"maximum":90}},{"name":"type","in":"query","required":false,"description":"Only direct, competitor or niche mentions","schema":{"type":"string","enum":["direct","competitor","niche"]}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of mentions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Mention ID"},"kind":{"type":"string","enum":["post","comment"],"description":"A Reddit post or a comment"},"title":{"type":"string","description":"The thread's title"},"text":{"type":"string","description":"The post or comment text that mentions you"},"subreddit":{"type":"string","description":"Subreddit, without r/"},"url":{"type":"string","description":"Link to the post or comment on Reddit"},"createdAt":{"type":"string","description":"When it was posted on Reddit"},"upvotes":{"type":"number","description":"Upvotes when last checked"},"commentCount":{"type":"number","description":"Replies in the thread when last checked"},"keywords":{"type":"array","items":{"type":"string"},"description":"Your tracked keywords it matched"},"types":{"type":"array","items":{"type":"string","enum":["direct","competitor","niche"]},"description":"direct (names you), competitor (names a competitor) or niche (your topic)"},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"description":"Tone toward you"},"relevance":{"type":"number","description":"How relevant it is to you, 0 to 100"},"status":{"type":"string","enum":["open","handled","dismissed"],"description":"open, handled (our team acted on it) or dismissed"}},"required":["id","kind","title","text","subreddit","url","createdAt","upvotes","commentCount","keywords","types","sentiment","relevance","status"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"post-81234","kind":"post","title":"Best tools for planning a weekly changelog?","text":"We tried a few, and one that kept coming up was yours.","subreddit":"startups","url":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","createdAt":"2026-11-14T09:30:00Z","upvotes":42,"commentCount":17,"keywords":["changelog"],"types":["direct"],"sentiment":"positive","relevance":86,"status":"open"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"days, type, limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/activity":{"get":{"operationId":"listActivity","summary":"List Activity","description":"Lists what recently happened to your content, newest first: posted, failed, cancelled, deleted or new replies.","tags":["Activity"],"security":[{"bearerAuth":["notifications:read"]}],"x-required-scope":"notifications:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"days","in":"query","required":false,"description":"How many days back to look, 1 to 30 (default 7)","schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","enum":["posted","failed","cancelled","deleted","new_replies"],"description":"posted (went live), failed (didn't go live or was removed), cancelled, deleted, or new_replies (people replied to it)"},"contentId":{"type":"string","nullable":true,"description":"The post or comment ID, for redrover_get_post or redrover_get_comment"},"contentType":{"type":"string","enum":["post","comment"],"nullable":true,"description":"post or comment"},"title":{"type":"string","nullable":true,"description":"The content's title or opening words"},"replyCount":{"type":"number","nullable":true,"description":"For new_replies, how many came in"},"at":{"type":"string","description":"When it happened"}},"required":["event","contentId","contentType","title","replyCount","at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"event":"posted","contentId":"48213","contentType":"post","title":"What we learned shipping a weekly changelog for a year","replyCount":null,"at":"2026-12-01T15:02:00Z"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"days, limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/strategy":{"get":{"operationId":"getStrategy","summary":"Get the Campaign Strategy","description":"Returns your campaign strategy brief: goals, priority subreddits, topics and the balance of direct and indirect content.","tags":["Strategy"],"security":[{"bearerAuth":["strategy:read"]}],"x-required-scope":"strategy:read","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The strategy brief","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string","description":"The campaign strategy brief in Markdown. Empty until our team writes it"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When it was last updated"}},"required":["content","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"content":"## Goals\n\nShow up in AI answers for changelog tools.","updatedAt":"2026-11-10T12:00:00Z"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/blog-campaigns":{"get":{"operationId":"listBlogCampaigns","summary":"List Blog Campaigns","description":"Lists your blog campaigns, newest first, with how many articles are written.","tags":["Strategy"],"security":[{"bearerAuth":["strategy:read"]}],"x-required-scope":"strategy:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of blog campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Blog campaign ID"},"name":{"type":"string","description":"The campaign's name"},"objective":{"type":"string","nullable":true,"description":"What the campaign is for"},"status":{"type":"string","description":"Where the campaign stands, like active or completed"},"cadenceDays":{"type":"number","nullable":true,"description":"Days between articles"},"startDate":{"type":"string","nullable":true,"description":"When it starts"},"endDate":{"type":"string","nullable":true,"description":"When it ends, if set"},"articles":{"type":"object","properties":{"planned":{"type":"number","description":"Articles in the campaign"},"done":{"type":"number","description":"Articles written"},"failed":{"type":"number","description":"Articles that could not be written"}},"required":["planned","done","failed"],"additionalProperties":false},"publishing":{"type":"boolean","description":"True when articles publish to your site automatically"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"}},"required":["id","name","objective","status","cadenceDays","startDate","endDate","articles","publishing","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"6a1b2c3d-4e5f-4a6b-9c7d-8e9f0a1b2c3d","name":"Q1 Changelog Guides","objective":"traffic","status":"active","cadenceDays":3,"startDate":"2026-12-01","endDate":"2027-02-28","articles":{"planned":30,"done":4,"failed":0},"publishing":true,"createdAt":"2026-11-20T15:00:00Z"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List Webhook Endpoints","description":"Lists the workspace's webhook endpoints, oldest first.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Every endpoint in the workspace. Secrets are never returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"workspaceId":{"type":"string","description":"The workspace whose events it gets"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added"],"description":"An event you can subscribe to"},"description":"The events it subscribes to"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","workspaceId","url","description","events","enabled","disabledReason","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","workspaceId":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","url":"https://example.com/hooks/redrover","description":"Post updates to our team channel","events":["post.posted","post.failed","comment.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-15T10:00:00Z","updatedAt":"2026-11-15T10:00:00Z"}]}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createWebhook","summary":"Create a Webhook Endpoint","description":"Adds an endpoint that gets the events you pick, and returns its signing secret once.\n\nStore secret right away: it is only in this response. Use it to verify each request.\n\nA workspace can have up to 10 endpoints. Webhooks need an API key; connected AI apps cannot manage them.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"Where we send events. Must be https and reach the public internet; private, loopback and cloud metadata addresses are refused"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added"]},"minItems":1,"description":"The events to send, like `post.posted`. See [Webhooks](/docs/webhooks) for the full list"},"description":{"type":"string","maxLength":200,"nullable":true,"description":"Your own note, up to 200 characters. null clears it"}},"required":["url","events"],"additionalProperties":false},"example":{"url":"https://example.com/hooks/redrover","events":["post.posted","post.failed","comment.posted"],"description":"Post updates to our team channel"}}}},"responses":{"201":{"description":"The new endpoint with its signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"workspaceId":{"type":"string","description":"The workspace whose events it gets"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added"],"description":"An event you can subscribe to"},"description":"The events it subscribes to"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"},"secret":{"type":"string","description":"The signing secret. Shown only in this response, so store it now"}},"required":["id","workspaceId","url","description","events","enabled","disabledReason","createdAt","updatedAt","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","workspaceId":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","url":"https://example.com/hooks/redrover","description":"Post updates to our team channel","events":["post.posted","post.failed","comment.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-15T10:00:00Z","updatedAt":"2026-11-15T10:00:00Z","secret":"whsec_3f9a1c7e5b2d8f4a6c0e9b1d7f3a5c8e2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a"}}}}},"400":{"description":"url is not https, cannot be found, or points to a private address. events is empty or names an unknown event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"409":{"description":"The workspace already has 10 endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/webhooks/{id}":{"get":{"operationId":"getWebhook","summary":"Get a Webhook Endpoint","description":"Reads one endpoint.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint ID from List Webhook Endpoints","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"workspaceId":{"type":"string","description":"The workspace whose events it gets"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added"],"description":"An event you can subscribe to"},"description":"The events it subscribes to"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","workspaceId","url","description","events","enabled","disabledReason","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","workspaceId":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","url":"https://example.com/hooks/redrover","description":"Post updates to our team channel","events":["post.posted","post.failed","comment.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-15T10:00:00Z","updatedAt":"2026-11-15T10:00:00Z"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No webhook endpoint with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"updateWebhook","summary":"Update a Webhook Endpoint","description":"Changes an endpoint's URL, events or description, or turns it off or back on.\n\nSend only the fields to change. Turning an endpoint back on with enabled: true clears its failure count. Events from while it was off are not resent.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint ID from List Webhook Endpoints","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"Where we send events. Must be https and reach the public internet; private, loopback and cloud metadata addresses are refused"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added"]},"minItems":1,"description":"The events to send, like `post.posted`. See [Webhooks](/docs/webhooks) for the full list"},"description":{"type":"string","maxLength":200,"nullable":true,"description":"Your own note, up to 200 characters. null clears it"},"enabled":{"type":"boolean","description":"false to stop sending events, true to start again"}},"additionalProperties":false},"example":{"enabled":true}}}},"responses":{"200":{"description":"The endpoint after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"workspaceId":{"type":"string","description":"The workspace whose events it gets"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added"],"description":"An event you can subscribe to"},"description":"The events it subscribes to"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","workspaceId","url","description","events","enabled","disabledReason","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","workspaceId":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","url":"https://example.com/hooks/redrover","description":"Post updates to our team channel","events":["post.posted","post.failed","comment.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-15T10:00:00Z","updatedAt":"2026-11-15T10:00:00Z"}}}}},"400":{"description":"url is not https, cannot be found, or points to a private address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No webhook endpoint with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a Webhook Endpoint","description":"Deletes an endpoint and drops any deliveries still waiting to retry.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint ID from List Webhook Endpoints","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Confirms the endpoint is gone","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","deleted":true}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No webhook endpoint with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/webhooks/{id}/test":{"post":{"operationId":"testWebhook","summary":"Send a Test Event","description":"Sends a signed webhook.test event to the endpoint right away and returns how it went.\n\nOne try, no retries. Works on endpoints that are turned off, so you can check a fix before turning one back on.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint ID from List Webhook Endpoints","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The delivery. status is succeeded when your endpoint answered with a 2xx","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Delivery ID, sent as RedRover-Delivery-Id"},"eventId":{"type":"string","description":"Event ID, the payload's id"},"eventType":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached","webhook.test"],"description":"The event type"},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"pending while retries remain"},"attempts":{"type":"integer","description":"Attempts made so far"},"responseStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint answered on the last attempt"},"error":{"type":"string","nullable":true,"description":"What went wrong on the last attempt"},"durationMs":{"type":"integer","nullable":true,"description":"How long the last attempt took"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"lastAttemptAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"nextAttemptAt":{"type":"string","nullable":true,"description":"When the next retry is due, while pending"}},"required":["id","eventId","eventType","status","attempts","responseStatus","error","durationMs","createdAt","lastAttemptAt","nextAttemptAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"0c4e8a2f-6b1d-4e3a-a5c7-9f2b4d6e8a1c","eventId":"e7a1c3f5-2b4d-4c6e-8f0a-1b3d5f7a9c2e","eventType":"webhook.test","status":"succeeded","attempts":1,"responseStatus":200,"error":null,"durationMs":184,"createdAt":"2026-11-15T15:01:04Z","lastAttemptAt":"2026-11-15T15:01:05Z","nextAttemptAt":null}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No webhook endpoint with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List Webhook Deliveries","description":"The endpoint's deliveries from the last 30 days, newest first.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint ID from List Webhook Endpoints","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"},{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Delivery ID, sent as RedRover-Delivery-Id"},"eventId":{"type":"string","description":"Event ID, the payload's id"},"eventType":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached","webhook.test"],"description":"The event type"},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"pending while retries remain"},"attempts":{"type":"integer","description":"Attempts made so far"},"responseStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint answered on the last attempt"},"error":{"type":"string","nullable":true,"description":"What went wrong on the last attempt"},"durationMs":{"type":"integer","nullable":true,"description":"How long the last attempt took"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"lastAttemptAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"nextAttemptAt":{"type":"string","nullable":true,"description":"When the next retry is due, while pending"}},"required":["id","eventId","eventType","status","attempts","responseStatus","error","durationMs","createdAt","lastAttemptAt","nextAttemptAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"0c4e8a2f-6b1d-4e3a-a5c7-9f2b4d6e8a1c","eventId":"e7a1c3f5-2b4d-4c6e-8f0a-1b3d5f7a9c2e","eventType":"post.posted","status":"succeeded","attempts":1,"responseStatus":200,"error":null,"durationMs":184,"createdAt":"2026-11-15T15:01:04Z","lastAttemptAt":"2026-11-15T15:01:05Z","nextAttemptAt":null}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No webhook endpoint with this ID in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/clients":{"get":{"operationId":"listClients","summary":"List Clients","description":"Lists your agency's clients, oldest first, including clients added after the key was made.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\nA sandbox key lists sandbox clients only.","tags":["Agency Partners"],"security":[{"bearerAuth":["clients:read"]}],"x-required-scope":"clients:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"reference","in":"query","required":false,"description":"Only the client with this reference","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of clients","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The client's workspace ID (UUID)"},"name":{"type":"string","description":"The client's name"},"reference":{"type":"string","nullable":true,"description":"Your own ID for the client, like a CRM record"},"contact":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Your contact's name"},"email":{"type":"string","nullable":true,"description":"Your contact's email"}},"required":["name","email"],"additionalProperties":false,"description":"Who you deal with at the client, for your records. Storing a contact sends no invite"},"sandbox":{"type":"boolean","description":"True for clients made with a sandbox key"},"createdAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","name","reference","contact","sandbox","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics","reference":"crm-1042","contact":{"name":"Jane Smith","email":"jane@acme.com"},"sandbox":false,"createdAt":"2026-11-16T10:00:00Z"}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"400":{"description":"limit or offset is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createClient","summary":"Add a Client","description":"Adds a client workspace under your agency, optionally with the client's own login.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\ncontact is who you deal with at the client, kept for your records. Storing it sends no invite.\n\nWith contactEmail, that person gets a client login to this workspace only: they can use it but never see billing or your other clients. No email is sent; you tell them how to sign in. It also becomes the contact's email when contact.email is not given.\n\nYour listeners get client.created. A sandbox key records a sandbox client instead, and nothing is created.","tags":["Agency Partners"],"security":[{"bearerAuth":["clients:write"]}],"x-required-scope":"clients:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The client's name, up to 200 characters"},"reference":{"type":"string","minLength":1,"maxLength":200,"description":"Your own ID for the client. Unique within your agency"},"contactEmail":{"type":"string","maxLength":320,"format":"email","description":"Adds this person as the client's own login"},"contact":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"nullable":true},"email":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string","maxLength":320,"format":"email","nullable":true}]},{"type":"string","enum":[""]}]}},"additionalProperties":false,"description":"Your contact at the client: `name` and `email`, both optional. No invite is sent"}},"required":["name"],"additionalProperties":false},"example":{"name":"Acme Analytics","reference":"crm-1042","contact":{"name":"Jane Smith","email":"jane@acme.com"}}}}},"responses":{"201":{"description":"The new client","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The client's workspace ID (UUID)"},"name":{"type":"string","description":"The client's name"},"reference":{"type":"string","nullable":true,"description":"Your own ID for the client, like a CRM record"},"contact":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Your contact's name"},"email":{"type":"string","nullable":true,"description":"Your contact's email"}},"required":["name","email"],"additionalProperties":false,"description":"Who you deal with at the client, for your records. Storing a contact sends no invite"},"sandbox":{"type":"boolean","description":"True for clients made with a sandbox key"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"invitedContactEmail":{"type":"string","nullable":true,"description":"The client login added with the client, when you sent one"}},"required":["id","name","reference","contact","sandbox","createdAt","invitedContactEmail"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics","reference":"crm-1042","contact":{"name":"Jane Smith","email":"jane@acme.com"},"sandbox":false,"createdAt":"2026-11-16T10:00:00Z","invitedContactEmail":null}}}}},"400":{"description":"name is missing or a field is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"409":{"description":"Another client already uses this name or reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/clients/{client}":{"get":{"operationId":"getClient","summary":"Get a Client","description":"Reads one client by workspace ID or by your reference.\n\nNeeds a partner key; any other key or a connected AI app gets 403.","tags":["Agency Partners"],"security":[{"bearerAuth":["clients:read"]}],"x-required-scope":"clients:read","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"}],"responses":{"200":{"description":"The client","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The client's workspace ID (UUID)"},"name":{"type":"string","description":"The client's name"},"reference":{"type":"string","nullable":true,"description":"Your own ID for the client, like a CRM record"},"contact":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Your contact's name"},"email":{"type":"string","nullable":true,"description":"Your contact's email"}},"required":["name","email"],"additionalProperties":false,"description":"Who you deal with at the client, for your records. Storing a contact sends no invite"},"sandbox":{"type":"boolean","description":"True for clients made with a sandbox key"},"createdAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","name","reference","contact","sandbox","createdAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics","reference":"crm-1042","contact":{"name":"Jane Smith","email":"jane@acme.com"},"sandbox":false,"createdAt":"2026-11-16T10:00:00Z"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"updateClient","summary":"Update a Client","description":"Renames a client or changes your reference or contact for it.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\nYour listeners get client.updated, with the previous name, reference and contact.","tags":["Agency Partners"],"security":[{"bearerAuth":["clients:write"]}],"x-required-scope":"clients:write","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The new name"},"reference":{"type":"string","minLength":1,"maxLength":200,"nullable":true,"description":"The new reference. null clears it"},"contact":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"nullable":true},"email":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string","maxLength":320,"format":"email","nullable":true}]},{"type":"string","enum":[""]}]}},"additionalProperties":false,"description":"The contact's `name` and `email`. A field left out stays; null clears it"}},"additionalProperties":false},"example":{"name":"Acme Analytics Inc."}}}},"responses":{"200":{"description":"The client after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The client's workspace ID (UUID)"},"name":{"type":"string","description":"The client's name"},"reference":{"type":"string","nullable":true,"description":"Your own ID for the client, like a CRM record"},"contact":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Your contact's name"},"email":{"type":"string","nullable":true,"description":"Your contact's email"}},"required":["name","email"],"additionalProperties":false,"description":"Who you deal with at the client, for your records. Storing a contact sends no invite"},"sandbox":{"type":"boolean","description":"True for clients made with a sandbox key"},"createdAt":{"type":"string","description":"ISO 8601 datetime"}},"required":["id","name","reference","contact","sandbox","createdAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","name":"Acme Analytics Inc.","reference":"crm-1042","contact":{"name":"Jane Smith","email":"jane@acme.com"},"sandbox":false,"createdAt":"2026-11-16T10:00:00Z"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"409":{"description":"Another client already uses this reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/clients/{client}/posts":{"get":{"operationId":"listClientPosts","summary":"List a Client's Posts","description":"Lists one client's posts, like List Posts with X-Workspace-Id.\n\nNeeds a partner key; any other key or a connected AI app gets 403.","tags":["Agency Partners"],"security":[{"bearerAuth":["posts:read"]}],"x-required-scope":"posts:read","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"},{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Only return content with this status","schema":{"type":"string","enum":["draft","pending_approval","scheduled","posted","failed","cancelled"]}}],"responses":{"200":{"description":"A page of posts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createClientPost","summary":"Schedule a Post for a Client","description":"Schedules a post for one client, with the same rules as Schedule a Post.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\nA sandbox key checks the post the same way, records it and answers with a simulated scheduled post. Nothing is published and no credits are used.","tags":["Agency Partners"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"description":"The post title"},"body":{"type":"string","minLength":1,"maxLength":40000,"description":"The post text"},"subreddit":{"type":"string","minLength":1,"maxLength":50,"pattern":"^\\/?(?:r\\/)?[A-Za-z0-9_]{2,24}\\/?$","description":"The subreddit, with or without r/"},"flair":{"type":"string","minLength":1,"maxLength":64,"description":"Post flair, when the subreddit asks for one"},"scheduledFor":{"type":"string","format":"date-time","description":"When it should go live, as an ISO 8601 datetime"}},"required":["title","body","subreddit","scheduledFor"],"additionalProperties":false},"example":{"title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"r/startups","scheduledFor":"2026-12-01T15:00:00Z"}}}},"responses":{"201":{"description":"The scheduled post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"400":{"description":"A field is missing or invalid, or scheduledFor is too soon","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"402":{"description":"The client doesn't have enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payment_required","message":"You're out of credits. This needs 32 credits and the workspace has 10. Top up at https://app.tryredrover.com/settings?tab=billing"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/clients/{client}/comments":{"get":{"operationId":"listClientComments","summary":"List a Client's Comments","description":"Lists one client's comments, like List Comments with X-Workspace-Id.\n\nNeeds a partner key; any other key or a connected AI app gets 403.","tags":["Agency Partners"],"security":[{"bearerAuth":["comments:read"]}],"x-required-scope":"comments:read","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"},{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Only return content with this status","schema":{"type":"string","enum":["draft","pending_approval","scheduled","posted","failed","cancelled"]}}],"responses":{"200":{"description":"A page of comments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"91574","type":"comment","status":"scheduled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createClientComment","summary":"Schedule a Comment for a Client","description":"Schedules a comment for one client, with the same rules as Schedule a Comment.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\nA sandbox key checks the comment the same way, records it and answers with a simulated scheduled comment. Nothing is published and no credits are used.","tags":["Agency Partners"],"security":[{"bearerAuth":["comments:write"]}],"x-required-scope":"comments:write","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"threadUrl":{"type":"string","pattern":"^https:\\/\\/(?:(?:www|old|new|np)\\.)?reddit\\.com\\/r\\/[\\w-]+\\/comments\\/[a-z0-9]+(?:[/?#]|$)","description":"The Reddit thread to reply in"},"body":{"type":"string","minLength":1,"maxLength":10000,"description":"The comment text"},"scheduledFor":{"type":"string","format":"date-time","description":"When it should go live, as an ISO 8601 datetime"}},"required":["threadUrl","body","scheduledFor"],"additionalProperties":false},"example":{"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","scheduledFor":"2026-12-01T15:00:00Z"}}}},"responses":{"201":{"description":"The scheduled comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"91574","type":"comment","status":"scheduled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}}}}},"400":{"description":"A field is missing or invalid, or scheduledFor is too soon","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"402":{"description":"The client doesn't have enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payment_required","message":"You're out of credits. This needs 32 credits and the workspace has 10. Top up at https://app.tryredrover.com/settings?tab=billing"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/agency/credits":{"get":{"operationId":"getAgencyCredits","summary":"Get Agency Credits","description":"Your agency's credit balance and what client caps set aside.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\nA sandbox key gets fixed figures with simulated: true.","tags":["Agency Partners"],"security":[{"bearerAuth":["credits:read"]}],"x-required-scope":"credits:read","parameters":[],"responses":{"200":{"description":"The agency's credits","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balance":{"type":"number","description":"Credits your agency has left"},"allocated":{"type":"number","description":"The sum of every client's monthly cap"},"lowBalanceThreshold":{"type":"number","description":"The balance below which credits.low fires: your auto top-up threshold, or 320 credits when you have none"},"simulated":{"type":"boolean","description":"True for sandbox keys"}},"required":["balance","allocated","lowBalanceThreshold","simulated"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"balance":4200,"allocated":1500,"lowBalanceThreshold":320,"simulated":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}},"503":{"description":"Credit balances are not available yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"The API is temporarily unavailable. Try again shortly."}}}}}}}},"/clients/{client}/credits":{"get":{"operationId":"getClientCredits","summary":"Get a Client's Credits","description":"One client's cap and what it used this period.\n\nNeeds a partner key; any other key or a connected AI app gets 403.","tags":["Agency Partners"],"security":[{"bearerAuth":["credits:read"]}],"x-required-scope":"credits:read","parameters":[{"name":"client","in":"path","required":true,"description":"The client's workspace ID, or your own reference for it. A UUID is tried as an ID first","schema":{"type":"string"},"example":"crm-1042"}],"responses":{"200":{"description":"The client's credits","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"clientId":{"type":"string","description":"The client's workspace ID"},"cap":{"type":"number","nullable":true,"description":"The client's cap, or null for none"},"usedThisPeriod":{"type":"number","description":"Credits the client used this period"},"capReached":{"type":"boolean","description":"True once the cap is used up"},"simulated":{"type":"boolean","description":"True for sandbox keys"}},"required":["clientId","cap","usedThisPeriod","capReached","simulated"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"clientId":"8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21","cap":600,"usedThisPeriod":240,"capReached":false,"simulated":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No client with this ID or reference in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}},"503":{"description":"Credit balances are not available yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"The API is temporarily unavailable. Try again shortly."}}}}}}}},"/agency/webhooks":{"get":{"operationId":"listAgencyWebhooks","summary":"List Agency Webhooks","description":"Lists your agency's listeners, which get events for every client.\n\nNeeds a partner key; any other key or a connected AI app gets 403.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read","parameters":[],"responses":{"200":{"description":"Every agency listener. Secrets are never returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"},"agencyId":{"type":"string","description":"Your agency's ID"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached"]},"description":"The events it subscribes to, client and agency events included"}},"required":["id","url","description","enabled","disabledReason","createdAt","updatedAt","agencyId","events"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","agencyId":"6a1e3c5b-7d9f-4b2a-8c4e-0f2a4c6e8b1d","url":"https://agency.example.com/hooks/redrover","description":"Sync clients to our CRM","events":["client.created","client.updated","credits.low","post.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-16T10:00:00Z","updatedAt":"2026-11-16T10:00:00Z"}]}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"post":{"operationId":"createAgencyWebhook","summary":"Create an Agency Webhook","description":"Adds a listener for all your clients' events, and returns its signing secret once.\n\nNeeds a partner key; any other key or a connected AI app gets 403.\n\nYour agency can have up to 10 listeners. Each event names the client in client (its ID and your reference). See Agency Partners.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"Where we send events. Must be https and reach the public internet"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached"]},"minItems":1,"description":"The events to send: any content event, plus client.created, client.updated, credits.low and client.cap_reached"},"description":{"type":"string","maxLength":200,"nullable":true,"description":"Your own note, up to 200 characters"}},"required":["url","events"],"additionalProperties":false},"example":{"url":"https://agency.example.com/hooks/redrover","events":["client.created","client.updated","credits.low","post.posted"],"description":"Sync clients to our CRM"}}}},"responses":{"201":{"description":"The new listener with its signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"},"agencyId":{"type":"string","description":"Your agency's ID"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached"]},"description":"The events it subscribes to, client and agency events included"},"secret":{"type":"string","description":"The signing secret. Shown only in this response, so store it now"}},"required":["id","url","description","enabled","disabledReason","createdAt","updatedAt","agencyId","events","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","agencyId":"6a1e3c5b-7d9f-4b2a-8c4e-0f2a4c6e8b1d","url":"https://agency.example.com/hooks/redrover","description":"Sync clients to our CRM","events":["client.created","client.updated","credits.low","post.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-16T10:00:00Z","updatedAt":"2026-11-16T10:00:00Z","secret":"whsec_3f9a1c7e5b2d8f4a6c0e9b1d7f3a5c8e2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a"}}}}},"400":{"description":"url is not https or points to a private address, or events is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"409":{"description":"Your agency already has 10 listeners","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/agency/webhooks/{id}":{"get":{"operationId":"getAgencyWebhook","summary":"Get an Agency Webhook","description":"Reads one agency listener.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read","parameters":[{"name":"id","in":"path","required":true,"description":"The listener ID from List Agency Webhooks","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"}],"responses":{"200":{"description":"The listener","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"},"agencyId":{"type":"string","description":"Your agency's ID"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached"]},"description":"The events it subscribes to, client and agency events included"}},"required":["id","url","description","enabled","disabledReason","createdAt","updatedAt","agencyId","events"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","agencyId":"6a1e3c5b-7d9f-4b2a-8c4e-0f2a4c6e8b1d","url":"https://agency.example.com/hooks/redrover","description":"Sync clients to our CRM","events":["client.created","client.updated","credits.low","post.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-16T10:00:00Z","updatedAt":"2026-11-16T10:00:00Z"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No listener with this ID in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"patch":{"operationId":"updateAgencyWebhook","summary":"Update an Agency Webhook","description":"Changes a listener's URL, events or note, or turns it off or back on.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"The listener ID from List Agency Webhooks","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"Where we send events. Must be https and reach the public internet"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached"]},"minItems":1,"description":"The events to send: any content event, plus client.created, client.updated, credits.low and client.cap_reached"},"description":{"type":"string","maxLength":200,"nullable":true,"description":"Your own note. null clears it"},"enabled":{"type":"boolean","description":"false turns the listener off; true turns it back on and clears its failure streak"}},"additionalProperties":false},"example":{"enabled":true}}}},"responses":{"200":{"description":"The listener after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Webhook endpoint ID (UUID)"},"url":{"type":"string","description":"Where we send events. Always https"},"description":{"type":"string","nullable":true,"description":"Your note about the endpoint"},"enabled":{"type":"boolean","description":"False when turned off, by you or after repeated failures"},"disabledReason":{"type":"string","nullable":true,"description":"Why we turned the endpoint off, when we did"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"updatedAt":{"type":"string","description":"ISO 8601 datetime"},"agencyId":{"type":"string","description":"Your agency's ID"},"events":{"type":"array","items":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached"]},"description":"The events it subscribes to, client and agency events included"}},"required":["id","url","description","enabled","disabledReason","createdAt","updatedAt","agencyId","events"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","agencyId":"6a1e3c5b-7d9f-4b2a-8c4e-0f2a4c6e8b1d","url":"https://agency.example.com/hooks/redrover","description":"Sync clients to our CRM","events":["client.created","client.updated","credits.low","post.posted"],"enabled":true,"disabledReason":null,"createdAt":"2026-11-16T10:00:00Z","updatedAt":"2026-11-16T10:00:00Z"}}}}},"400":{"description":"A field is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No listener with this ID in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}},"delete":{"operationId":"deleteAgencyWebhook","summary":"Delete an Agency Webhook","description":"Removes a listener and its delivery history.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"The listener ID from List Agency Webhooks","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"}],"responses":{"200":{"description":"The listener is gone","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93","deleted":true}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No listener with this ID in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/agency/webhooks/{id}/test":{"post":{"operationId":"testAgencyWebhook","summary":"Send a Test Event to an Agency Webhook","description":"Sends a webhook.test event right away and returns how it went.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"The listener ID from List Agency Webhooks","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"}],"responses":{"200":{"description":"The test delivery","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Delivery ID, sent as RedRover-Delivery-Id"},"eventId":{"type":"string","description":"Event ID, the payload's id"},"eventType":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached","webhook.test"],"description":"The event type"},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"pending while retries remain"},"attempts":{"type":"integer","description":"Attempts made so far"},"responseStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint answered on the last attempt"},"error":{"type":"string","nullable":true,"description":"What went wrong on the last attempt"},"durationMs":{"type":"integer","nullable":true,"description":"How long the last attempt took"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"lastAttemptAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"nextAttemptAt":{"type":"string","nullable":true,"description":"When the next retry is due, while pending"}},"required":["id","eventId","eventType","status","attempts","responseStatus","error","durationMs","createdAt","lastAttemptAt","nextAttemptAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"0c4e8a2f-6b1d-4e3a-a5c7-9f2b4d6e8a1c","eventId":"e7a1c3f5-2b4d-4c6e-8f0a-1b3d5f7a9c2e","eventType":"webhook.test","status":"succeeded","attempts":1,"responseStatus":200,"error":null,"durationMs":184,"createdAt":"2026-11-15T15:01:04Z","lastAttemptAt":"2026-11-15T15:01:05Z","nextAttemptAt":null}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No listener with this ID in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/agency/webhooks/{id}/deliveries":{"get":{"operationId":"listAgencyWebhookDeliveries","summary":"List Agency Webhook Deliveries","description":"The listener's deliveries from the last 30 days, newest first.","tags":["Agency Partners"],"security":[{"bearerAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read","parameters":[{"name":"id","in":"path","required":true,"description":"The listener ID from List Agency Webhooks","schema":{"type":"string"},"example":"5d2f8a1c-4b6e-4f3a-9d7c-1e8b2a6f0c93"},{"name":"limit","in":"query","required":false,"description":"How many results to return, 1 to 100 (default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"How many results to skip (default 0)","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Delivery ID, sent as RedRover-Delivery-Id"},"eventId":{"type":"string","description":"Event ID, the payload's id"},"eventType":{"type":"string","enum":["post.scheduled","post.posted","post.failed","post.needs_approval","post.cancelled","comment.scheduled","comment.posted","comment.failed","comment.needs_approval","comment.cancelled","review.note_added","client.created","client.updated","credits.low","client.cap_reached","webhook.test"],"description":"The event type"},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"pending while retries remain"},"attempts":{"type":"integer","description":"Attempts made so far"},"responseStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint answered on the last attempt"},"error":{"type":"string","nullable":true,"description":"What went wrong on the last attempt"},"durationMs":{"type":"integer","nullable":true,"description":"How long the last attempt took"},"createdAt":{"type":"string","description":"ISO 8601 datetime"},"lastAttemptAt":{"type":"string","nullable":true,"description":"ISO 8601 datetime"},"nextAttemptAt":{"type":"string","nullable":true,"description":"When the next retry is due, while pending"}},"required":["id","eventId","eventType","status","attempts","responseStatus","error","durationMs","createdAt","lastAttemptAt","nextAttemptAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response"},"offset":{"type":"integer","description":"How many results were skipped"},"hasMore":{"type":"boolean","description":"True when more results follow at a higher offset"}},"required":["limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":"0c4e8a2f-6b1d-4e3a-a5c7-9f2b4d6e8a1c","eventId":"e7a1c3f5-2b4d-4c6e-8f0a-1b3d5f7a9c2e","eventType":"client.created","status":"succeeded","attempts":1,"responseStatus":200,"error":null,"durationMs":184,"createdAt":"2026-11-15T15:01:04Z","lastAttemptAt":"2026-11-15T15:01:05Z","nextAttemptAt":null}],"pagination":{"limit":25,"offset":0,"hasMore":false}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"404":{"description":"No listener with this ID in your agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Post not found"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/content/check":{"post":{"operationId":"checkContent","summary":"Check Content","description":"Runs our writing checks on one post or comment and returns what they flag. Fast, and uses no AI credits.","tags":["Content Tools"],"security":[{"bearerAuth":["workspace:read"]}],"x-required-scope":"workspace:read","parameters":[{"name":"X-Workspace-Id","in":"header","required":false,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"title":{"type":"string","minLength":1,"maxLength":300,"description":"Post title. Required for posts, not allowed on comments"},"body":{"type":"string","minLength":1,"maxLength":40000,"description":"The text: up to 40,000 characters for posts, 10,000 for comments"},"subreddit":{"type":"string","minLength":1,"maxLength":50,"description":"The subreddit it is meant for, which helps the checks"}},"required":["type","body"],"additionalProperties":false},"example":{"type":"post","title":"What we learned shipping a weekly changelog","body":"We started writing a public changelog & it changed how we plan.","subreddit":"startups"}}}},"responses":{"200":{"description":"What the checks found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"passed":{"type":"boolean","description":"True when no check flagged anything"},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","description":"The check that flagged it, like long-dash"},"field":{"type":"string","enum":["title","body"]},"message":{"type":"string","description":"What to fix"},"span":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"}},"required":["start","end","text"],"additionalProperties":false,"nullable":true,"description":"Where in the field, when the check can point at it"}},"required":["rule","field","message","span"],"additionalProperties":false}}},"required":["passed","findings"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"passed":false,"findings":[{"rule":"ampersand","field":"body","message":"Write out and instead of using an ampersand","span":{"start":41,"end":42,"text":"&"}}]}}}}},"400":{"description":"The content is missing a field or too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/content/reddify":{"post":{"operationId":"rewriteContent","summary":"Rewrite Content","description":"Rewrites one post or comment so it reads like a person wrote it for Reddit, then checks and revises it.\n\nA rewrite can take up to a few minutes. Give your HTTP client a timeout of at least 5 minutes.","tags":["Content Tools"],"security":[{"bearerAuth":["workspace:write"]}],"x-required-scope":"workspace:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":false,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"title":{"type":"string","minLength":1,"maxLength":300,"description":"Post title. Required for posts, not allowed on comments"},"body":{"type":"string","minLength":1,"maxLength":40000,"description":"The text: up to 40,000 characters for posts, 10,000 for comments"},"subreddit":{"type":"string","minLength":1,"maxLength":50,"description":"The subreddit it is meant for, which helps the checks"}},"required":["type","body"],"additionalProperties":false},"example":{"type":"post","title":"What we learned shipping a weekly changelog","body":"We started writing a public changelog every Friday. It changed how we plan."}}}},"responses":{"200":{"description":"The rewritten content and what the checks still flag","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","enum":["post","comment"]},"title":{"type":"string","description":"The rewritten title. Posts only"},"body":{"type":"string","description":"The rewritten body"},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","description":"The check that flagged it, like long-dash"},"field":{"type":"string","enum":["title","body"]},"message":{"type":"string","description":"What to fix"},"span":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"}},"required":["start","end","text"],"additionalProperties":false,"nullable":true,"description":"Where in the field, when the check can point at it"}},"required":["rule","field","message","span"],"additionalProperties":false},"description":"What the checks still flag"},"passed":{"type":"boolean"},"passes":{"type":"integer","description":"Rewrite passes it took, at most 3"}},"required":["type","body","findings","passed","passes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"type":"post","title":"What a year of weekly changelogs taught us","body":"We started posting a changelog every Friday. A few things surprised us...","findings":[],"passed":true,"passes":1}}}}},"400":{"description":"The content is invalid, or could not be rewritten","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}},"503":{"description":"The rewrite could not run right now. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"The API is temporarily unavailable. Try again shortly."}}}}}}}},"/content/batches/preview":{"post":{"operationId":"previewContentBatch","summary":"Preview a Bulk Schedule","description":"Checks and prices up to 50 posts and comments at once, without scheduling anything.\n\nEvery item gets its own list of errors, so you can fix them all in one go. Once every item is valid and the workspace has the credits, the response carries a confirmToken.\n\nSchedule the batch with Confirm a Bulk Schedule, sending the same items and that token within 30 minutes.\n\nA batch with comments in it also needs the comments:write scope.","tags":["Content Tools"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","minLength":1,"maxLength":40000},"subreddit":{"type":"string","minLength":1,"maxLength":50,"pattern":"^\\/?(?:r\\/)?[A-Za-z0-9_]{2,24}\\/?$"},"flair":{"type":"string","minLength":1,"maxLength":64},"scheduledFor":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["post"]}},"required":["title","body","subreddit","scheduledFor","type"],"additionalProperties":false},{"type":"object","properties":{"threadUrl":{"type":"string","pattern":"^https:\\/\\/(?:(?:www|old|new|np)\\.)?reddit\\.com\\/r\\/[\\w-]+\\/comments\\/[a-z0-9]+(?:[/?#]|$)"},"body":{"type":"string","minLength":1,"maxLength":10000},"scheduledFor":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["comment"]}},"required":["threadUrl","body","scheduledFor","type"],"additionalProperties":false}]},"minItems":1,"maxItems":50,"description":"Up to 50 posts and comments. Each is the body you'd send to Schedule a Post or Schedule a Comment, plus `type`: `post` or `comment`"}},"required":["items"],"additionalProperties":false},"example":{"items":[{"type":"post","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","scheduledFor":"2026-12-01T15:00:00Z"},{"type":"comment","threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","scheduledFor":"2026-12-01T15:00:00Z"}]}}}},"responses":{"200":{"description":"Each item's verdict, the total credits and, when the batch is good, a confirm token","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position in the items you sent, from 0"},"type":{"type":"string","enum":["post","comment"],"nullable":true,"description":"post or comment. Null when the type itself is missing"},"ok":{"type":"boolean","description":"True when the item can be scheduled as sent"},"errors":{"type":"array","items":{"type":"string"},"description":"What to fix before this item can be scheduled"},"credits":{"type":"integer","description":"Credits this item will take once scheduled"},"scheduledFor":{"type":"string","format":"date-time","nullable":true,"description":"When it would go live, when the time is valid"}},"required":["index","type","ok","errors","credits","scheduledFor"],"additionalProperties":false}},"ok":{"type":"boolean","description":"True when every item is valid and the credits cover the batch"},"totalCredits":{"type":"integer","description":"Credits the whole batch will take"},"creditShortfall":{"type":"object","properties":{"needed":{"type":"integer"},"available":{"type":"integer"}},"required":["needed","available"],"additionalProperties":false,"nullable":true,"description":"Set when the workspace doesn't have enough credits"},"confirmToken":{"type":"string","nullable":true,"description":"Pass this with the same items to confirm. Null until every item is valid"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When the confirm token stops working"}},"required":["items","ok","totalCredits","creditShortfall","confirmToken","expiresAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"items":[{"index":0,"type":"post","ok":true,"errors":[],"credits":32,"scheduledFor":"2026-12-01T15:00:00.000Z"},{"index":1,"type":"comment","ok":true,"errors":[],"credits":8,"scheduledFor":"2026-12-01T15:00:00.000Z"}],"ok":true,"totalCredits":40,"creditShortfall":null,"confirmToken":"eyJ2IjoxLCJoIjoiNGYyYSIsImV4cCI6MTc2NDYwMTIwMDAwMH0","expiresAt":"2026-11-30T15:30:00.000Z"}}}}},"400":{"description":"items is missing, empty, or longer than 50","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/content/batches/confirm":{"post":{"operationId":"confirmContentBatch","summary":"Confirm a Bulk Schedule","description":"Schedules a previewed batch, all or nothing.\n\nSend the same items you previewed with their confirmToken, and an Idempotency-Key header holding any unique string. Retrying with the same key returns the first result instead of scheduling the batch twice.\n\nEvery check runs again before anything is written, so an item whose time is now less than 5 minutes away fails the confirm. If any item can't be scheduled, the ones already created are cancelled and their credits returned.","tags":["Content Tools"],"security":[{"bearerAuth":["posts:write"]}],"x-required-scope":"posts:write","parameters":[{"name":"X-Workspace-Id","in":"header","required":true,"description":"The workspace to act on, from List Workspaces. Optional when the key can reach exactly one workspace","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmToken":{"type":"string","minLength":1,"maxLength":2000,"description":"The token from the preview of these exact items"},"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","minLength":1,"maxLength":40000},"subreddit":{"type":"string","minLength":1,"maxLength":50,"pattern":"^\\/?(?:r\\/)?[A-Za-z0-9_]{2,24}\\/?$"},"flair":{"type":"string","minLength":1,"maxLength":64},"scheduledFor":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["post"]}},"required":["title","body","subreddit","scheduledFor","type"],"additionalProperties":false},{"type":"object","properties":{"threadUrl":{"type":"string","pattern":"^https:\\/\\/(?:(?:www|old|new|np)\\.)?reddit\\.com\\/r\\/[\\w-]+\\/comments\\/[a-z0-9]+(?:[/?#]|$)"},"body":{"type":"string","minLength":1,"maxLength":10000},"scheduledFor":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["comment"]}},"required":["threadUrl","body","scheduledFor","type"],"additionalProperties":false}]},"minItems":1,"maxItems":50,"description":"Up to 50 posts and comments. Each is the body you'd send to Schedule a Post or Schedule a Comment, plus `type`: `post` or `comment`"}},"required":["confirmToken","items"],"additionalProperties":false},"example":{"confirmToken":"eyJ2IjoxLCJoIjoiNGYyYSIsImV4cCI6MTc2NDYwMTIwMDAwMH0","items":[{"type":"post","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","scheduledFor":"2026-12-01T15:00:00Z"},{"type":"comment","threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","scheduledFor":"2026-12-01T15:00:00Z"}]}}}},"responses":{"201":{"description":"Every scheduled item, in the order sent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"scheduled":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Content ID. Content waiting for your approval has a UUID; scheduled content has a number"},"type":{"type":"string","enum":["post","comment"],"description":"post or comment"},"status":{"type":"string","enum":["draft","pending_approval","approved","scheduled","posted","failed","cancelled"],"description":"Where it stands"},"title":{"type":"string","nullable":true,"description":"Post title. Null for comments"},"body":{"type":"string","nullable":true,"description":"The text"},"subreddit":{"type":"string","nullable":true,"description":"Subreddit, without r/"},"flair":{"type":"string","nullable":true,"description":"Post flair. Posts only"},"threadUrl":{"type":"string","nullable":true,"description":"Comments only: the thread the comment replies in"},"scheduledFor":{"type":"string","nullable":true,"description":"When it is due to go live"},"postedAt":{"type":"string","nullable":true,"description":"When it went live"},"url":{"type":"string","nullable":true,"description":"The live link once posted"},"upvotes":{"type":"number","nullable":true,"description":"Upvotes once posted"},"commentCount":{"type":"number","nullable":true,"description":"Replies once posted"},"failureReason":{"type":"string","nullable":true,"description":"Why it failed or was removed, when it did"},"canChange":{"type":"boolean","description":"Whether you can still edit, reschedule or cancel it"}},"required":["id","type","status","title","body","subreddit","flair","threadUrl","scheduledFor","postedAt","url","upvotes","commentCount","failureReason","canChange"],"additionalProperties":false},"description":"The scheduled items, in the order sent"},"totalCredits":{"type":"integer","description":"Credits the batch took"}},"required":["scheduled","totalCredits"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"scheduled":[{"id":"48213","type":"post","status":"scheduled","title":"What we learned shipping a weekly changelog for a year","body":"We started writing a public changelog every Friday. Here is what changed for us...","subreddit":"startups","flair":"Lessons Learned","threadUrl":null,"scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true},{"id":"91574","type":"comment","status":"scheduled","title":null,"body":"We batch ours on Thursdays and ship Friday morning. Keeps it honest.","subreddit":"startups","flair":null,"threadUrl":"https://www.reddit.com/r/startups/comments/1abcde2/how_do_you_plan_content/","scheduledFor":"2026-12-01T15:00:00Z","postedAt":null,"url":null,"upvotes":null,"commentCount":null,"failureReason":null,"canChange":true}],"totalCredits":40}}}}},"400":{"description":"The Idempotency-Key header is missing, the token is invalid or expired, the items differ from the preview, or an item no longer passes its checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"scheduledFor: must be an ISO 8601 datetime"}}}}},"401":{"description":"The Authorization header is missing, or the key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"402":{"description":"The workspace no longer has enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payment_required","message":"You're out of credits. This needs 32 credits and the workspace has 10. Top up at https://app.tryredrover.com/settings?tab=billing"}}}}},"403":{"description":"The key lacks the endpoint's scope, or cannot reach the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"This API key is missing the posts:write scope"}}}}},"409":{"description":"The same Idempotency-Key is being used for a different batch, or this batch is still being scheduled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"This content is already approved"}}}}},"429":{"description":"More than 120 requests in a minute. Wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded"}}}}},"500":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"Something went wrong"}}}}}}}},"/health":{"get":{"operationId":"healthCheck","summary":"Health Check","description":"Returns ok when the API is up. Needs no API key, is not rate limited and reads no data, so it is safe to poll from uptime monitors.\n\nThis is the one response without a data envelope. For incidents and history, see the status page.","tags":["Status"],"security":[],"parameters":[],"responses":{"200":{"description":"The API is up","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Always `ok` when the API is up"}},"required":["status"],"additionalProperties":false},"example":{"status":"ok"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An rr_live_ API key from the Developers page, or an OAuth access token from a connected AI app","x-scopes":{"workspace:read":"Read the workspace profile, company information and banned subreddits, and run content checks","workspace:write":"Change the workspace profile and rewrite content","posts:read":"List and read posts and their review notes","posts:write":"Schedule, edit, approve and cancel posts, and leave review notes on them","comments:read":"List and read comments and their review notes","comments:write":"Schedule, edit, approve and cancel comments, and leave review notes on them","sales-decks:read":"Read sales decks","sales-decks:write":"Edit sales decks","analytics:read":"Read Reddit results and AI search visibility","knowledge:write":"Update company information and ban or unban subreddits","keywords:read":"List keywords and target prompts","keywords:write":"Add and retire target prompts","webhooks:read":"List webhook endpoints and their recent deliveries","webhooks:write":"Create, change and delete webhook endpoints, and send test events","reports:read":"List and read weekly gameplans, weekly summaries and performance reports","mentions:read":"List mentions of your brand on Reddit","notifications:read":"List recent activity on your content: status changes, new replies and removals","strategy:read":"Read the campaign strategy and list blog campaigns","post-call:read":"Read post-call packages","post-call:write":"Prepare, rebuild and mark post-call packages delivered"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","payment_required","forbidden","not_found","invalid_request","conflict","rate_limited","internal_error","service_unavailable"]},"message":{"type":"string","description":"A readable explanation"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}