API reference

Generated from /openapi.json, which is built from the same tool table that runs the Distribb MCP server. Base URL https://distribb.io/api/v1. Send your API key as Authorization: Bearer. The API documentation has the full guide with examples.

agent tools

GET/agent-tools

Find integration tools. 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.

  • area (query)
  • query (query): Words describing the task, e.g. "pause campaign".
  • integration (query): Integration key or name, e.g. "hunter".
  • names (query): Exact tool names, for their input_schema.

POST/agent-tools/call

Read from an integration. 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.

  • project_id (body, required): Distribb project ID (from list_projects).
  • tool (body, required): Tool name from find_integration_tools.
  • arguments (body): The tool's arguments, per its input_schema.
  • mode (body)

GET/agent-tools/jobs/{job_id}

Get a long-running result. 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.

  • job_id (path, required)

ai visibility

GET/ai-visibility

AI visibility report. How often the brand is cited by AI assistants (ChatGPT, Claude, Gemini, Perplexity) for tracked buyer prompts.

  • project_id (query, required): Distribb project ID (from list_projects).
  • view (query): summary or detail. Default summary.

articles

GET/articles

List articles. 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).

  • project_id (query): Distribb project ID (from list_projects).
  • status (query): Draft, Planned, or Published.
  • scheduled_after (query): ISO date, inclusive, e.g. 2026-10-01.
  • scheduled_before (query): ISO date, inclusive, e.g. 2026-10-07.
  • limit (query): Max 200. Default 50.
  • offset (query)

POST/articles

Create article. 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.

  • project_id (body, required): Distribb project ID (from list_projects).
  • keyword (body, required): Target keyword for the article.
  • title (body)
  • content (body): Full HTML body. Omit to let Distribb generate it.
  • meta_description (body)
  • feature_image (body): Absolute URL of the hero image, e.g. from upload_image.
  • alt_text (body): Alt text for the feature image.
  • article_style (body): e.g. listicle, how-to, comparison.
  • scheduled_date (body): ISO 8601 publish datetime.
  • category (body)

GET/articles/{article_id}

Get article. Fetch one article with its full HTML content, keyword, status, schedule, feature image, whether it is claimed, and its live URL if published.

  • article_id (path, required)

PUT/articles/{article_id}

Update article. 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.

  • article_id (path, required)
  • { (body)
  • c (body)
  • h (body)
  • a (body)
  • n (body)
  • g (body)
  • e (body)
  • s (body)
  • } (body)

POST/articles/{article_id}/publish

Publish article. Publish an article now to the connected CMS (WordPress, Webflow, Shopify, and other supported platforms).

  • article_id (path, required)

gbp

GET/gbp/performance

Google Business Profile performance. 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.

  • project_id (query, required): Distribb project ID (from list_projects).
  • days (query): Length of the period in days. Default 28.

GET/gbp/reviews

List Google reviews. List live Google Business Profile reviews for a project. Filter to unreplied reviews with has_reply false.

  • project_id (query, required): Distribb project ID (from list_projects).
  • has_reply (query): false returns only reviews still waiting on a reply.
  • limit (query)

POST/gbp/reviews/reply

Reply to Google review. Post a public owner reply to a Google Business Profile review. The reply goes live on Google.

  • project_id (body, required): Distribb project ID (from list_projects).
  • review_id (body, required): review_id from gbp_reviews.
  • message (body, required): The public reply text.

GET/gbp/status

Google Business Profile status. Google Business Profile connection status and review stats for a project.

  • project_id (query, required): Distribb project ID (from list_projects).

images

POST/images

Upload image. 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).

  • image_base64 (body): Base64 image bytes, or a data:image/...;base64 URL.
  • image_url (body): Public http(s) URL of an image to copy.
  • file (body): An image file from the conversation.

integrations

GET/integrations

List CMS integrations. List connected CMS and publishing integrations (WordPress, Webflow, Shopify, Wix, Framer, Ghost, Notion, and more) and their status.

  • project_id (query): Distribb project ID (from list_projects).

GET/integrations/catalog

Integrations catalog. 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.

  • project_id (query, required): Distribb project ID (from list_projects).
  • category (query): Only this group. Omit for everything.

GET/integrations/connect

