# Distribb API documentation

Source: https://distribb.io/api-docs

# API documentation. Plug your AI agent in.

Connect your AI agent to Distribb. Your agent can research keywords, write and publish articles, and read backlinks and Search Console data, on any plan.

Base URLhttps://distribb.io/api/v1

[Get your API key](https://distribb.io/integrations?add=ai-agents) Use the MCP server

REST and JSONBearer token authMCP for Claude

## Quick Start

Fastest setup (Cursor, Claude Code, Codex, and 45+ agents):

`npx skills add Bomx/distribb-skill`

  1. Sign up at [distribb.io](https://distribb.io/#pricing)
  2. Find your API key in [Integrations → AI Agents](https://distribb.io/integrations?add=ai-agents)
  3. Set it as an environment variable: `export DISTRIBB_API_KEY=your_key`
  4. Install the skill: `npx skills add Bomx/distribb-skill`
  5. Or use curl directly: `curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" https://distribb.io/api/v1/projects | jq .`

## Authentication

All API requests require a Bearer token in the **Authorization** header. Your API key is available in [Integrations → AI Agents](https://distribb.io/integrations?add=ai-agents).

Authorization: Bearer your_api_key_here

## Endpoints

GET /projects POST /projects GET /projects/:id PUT /projects/:id POST /projects/:id/onboarding POST /projects/:id/article-plan POST /projects/:id/wordpress GET /articles POST /articles PUT /articles/:id GET /articles/:id DEL /articles/:id POST /articles/generate POST /articles/:id/publish GET /articles/:id/brief POST /images POST /screenshots POST /keywords/search GET /internal-links GET /backlink-targets GET /backlinks/status GET /backlinks GET /business-context GET /integrations GET /search-console GET /rankings · /analytics GET /ai-visibility POST /ai-visibility/scan POST /ai-visibility/prompts GET /suggestions POST /suggestions/run POST /suggestions/:id/… GET /microworkers/campaigns POST /microworkers/campaigns GET /outreach/entitlement POST /outreach/sync MCP MCP Server: Claude / Cursor native tools

### Endpoint reference

GET /projects List all your projects

30 req/min

Returns all active projects linked to your account. Use the project `ID` in subsequent API calls.

Response

{ "projects": [ { "ID": 1, "BusinessName": "Acme Corp", "WebsiteUrl": "https://acme.com", "BusinessDescription": "...", "Language": "English (US)", "Status": "Active", "BacklinkCredits": 10, "ArticlesPerDay": 1 } ] }

## New-client flow (agencies)

Spinning up a client from scratch is a deliberate 3-call sequence. Creating the project does NOT spend keyword-research credits, so you can create and configure freely, then ask the user before starting research.

  1. `POST /projects` with the client's `website_url` (plus any settings) to create and configure the project.
  2. `POST /projects/:id/onboarding` to start keyword research and the first articles. Ask the user first; this one spends credits.
  3. `POST /projects/:id/wordpress` to connect the client's CMS so articles can publish.

POST /projects Create + configure a project

10 req/min

Create a new project for the authenticated account. Only `website_url` is required; you can pass any writable field from PUT /projects/:id in the same body to configure the project on create. Creating a project does NOT start keyword research (that spends credits), so after creating, ask the user, then call `POST /projects/:id/onboarding`.

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
website_url| string| Yes| Client site URL (normalized and validated)  
business_name| string| No| Business name  
business_description| string| No| What the business does  
target_audience| string[]| No| Audience segments  
(any writable field)| any| No| Any key from the PUT writable set (same validation)  
  
Response (201)

{ "project_id": 42, "website_url": "https://client.com", "backlink_credits": 100, "project_slots": { "used": 3, "total": 5 }, "message": "Project created. Keyword research has NOT started yet.", "next_step": "Ask the user if they want to start keyword research now...", "settings_applied": ["tone", "language"] }

Response (200, idempotent reuse)

Posting the same `website_url` again returns the existing active project instead of creating a duplicate.

{ "project_id": 42, "website_url": "https://client.com", "already_existed": true, "message": "A project already exists for this website; returning it." }

Response (402, project limit reached)

Project slots are gated by the account's paid quantity. At the limit, this returns a machine-readable body with a `purchase_url` the human can click to buy another slot; retry the same body once they confirm.

HTTP/1.1 402 Payment Required { "error": "project_limit_reached", "active_projects": 5, "project_quantity": 5, "purchase_url": "https://distribb.io/dashboard?add_project=1", "instructions_for_agent": "Tell the user they've hit their project limit and share purchase_url..." }

GET /projects/:id Read one project's full settings

30 req/min

Returns the project plus a `settings` object that mirrors the writable keys of PUT /projects/:id. GET it, tweak keys, and PUT the same shape back (read-modify-write).

Response

{ "project": { "ID": 42, "BusinessName": "Acme Corp", "WebsiteUrl": "https://acme.com", ... }, "settings": { "tone": "Informative", "language": "English (US)", "keyword_region": "United States", "internal_links_per_article": 5, "competitors": ["https://competitor.com"], "duplicate_content_protection": true, "articles_per_day": 1 } }

PUT /projects/:id Update project settings

10 req/min

Accepts the same field set as the Settings UI. Send only the fields you want to change; article-quality and image preferences are MERGED, so a partial update never resets the others. GET this project to see the `settings` object; every key there is writable here.

**Watch the exact key names:** the tone key is `tone` (not `content_style`), the duplicate-content toggle is `duplicate_content_protection` (not a bare `duplicate_content_guard`), and `articles_per_day` is plan-controlled and NOT settable (it is echoed back under `ignored`, never written).

#### Writable fields (JSON body)

Field| Type| Notes  
---|---|---  
ai_instructions| string| Custom writer instructions (null to clear)  
business_name| string| Business name  
business_description| string| What the business does  
target_audience| string[]| Audience segments  
sitemap_url| string| Sitemap URL  
blog_root_url| string| Blog root URL  
content_pillars| string[]| Pillar page URLs (list or CSV)  
internal_links_per_article| int| 1 to 5 (alias: internal_links)  
tone| enum| Informative, Conversational, Persuasive  
language| string| Supported label, e.g. "English (US)", "French"  
keyword_region| string| e.g. "United States", "United Kingdom", "Worldwide"  
writing_profile| enum| Experienced practitioner, Simple educational, Balanced SEO  
product_positioning| enum| Neutral operational, Soft mention, Promotional  
custom_author_name| string| Byline author name  
social_media_ai_instructions| string| Social repurposing instructions  
publish_time| string| 24-hour "HH:MM", e.g. "09:00"  
timezone| string| IANA name, e.g. "America/New_York"  
publishing_status| enum| Publish Immediately, Save as Drafts, Send as Drafts  
social_media_publishing_status| enum| Publish Immediately, Save as Drafts  
image_hosting| enum| Distribb, CMS  
image_style| string| Free-form style description (null to clear)  
brand_color| string| Hex, e.g. "#e11d2a"  
image_prompt_instructions| string| Extra image-prompt guidance  
title_based_featured_image| bool| Render the title onto the featured image  
cta_intensity| enum| None, Soft, Direct  
first_person_writing| bool| Write in first person  
table_of_contents| bool| Add a table of contents  
avoid_formulaic_section_endings| bool| Suppress formulaic section closers  
require_operational_examples| bool| Require concrete operational examples  
strict_banned_phrase_guard| bool| Enforce banned phrases strictly  
banned_phrases| string[]| Phrases to avoid (list or newline text)  
brand_intelligence| bool| Brand intelligence on/off  
duplicate_content_protection| bool| Duplicate-content guard on/off  
videos_enabled| bool| Embed YouTube videos on/off  
backlinks_network| bool| Participate in the backlink network  
competitors| string[]| Competitor domains (list or CSV)  
  
**Not settable via API:** `articles_per_day` (plan-controlled) and optimization thresholds (applied at scan time). Passing them is accepted but echoed under `ignored`. Connect WordPress via POST /projects/:id/wordpress.

Response

{ "project_id": 42, "updated_fields": ["tone", "duplicate_content_protection"], "updated_columns": ["ContentStyle", "DuplicateContentGuardEnabled"], "message": "Project settings updated.", "ignored": ["articles_per_day"], "notes": { "articles_per_day": "Controlled by the plan; not settable via the API." } }

POST /projects/:id/onboarding Start keyword research + first articles

5 req/min

Runs the same discovery pipeline the dashboard runs when onboarding finishes: keyword research, then the first planned articles. Ask the user before calling this; it spends keyword and LLM credits. Idempotent: if the project already has articles it will not re-run. Legacy Free Agentic and Agentic accounts bring their own keywords, so research is skipped and the response says so.

Response (202)

{ "project_id": 42, "status": "started", "message": "Keyword research started. Your content calendar will fill shortly...", "poll": "/api/v1/articles?project_id=42" }

Response (200, skipped)

{ "project_id": 42, "status": "skipped_byok", "message": "Your plan brings its own keywords... Use POST /api/v1/keywords/search." }

POST /projects/:id/wordpress Connect a WordPress site

10 req/min

Connect (or reconnect) a project's WordPress site via the Distribb plugin. Install the Distribb WordPress plugin on the site, copy its Integration Key, and send it here. Credentials are validated before saving (format check plus live probe), exactly like the Settings UI.

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
wordpress_url| string| Yes| The WordPress site URL  
integration_key| string| Yes| The Distribb plugin Integration Key  
wp_username| string| No| Optional WordPress username  
  
Response

{ "project_id": 42, "wordpress_url": "https://client.com", "status": "connected", "message": "WordPress connected successfully." }

GET /articles List articles with filters

30 req/min

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| No| Filter by project  
status| string| No| Draft, Planned, Published, Generating  
limit| int| No| Max results (default 50, max 200)  
offset| int| No| Pagination offset  
  
Response

{ "articles": [ { "ID": 42, "Title": "Best CRM for Startups", "MainKeyword": "best crm for startups", "Status": "Draft", "ScheduledDate": "2026-03-25T09:00:00", "ProjectID": 1, "Slug": "best-crm-for-startups", "ArticleStyle": "Informative" } ], "count": 1 }

POST /articles Submit a new article

10 req/min

Submit AI-generated content. Distribb handles backlink credit processing, stores the article, and prepares it for publishing.

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Target project ID  
keyword| string| Yes| Main keyword / topic  
title| string| No| Article title (defaults to keyword)  
content| string| No| Full HTML content  
meta_description| string| No| SEO meta description  
scheduled_date| string| No| ISO 8601 date (e.g. 2026-03-25T09:00:00Z)  
article_style| string| No| Informative, Listicle, How-To, etc.  
status| string| No| Draft (default) or Planned  
  
Response (201)

{ "article_id": 123, "status": "Draft", "keyword": "best crm for startups", "slug": "best-crm-for-startups", "message": "Article created as Draft.", "backlinks_processed": 2 }

PUT /articles/:id Update an existing article

10 req/min

Update an article's content, title, meta description, status, or scheduled date. Useful for revising articles to add backlink targets after receiving a `backlinks_warning`. Cannot update published articles.

Body Parameters

`content`| string| Updated HTML content  
---|---|---  
`title`| string| Updated title  
`meta_description`| string| Updated meta description  
`status`| string| "Draft" or "Planned"  
`scheduled_date`| string| ISO 8601 date (e.g. 2026-04-01T09:00:00Z)  
  
Send only the fields you want to update. If content is updated and the project participates in the backlink network, backlinks are re-scanned.

Response

{ "article_id": 123, "updated_fields": ["Content", "IsPreGenerated"], "message": "Article updated successfully.", "backlinks_processed": 2 }

GET /articles/:id Get a single article

30 req/min

Retrieve full article details including content. The article must belong to your account.

Response

{ "ID": 123, "Title": "Best CRM for Startups", "MainKeyword": "best crm for startups", "Content": "<h1>Best CRM for...</h1>...", "MetaDescription": "Compare the top CRM...", "Status": "Draft", "Slug": "best-crm-for-startups", "ScheduledDate": "2026-03-25T09:00:00", "ProjectID": 1, "ArticleStyle": "Informative" }

DELETE /articles/:id Delete a draft or planned article

10 req/min

Delete an article that belongs to your account. Draft and Planned articles are removed. Published articles are blocked (400); unschedule them, or unpublish or hide them from the dashboard or your CMS first.

Response

{ "article_id": 123, "deleted": true, "message": "Article deleted." }

POST /keywords/search Search keywords with volume data

5 req/min

Search for keyword ideas with search volume and difficulty data. Current plans use Distribb's keyword data. Legacy Free Agentic accounts use their own DataForSEO or Ahrefs keys (see BYO Keys below). Also available at the alias `POST /keywords/research` (identical behavior).

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
keyword| string| Yes| Seed keyword to research  
project_id| int| No| Project for context and ownership  
limit| int| No| Related keyword ideas to return besides the seed, 1 to 100. Default 20  
  
Response

{ "keywords": [ { "keyword": "crm software for small business", "search_volume": 2400, "keyword_difficulty": 38, "cpc": 14.2 } ], "market": { "country": "United States", "language": "English" } }

`cpc` is the Google Ads cost per click in USD. `market` is the market the numbers come from. A project set to Worldwide gets United States numbers, and `market` then also carries `requested_country` and a `note` saying so.

Bring-Your-Own-Keys (legacy Free Agentic accounts)

The Free Agentic plan is no longer offered. The current plans are Pro at $97/month and Accelerator at $495/month, and neither sees this response. If the calling user is on a **legacy Free Agentic** account and has not yet saved a DataForSEO or Ahrefs API key, this endpoint returns **HTTP 402 Payment Required** with a machine-readable body so your agent knows what to do. Paid plans never see this response.

HTTP/1.1 402 Payment Required { "error": "byo_keys_required", "message": "Keyword research requires your own DataForSEO or Ahrefs API key.", "plan": "Agentic Free", "required": { "any_of": ["dataforseo", "ahrefs"] }, "setup_url": "https://distribb.io/settings#seo-keys", "docs_url": "https://distribb.io/api-docs#byo-keys", "instructions_for_agent": "Tell the user to add their DataForSEO Login + API Key (or Ahrefs API Key) at distribb.io/settings, then re-run keyword research." }

**Agent contract:** on receiving 402 with `error = "byo_keys_required"`, halt the keyword-research step and surface `instructions_for_agent` verbatim to the human user. Do not retry until `setup_url` has been visited and credentials saved. 

Provider precedence when both keys are saved: DataForSEO is used first (full keyword expansion); if only Ahrefs is saved, the response is sourced from Ahrefs Keywords Explorer (`"source": "byo_ahrefs"`). All other Distribb endpoints (articles, integrations, backlinks) work normally without BYO keys. 

GET /backlinks/status Check backlink credits and stats

30 req/min

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| No| Filter to a specific project  
  
Response

{ "projects": [ { "project_id": 1, "business_name": "Acme Corp", "backlink_credits": 10, "network_participation": "Yes", "backlinks_received": 5, "verified": 4, "pending": 1 } ] }

GET /backlinks Full link-level backlink ledger

30 req/min

The link-level detail behind the aggregate /backlinks/status: earned links (source domain, DR, business, target URL, status, date), upcoming scheduled links, and a velocity summary. Per-link anchor text is not captured yet, so an anchor-mix breakdown is intentionally omitted rather than guessed.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
earned_limit| int| No| Max earned links (default 100, max 500)  
scheduled_limit| int| No| Max scheduled links (default 50, max 200)  
  
Response

{ "project_id": 1, "earned": [ { "source_domain": "partner-site.com", "source_business": "Partner Co", "source_dr": 54, "target_url": "https://acme.com/crm-guide", "status": "Verified", "date": "2026-06-30" } ], "earned_count": 1, "scheduled": [ { "source_domain": "another-site.com", "source_business": "Another Co", "source_dr": 41, "target_url": "https://acme.com/pricing", "status": "Scheduled", "scheduled_since": "2026-07-02" } ], "scheduled_count": 1, "velocity": { "velocity_cap": 10, "velocity_used": 3 }, "note": "Per-link anchor text is not captured yet; anchor-mix distribution is not included." }

GET /integrations List connected CMS and social platforms

30 req/min

Lists active CMS and social integrations. Each row returns `Platform` (the platform/CMS type, e.g. WordPress, Shopify, Google Search Console, a social type), a friendly `IntegrationName` label, and `Status`.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| No| Filter to a specific project  
  
Response

{ "integrations": [ { "ID": 1, "Platform": "WordPress", "IntegrationName": "WordPress", "Status": "Active", "ProjectID": 1, "BusinessName": "Acme Corp" } ] }

GET /internal-links Get internal link candidates

10 req/min

Returns published articles from your site that are relevant to a keyword. Use these as internal links in your new article for better SEO.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
keyword| string| Yes| Target keyword for the article  
  
Response

{ "links": [ { "url": "https://acme.com/crm-guide", "title": "The Complete CRM Guide", "keyword": "crm guide", "meta_description": "Everything you need..." } ], "num_links_recommended": 5, "website_url": "https://acme.com" }

GET /backlink-targets Get network backlink URLs

10 req/min

Returns URLs from other Distribb network members. Include 1-2 of these as natural references in your article to earn backlink credits. When you submit the article, Distribb detects these links and credits your project automatically.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
keyword| string| Yes| Target keyword for the article  
  
Response

{ "targets": [ { "url": "https://partner-site.com/related-article", "title": "Related Partner Article", "meta_description": "...", "project_name": "Partner Co" } ], "credits": 10, "instructions": "Include 1-2 of these URLs as natural references..." }

POST /projects/:id/article-plan Set the project's article plan

10 req/min

Switch between the article plans the account already includes: `8` premium articles a month, `30` (one a day) or `5` (5 premium articles a month). Accelerator members choose `"premium30"` (30 premium articles a month, one a day) in place of `30`, plus `60` and `90`. `GET /projects/:id` lists them under `article_plan` with the recommended one. Plans that would cost extra are refused, so this never bills. During onboarding the choice replaces the default the setup wizard would apply.

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
plan| int or string| Yes| 8, 30, 5, 60, 90 or "premium30"  
premium| bool| No| With plan 30: the same as "premium30"  
  
GET /articles/:id/brief Everything needed to write one planned article

60 req/min

Saving 2,000+ characters of content on a Planned article with `PUT /articles/:id` claims it: Distribb's writer skips it and publishes your content exactly as saved on its date, adding no images, internal links or exchange links. Claim more than 72 hours before the scheduled date; once Distribb's writer has started an article the PUT returns 409 `already_being_written`. The brief returns the claim window, the instructions for this article, the word-count target, the exchange partner links the article is committed to carry (include every one, anchored with the partner's business name), the planned internal links, the call-to-action URL, and image requirements.

Response (abridged)

{ "claim": { "claimable": true, "claim_by": "2026-10-06T09:00:00" }, "targets": { "word_count": 1800 }, "required_links": { "exchange_partners": [ { "url": "https://partner.com", "anchor": "Partner Co" } ], "internal": [ { "url": "https://yoursite.com/blog/guide", "anchor": "..." } ], "call_to_action_url": "https://yoursite.com/pricing" }, "images": { "feature_image": "Required...", "style": "Realism" } }

POST /images Host an image for an article

30 req/min

Host an image you created, or copy a public image URL, and get back a public URL to use in `<img src>` and as `feature_image`. JPG, PNG, WebP or GIF, 12 MB max. Send exactly one source.

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
image_base64| string| One of| Base64 image bytes, or a `data:image/...;base64` URL  
image_url| string| One of| Public http(s) URL of an image to copy  
  
Response (201)

{ "url": "https://rebelgrowth.s3.us-east-1.amazonaws.com/blog-images/...", "width": 1536, "height": 1024 }

POST /screenshots Screenshot a public web page

30 req/min, 120 per day

Capture a public page, such as the homepage of a product ranked in a listicle, and host the screenshot. Runs in the background: the first call returns 202 `processing`; send the same `url` again (or `GET /screenshots/:screenshot_id`) after about 20 seconds to get `image_url`, or a 422 with the `reason` the page could not be captured cleanly (cookie banner left, broken images, wrong brand).

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
url| string| Yes| The public page to capture  
name| string| Yes| The business or product the page belongs to  
  
POST /articles/generate Expand your content into a full article (Pro only)

5 req/min

Submit your own content (notes, drafts, talking points) and Distribb's AI will expand it into a full SEO-optimized article with YouTube videos, images, quotes, backlinks, and internal links. Requires the **Pro plan** and costs 1 article credit. Not available on the Agentic plan (use `POST /articles` instead to submit your own AI-generated content).

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Target project ID  
keyword| string| Yes| Target keyword / topic for SEO  
source_content| string| Yes| Your content to expand (notes, draft, talking points, etc.)  
instructions| string| No| Additional guidance (e.g. "add YouTube videos", "focus on beginners")  
title| string| No| Article title (defaults to keyword)  
article_style| string| No| Informative, Listicle, How-To, etc. (default: Informative)  
  
Response (202)

{ "article_id": 456, "status": "generating", "keyword": "link building strategies", "slug": "link-building-strategies", "message": "Article generation started. Distribb will expand your content...", "article_credits_remaining": 29 }

POST /articles/:id/publish Publish to connected CMS

5 req/min

Triggers CMS publishing for an article. Distribb handles the integration (WordPress, Webflow, Shopify, Ghost, Wix, Notion, Framer, or Webhook) based on the project's connected platform.

Response (200)

{ "status": "published", "article_id": 123 }

Response (202 - Queued for Retry)

{ "error": "Publishing failed. The article has been queued and will be retried.", "article_id": 123 }

GET /business-context Get project business details

30 req/min

Returns project-specific context needed for high-quality content: business name, description, competitors, custom AI instructions, and language. Use this to ground your AI writer in the user's brand voice.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
  
Response

{ "business_name": "Acme Corp", "website_url": "https://acme.com", "description": "CRM platform for startups...", "competitors": ["https://competitor1.com", "https://competitor2.com"], "ai_instructions": "Use a friendly tone, focus on SaaS...", "language": "English (US)", "target_audience": "SaaS founders, startup CTOs", "internal_links_per_article": 5 }

GET /search-console GSC search performance by query and page

10 req/min

Google Search Console performance for a project: top queries, top pages, and site totals (clicks, impressions, CTR, average position) over the last N days. Requires the user to have connected GSC (Integrations, Google Search Console). If GSC is not connected, returns HTTP 200 with `connected: false` plus an `instructions_for_agent` string telling the user to connect it.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
days| int| No| Lookback window (default 28, max 90)  
limit| int| No| Rows per dimension (default 25, max 1000)  
start_row| int| No| Pagination offset; see the `pagination` block  
compare| bool| No| Add period-over-period deltas (see below)  
  
Each query/page row carries `is_brand` (matches the business name) and `striking_distance` (impressions ≥ 10 and average position 4 to 20). Paginate with `start_row`; the response returns a `pagination` block whose `next_start_row` is null on the last page. With `compare=true`, each row adds `delta_clicks`, `delta_impressions`, `delta_position`, and `is_new` versus the immediately preceding window, and a top-level `comparison` block adds `previous_totals` and `delta_totals`.

Response

{ "connected": true, "project_id": 1, "property": "https://acme.com/", "date_range": { "start_date": "2026-06-07", "end_date": "2026-07-05", "days": 28 }, "totals": { "clicks": 1240, "impressions": 88200, "ctr": 0.0141, "avg_position": 18.4 }, "top_queries": [ { "query": "best crm for startups", "clicks": 92, "impressions": 4100, "ctr": 0.0224, "position": 7.2, "is_brand": false, "striking_distance": true } ], "top_pages": [ "..." ], "pagination": { "limit": 25, "start_row": 0, "next_start_row": 25 } }

With ?compare=true (adds)

{ "comparison": { "previous_date_range": { "start_date": "2026-05-10", "end_date": "2026-06-06", "days": 28 }, "previous_totals": { "clicks": 1010, "impressions": 80100, "ctr": 0.0126, "avg_position": 19.1 }, "delta_totals": { "clicks": 230, "impressions": 8100, "ctr": 0.0015, "avg_position": -0.7 } } }

GET /rankings · /analytics Aliases of /search-console

10 req/min

Documented aliases of /search-console, for agents that look for `/rankings` or `/analytics`. Same handler, same parameters, same response. Note: this is Search Console search performance (clicks, impressions, CTR, position by query and page), NOT web-session analytics.

GET /ai-visibility AI-visibility (AEO) data by view

30 req/min

Read AI-visibility data for a project: how often it is cited across AI answer engines, its share of voice, and tracked prompts. API-key mirror of the dashboard AI-visibility pane.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
view| string| No| summary (default), prompts, competitors, cited_pages  
page, per_page| int| No| Pagination for `view=prompts`  
  
Response (view=summary)

{ "visibility_score": 42, "share_of_voice": 0.18, "engines": [ { "engine": "perplexity", "cited": true } ], "manual_scans_used": 1, "manual_scans_limit": 2, "can_scan": true }

POST /ai-visibility/scan Trigger an on-demand scan

6 req/min

Trigger an on-demand AI-visibility scan (the "Scan now" action). Enforces a per-project daily manual-scan cap that is SHARED with the dashboard button and the Distribb Agent, so heavy API scanning draws from the same budget. Returns 202 when queued, 429 when the cap is hit. `project_id` in the body or query.

Response (202, queued)

{ "status": "queued", "project_id": 1, "manual_scans_used": 2, "manual_scans_limit": 2, "message": "Scan queued. Poll GET /api/v1/ai-visibility?view=summary until it completes." }

Response (429, rate limited)

HTTP/1.1 429 Too Many Requests { "status": "rate_limited", "manual_scans_used": 2, "manual_scans_limit": 2, "error": "Daily scan limit reached (2/2). Resets at midnight UTC." }

POST /ai-visibility/prompts Add or remove a tracked prompt

20 req/min

Add (`POST`) or remove (`DELETE`) a tracked AI-visibility prompt. Added prompts are scanned on the next scan; removal is a soft-delete (past results are kept).

#### JSON Body

Field| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
prompt| string| Yes| The prompt to track (or remove)  
  
Response

{ "status": "added", "prompt": "best crm for startups" }

GET /suggestions List content-optimization suggestions

30 req/min

List a project's content-optimization suggestions (top queries and pages where a rewrite could lift rankings). Returns per-status counts, the project's suggestion settings, and whether GSC is connected. Suggestions are largely GSC-driven, so a disconnected project will usually have none.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| Yes| Your project ID  
status| string| No| pending, approved, rewriting, ready, published, rejected, failed, superseded  
type| string| No| Filter by opportunity_type: cannibalisation, declining_page, striking_distance, ctr_underperform, etc.  
limit| int| No| Max results (default 100, max 500)  
  
Response

{ "project_id": 1, "suggestions": [ { "id": 7, "status": "pending", "article_title": "Best CRM for Startups" } ], "counts": { "pending": 3, "ready": 1, "published": 5 }, "gsc_connected": true }

POST /suggestions/run Trigger an on-demand suggestion scan

3 req/min

Pull GSC, score articles, and insert new `pending` suggestions (deduped against existing open ones). Mirrors the weekly Monday cron. Returns the count created. `project_id` in the body or query.

Response

{ "project_id": 1, "created": 4, "message": "4 new suggestion(s) created. List them with GET /api/v1/suggestions?..." }

POST /suggestions/:id/… Read + act on a single suggestion

5-30 req/min

The full review-and-publish loop for one suggestion. The typical path is approve (starts a background rewrite), poll the single-suggestion GET until `status` is `ready`, review the diff, then publish.

#### Endpoints

Method + Path| Description  
---|---  
GET /suggestions/:id| Get one suggestion, including `proposed_diff` once a rewrite is ready  
GET /suggestions/:id/diff| Before/after rewrite plus the GSC `trigger_snapshot` (null until `ready`)  
POST /suggestions/:id/approve| Approve a `pending` suggestion; kicks off scrape + LLM rewrite. Poll until `ready`  
POST /suggestions/:id/reject| Reject so it stops showing as actionable. Optional body `{ "reason": "..." }`  
POST /suggestions/:id/publish| Publish a `ready` rewrite to the connected CMS (409 if the article changed since staging)  
POST /suggestions/:id/regenerate| Re-run the rewrite with optional `{ "feedback": "..." }`. Paid plans only (402 on free)  
  
Response (approve)

{ "suggestion": { "id": 7, "status": "approved" }, "message": "Approved. A background rewrite has started; poll until status is 'ready', then publish it." }

GET /microworkers/campaigns List registered Microworkers campaigns

30 req/min

List project-scoped Microworkers campaigns registered through Distribb.

#### Query Parameters

Name| Type| Required| Description  
---|---|---|---  
project_id| int| No| Filter to a specific project  
limit| int| No| Max results (default 50, max 100)  
offset| int| No| Pagination offset  
  
Response

{ "campaigns": [ { "ID": 3, "ProjectID": 1, "MicroworkersCampaignID": "abc123", "Platform": "linkedin", "Title": "Share our article", "Status": "running", "AvailablePositions": 50, "PaymentPerTask": 0.15 } ], "count": 1 }

POST /microworkers/campaigns Create + manage Microworkers campaigns

5-30 req/min

Create a Microworkers Basic Campaign and register it to a project, or register/inspect an existing one. Creating a campaign also builds its Microworkers template.

#### Endpoints

Method + Path| Description  
---|---  
POST /microworkers/campaigns| Create + register. Body: `project_id`, `title`, `description`, `template_html` (plus optional `available_positions`, `payment_per_task` ≥ 0.15, etc.)  
POST /microworkers/campaigns/register| Register an existing campaign by `campaign_id` so this key can manage it  
GET /microworkers/campaigns/:id| Get a registered campaign plus its live Microworkers status  
GET /microworkers/campaigns/:id/slots| List slots/submissions (query: `page`, `pageSize`, `status`)  
POST /microworkers/slots/:id/rate| Rate a slot. Body: `campaign_id`, `rating` (OK, NOK, REVISE), optional `comment`  
  
Response (201, create)

{ "campaign_id": "abc123", "template_id": "tpl_456", "project_id": 1, "status": "created", "external_url": "https://ttv.microworkers.com/campaign/abc123", "message": "Microworkers campaign created and registered to the project." }

GET /outreach/entitlement Check Outreach Pro entitlement

30 req/min

Returns whether the authenticated account is entitled to Outreach Pro (the flag is set and the account is active). Returns 403 when the Outreach Pro beta is closed for the account.

Response

{ "entitled": true, "plan": "Outreach Pro", "status": "active" }

POST /outreach/sync Mirror the Outreach skill DB

10 req/min

Idempotent upsert of the local Outreach skill database into MySQL mirror tables, keyed by the authenticated account. Body: `{ since, persons[], identities[], leads[], actions[], suppressions[] }`. The client re-pushes boundary rows; the upsert makes it idempotent. Returns per-table counts. 403 if not entitled.

Response

{ "synced": { "persons": 12, "identities": 3, "leads": 40, "actions": 88, "suppressions": 5 } }

POST your_webhook_url Payload Distribb sends to your endpoint

A custom Webhook integration receives initial articles and later edits at the same URL, using the same access token. Handle `publish_articles` and `update_articles` separately. Your endpoint must accept this JSON shape, validate the bearer token, and respond within 30 seconds. Use `202` if you queue the work.

#### Headers

Name| Value  
---|---  
Content-Type| `application/json`  
Authorization| `Bearer <your access token>`: the token you set in Settings → Integrations → Webhook  
X-API-Key| `<your access token>`: same value, sent for receivers that read this header (AWS API Gateway, generic SaaS)  
x-make-apikey| `<your access token>`: same value, sent for Make.com Custom Webhook "API Key restriction"  
User-Agent| `Distribb-Publisher/1.0`  
Idempotency-Key| A unique delivery key, reused for retries of that delivery. Later edits have a new key even when the article ID stays the same.  
  
Distribb sends your access token under three header names so the request authenticates against any common webhook receiver without extra configuration. Your endpoint only needs to validate _one_ of them.

#### Body

Field| Type| Description  
---|---|---  
event_type| string| `"publish_articles"` on the first send for a given slug; `"update_articles"` when the user clicks **Sync to CMS** on an article that is already live. Route on this field to decide CREATE vs UPDATE on your side.  
timestamp| string| When the webhook was sent (ISO 8601, UTC)  
data.articles[].id| string| Stable Distribb article ID. Store it as a unique post identifier. Do not discard all later deliveries with the same ID: they can contain edits.  
data.articles[].title| string| Article title  
data.articles[].slug| string| URL slug, e.g. `lawn-care-toronto`. A fallback to match older posts without a stored Distribb ID. Preserve the existing permalink on content updates.  
data.articles[].url, published_url| string, optional| The existing stored public URL. An update can identify the article by ID even if its URL is unknown.  
data.articles[].external_id| string, optional| The remote post ID, when known.  
data.articles[].content_html| string| Full article body as **HTML** (with `<h2>`, `<p>`, `<ul>`, `<figure>`, etc.). Render this if your CMS displays HTML directly.  
data.articles[].content_markdown| string| Same body converted to **real Markdown**. Render this if your CMS expects Markdown. Pick _one_ of the two, never both.  
data.articles[].meta_description| string| SEO meta description (~155 chars)  
data.articles[].published_at| string, optional| When the article went live (ISO 8601, UTC). **Use this as the post date.** Sent with every article delivered as `"Published"` and unchanged on later updates. Omitted for drafts; when it is absent, keep your stored date.  
data.articles[].created_at| string, optional| When Distribb wrote the article (ISO 8601, UTC), often days or weeks before it is published, so it is not a post date. Omitted on updates when unknown; keep your stored date when it is absent.  
data.articles[].updated_at| string| Saved modification time, or delivery time when no modification date is available.  
data.articles[].image_url| string| Public URL of the feature image (already hosted on our CDN). Use as-is or re-upload to your storage.  
data.articles[].alt_text| string| Alt text for the feature image  
data.articles[].tags| string[]| SEO tags / keywords  
data.articles[].author| string| Author display name  
data.articles[].status| string| `"Published"` or `"Draft"`. Sync preserves the article’s current publication status.  
data.articles[].is_update| boolean| `true` on sync events, `false` on first publish. Redundant with `event_type` but handy if your router checks the article object directly.  
data.articles[].update_only| boolean| `true` on updates. If the existing post is missing, return an error and create nothing.  
  
Example payload: initial publish

{ "event_type": "publish_articles", "timestamp": "2026-04-18T15:21:00Z", "data": { "articles": [ { "id": "63452", "title": "Essential Lawn Maintenance Toronto Guide 2026", "slug": "essential-lawn-maintenance-toronto-2026", "content_html": "<h2>Why a Healthy Lawn Matters</h2><p>Toronto lawns face...</p>...", "content_markdown": "## Why a Healthy Lawn Matters\n\nToronto lawns face...", "meta_description": "A practical guide to year-round lawn care in Toronto...", "created_at": "2026-04-15T12:23:16Z", "published_at": "2026-04-18T15:21:00Z", "image_url": "https://rebelgrowth.s3.us-east-1.amazonaws.com/blog-images/lawn-1.jpg", "alt_text": "lawn maintenance Toronto", "tags": ["lawn care", "toronto", "seasonal"], "author": "Trim Gym Lawn Care", "status": "Published", "is_update": false } ] } }

Example payload: sync (user re-edited in Distribb, clicked “Sync to CMS”)

{ "event_type": "update_articles", "timestamp": "2026-04-19T09:12:33Z", "data": { "articles": [ { "id": "63452", "slug": "essential-lawn-maintenance-toronto-2026", "title": "Essential Lawn Maintenance Toronto Guide 2026 (Updated)", "content_html": "...revised body...", "status": "Published", "is_update": true, "update_only": true, "published_at": "2026-04-18T15:21:00Z" // remaining fields identical shape; only changed values differ } ] } }

Expected response (200)

{ "success": true, "action": "updated", "published_url": "https://yourdomain.com/blog/essential-lawn-maintenance-toronto-2026" }

Return the existing `published_url` so Distribb can show the article link. A `2xx` response confirms receipt; it does not prove your public page has changed. Distribb checks the body for explicit failures, ignored updates, zero processed articles, and unexpected create responses. Initial publication can retry on server errors and timeouts; updates are sent once so an uncertain result is not replayed automatically.

Handling updates (recommended)

Users can click **Send changes to Webhook** on a published article or ask the Distribb Agent to send edits. Your existing route receives `event_type: "update_articles"`, `is_update: true`, and `update_only: true`. Find the existing post by its stored Distribb ID, update its content, and preserve its permalink and original dates. Match by slug only for older posts without that ID. If no post matches, return `404`.

if (payload.event_type === "update_articles") { // Placeholder DB methods; run inside your authenticated route. const existing = await db.posts.findOne({ distribb_id: article.id }) || await db.posts.findOne({ slug: article.slug, distribb_id: null }); if (!existing) { return res.status(404).json({ success: false, error: 'Article not found for update' }); } await db.posts.update(existing.id, { ...mapArticleFields(article), distribb_id: article.id, slug: existing.slug, created_at: existing.created_at, published_at: article.published_at || existing.published_at }); return res.json({ success: true, action: 'updated', published_url: existing.url }); } else if (payload.event_type === 'publish_articles') { // Use a unique Distribb ID to deduplicate initial publish retries. await db.posts.upsertByDistribbId(article.id, mapArticleFields(article)); }

Never fall back to creating a post from an update event. If your route only handles publication today, add this update branch to the same route; you do not need another integration or webhook URL.

Common pitfalls

  * **Wall-of-text output** → you're rendering `content_html` through a Markdown parser (or `content_markdown` through an HTML renderer). Pick the field that matches your renderer.
  * **Missing images** → your CMS strips remote `<img>` tags. Either allow our S3 domain or re-upload `image_url` to your own storage before saving.
  * **401 from your endpoint** → the bearer token in Settings doesn't match what your endpoint expects. Update one of them.
  * **Duplicate posts after Sync** → handle `"update_articles"` by finding and updating the existing post. Return an error if the post is missing.

##  MCP Server Model Context Protocol

Instead of writing curl commands, connect Distribb to Claude and call every endpoint as a native tool. The agent calls `list_projects`, `create_article`, `publish_article` directly, with no CLI flags and no shell scripts.

The hosted server is the recommended path: nothing to install, nothing to run, and you sign in with your Distribb account instead of pasting an API key.

1

**Add the server URL**

In Claude, open Settings → Connectors → Add custom connector and paste:

https://distribb.io/mcp

2

**Approve access**

You are redirected to Distribb, where you sign in and approve the connection. Distribb uses OAuth 2.0 with PKCE, so Claude never sees your password and you never paste an API key. Revoke access at any time from your Distribb settings.

3

**Start working**

Tools run against your own projects. Refresh the connector’s tool list after an update to load newly added tools. Ask for what you want in plain language, for example “find keywords for my project and plan four articles for next month”.

Transport is streamable HTTP. Every tool enforces the same plan limits, rate limits and per-account scoping as the REST API documented above, because each tool call is dispatched to these very same endpoints.

* * *

Read-only SEO tools

list_projects List every project (website) on the account with plan, publishing cadence,...

get_project Full settings for one project: AI writing instructions, tone, publish sched...

list_articles List articles for a project or the whole account

get_article Fetch one article with its full HTML content, keyword, status, schedule, an...

backlinks_status Backlink exchange status for a project: credits, links received, links give...

list_backlinks List the verified backlinks a project has received and given through the Di...

search_console_performance Google Search Console performance for a project: clicks, impressions, posit...

ai_visibility_report How often the brand is cited by AI assistants (ChatGPT, Claude, Gemini, Per...

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

gbp_reviews List live Google Business Profile reviews for a project

list_integrations List connected CMS and publishing integrations (WordPress, Webflow, Shopify...

SEO tools that write

These change data. `publish_article` pushes a post to your connected CMS, and `gbp_reply_review` posts a reply that is publicly visible on Google. Nothing in this server deletes projects, articles or reviews.

update_project Update project settings: ai_instructions, tone, publish_time, timezone, bac...

create_project Create a new project for a website

create_article Plan or create an article on a project

update_article Update an article: title, content, keyword, meta_description, article_style...

publish_article Publish an article now to the connected CMS (WordPress, Webflow, Shopify, a...

keyword_research Run keyword research for a seed keyword: search volume, difficulty, and rel...

gbp_reply_review Post a public owner reply to a Google Business Profile review

* * *

Publish reels and configure comment-triggered DMs

ChatGPT, Claude Code and other MCP clients share these tools. Select the requested account, upload the video, publish the caption and verify the DM rule.

list_social_accounts → upload_social_media → publish_social_post → get_social_post

Pass an explicit `account_id`, `is_comment_for_guide: true` and `comment_for_guide_config` with `match_mode`, `trigger_keyword`, `delivery_method: "dm"`, `delivery_url` and a `custom_message` containing `{url}`. Private DM delivery requires Instagram. By default (`button_first: true`) the first DM asks the commenter to tap a button, and the DM with the link is sent after the tap. Set the first DM with `button_message` (640 characters max) and the button text with `button_label` (20 max), or send `button_first: false` to put the link in the first DM. Once the DM is sent, the comment also gets a public reply picked at random from `public_replies` (up to 6 of 300 characters; `{{first_name}}` uses the commenter's name). Defaults are "Thanks! Please see DMs.", "Sent you a message! Check it out!" and "Nice! Check your DMs!"; send `public_reply: false` to skip it. Save the returned post ID and check `comment_for_guide.automation.status`.

Use `configure_social_post_auto_reply` to retry, edit or disable the rule on its existing post. If a publishing response was lost, use `list_social_posts` before trying again. Retrying a DM rule does not publish another reel.

GET /api/v1/social/accounts?project_id=42 POST /api/v1/social/media POST /api/v1/social/publish GET /api/v1/social/posts?project_id=42 GET /api/v1/social/posts/{post_id} PUT /api/v1/social/posts/{post_id}/comment-for-guide

Media uploads accept a multipart `file` plus `project_id`, or JSON with `project_id` and a public `media_url` or attached `file.download_url`. Upload MP4/MOV videos up to 64 MB or images up to 12 MB. Pass the returned `media` object in the publish request’s `media_files` array.

The [social publishing guide](https://github.com/Bomx/distribb-skill/blob/main/references/social-publishing.md) includes full JSON requests, CLI commands, scheduling and delivery status meanings. The [downloadable skill and CLI](https://github.com/Bomx/distribb-skill) use your `DISTRIBB_API_KEY` for the same API flow.

## Typical Workflow

Here is how an AI agent typically uses the API to create and publish an SEO article:

1. GET /projects # Get your project ID 2. GET /business-context?project_id=1 # Fetch brand voice + competitors 3. POST /keywords/search # Find target keywords 4. GET /internal-links?project_id=1&keyword=... # Get pages to link to 5. GET /backlink-targets?project_id=1&keyword=... # Get network URLs to cite 6. # Your AI writes the article using context from steps 2-5 7. POST /articles # Submit the article 8. POST /articles/123/publish # Publish to CMS

## Errors

All error responses follow the same format:

{ "error": "Description of what went wrong" }

Status Code| Meaning  
---|---  
400| Bad request. Missing or invalid parameters  
401| Unauthorized. Invalid or missing API key  
402| Payment required. `project_limit_reached` (POST /projects; body carries a `purchase_url`) or `byo_keys_required` (keyword search on a legacy Free Agentic account). Both return a machine-readable body with next-step instructions.  
403| Forbidden. Resource does not belong to your account, or a beta feature is closed  
404| Not found. The resource does not exist  
409| Conflict. The target changed since it was staged (e.g. publishing a suggestion whose article moved)  
429| Rate limited. Too many requests, or a daily cap (e.g. AI-visibility scans) was hit; wait and retry  
500| Server error. Something went wrong on our end
