{"components":{"securitySchemes":{"bearerAuth":{"description":"Your API key from Integrations, Add Integration, AI Agents.","scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"support@distribb.io"},"description":"The Distribb REST API. This file is generated from the same tool table that runs the Distribb MCP server (mcp_connector.py), so it lists every endpoint an agent can call through MCP. The full hand-written reference, with more endpoints and examples, is at https://distribb.io/api-docs.","title":"Distribb API","version":"1.3.1"},"openapi":"3.1.0","paths":{"/agent-tools":{"get":{"description":"Search the tools of the connected integrations: Meta, Google, TikTok and LinkedIn ad campaigns, video ads and competitor ads, social DMs, comments and inbox, analytics and bank accounts, outreach, Google Business, Search Console, databases, GitHub, website pages on WordPress and the newest integrations. Filter by area, query or integration; pass names to get each tool's input_schema. read_only and preview_safe tools (which change nothing without confirm=true) run with run_integration_read; the rest with run_integration_action.","operationId":"find_integration_tools","parameters":[{"in":"query","name":"area","required":false,"schema":{"enum":["integrations","social","paid_ads","analytics","search_console","google_business","outreach","databases","lab","website_pages"],"type":"string"}},{"in":"query","name":"query","required":false,"schema":{"description":"Words describing the task, e.g. \"pause campaign\".","type":"string"}},{"in":"query","name":"integration","required":false,"schema":{"description":"Integration key or name, e.g. \"hunter\".","type":"string"}},{"in":"query","name":"names","required":false,"schema":{"description":"Exact tool names, for their input_schema.","items":{"type":"string"},"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Find integration tools","tags":["agent-tools"]}},"/agent-tools/call":{"post":{"description":"Run one read_only integration tool (results, accounts, campaigns, inbox, analytics, research), or preview a preview_safe change: it returns exactly what would change and changes nothing. Show a preview to the user before running it with run_integration_action. A result with status running has a job_id for get_integration_result.","operationId":"run_integration_read","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"arguments":{"description":"The tool's arguments, per its input_schema.","type":"object"},"mode":{"type":"string"},"project_id":{"description":"Distribb project ID (from list_projects).","type":"integer"},"tool":{"description":"Tool name from find_integration_tools.","type":"string"}},"required":["project_id","tool"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Read from an integration","tags":["agent-tools"]}},"/agent-tools/jobs/{job_id}":{"get":{"description":"The result of an integration tool call that came back with status running and a job_id (scans and audits can take a few minutes). Results are kept for an hour.","operationId":"get_integration_result","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Get a long-running result","tags":["agent-tools"]}},"/ai-visibility":{"get":{"description":"How often the brand is cited by AI assistants (ChatGPT, Claude, Gemini, Perplexity) for tracked buyer prompts.","operationId":"ai_visibility_report","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"view","required":false,"schema":{"description":"summary or detail. Default summary.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"AI visibility report","tags":["ai-visibility"]}},"/articles":{"get":{"description":"List articles for a project or the whole account, newest scheduled date first. Filter by status (Draft, Planned, Published) and by a scheduled-date window. Each row includes the live url, claimed (finished content is already saved, so Distribb will not write it) and distribb_is_writing (Distribb's writer has started it).","operationId":"list_articles","parameters":[{"in":"query","name":"project_id","required":false,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"status","required":false,"schema":{"description":"Draft, Planned, or Published.","type":"string"}},{"in":"query","name":"scheduled_after","required":false,"schema":{"description":"ISO date, inclusive, e.g. 2026-10-01.","type":"string"}},{"in":"query","name":"scheduled_before","required":false,"schema":{"description":"ISO date, inclusive, e.g. 2026-10-07.","type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"description":"Max 200. Default 50.","type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List articles","tags":["articles"]},"post":{"description":"Plan or create an article on a project. Provide keyword; optionally title, HTML content, meta_description, feature_image (URL from upload_image), article_style, scheduled_date (ISO 8601), and category. Without content Distribb writes it at the scheduled time. With content of 2,000+ characters it is published exactly as sent on that date: Distribb adds no images, internal links or exchange links to it.","operationId":"create_article","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"alt_text":{"description":"Alt text for the feature image.","type":"string"},"article_style":{"description":"e.g. listicle, how-to, comparison.","type":"string"},"category":{"type":"string"},"content":{"description":"Full HTML body. Omit to let Distribb generate it.","type":"string"},"feature_image":{"description":"Absolute URL of the hero image, e.g. from upload_image.","type":"string"},"keyword":{"description":"Target keyword for the article.","type":"string"},"meta_description":{"type":"string"},"project_id":{"description":"Distribb project ID (from list_projects).","type":"integer"},"scheduled_date":{"description":"ISO 8601 publish datetime.","type":"string"},"title":{"type":"string"}},"required":["keyword","project_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Create article","tags":["articles"]}},"/articles/{article_id}":{"get":{"description":"Fetch one article with its full HTML content, keyword, status, schedule, feature image, whether it is claimed, and its live URL if published.","operationId":"get_article","parameters":[{"in":"path","name":"article_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Get article","tags":["articles"]},"put":{"description":"Update an article: title, content, keyword, meta_description, article_style, status, category, scheduled_date (null to unschedule), feature_image, alt_text. Saving 2,000+ characters of content on a Planned article claims it: Distribb will not write it and publishes the saved content exactly as sent on its date. Refused with already_being_written once Distribb's writer has started the article. Set sync true to also push the edit to the live CMS post of a published article.","operationId":"update_article","parameters":[{"in":"path","name":"article_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"a":{"type":"string"},"c":{"type":"string"},"e":{"type":"string"},"g":{"type":"string"},"h":{"type":"string"},"n":{"type":"string"},"s":{"type":"string"},"{":{"type":"string"},"}":{"type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Update article","tags":["articles"]}},"/articles/{article_id}/publish":{"post":{"description":"Publish an article now to the connected CMS (WordPress, Webflow, Shopify, and other supported platforms).","operationId":"publish_article","parameters":[{"in":"path","name":"article_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Publish article","tags":["articles"]}},"/backlinks":{"get":{"description":"List the verified backlinks a project has received and given through the Distribb exchange, with source and target URLs.","operationId":"list_backlinks","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List backlinks","tags":["backlinks"]}},"/backlinks/status":{"get":{"description":"Backlink exchange status for a project: credits, links received, links given, and participation state.","operationId":"backlinks_status","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Backlink status","tags":["backlinks"]}},"/gbp/performance":{"get":{"description":"What the Google Business Profile brought in: calls, direction requests, website clicks, profile views and bookings for the last N days against the period before, plus the searches that showed the profile. Google publishes these 2-3 days late.","operationId":"gbp_performance","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"days","required":false,"schema":{"description":"Length of the period in days. Default 28.","maximum":90,"minimum":7,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Google Business Profile performance","tags":["gbp"]}},"/gbp/reviews":{"get":{"description":"List live Google Business Profile reviews for a project. Filter to unreplied reviews with has_reply false.","operationId":"gbp_reviews","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"has_reply","required":false,"schema":{"description":"false returns only reviews still waiting on a reply.","type":"boolean"}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List Google reviews","tags":["gbp"]}},"/gbp/reviews/reply":{"post":{"description":"Post a public owner reply to a Google Business Profile review. The reply goes live on Google.","operationId":"gbp_reply_review","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"message":{"description":"The public reply text.","type":"string"},"project_id":{"description":"Distribb project ID (from list_projects).","type":"integer"},"review_id":{"description":"review_id from gbp_reviews.","type":"string"}},"required":["message","project_id","review_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Reply to Google review","tags":["gbp"]}},"/gbp/status":{"get":{"description":"Google Business Profile connection status and review stats for a project.","operationId":"gbp_status","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Google Business Profile status","tags":["gbp"]}},"/images":{"post":{"description":"Host an image for an article and get back its public URL. Send exactly one of image_base64 (PNG, JPG, WebP or GIF, 12 MB max), image_url (a public image URL to copy), or file (an image file from this conversation).","operationId":"upload_image","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"file":{"description":"An image file from the conversation.","properties":{"download_url":{"type":"string"},"file_id":{"type":"string"},"file_name":{"type":"string"},"mime_type":{"type":"string"}},"required":["download_url"],"type":"object"},"image_base64":{"description":"Base64 image bytes, or a data:image/...;base64 URL.","type":"string"},"image_url":{"description":"Public http(s) URL of an image to copy.","type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Upload image","tags":["images"]}},"/integrations":{"get":{"description":"List connected CMS and publishing integrations (WordPress, Webflow, Shopify, Wix, Framer, Ghost, Notion, and more) and their status.","operationId":"list_integrations","parameters":[{"in":"query","name":"project_id","required":false,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List CMS integrations","tags":["integrations"]}},"/integrations/catalog":{"get":{"description":"Every integration this account can connect on a project: website CMS, social accounts, ad accounts, Search Console, analytics tools, banks, databases, GitHub and the newest ones. Shows whether each is connected and to which accounts, the agent tools it unlocks, and the connect_url to send the user. Call it when the user asks what they can connect, before using an integration, and after they say they connected one.","operationId":"integrations_catalog","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"category","required":false,"schema":{"description":"Only this group. Omit for everything.","enum":["blog","social","ads","analytics","developer","lab"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Integrations catalog","tags":["integrations"]}},"/integrations/connect":{"get":{"description":"The link that connects one integration (for example \"meta ads\", \"instagram\", \"google analytics\", \"hunter\" or \"supabase\") and the steps the user follows. The user opens it and signs in or pastes their key on Distribb itself. Never ask for passwords or API keys in the chat.","operationId":"connect_integration","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"integration","required":true,"schema":{"description":"Key or name from integrations_catalog.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Get a connect link","tags":["integrations"]}},"/keywords/search":{"post":{"description":"Run keyword research for a seed keyword: search volume, difficulty, cost per click, and related keyword ideas in the project's market.","operationId":"keyword_research","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"Seed keyword, e.g. \"crm software\".","type":"string"},"limit":{"description":"How many related keyword ideas to return besides the seed. Default 20.","maximum":100,"minimum":1,"type":"integer"},"project_id":{"description":"Distribb project ID (from list_projects).","type":"integer"}},"required":["keyword","project_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Keyword research","tags":["keywords"]}},"/playbooks/{topic}":{"get":{"description":"Distribb's playbooks for agents: seo, social-media, outreach, paid-ads, and integrations (which connections to set up first and how to use each one). Read the relevant one before planning work in that area. Without a topic, lists them.","operationId":"get_playbook","parameters":[{"in":"path","name":"topic","required":true,"schema":{"enum":["seo","social-media","outreach","paid-ads","integrations"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Read a playbook","tags":["playbooks"]}},"/projects":{"get":{"description":"List every project (website) on the account with plan, publishing cadence, and CMS connection status.","operationId":"list_projects","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List projects","tags":["projects"]},"post":{"description":"Create a new project for a website. Optionally include business_name, business_description, and any writable settings keys.","operationId":"create_project","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"business_description":{"type":"string"},"business_name":{"type":"string"},"website_url":{"description":"The site to create the project for, e.g. https://acme.com.","type":"string"}},"required":["website_url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Create project","tags":["projects"]}},"/projects/{project_id}":{"get":{"description":"Full settings for one project: AI writing instructions, tone, publish schedule, timezone, backlink participation, every writable settings key, the article plans it can switch to (article_plan), and onboarding progress (setup).","operationId":"get_project","parameters":[{"in":"path","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Get project settings","tags":["projects"]},"put":{"description":"Update project settings: ai_instructions, tone, publish_time, timezone, backlinks_network, business_description, primary_location, and any writable key shown by get_project. Pass only the keys to change.","operationId":"update_project","parameters":[{"in":"path","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"e":{"type":"string"},"g":{"type":"string"},"i":{"type":"string"},"n":{"type":"string"},"s":{"type":"string"},"t":{"type":"string"},"{":{"type":"string"},"}":{"type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Update project settings","tags":["projects"]}},"/projects/{project_id}/article-plan":{"post":{"description":"Set how many articles a month the project gets. Pro: 8 (premium, longer articles), 30 (one a day) or 5 (5 premium articles). Accelerator: 8, 5, 30 with premium true (30 premium articles, one a day, listed as premium30), 60 or 90. Only plans included in the account are accepted, so nothing is billed. get_project lists them under article_plan, with the recommended one.","operationId":"set_article_plan","parameters":[{"in":"path","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"plan":{"description":"Articles per month.","enum":[8,30,5,60,90],"type":"integer"},"premium":{"description":"With plan 30 on Accelerator: 30 premium articles a month.","type":"boolean"}},"required":["plan"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Set article plan","tags":["projects"]}},"/projects/{project_id}/onboarding":{"post":{"description":"Start keyword research and the first articles for a project (spends research credits). For an account that has not finished onboarding, this also finishes it: the account leaves the setup wizard and the calendar fills with planned articles. Returns site_scan_running while Distribb is still reading the website.","operationId":"start_onboarding","parameters":[{"in":"path","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Start keyword research","tags":["projects"]}},"/screenshots":{"post":{"description":"Take a screenshot of a public web page, such as the homepage of a product ranked in a listicle, and host it. Runs in the background: the first call returns status processing; call again with the same url after about 20 seconds to get image_url, or a reason if the page could not be captured cleanly.","operationId":"screenshot_page","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"The business or product the page belongs to.","type":"string"},"url":{"description":"The public page to capture.","type":"string"}},"required":["name","url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Screenshot a web page","tags":["screenshots"]}},"/search-console":{"get":{"description":"Google Search Console performance for a project: clicks, impressions, positions, and top queries over the last N days.","operationId":"search_console_performance","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"days","required":false,"schema":{"description":"Lookback window, default 28.","type":"integer"}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Search Console performance","tags":["search-console"]}},"/social/accounts":{"get":{"description":"List this project's social accounts, usernames and account_id values. Match the requested handle before publishing; projects can have several Instagram accounts.","operationId":"list_social_accounts","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List connected social accounts","tags":["social"]}},"/social/media":{"post":{"description":"Host an existing image (12 MB max) or MP4/MOV video (64 MB max) for social publishing. Supply a public media_url or an attached file. Returns media with type and s3_url for publish_social_post. Does not publish a post.","operationId":"upload_social_media","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"file":{"properties":{"download_url":{"type":"string"},"file_id":{"type":"string"},"file_name":{"type":"string"},"mime_type":{"type":"string"}},"required":["download_url"],"type":"object"},"media_url":{"description":"Public http(s) download URL of the image or video.","type":"string"},"name":{"type":"string"},"project_id":{"description":"Distribb project ID (from list_projects).","type":"integer"}},"required":["project_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Upload social image or video","tags":["social"]}},"/social/posts":{"get":{"description":"List a project's recent saved social posts, including drafts, scheduled and published posts. Use after an uncertain publish response to find the saved post before retrying. Get a specific post to verify its delivery rule.","operationId":"list_social_posts","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"limit","required":false,"schema":{"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List recent social posts","tags":["social"]}},"/social/posts/{post_id}":{"get":{"description":"Read a saved social post, publishing results and comment-for-guide settings. Reads back a saved provider DM rule before reporting active. An unverified, pending or failed rule needs configuration on this existing post, not another publish.","operationId":"get_social_post","parameters":[{"in":"path","name":"post_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Get social post and delivery status","tags":["social"]}},"/social/posts/{post_id}/comment-for-guide":{"put":{"description":"Configure, retry, update or disable comment-for-guide on an existing social post. Uses its published account and verifies the DM rule after saving. Send is_comment_for_guide false to disable; omit config to retry saved settings. Does not republish the reel or send a test DM. Check comment_for_guide.automation.status for active, disabled, pending or failed.","operationId":"configure_social_post_auto_reply","parameters":[{"in":"path","name":"post_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"comment_for_guide_config":{"additionalProperties":false,"properties":{"button_first":{"description":"Instagram DM only, default true. The first DM asks the commenter to tap a button; custom_message with the link is sent after the tap, the way ManyChat does it.","type":"boolean"},"button_label":{"description":"Button text, at most 20 characters. Default: \"Send me the link\"","maxLength":20,"type":"string"},"button_message":{"description":"First DM, sent with the button. Default: \"Thanks for your comment! Tap the button below and I'll send you the link.\"","maxLength":640,"type":"string"},"custom_message":{"description":"Message containing {url}, replaced by delivery_url.","maxLength":1000,"type":"string"},"delivery_method":{"enum":["dm","reply"],"type":"string"},"delivery_url":{"description":"Absolute http(s) link to deliver.","type":"string"},"is_active":{"type":"boolean"},"match_mode":{"enum":["keyword","all"],"type":"string"},"public_replies":{"description":"Public replies under the comment, up to 6 of 300 characters. {{first_name}} greets the commenter by name. Default: [\"Thanks! Please see DMs.\", \"Sent you a message! Check it out!\", \"Nice! Check your DMs!\"]","items":{"maxLength":300,"type":"string"},"maxItems":6,"type":"array"},"public_reply":{"description":"DM delivery only, default true. Once the DM is sent, also answer the comment publicly with one of public_replies, picked at random.","type":"boolean"},"trigger_keyword":{"maxLength":100,"type":"string"}},"required":["delivery_url"],"type":"object"},"is_comment_for_guide":{"type":"boolean"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Configure comment-triggered delivery","tags":["social"]}},"/social/publish":{"post":{"description":"Publish a caption and uploaded media to the selected connected accounts, or schedule in UTC. For an Instagram reel, pass the uploaded video in media_files. For comment-triggered DMs, set is_comment_for_guide true and supply comment_for_guide_config with match_mode keyword, trigger_keyword, delivery_method dm, delivery_url, custom_message containing {url}, and is_active true. Always select account_id from list_social_accounts. Returns saved post IDs; verify publishing and delivery with get_social_post. Retry DM setup using configure_social_post_auto_reply on the same post, never by republishing.","operationId":"publish_social_post","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"properties":{"comment_for_guide_config":{"additionalProperties":false,"properties":{"button_first":{"description":"Instagram DM only, default true. The first DM asks the commenter to tap a button; custom_message with the link is sent after the tap, the way ManyChat does it.","type":"boolean"},"button_label":{"description":"Button text, at most 20 characters. Default: \"Send me the link\"","maxLength":20,"type":"string"},"button_message":{"description":"First DM, sent with the button. Default: \"Thanks for your comment! Tap the button below and I'll send you the link.\"","maxLength":640,"type":"string"},"custom_message":{"description":"Message containing {url}, replaced by delivery_url.","maxLength":1000,"type":"string"},"delivery_method":{"enum":["dm","reply"],"type":"string"},"delivery_url":{"description":"Absolute http(s) link to deliver.","type":"string"},"is_active":{"type":"boolean"},"match_mode":{"enum":["keyword","all"],"type":"string"},"public_replies":{"description":"Public replies under the comment, up to 6 of 300 characters. {{first_name}} greets the commenter by name. Default: [\"Thanks! Please see DMs.\", \"Sent you a message! Check it out!\", \"Nice! Check your DMs!\"]","items":{"maxLength":300,"type":"string"},"maxItems":6,"type":"array"},"public_reply":{"description":"DM delivery only, default true. Once the DM is sent, also answer the comment publicly with one of public_replies, picked at random.","type":"boolean"},"trigger_keyword":{"maxLength":100,"type":"string"}},"required":["delivery_url"],"type":"object"},"content":{"description":"Final caption to publish.","type":"string"},"is_comment_for_guide":{"type":"boolean"},"link":{"type":"string"},"media_files":{"items":{"properties":{"name":{"type":"string"},"s3_url":{"type":"string"},"type":{"enum":["image","video"],"type":"string"}},"required":["type","s3_url"],"type":"object"},"type":"array"},"platform_overrides":{"description":"Optional platform-specific text and publishing settings.","type":"object"},"platforms":{"description":"One account per platform per request.","items":{"properties":{"account_id":{"type":"string"},"platform":{"type":"string"}},"required":["platform","account_id"],"type":"object"},"type":"array"},"project_id":{"description":"Distribb project ID (from list_projects).","type":"integer"},"scheduled_for":{"description":"Future ISO8601 UTC datetime; omit to publish now.","type":"string"}},"required":["content","platforms","project_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Publish or schedule a social post","tags":["social"]}},"/suggestions":{"get":{"description":"List the improvements Distribb suggested for existing pages from Google Search Console data, with their status (pending, ready, published, rejected) and target page.","operationId":"list_optimizations","parameters":[{"in":"query","name":"project_id","required":true,"schema":{"description":"Distribb project ID (from list_projects).","type":"integer"}},{"in":"query","name":"status","required":false,"schema":{"description":"pending, approved, ready, published, rejected or failed.","type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"List optimizations","tags":["suggestions"]}},"/suggestions/{optimization_id}":{"get":{"description":"One optimization in full: the diagnosis, the Search Console data behind it, and the before and after content.","operationId":"get_optimization","parameters":[{"in":"path","name":"optimization_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Get optimization","tags":["suggestions"]}},"/suggestions/{optimization_id}/publish":{"post":{"description":"Push a ready optimization to the live page on the connected site. Some rewrites of articles already live on a CMS can only be applied by hand; those return an error saying so and change nothing.","operationId":"publish_optimization","parameters":[{"in":"path","name":"optimization_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Publish optimization","tags":["suggestions"]}},"/suggestions/{optimization_id}/{action}":{"post":{"description":"Approve an optimization (Distribb then writes the improved version, status becomes ready) or reject it with a reason. Nothing changes on the live site.","operationId":"review_optimization","parameters":[{"in":"path","name":"optimization_id","required":true,"schema":{"type":"integer"}},{"in":"path","name":"action","required":true,"schema":{"enum":["approve","reject"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limited"}},"summary":"Approve or reject optimization","tags":["suggestions"]}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://distribb.io/api/v1"}]}