{"openapi":"3.1.0","info":{"title":"follow.fast API","version":"1.0.0","description":"Drive follow.fast programmatically: generate slideshow candidates, review and approve them, publish, and read results. Authenticate with an API key (`Authorization: Bearer ff_...`) from Account -> API keys. Keys are scoped to one organization and are `read` or `read_write`. Rate limit: 60 requests/minute sustained, 120 burst. Responses are `{ data, meta? }`; errors are `{ error: { code, message, details? } }`. POSTs accept an `Idempotency-Key` header. Also available as an MCP server at POST /api/mcp."},"servers":[{"url":"https://app.follow.fast/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/workspaces":{"get":{"operationId":"list_workspaces","summary":"List workspaces","description":"List the workspaces (one per product/app) of your organization with their brand, posting plan and connected accounts. Call this first: the `slug` identifies a workspace in every other operation.","tags":["Workspaces"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{slug}":{"get":{"operationId":"get_workspace","summary":"Get one workspace","description":"Get a workspace by slug: brand voice, posting plan (posts per day, windows, timezone), autopilot flag and connected accounts. Returns 404 if the slug is not in your organization.","tags":["Workspaces"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"slug","in":"path","required":true,"description":"Workspace slug, from list_workspaces.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts":{"get":{"operationId":"list_posts","summary":"List posts","description":"List posts (one per platform group: a Meta post for Instagram+Facebook, a TikTok post), newest first. Filter by workspace slug, status (draft, approved, scheduled, publishing, published, failed, needs_manual) and a time window; `from`/`to` apply to the scheduled time, or the creation time for unscheduled posts. Each item has `displayStatus` (status refined: a failed post with some targets published is \"partial\"), targets (per-platform status, permalink, error) and a preview image URL. Use get_post for full metrics. Rejected candidates are not listed.","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"workspace","in":"query","required":false,"description":"Only this workspace.","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","approved","scheduled","publishing","published","failed","needs_manual"]}},{"name":"from","in":"query","required":false,"description":"Inclusive start (ISO 8601).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Exclusive end (ISO 8601).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_post","summary":"Create posts from your own images","description":"Bring your own content: create draft posts from images you already have (public URLs or base64; REST also accepts multipart/form-data with `images` files). One carousel (or single image) for Instagram/Facebook (and Threads / Bluesky when connected and requested or enabled) and one TikTok photo post are created from the same images, as a candidate that you then approve_candidate or publish_now. Nothing is published by this call. 2-10 images make a carousel. Captions are checked against platform limits and the workspace's banned words.","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"201":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"workspace":{"type":"string","minLength":1,"description":"Workspace slug, from list_workspaces."},"images":{"minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public http(s) image URL; the server downloads it."}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"base64":{"type":"string","minLength":1,"description":"Base64 image bytes (a data: URI prefix is accepted)."},"filename":{"type":"string"}},"required":["base64"],"additionalProperties":false}]},"description":"Images in slide order."},"caption":{"type":"string","minLength":1,"maxLength":2200},"tiktokCaption":{"description":"Defaults to caption.","type":"string","maxLength":2200},"hashtags":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"platforms":{"description":"Default: every connected platform of the workspace; Threads and Bluesky join by default only when the workspace's posting plan has them switched on. They take the feed images (Bluesky: the first 4).","minItems":1,"type":"array","items":{"type":"string","enum":["instagram","facebook_page","tiktok","bluesky","threads"]}}},"required":["workspace","images","caption"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"workspace":{"type":"string"},"caption":{"type":"string"},"tiktokCaption":{"type":"string"},"hashtags":{"type":"string","description":"Space or comma separated."},"platforms":{"type":"string","description":"Space or comma separated."},"images":{"type":"array","items":{"type":"string","format":"binary"}},"image_urls":{"type":"string","description":"Space or comma separated URLs."}},"required":["workspace","caption"]}}}}}},"/posts/{id}":{"get":{"operationId":"get_post","summary":"Get a post","description":"Get one post with all image URLs (in slide order), caption, hashtags, schedule, per-platform targets (status, permalink, error) and metrics (views, likes, saves, and the frozen 72h snapshot with score/verdict once available).","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_post","summary":"Edit caption, hashtags or schedule","description":"Edit an unpublished post (draft, approved, scheduled or failed): `caption`, `hashtags` (array, # optional) and/or `scheduledAt` (ISO 8601, in the future; only for approved or scheduled posts, drafts get their slot at approval; null is not allowed). Moving a scheduled post cancels its queued publish job and re-queues it for the new time. Banned words for the workspace are rejected (422). Slide text and images are edited in the web app, not here.","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"caption":{"type":"string","minLength":1,"maxLength":2200},"hashtags":{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"scheduledAt":{"description":"New publish time. Must be in the future.","type":"string"}},"required":[]}}}}},"delete":{"operationId":"delete_post","summary":"Delete an unpublished post","description":"Permanently delete a post that has not been published (not publishing, published, or with any published target). Use reject_candidate to discard an unreviewed candidate instead. Cancels a queued publish job.","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates":{"get":{"operationId":"list_candidates","summary":"List candidates awaiting review","description":"List generated candidates that are waiting for review (status draft, not rejected). A candidate is one slideshow idea with a feed variant (Instagram/Facebook) and a vertical variant (TikTok). `state` is pending, rendering, ready or error: only `ready` candidates can be approved. This is where new candidate ids show up after generate_posts.","tags":["Candidates"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"workspace","in":"query","required":false,"description":"Only this workspace.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates/{id}":{"get":{"operationId":"get_candidate","summary":"Get a candidate","description":"Get a candidate by id: its state, hook, slide texts, captions per platform, and the posts (with image URLs) it produced. Works for pending, approved and rejected candidates too.","tags":["Candidates"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{slug}/generate":{"post":{"operationId":"generate_posts","summary":"Generate candidates","description":"Ask follow.fast to generate new slideshow candidates for a workspace, using its brand, hooks, personas and past results. Asynchronous: returns 202 with a `jobId` immediately; poll get_generation_status until it is `done` (usually under a few minutes) and it lists the new candidates, or call list_candidates. New candidates are drafts and must be approved (approve_candidate) before anything is published. Max 10 per call.","tags":["Workspaces"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"slug","in":"path","required":true,"description":"Workspace slug, from list_workspaces.","schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"count":{"description":"How many candidates. Default: the workspace's daily amount.","type":"integer","minimum":1,"maximum":10},"targetDate":{"description":"Local date (YYYY-MM-DD) the candidates are meant for. Default: tomorrow in the workspace timezone.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":[]}}}}}},"/jobs/{id}":{"get":{"operationId":"get_generation_status","summary":"Generation job status","description":"Status of a generate_posts job: queued, running, done or failed. When done, `candidates` lists the candidates it created (they may still be rendering: check each candidate's `state`).","tags":["Candidates"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"id","in":"path","required":true,"description":"jobId returned by generate_posts.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates/{id}/approve":{"post":{"operationId":"approve_candidate","summary":"Approve a candidate","description":"Approve a ready candidate: both its posts get the next free slots from the workspace's posting plan and are published automatically at those times (use update_post/reschedule_post to move one, publish_now to go immediately). Fails with 409 if the candidate is still rendering or has nothing left to approve, and 422 if TikTok Direct Post settings are incomplete. Review the candidate first (get_candidate): this is the step that commits to posting.","tags":["Candidates"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates/{id}/reject":{"post":{"operationId":"reject_candidate","summary":"Reject a candidate","description":"Reject a draft candidate so it is never posted. Only works while its posts are still drafts (409 otherwise). Rejected candidates disappear from list_candidates and list_posts.","tags":["Candidates"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/{id}/publish-now":{"post":{"operationId":"publish_now","summary":"Publish a post now","description":"Publish a draft, approved or scheduled post immediately instead of waiting for its slot. Returns the post; publishing is asynchronous, so poll get_post for target status and permalinks. 409 if already publishing/published or still rendering; 422 if TikTok settings are incomplete.","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/{id}/retry":{"post":{"operationId":"retry_post","summary":"Retry a failed post","description":"Retry a post whose status is failed or needs_manual (read each target's `status` and `error` with get_post first; some failures need a reconnected account). Only targets that are not already published are republished, so a partly published post (displayStatus \"partial\") never double-posts. Targets with status needs_check (the publish call had an unknown outcome: it may be live) are NOT retried by a plain retry: check the account, then pass `platform` (and `handle` when the workspace has several accounts on it) to retry just that target. With `platform` only the matching failed or needs_check target(s) are retried.","tags":["Posts"],"security":[{"bearerAuth":[]}],"x-required-scope":"read_write","parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and request replay the first response for 24h.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"platform":{"description":"Retry only the target(s) on this platform. Required to retry a needs_check target (confirms you checked the account).","type":"string","enum":["instagram","facebook_page","tiktok","bluesky","threads"]},"handle":{"description":"With `platform`: the account handle, when the post has several targets on that platform.","type":"string"}},"required":[]}}}}}},"/results":{"get":{"operationId":"get_results","summary":"Performance by dimension","description":"How posts performed. Posts are scored on views frozen at 72h relative to the median of the same workspace and platform; a verdict (scale / keep / retire) needs at least 3 scored posts per option. Returns per-dimension tables (hook, format, template, persona, slot, slides, type: n, meanScore, medianViews, verdict), a weekly trend and the most recent scored posts. Use it to decide what to make more of before generating.","tags":["Insights"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"workspace","in":"query","required":false,"description":"Only this workspace; default all of them.","schema":{"type":"string","minLength":1}},{"name":"recent","in":"query","required":false,"description":"How many recent scored posts to include.","schema":{"default":20,"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calendar":{"get":{"operationId":"get_calendar","summary":"Scheduled posts in a window","description":"Posts with a scheduled/publish time in a window, oldest first, with status and preview image. Default window: now to 14 days ahead (max 92 days). Use it to find free days before approving more, or to see what is going out.","tags":["Insights"],"security":[{"bearerAuth":[]}],"x-required-scope":"read","parameters":[{"name":"workspace","in":"query","required":false,"description":"Workspace slug, from list_workspaces.","schema":{"type":"string","minLength":1}},{"name":"from","in":"query","required":false,"description":"Inclusive start. Default now.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Exclusive end. Default from + 14 days.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. The payload is in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"meta":{"type":"object"}},"required":["data"]}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope is read but this needs read_write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict with the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}":{"get":{"operationId":"get_asset","summary":"Download an image or video","description":"The bytes behind the image URLs in post and candidate responses. Needs the same bearer key.","tags":["Assets"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Image or video bytes.","content":{"image/*":{},"video/*":{}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key starting with ff_"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}