Get a connect link. 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.

  • project_id (query, required): Distribb project ID (from list_projects).
  • integration (query, required): Key or name from integrations_catalog.

keywords

POST/keywords/search

Keyword research. Run keyword research for a seed keyword: search volume, difficulty, cost per click, and related keyword ideas in the project's market.

  • project_id (body, required): Distribb project ID (from list_projects).
  • keyword (body, required): Seed keyword, e.g. "crm software".
  • limit (body): How many related keyword ideas to return besides the seed. Default 20.

playbooks

GET/playbooks/{topic}

Read a playbook. 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.

  • topic (path, required)

projects

GET/projects

List projects. List every project (website) on the account with plan, publishing cadence, and CMS connection status.

POST/projects

Create project. Create a new project for a website. Optionally include business_name, business_description, and any writable settings keys.

  • website_url (body, required): The site to create the project for, e.g. https://acme.com.
  • business_name (body)
  • business_description (body)

GET/projects/{project_id}

Get project settings. 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).

  • project_id (path, required): Distribb project ID (from list_projects).

PUT/projects/{project_id}

Update project settings. 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.

  • project_id (path, required): Distribb project ID (from list_projects).
  • { (body)
  • s (body)
  • e (body)
  • t (body)
  • i (body)
  • n (body)
  • g (body)
  • } (body)

POST/projects/{project_id}/article-plan

Set article plan. Set how many articles a month the project gets: 8 (premium, longer articles), 30 (one a day) or 5 (backlinks focused); Accelerator members can also choose 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.

  • project_id (path, required): Distribb project ID (from list_projects).
  • plan (body, required): Articles per month.

POST/projects/{project_id}/onboarding

Start keyword research. 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.

  • project_id (path, required): Distribb project ID (from list_projects).

screenshots

POST/screenshots

Screenshot a web page. 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.

  • url (body, required): The public page to capture.
  • name (body, required): The business or product the page belongs to.

search console

GET/search-console

Search Console performance. Google Search Console performance for a project: clicks, impressions, positions, and top queries over the last N days.

  • project_id (query, required): Distribb project ID (from list_projects).
  • days (query): Lookback window, default 28.
  • limit (query)

social

GET/social/accounts

List connected social accounts. List this project's social accounts, usernames and account_id values. Match the requested handle before publishing; projects can have several Instagram accounts.

  • project_id (query, required): Distribb project ID (from list_projects).

POST/social/media

Upload social image or video. 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.

  • project_id (body, required): Distribb project ID (from list_projects).
  • media_url (body): Public http(s) download URL of the image or video.
  • name (body)
  • file (body)

GET/social/posts

List recent social posts. 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.

  • project_id (query, required): Distribb project ID (from list_projects).
  • limit (query)

GET/social/posts/{post_id}

Get social post and delivery status. 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.

  • post_id (path, required)

PUT/social/posts/{post_id}/comment-for-guide

Configure comment-triggered delivery. 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.

  • post_id (path, required)
  • is_comment_for_guide (body)
  • comment_for_guide_config (body)

POST/social/publish

Publish or schedule a social post. 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.

  • project_id (body, required): Distribb project ID (from list_projects).
  • content (body, required): Final caption to publish.
  • platforms (body, required): One account per platform per request.
  • media_files (body)
  • link (body)
  • scheduled_for (body): Future ISO8601 UTC datetime; omit to publish now.
  • platform_overrides (body): Optional platform-specific text and publishing settings.
  • is_comment_for_guide (body)
  • comment_for_guide_config (body)

suggestions

GET/suggestions

List optimizations. List the improvements Distribb suggested for existing pages from Google Search Console data, with their status (pending, ready, published, rejected) and target page.

  • project_id (query, required): Distribb project ID (from list_projects).
  • status (query): pending, approved, ready, published, rejected or failed.
  • limit (query)

GET/suggestions/{optimization_id}

Get optimization. One optimization in full: the diagnosis, the Search Console data behind it, and the before and after content.

  • optimization_id (path, required)

POST/suggestions/{optimization_id}/publish

Publish optimization. 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.

  • optimization_id (path, required)

POST/suggestions/{optimization_id}/{action}

Approve or reject optimization. Approve an optimization (Distribb then writes the improved version, status becomes ready) or reject it with a reason. Nothing changes on the live site.

  • optimization_id (path, required)
  • action (path, required)