{"openapi":"3.1.0","info":{"title":"Clipflow API","version":"1.0.0","description":"Read your posts, projects, media files and transcripts across every organization you belong to.\n\n## Authentication\n\nThe API uses **OAuth 2.1** — the authorization code flow with PKCE (`S256`, required).\nEvery request must send the access token as a bearer header:\n\n```\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### 1. Get a client\n**MCP connectors and assistants** self-register (RFC 7591) and start with\n**read access**. The person who connects can later grant that connection\npermission to create and edit content from within Clipflow. **Organizations\nbuilding their own integrations** are issued a private client by Clipflow —\nget in touch.\n\nDiscover every endpoint below via RFC 8414 metadata:\n\n```\nPOST https://app.clipflow.co/oauth/register\nGET  https://app.clipflow.co/.well-known/oauth-authorization-server\n```\n\n### 2. Authorize the user\nRedirect the user to the authorization endpoint with a PKCE `code_challenge` (`S256`) and\nthe scopes you need (see below). They approve access on a consent screen.\n\n```\nhttps://app.clipflow.co/oauth/authorize\n```\n\n### 3. Exchange the code\nExchange the returned code — with your `code_verifier` — for an access token and a refresh token:\n\n```\nPOST https://app.clipflow.co/oauth/token\n```\n\n### 4. Refresh\nWhen the access token expires, use the refresh token (`grant_type=refresh_token`) at the same endpoint.\n\n## Scopes\nEach endpoint lists the scope it requires (e.g. `posts.read`). A token is granted only the scopes\nthe user approved; a call missing its scope returns `403`. Requesting an expansion that reaches\nanother entity (`?expand=channel`) also requires that entity's read scope.\n\nA self-registered client starts with the read scopes (`*.read`) only. Write scopes (`*.write`)\nare granted per connection: the person who connected raises the connection's access from within\nClipflow, existing tokens are revoked, and the client re-authorizes against a consent screen\nlisting the write scopes.\n\n## Errors\n- `401` — missing or invalid token\n- `403` — token lacks the required scope\n- `404` — not found (also returned for records outside your access, so ids can't be probed)\n"},"servers":[{"url":"https://api.clipflow.co"}],"paths":{"/v1/analytics/overview":{"get":{"summary":"How channels and posts performed over a period, against the preceding one","parameters":[{"name":"channel_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Channel prefix_id — only records linked to this channel"},{"name":"custom_label_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Optional CustomLabel prefix_ids — narrows the post sections only"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601), used when period is custom"},{"name":"organization_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Organization prefix_id to narrow results"},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["last_7_days","last_14_days","last_30_days","last_75_days","last_90_days","previous_month","custom"],"default":"last_75_days"},"description":"Date period for the report"},{"name":"platform_product_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional PlatformProduct prefix_id — narrows the post sections only"},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601), used when period is custom"},{"name":"title","in":"query","required":false,"schema":{"type":"string"},"description":"Optional title search (case-insensitive, partial match)"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["analytics.read"]}]}},"/v1/me":{"get":{"summary":"The authenticated user, their organizations, and granted scopes","parameters":[],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":[]}]}},"/v1/media_files":{"get":{"summary":"List media files","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor: return results after this prefix_id (use meta.next_cursor from the previous page)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated serializer expansions. Expansions are opt-in — omit for the endpoint's default set, which is usually none. Allowed: file, rich_text_pages, transcript"},{"name":"media_status","in":"query","required":false,"schema":{"type":"string","enum":["declined","pending","changes_required","reviewed","approved","unused"]},"description":"Optional media status filter (unused means approved or reviewed media not yet assigned to a post)"},{"name":"media_type","in":"query","required":false,"schema":{"type":"string","enum":["edited_video","final_video","raw_video","sample_video"]},"description":"Optional media type filter"},{"name":"organization_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Organization prefix_id to narrow results"},{"name":"title","in":"query","required":false,"schema":{"type":"string"},"description":"Optional title search (case-insensitive, partial match)"},{"name":"user_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional User prefix_id — only media files uploaded by this user"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["media_files.read"]}]}},"/v1/media_files/{id}":{"get":{"summary":"Fetch a media file, including transcript pages","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefix id"},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated serializer expansions. Expansions are opt-in — omit for the endpoint's default set, which is usually none. Allowed: file, rich_text_pages, transcript"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["media_files.read"]}]}},"/v1/organizations":{"get":{"summary":"List organizations the user belongs to","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor: return results after this prefix_id (use meta.next_cursor from the previous page)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["organizations.read"]}]}},"/v1/organizations/{id}/channel_products":{"get":{"summary":"An organization's channels and the platform products that can be posted to on each","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefix id"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["channels.read"]}]}},"/v1/posts":{"get":{"summary":"List posts","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor: return results after this prefix_id (use meta.next_cursor from the previous page)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"channel_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Channel prefix_id — only records linked to this channel"},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated serializer expansions. Expansions are opt-in — omit for the endpoint's default set, which is usually none. Allowed: channel, organization, platform_product, project"},{"name":"organization_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Organization prefix_id to narrow results"},{"name":"platform_key","in":"query","required":false,"schema":{"type":"string"},"description":"Optional platform key from channel_products — only posts on this platform. Not combinable with platform_product_id or platform_product_key"},{"name":"platform_product_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional PlatformProduct prefix_id — only posts of this product. Not combinable with platform_key or platform_product_key"},{"name":"platform_product_key","in":"query","required":false,"schema":{"type":"string"},"description":"Optional platform product key from channel_products — only posts of this product. Not combinable with platform_key or platform_product_id"},{"name":"post_status","in":"query","required":false,"schema":{"type":"string","enum":["declined","draft","changes_required","reviewed","ready","done","failed"]},"description":"Optional post status filter"},{"name":"scheduled_after","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional ISO 8601 date-time with an explicit offset — only posts scheduled at or after it, e.g. 2026-11-01T00:00:00+10:00"},{"name":"scheduled_before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional ISO 8601 date-time with an explicit offset — only posts scheduled before it, e.g. 2026-11-08T00:00:00+10:00"},{"name":"tags[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Optional — only posts having any of these exact tags (case-insensitive)"},{"name":"title","in":"query","required":false,"schema":{"type":"string"},"description":"Optional title search (case-insensitive, partial match)"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["posts.read"]}]}},"/v1/posts/{id}":{"get":{"summary":"Fetch a post","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefix id"},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated serializer expansions. Expansions are opt-in — omit for the endpoint's default set, which is usually none. Allowed: channel, organization, platform_product, project"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["posts.read"]}]}},"/v1/projects":{"get":{"summary":"List projects","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor: return results after this prefix_id (use meta.next_cursor from the previous page)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"assignee_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional User prefix_id — only projects assigned to this user"},{"name":"channel_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Channel prefix_id — only records linked to this channel"},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated serializer expansions. Expansions are opt-in — omit for the endpoint's default set, which is usually none. Allowed: organization, status"},{"name":"is_archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"Pass true to list only archived projects (archived projects are excluded by default)"},{"name":"is_template","in":"query","required":false,"schema":{"type":"boolean"},"description":"Pass true to list only project templates (templates are excluded by default)"},{"name":"organization_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Organization prefix_id to narrow results"},{"name":"parent_project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Project prefix_id — only that project's sub-projects"},{"name":"priority","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high","urgent"]},"description":"Optional project priority filter"},{"name":"project_category_key","in":"query","required":false,"schema":{"type":"string"},"description":"Optional project category key filter (organization-defined categories)"},{"name":"project_status_key","in":"query","required":false,"schema":{"type":"string","enum":["complete","incomplete"]},"description":"Optional completion filter"},{"name":"relevance","in":"query","required":false,"schema":{"type":"string","enum":["evergreen","time_sensitive"]},"description":"Optional project relevance filter"},{"name":"status_key","in":"query","required":false,"schema":{"type":"string"},"description":"Optional workflow status key filter (organization-defined statuses)"},{"name":"title","in":"query","required":false,"schema":{"type":"string"},"description":"Optional title search (case-insensitive, partial match)"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["projects.read"]}]}},"/v1/projects/{id}":{"get":{"summary":"Fetch a project","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefix id"},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated serializer expansions. Expansions are opt-in — omit for the endpoint's default set, which is usually none. Allowed: organization, status"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["projects.read"]}]}},"/v1/projects/{id}/overview":{"get":{"summary":"A snapshot of a project: status, media, posts, pages and task counts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefix id"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["projects.read","posts.read","media_files.read","rich_text_pages.read"]}]}},"/v1/rich_text_pages/{id}":{"get":{"summary":"Fetch a rich text page (document)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefix id"}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found"}},"security":[{"oauth2":["rich_text_pages.read"]}]}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://app.clipflow.co/oauth/authorize","tokenUrl":"https://app.clipflow.co/oauth/token","refreshUrl":"https://app.clipflow.co/oauth/token","scopes":{"agents.read":"Read your agents","analytics.read":"Read channel and post performance","asset_files.read":"Read your files","asset_files.write":"Upload files","channels.read":"Read your channels","comments.read":"Read comments","comments.write":"Create and edit comments","designs.read":"Read designs","designs.write":"Import and update designs","ideas.read":"Read your ideas","ideas.write":"Create and edit ideas","media_files.read":"Read your media files","media_files.write":"Upload and edit media files","organizations.read":"Read your organizations","posts.read":"Read your posts","posts.write":"Create and edit posts","projects.read":"Read your projects","projects.write":"Create and edit projects","rich_text_pages.read":"Read your pages","rich_text_pages.write":"Create and edit pages"}}}}}}}