by Bomx
Distribb CLI, Claude, Codex, Hermes, OpenClaw skill for AI-powered SEO. Write content with your own AI, publish through Distribb's backlink network.
# Add to your Claude Code skills
git clone https://github.com/Bomx/distribb-skillGuides for using ai agents skills like distribb-skill.
distribb-skill is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by Bomx. Distribb CLI, Claude, Codex, Hermes, OpenClaw skill for AI-powered SEO. Write content with your own AI, publish through Distribb's backlink network. It has 102 GitHub stars.
distribb-skill's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/Bomx/distribb-skill" and add it to your Claude Code skills directory (see the Installation section above). distribb-skill ships a SKILL.md manifest, so compatible agents can discover and load it automatically.
distribb-skill is primarily written in Python. It is open-source under Bomx on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh distribb-skill against similar tools.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
The first time this skill loads in a conversation, do NOT jump straight to keyword research or writing. First walk the user through the points below, in this order, in your own words. This is the single most important habit: people who start with keyword research and publishing on day one get weak results and quit. People who follow the process get results.
Distribb is your SEO platform. You (the AI agent) do the thinking and the writing. Distribb provides the infrastructure: real keyword data, a backlink exchange network of real businesses, Google Search Console analysis, CMS publishing (WordPress, Webflow, Shopify, Ghost, Wix, Notion, GoHighLevel, Framer, or any API webhook), a content calendar, social repurposing, and done-for-you distribution on the Accelerator plan. You bring your own AI model. Distribb does everything around the writing.
Tell the user this is the order that works, and that you will guide them through it:
references/onboarding-guide.md for exactly what onboarding asks and why.references/onboarding-guide.md for the GSC connection details, including what to do if the user does not have Search Console set up yet./gsc-audit <domain> or follow references/audit-playbook.md. The audit is available on every plan, including Free.references/audit-playbook.md (topical authority section)./optimize.This whole skill exists to run that loop for the user. When in doubt, point them back to it.
Distribb runs a network of real businesses that exchange backlinks. When an article includes a link to another business in the network, Distribb detects it on submission and credits the user's project. The more links the user gives, the more they receive. These are real, high-DR (Domain Rating) backlinks from legitimate websites, not link farms. Free plans receive 1 backlink per month. Paid plans get unlimited exchange access. Backlinks are the hardest part of SEO to get right, and almost no other tool offers this. See references/plans-and-backlinks.md.
This skill ships ready-to-use slash commands so the user can drive the whole workflow with /:
| Command | What it does |
|---|---|
/distribb |
Overview, account status, and the proper SEO process above |
/distribb-setup |
Check the API key, confirm website + GSC are connected, and enable the other slash commands |
/gsc-audit <domain> |
Full SEO audit from Search Console + on-page + competitor + cannibalization + topic clusters |
/keyword-research <seed> |
Keyword ideas with volume and difficulty |
/write-article <keyword> |
Research, write, add internal links + backlinks, and publish one article |
/optimize |
Find and rewrite pages stuck on page 2+ using GSC data |
/backlinks |
Check backlink credits, see targets, and explain how the exchange works |
/content-calendar |
List, schedule, and manage planned/draft/published articles |
/ai-visibility |
Find where the user should be recommended by ChatGPT/Perplexity/Gemini and which listicles to pitch |
/news-writer <site-url-or-niche> |
Newsjack: find fresh news in the niche, write grounded news drafts, and queue them in Distribb |
/statistics-page-writer <topic> |
Deep-research and publish a sourced statistics page journalists cite for months |
If these commands are not yet available when the user types them, run /distribb-setup (or copy this skill's commands/*.md into the project's .claude/commands/ folder) to register them. See the Slash Commands section below.
If the user has no Distribb account yet, send them to https://distribb.io to sign up and go through onboarding. Their Distribb API key appears in Settings afterward. Plans at a glance (full detail in references/plans-and-backlinks.md):
POST /articles/generate path), per-project credits.references/plans-and-backlinks.md.Free Agentic plan, keyword research returns HTTP 402 until keys are saved: On Free Agentic, POST /keywords/search returns HTTP 402 Payment Required with error: "byo_keys_required" until the user saves a DataForSEO or Ahrefs API key at https://distribb.io/settings#seo-keys. The 402 body includes an instructions_for_agent string. Surface it verbatim to the user, do not retry. See the Keyword Research, BYO Keys section below for the full contract.
export DISTRIBB_API_KEY=your_api_key_here
No installation required. All commands use curl and jq.
| Property | Value |
|---|---|
| name | distribb |
| description | SEO platform: keyword research, article writing, backlink exchange network, CMS publishing, social media repurposing, content calendar |
| allowed-tools | Bash(curl:), Bash(jq:), Bash(cat:*), WebFetch, WebSearch, Read, Write |
All endpoints use: https://distribb.io/api/v1
All requests require the header: Authorization: Bearer $DISTRIBB_API_KEY
Before running any workflow, verify your API key works:
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects | jq .
If you get {"error": "Missing or invalid API key..."} or {"error": "Account is not active."}, the key is wrong or the account is inactive. Ask the user to check their API key in Settings at https://distribb.io/settings.
| Capability | How It Works | Endpoint |
|---|---|---|
| Generate Article | Submit source content, Distribb AI expands into full SEO article (Pro plan only) | POST /articles/generate |
| Keyword Research | Search volume, difficulty scores, keyword ideas. Paid plans use Distribb data; Free Agentic uses the user's own DataForSEO or Ahrefs key (returns HTTP 402 if not set) | POST /keywords/search (alias: POST /keywords/research) |
| Backlink Exchange | Get real backlinks from other businesses in the network | GET /backlink-targets |
| CMS Publishing | Publish to WordPress, Webflow, Shopify, Ghost, custom API | POST /articles/:id/publish |
| Content Calendar | Schedule articles, track status, manage your pipeline | GET /articles, POST /articles, PUT /articles/:id, DELETE /articles/:id |
| Project Settings | Read & edit the FULL settings surface (~30 fields): instructions, sitemap/blog URLs, content pillars, tone, writing profile, positioning, images/brand, competitors, toggles, publish time/timezone | GET /projects/:id, PUT /projects/:id |
| Create + Onboard Project | Create a new project (gated to paid slots; returns a buy-a-slot link if over) and optionally start keyword research + first articles. Ask the user before running research. Connect WordPress via API too | POST /projects, POST /projects/:id/onboarding, POST /projects/:id/wordpress |
| Internal Linking | Get your published article URLs to cross-link in new content | GET /internal-links |
| Business Context | Get brand voice, competitors, custom instructions | GET /business-context |
| Integrations | See connected CMS platforms | GET /integrations |
| Google Search Console | Pull the user's real GSC performance, top queries, top pages, clicks, impressions, CTR, position (if they've connected GSC) | GET /search-console |
| Content Optimizations | Find pages worth rewriting (mostly from GSC), review the AI's before/after diff, then approve and publish the rewrite to the CMS | GET /suggestions, POST /suggestions/run, POST /suggestions/:id/approve|publish|regenerate|reject |
| Social Media Repurposing | Auto-generates social posts (X, LinkedIn, Reddit, etc.) when an article is published | Automatic (no endpoint needed) |
| Microworkers Campaign Management | Create/register campaigns, list submissions, and rate worker slots for Reddit, Quora, YouTube, or generic proof tasks | GET/POST /microworkers/campaigns, GET /microworkers/campaigns/:id/slots, POST /microworkers/slots/:slot_id/rate |
Before any keyword research or writing, the user must have completed onboarding at https://distribb.io and connected two things. Everything downstream depends on this.
What onboarding collects (so you know what Distribb already knows, and what to fill if it is thin): the website URL, then an AI pass that auto-populates business details. It captures language, tone (Informative / Conversational / Persuasive), writing profile (Experienced practitioner / Simple educational / Balanced SEO), product positioning, sitemap + blog root URL, content pillar URLs, internal-link count, keyword region, publishing time + timezone, blog publishing preference (publish live / save as draft in Distribb / send as draft to the CMS), image hosting + style, YouTube-videos toggle, brand intelligence, duplicate-content protection, custom AI instructions, 3-7 competitors, and the Google Search Console connection. Full field-by-field detail and how to read or change each via the API is in references/onboarding-guide.md.
The two connections that matter most:
GET /integrations.GET /search-console (returns connected: true/false). If the user has GSC access but has not connected it to Distribb, send them to https://distribb.io/integrations . If the user does not have Search Console set up at all yet, point them to Google's guide first: https://support.google.com/webmasters/answer/10267942?hl=en , then have them connect it in Distribb.Also confirm the site actually has a blog to publish to. A site with no blog index has nowhere for articles to live, and this is a common reason new users see no results.
Real SEO starts with an audit, not with publishing. Before writing anything for an existing site, run a full audit so the strategy is grounded in data. The audit is available on every plan, including Free (it only needs the website and, ideally, GSC).
A Distribb audit covers:
Run it with /gsc-audit <domain> or follow the full playbook in references/audit-playbook.md. The audit pulls real data from GET /search-console, GET /suggestions, and GET /business-context, crawls the live site for on-page checks, and ends with a prioritized action list wired to Distribb (new articles for gaps, optimization suggestions for page-2 pages). For very large GSC datasets, run each analysis in its own sub-agent so context stays manageable.
Users often ask "where do I see X?" Here is the map (full detail in references/platform-guide.md):
| Page | What the user does there | API equivalent you can use |
|---|---|---|
| Dashboard | Overview of projects and recent activity | GET /projects |
| Content Calendar | See and manage planned / draft / published articles and their schedule | GET /articles, POST /articles, PUT /articles/:id, DELETE /articles/:id |
| Settings | Business description, custom AI instructions, publish time, timezone, backlink-network toggle, SEO data keys | GET /projects/:id, PUT /projects/:id |
| Integrations | Connect CMS, social accounts, and Google Search Console | GET /integrations, GET /search-console |
| Backlinks | See backlinks earned and given, and credits | GET /backlinks/status, GET /backlink-targets |
| Optimizations / Suggestions | Review and approve GSC-driven rewrites of underperforming pages | GET /suggestions, POST /suggestions/run, approve/publish |
Yes, you (the agent) can check backlinks for the user. Use GET /backlinks/status?project_id=... for credits and counts, and GET /backlink-targets for who they can link to next. The dashboard Backlinks page shows the same data visually.
Quick reference (full detail in references/plans-and-backlinks.md):
/ai-visibility workflow. Direct them to https://distribb.io to upgrade.The full end-to-end process for creating a high-ranking SEO article:
# 1. DISCOVER: Get project info
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects | jq .
# 2. BUSINESS CONTEXT: Get brand voice, competitors, custom instructions
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/business-context?project_id=42" | jq .
# 3. KEYWORD RESEARCH: Find what to write about
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword": "crm software", "project_id": 42}' \
https://distribb.io/api/v1/keywords/search | jq .
# 4. INTERNAL LINKS: Get pages to cross-link in your article
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/internal-links?project_id=42&keyword=crm+software" | jq .
# 5. BACKLINK TARGETS (REQUIRED if BecklinksNetworkParticipation is "Yes")
# This is how the user earns backlinks from real businesses. Do NOT skip this step.
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/backlink-targets?project_id=42&keyword=crm+software" | jq .
# 6. WRITE THE ARTICLE using your AI, weaving in internal links + backlink targets
# Output valid HTML. Follow the SEO writing guidelines below.
# You MUST include 1-2 URLs from the backlink-targets response as natural references.
# 7. SUBMIT: Save to Distribb's content calendar
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": 42,
"keyword": "best crm for small business",
"title": "Best CRM for Small Business: 2026 Guide",
"content": "<h2>Introduction</h2><p>Your full HTML article here...</p>",
"meta_description": "Compare the best CRM tools for small business in 2026.",
"scheduled_date": "2026-04-01T09:00:00Z",
"status": "Planned"
}' \
https://distribb.io/api/v1/articles | jq .
# 8. PUBLISH: Push to CMS (or let it auto-publish on schedule)
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/articles/123/publish | jq .
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects | jq .
Response:
{
"projects": [
{
"ID": 42,
"BusinessName": "Acme Corp",
"WebsiteUrl": "https://acme.com",
"BusinessDescription": "...",
"Language": "English (US)",
"Status": "Active",
"BacklinkCredits": 10,
"BecklinksNetworkParticipation": "Yes",
"ArticlesPerDay": 1
}
]
}
IMPORTANT: Check the BecklinksNetworkParticipation field. If it is "Yes", this project is part of the backlink exchange network. You MUST call /backlink-targets before writing each article and include 1-2 target URLs in the content. This is how the user earns backlinks from other real businesses. Skipping this means the user gives nothing and receives nothing from the network.
GET returns a settings object; PUT accepts that same shape. So the loop is: GET, change the keys you want, PUT them back (read-modify-write). The PUT exposes the entire Settings UI, ~30 fields, not just a handful, so you can configure a project end-to-end without the dashboard. This is what makes agency-scale onboarding possible.
# Read current settings (returns { "project": {...}, "settings": {...} })
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects/42 | jq .settings
# Edit settings (send ONLY the keys you want to change — partial updates are safe)
curl -s -X PUT -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sitemap_url": "https://acme.com/sitemap.xml",
"blog_root_url": "https://acme.com/blog",
"content_pillars": ["https://acme.com/crm", "https://acme.com/pricing"],
"internal_links_per_article": 3,
"tone": "Conversational",
"writing_profile": "Balanced SEO",
"product_positioning": "Soft mention",
"image_hosting": "CMS",
"brand_color": "#1d4ed8",
"cta_intensity": "Soft",
"competitors": ["https://competitor1.com", "https://competitor2.com"],
"brand_intelligence": true,
"duplicate_content_protection": true,
"timezone": "America/New_York"
}' \
https://distribb.io/api/v1/projects/42 | jq .
Writable fields (every key the settings object returns is writable; aliases in parentheses):
| Field | Meaning / allowed values |
|---|---|
ai_instructions |
Custom writing guidelines applied to every article. |
business_name, business_description |
Brand name + what the business does (writing context). |
target_audience |
List of audience strings, e.g. ["SaaS founders"]. |
sitemap_url |
Sitemap URL (used to build the internal-link index). |
blog_root_url |
Blog root URL. |
content_pillars |
List of URLs (drives topic clusters + internal links). Each must be a valid URL, no spaces. |
internal_links_per_article (internal_links) |
Integer 1–5. |
tone |
Informative | Conversational | Persuasive. |
language |
UI label or code, e.g. English (US), French, en-gb. |
keyword_region |
e.g. United States, United Kingdom, Worldwide. |
writing_profile |
Experienced practitioner | Simple educational | Balanced SEO. |
product_positioning |
Neutral operational | Soft mention | Promotional. |
custom_author_name |
Byline author name. |
social_media_ai_instructions |
Custom instructions for repurposed social posts. |
publish_time |
Daily auto-publish time, 24-hour "HH:MM". |
timezone |
IANA name, e.g. "Europe/Madrid". |
publishing_status |
Publish Immediately | Save as Drafts | Send as Drafts. |
social_media_publishing_status |
Save as Drafts | Publish Immediately. |
image_hosting |
Distribb | CMS. |
image_style |
Free text (e.g. Realism, or a custom description). |
brand_color |
Hex string like "#e11d2a". |
image_prompt_instructions |
Extra guidance for image generation. |
title_based_featured_image |
true/false, title-card featured image. |
cta_intensity |
None | Soft | Direct. |
first_person_writing |
true/false. |
table_of_contents |
true/false, auto table of contents. |
avoid_formulaic_section_endings |
true/false. |
require_operational_examples |
true/false. |
strict_banned_phrase_guard |
true/false. |
banned_phrases (extra_banned_phrases) |
List of phrases to never use. |
brand_intelligence |
true/false. |
duplicate_content_protection (duplicate_content_guard_enabled) |
true/false. |
videos_enabled |
true/false. |
backlinks_network |
true/false, join/leave the backlink exchange. |
competitors (competitor_websites) |
List of competitor domains (read AND write). |
Partial updates are safe. The article-quality and image preferences are stored as merged JSON, so sending just {"cta_intensity": "Soft"} changes ONLY that, the other quality flags keep their current values. Invalid enum values return 400 with a message naming the allowed values.
Response (200):
{
"project_id": 42,
"updated_fields": ["tone", "cta_intensity", "competitors"],
"updated_columns": ["ContentStyle", "ArticleQualitySettings", "CompetitorWebsites"],
"message": "Project settings updated."
}
Not settable via API:
articles_per_day — plan-controlled. If sent, it's echoed back under ignored. Read it via GET /api/v1/projects or the settings block.min_position, max_position, min_impressions_per_week, min_article_age_days, excluded_article_ids) — applied at scan time by POST /api/v1/suggestions/run, not yet persisted per project. Sent values are echoed under ignored.Spin up a brand-new project for a client and configure it in ONE call. You can pass any writable settings field from the table above alongside the basics.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"website_url": "https://client.com",
"business_name": "Client Co",
"business_description": "Bookkeeping for trades businesses.",
"target_audience": ["plumbers", "electricians"],
"tone": "Conversational",
"content_pillars": ["https://client.com/bookkeeping", "https://client.com/payroll"],
"competitors": ["https://rival.com"]
}' \
https://distribb.io/api/v1/projects | jq .
Response (201): { "project_id": 77, "project_slots": {"used": 3, "total": 5}, "next_step": "...", ... }
Project slots are gated by the paid quantity. If the account is already at its limit, you get HTTP 402:
{
"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 ..."
}
When you see this: show the user purchase_url (one click opens the "Buy More Seats" dialog in their dashboard). Once they confirm they bought a slot, retry the same POST. Never try to bypass the limit.
Creating a project does NOT start keyword research (that spends credits). After it's created, ASK the user whether they want to kick off keyword research + the first articles now. If yes, call the onboarding endpoint below.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects/77/onboarding | jq .
Starts the same pipeline the dashboard runs when onboarding finishes: GSC-aware keyword discovery -> a planned content calendar -> the first articles begin generating. Returns 202; poll GET /api/v1/articles?project_id=77 to watch planned articles appear.
already_onboarded and does nothing.skipped_byok (those plans bring their own keywords — use POST /api/v1/keywords/search then POST /api/v1/articles).curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "wordpress_url": "https://client.com", "integration_key": "<plugin Integration Key>" }' \
https://distribb.io/api/v1/projects/77/wordpress | jq .
Install the Distribb WordPress plugin on the site, copy its Integration Key, and send it here. Credentials are validated (format check + live probe) before saving, the same checks the dashboard runs. Returns { "status": "connected" }; if live validation is inconclusive (WAF/network) it still saves and returns a warning.
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/business-context?project_id=42" | jq .
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
}
Use this before writing. The competitors list tells you which domains to NEVER link to. The ai_instructions field has custom writing guidelines from the user.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword": "project management", "project_id": 42}' \
https://distribb.io/api/v1/keywords/search | jq .
Response (200 OK):
{
"keywords": [
{
"keyword": "best project management tools",
"search_volume": 12000,
"keyword_difficulty": 35
}
]
}
Returns the seed keyword plus up to 20 related keywords with volume and difficulty.
If the calling user is on the Free Agentic plan and has not yet saved a DataForSEO or Ahrefs API key, this endpoint returns HTTP 402 Payment Required with a structured body so your agent knows exactly what to do. Paid plans (Agentic Mode and above) never see this response.
Response (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, what to do when you see this 402:
instructions_for_agent string verbatim to the human user.setup_url (Distribb Settings → SEO Data API Keys).Pseudocode:
resp = call_distribb("/api/v1/keywords/search", body)
if resp.status_code == 402 and resp.json().get("error") == "byo_keys_required":
instructions = resp.json()["instructions_for_agent"]
setup_url = resp.json()["setup_url"]
say_to_user(f"{instructions} Setup link: {setup_url}")
return # do not retry; wait for user
If the user has saved only an Ahrefs key (not DataForSEO), the response is sourced from Ahrefs Keywords Explorer and includes "source": "byo_ahrefs" plus a note field. All other endpoints in this skill (articles, integrations, backlinks, internal links) work normally for Free Agentic users without any BYO keys.
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/internal-links?project_id=42&keyword=crm+software" | jq .
Response:
{
"links": [
{
"url": "https://acme.com/blog/crm-guide",
"title": "The Complete CRM Guide",
"keyword": "crm guide",
"meta_description": "Everything you need..."
}
],
"num_links_recommended": 5,
"website_url": "https://acme.com"
}
Include the recommended number of internal links in each article. Place them naturally in the middle of paragraphs using <a href="EXACT_URL">descriptive anchor text</a>. Never use "click here". Space links at least 2 paragraphs apart.
# Get backlink targets to include in your article
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/backlink-targets?project_id=42&keyword=crm+software" | jq .
# Check credits and status
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/backlinks/status?project_id=42" | jq .
Targets response:
{
"targets": [
{
"url": "https://partner-site.com/related-article",
"title": "Related Partner Article",
"meta_description": "...",
"project_name": "Partner Co"
}
],
"category": "saas",
"credits": 10,
"instructions": "Include 1-2 of these URLs as natural references..."
}
How the backlink exchange works: Distribb connects real businesses that exchange backlinks with each other. When you include a link to a network partner in your article, Distribb detects it on submission and credits the user's project. The more backlinks the user gives out, the more they receive in return. These are high-quality, high-DR backlinks from real business websites.
The category field shows how the keyword was classified (e.g. "saas", "ecommerce"). Targets are capped at 5 per request. Include 1-2 backlink targets per article as natural references. Do NOT fabricate information about linked sites. Use topically relevant anchor text.
If the user wants Distribb to write the article from their source content (notes, drafts, talking points), use this endpoint. Distribb's AI will expand it into a full SEO article with YouTube videos, images, quotes, backlinks, and internal links. Costs 1 article credit. Not available on the Agentic plan.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": 42,
"keyword": "link building strategies",
"source_content": "Link building is about getting other websites to link to yours. Three main approaches: guest posting, broken link building, and creating linkable assets like original research...",
"instructions": "Add YouTube videos, include data and statistics",
"article_style": "Informative"
}' \
https://distribb.io/api/v1/articles/generate | jq .
Response (202):
{
"article_id": 456,
"status": "generating",
"keyword": "link building strategies",
"slug": "link-building-strategies",
"message": "Article generation started...",
"article_credits_remaining": 29
}
The article takes a few minutes to generate. Poll GET /api/v1/articles/456 to check when Status changes from Planned to Draft or Published.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": 42,
"keyword": "best crm tools for startups",
"title": "10 Best CRM Tools for Startups in 2026",
"content": "<h2>Introduction</h2><p>Finding the right CRM...</p>",
"meta_description": "Compare the 10 best CRM tools for startups.",
"scheduled_date": "2026-04-01T09:00:00Z",
"status": "Planned"
}' \
https://distribb.io/api/v1/articles | jq .
Response (201):
{
"article_id": 123,
"status": "Planned",
"keyword": "best crm tools for startups",
"slug": "best-crm-tools-for-startups",
"message": "Article created as Planned.",
"backlinks_processed": 2
}
If the article contained NO network backlinks, the response includes a warning:
{
"article_id": 124,
"status": "Draft",
"keyword": "crm for freelancers",
"slug": "crm-for-freelancers",
"message": "Article created as Draft.",
"backlinks_processed": 0,
"backlinks_warning": "Your project participates in the backlinks network but this article contains no backlinks to other network members. Include backlink targets (from GET /api/v1/backlink-targets) to earn credits and keep receiving backlinks."
}
IMPORTANT: If backlinks_warning is present in the response:
GET /backlink-targets to fetch network URLs for the article's keyword.PUT /api/v1/articles/{article_id} with the revised content.For long articles, write the HTML to a file and use @ syntax:
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg content "$(cat article.html)" '{
"project_id": 42,
"keyword": "best crm tools",
"title": "10 Best CRM Tools",
"content": $content,
"status": "Draft"
}')" \
https://distribb.io/api/v1/articles | jq .
Setting a scheduled_date schedules the article: submit it as a Draft with a date and Distribb auto-promotes it to Planned (passing status: Planned yourself is still fine). Omit the date and it stays a Draft for review. What happens ON the date depends on the project's PublishingStatus (read it from GET /api/v1/projects): Publish Immediately goes live; Save as Drafts keeps it as a draft inside Distribb for manual review; Send as Drafts pushes it to the CMS as a draft. So a correctly-scheduled article on a Save as Drafts project will NOT auto-publish to the live site, that is by design, not a bug.
Use this to revise an article after submission, for example to add backlink targets if the creation response included a backlinks_warning.
curl -s -X PUT -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg content "$(cat revised-article.html)" '{
"content": $content
}')" \
https://distribb.io/api/v1/articles/123 | jq .
Updatable fields: title, content, meta_description, keyword, article_style, status (Draft or Planned), scheduled_date. Send only the fields you want to change. Changing keyword also regenerates the article's slug. Scheduling is symmetric: sending a scheduled_date on a Draft promotes it to Planned (so it actually enters the publish pipeline), and sending "scheduled_date": null unschedules it, dropping a Planned article back to Draft. Pass an explicit status if you want to override either default.
Response (200):
{
"article_id": 123,
"updated_fields": ["Content", "IsPreGenerated"],
"message": "Article updated successfully.",
"backlinks_processed": 2
}
If content is updated and the project participates in the backlink network, Distribb re-scans for network backlinks and updates credits. You cannot update published articles.
curl -s -X DELETE -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/articles/123 | jq .
Deletes a Draft or Planned article. Published articles cannot be deleted (the live CMS post would be orphaned), you get a 400. Unpublish or hide it from the dashboard/CMS first, or simply unschedule it.
Response (200):
{ "article_id": 123, "deleted": true, "message": "Article deleted." }
To take an article off the calendar without deleting it, unschedule instead: PUT /api/v1/articles/123 with body {"scheduled_date": null}.
# All articles for a project (default: 50 per page)
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/articles?project_id=42" | jq .
# Filter by status
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/articles?project_id=42&status=Published" | jq .
# Pagination: use limit (max 200) and offset
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/articles?project_id=42&limit=20&offset=40" | jq .
Query parameters: project_id (optional), status (optional: Draft, Planned, Published), limit (default 50, max 200), offset (default 0).
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/articles/123 | jq .
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/articles/123/publish | jq .
Pushes the article to the user's connected CMS (WordPress, Webflow, Shopify, etc.). A manual publish like this always goes live, even if the project is set to Save as Drafts / Send as Drafts, that preference only controls AUTOMATIC scheduled publishing, not a deliberate "publish now". Returns 200 with {"status":"published","url":...} once the CMS confirms a live URL; 202 with {"status":"pending"} if the CMS hasn't confirmed yet (it will retry, the article is NOT lost).
The project must have a website/CMS connected. If none is, this returns 400 with {"error":"no_cms_integration"} and a connect_url. Surface that to the user verbatim, there is nowhere to publish until they connect their site at https://distribb.io/integrations . This is the single most common reason a scheduled article never publishes: a Google Search Console (analytics) connection is NOT a publishing destination. Before you tell a user an article will publish, confirm a CMS is connected with GET /api/v1/integrations.
When an article is published to the user's CMS, Distribb automatically generates social media posts for every platform the user has connected (X/Twitter, LinkedIn, Reddit, Facebook, Instagram, etc.). The agent does not need to call any endpoint for this. It happens server-side.
The social posts are created as drafts in the user's content calendar so they can review, edit, or schedule them from the Distribb dashboard. If the user has connected social accounts, publishing an article through the API triggers this automatically.
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/integrations?project_id=42" | jq .
Pull the user's real search performance from Google Search Console, top queries, top pages, and site totals (clicks, impressions, CTR, average position). Use it to find queries worth targeting, pages sitting just off page 1, or terms the user already ranks for. Requires the user to have connected GSC.
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/search-console?project_id=42&days=28&limit=25" | jq .
Query parameters: project_id (required), days (default 28, max 90), limit (rows per list, default 25, max 100).
Response (200, connected):
{
"connected": true,
"project_id": 42,
"property": "sc-domain:acme.com",
"date_range": { "start_date": "2026-05-06", "end_date": "2026-06-03", "days": 28 },
"totals": { "clicks": 1840, "impressions": 92344, "ctr": 0.0199, "avg_position": 18.4 },
"top_queries": [
{ "query": "best crm for small business", "clicks": 210, "impressions": 8100, "ctr": 0.0259, "position": 7.2 }
],
"top_pages": [
{ "page": "https://acme.com/blog/crm-guide", "clicks": 320, "impressions": 14200, "ctr": 0.0225, "position": 9.1 }
]
}
Response (200, NOT connected):
{
"connected": false,
"message": "Google Search Console is not connected for this project.",
"instructions_for_agent": "Tell the user to connect Google Search Console at https://distribb.io/integrations ...",
"connect_url": "https://distribb.io/integrations"
}
Agent contract:
connected is false, stop and tell the user the instructions_for_agent text verbatim, link them to connect_url (https://distribb.io/integrations), and do not retry until they confirm they've connected GSC.connected is true but the body has "error": "gsc_fetch_failed", their Google token likely expired, tell them to reconnect at the same URL.How to use the data: queries with lots of impressions but low CTR or an average position of ~8-20 are the best targets, write a new article or refresh an existing one for them. Pages at the bottom of page 1 (position ~8-12) often just need internal links and a content refresh to climb. Pair this with POST /articles (write the piece) and GET /internal-links (cross-link it).
Distribb continuously finds pages where a rewrite could win more traffic, mostly from the user's Google Search Console data (queries with impressions but low CTR, pages stuck at the bottom of page 1). Each one is a suggestion: Distribb scrapes the live page, has its AI draft an improved version, and stages a before/after diff for review. You (the agent) list them, inspect the diff, approve (which triggers the rewrite), then publish the approved rewrite straight to the user's CMS. This is the highest-leverage ongoing SEO loop, it acts on pages that already rank, so wins come faster than net-new articles.
Lifecycle: pending → (approve) → rewriting → ready → (publish) → published. A suggestion can also be rejected, failed, or superseded (the article changed after the suggestion was created, so the staged rewrite is stale).
# Generate a fresh batch now (pulls GSC + scores articles). Mirrors the weekly cron.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id": 42}' \
https://distribb.io/api/v1/suggestions/run | jq .
# List suggestions (optionally filter by status: pending, ready, published, ...)
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/suggestions?project_id=42&status=pending" | jq .
# Inspect a single suggestion, then its before/after rewrite
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/suggestions/123 | jq .
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/suggestions/123/diff | jq .
# Approve -> starts a background rewrite. Poll the suggestion until status is "ready".
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/suggestions/123/approve | jq .
# Once "ready", publish the rewrite to the connected CMS
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/suggestions/123/publish | jq .
# Not happy with the rewrite? Regenerate with feedback (only valid while "ready")
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"feedback": "Keep the pricing table, tighten the intro, add a FAQ."}' \
https://distribb.io/api/v1/suggestions/123/regenerate | jq .
# Or dismiss it
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason": "Page is being deprecated."}' \
https://distribb.io/api/v1/suggestions/123/reject | jq .
List response (200):
{
"project_id": 42,
"gsc_connected": true,
"counts": { "pending": 4, "ready": 1, "published": 9, "rejected": 2 },
"settings": { "enabled": true },
"suggestions": [
{
"id": 123,
"project_id": 42,
"article_id": 8801,
"status": "pending",
"suggestion_type": "content_rewrite",
"source_type": "distribb",
"article_title": "Best CRM for Small Business",
"article_url": "https://acme.com/blog/crm-guide",
"trigger_snapshot": { "query": "best crm for small business", "impressions": 8100, "ctr": 0.012, "position": 11.4 },
"created_at": "2026-06-16T06:00:00"
}
]
}
Agent contract:
publish pushes the rewrite live to the user's CMS. Show the user the diff (GET /suggestions/:id/diff) and get a clear go-ahead before approving/publishing, unless they've explicitly told you to run optimizations autonomously.rewriting. Poll GET /api/v1/suggestions/:id every ~15-30s until status is ready (rewrite staged) or failed. Do not publish until ready.409 on approve or publish is a conflict, the article changed since the suggestion was created (status flips to superseded). Run POST /suggestions/run to regenerate fresh suggestions against the current article, then start over.gsc_connected is false and the list is empty, follow the instructions_for_agent string: tell the user to connect GSC at https://distribb.io/integrations, then POST /suggestions/run.Parameters:
GET /suggestions, project_id (required), status (optional), limit (default 100, max 500).POST /suggestions/run, project_id (required).POST /suggestions/:id/reject, optional reason. POST /suggestions/:id/regenerate, optional feedback.Use these endpoints to manage Microworkers Basic Campaigns through Distribb. Campaigns are project-scoped, so always pass project_id when creating or registering a campaign. Only rate a worker slot OK after the submitted proof has been verified.
# List registered campaigns
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/microworkers/campaigns?project_id=42" | jq .
# Create a campaign with a Microworkers template
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg template_html "$(cat microworkers-template.html)" '{
"project_id": 42,
"title": "Post a Reddit Comment",
"description": "Follow the Distribb task page, post the exact comment, and submit the comment URL plus confirmation code.",
"template_html": $template_html,
"platform": "reddit",
"campaign_type": "reddit_comment",
"category_id": "4004",
"available_positions": 50,
"payment_per_task": 0.15,
"minutes_to_finish": 10
}')" \
https://distribb.io/api/v1/microworkers/campaigns | jq .
# Register an existing campaign created by a VPS script
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id": 42, "campaign_id": "123456", "platform": "reddit", "campaign_type": "reddit_comment"}' \
https://distribb.io/api/v1/microworkers/campaigns/register | jq .
# Get live campaign details
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/microworkers/campaigns/123456 | jq .
# List submitted slots that need rating
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/microworkers/campaigns/123456/slots?status=NOTRATED&pageSize=50" | jq .
# Rate a slot after proof verification
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"campaign_id": "123456", "rating": "OK", "comment": "Proof verified. Thank you."}' \
https://distribb.io/api/v1/microworkers/slots/7890/rate | jq .
Create campaign request fields: project_id, title, description, and template_html are required. Optional fields: platform, campaign_type, category_id, available_positions, payment_per_task (minimum 0.15), minutes_to_finish, ttr, speed, template_title, number_of_file_proofs, and allowed_file_types.
Rating rules: rating must be OK, NOK, or REVISE. Use NOK with a clear worker-facing comment when proof is invalid. Use REVISE when the worker can fix the submission.
Follow this for EVERY article. The goal: content a human wants to read AND that AI search engines (ChatGPT, Perplexity, Gemini, Google AI Overviews) quote and recommend.
Pick the format from search intent, then follow its spine:
## 1. [Named option] ... ## N. [Named option] -> optional ONE "how to choose" checklist near the end -> FAQ -> short conclusion## Step 1: [Action] ... (sequential) -> FAQ -> conclusionThe worst mistake is writing a "best X" listicle as a how-to ("Step 1: define your goals"). Name the actual options. That IS the article.
## N. [Name]): one line of what it is (plain "is/has") -> who it's best for -> 2-4 sentences of concrete, sourced reasons it earns the spot -> an honest caveat/limitation -> vary the closer (don't end every item with "Bottom line:").## Step N: [Action]): goal -> exact imperative instructions -> a milestone ("By now you should have...").Write the draft, cut these AI tells, then ask "what still reads like AI?" and fix it:
ai_instructions ask for that, follow them.)/internal-links response.<a href="https://site.com/exact-url">descriptive anchor text</a>GET /backlink-targets before writing if the project has BecklinksNetworkParticipation: "Yes".title and meta_description to understand what the page covers and reference it honestly.backlinks_warning. Inform the user./business-context.# Step 1: Get project info
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects | jq .
# Pick project ID 42
# Step 2: Get business context
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/business-context?project_id=42" | jq .
# Note: competitors are ["hubspot.com", "salesforce.com"]
# Note: ai_instructions say "Focus on small business use cases"
# Step 3: Find a keyword
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword": "crm software", "project_id": 42}' \
https://distribb.io/api/v1/keywords/search | jq .
# Pick: "best crm for small business" (volume: 8100, difficulty: 42)
# Step 4: Get internal links
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/internal-links?project_id=42&keyword=best+crm+for+small+business" | jq .
# Got 5 links to include
# Step 5: Get backlink targets (REQUIRED - project has BecklinksNetworkParticipation: "Yes")
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/backlink-targets?project_id=42&keyword=best+crm+for+small+business" | jq .
# Got 3 targets. MUST include 1-2 in the article to earn backlink credits.
# Step 6: Write the article (using your AI)
# - Include 5 internal links from step 4
# - Include 1-2 backlink target URLs from step 5 as natural references (mandatory)
# - Follow the SEO writing guidelines above
# - Never link to hubspot.com or salesforce.com (competitors)
# - Output valid HTML
# Step 7: Submit to Distribb
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg content "$(cat article.html)" '{
"project_id": 42,
"keyword": "best crm for small business",
"title": "Best CRM for Small Business: 2026 Guide",
"content": $content,
"meta_description": "We compared 12 CRM tools for small business. See pricing, features, and our data.",
"scheduled_date": "2026-04-01T09:00:00Z",
"status": "Planned"
}')" \
https://distribb.io/api/v1/articles | jq .
# Step 8: Article appears in the Distribb content calendar
# It auto-publishes at the scheduled time, or publish immediately:
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/articles/456/publish | jq .
Use this workflow when the user asks you to:
This is a 3-phase research playbook. You (the agent) act as an AI search visibility strategist. The deliverable is actionable enough for a VA or outreach person to execute without re-asking the user any questions.
If the user is running this workflow for a project other than their own Distribb business, swap "Distribb" for the target project's business name and competitors from GET /business-context?project_id=.... Otherwise default to Distribb.io itself (a SaaS that does AI SEO keyword research, content writing/publishing, a backlink exchange network, social repurposing, and AI-search visibility).
Generate at least 100 realistic prompts that a potential Distribb buyer would type into ChatGPT, Perplexity, Gemini, Claude, or Google AI Overviews, prompts where Distribb should be recommended.
Cover all of these prompt categories (≥10 per category):
Bias toward buying intent, comparison intent, and problem-aware intent. Skip pure informational queries ("what is SEO").
For every prompt, capture these columns:
| Column | Notes |
|---|---|
| Prompt | The exact phrasing a buyer would type |
| Search intent | Informational / Comparison / Transactional |
| Buyer stage | Problem-aware / Solution-aware / Ready-to-buy |
| Ideal Distribb angle | The single sentence positioning that should land in the AI answer |
| Main competitors likely to appear | Surfer, Jasper, Frase, MarketMuse, Clearscope, Scalenut, Outranking, SE Ranking, Semrush, Ahrefs, KoalaWriter, NeuronWriter, Copy.ai, Writesonic, etc. |
| Priority | 1-10 (10 = closest to ready-to-buy + highest commercial value) |
| Why this prompt matters | One-line rationale |
Take the 30 highest-priority prompts from Phase 1 and actually run them. Use WebSearch and/or WebFetch against live AI-search-shaped queries, do not guess. For each, capture:
| Column | Notes |
|---|---|
| Prompt | From Phase 1 |
| Distribb appears? | Yes / No / Partial (e.g. mentioned but not recommended) |
| Competitors that appear | List the actual names in the live answer |
| Sources cited / referenced | URLs that the AI/SERP is citing, listicles, blogs, Reddit, YouTube, G2/Capterra, Product Hunt, company pages |
| Article(s) most influencing the answer | The 1-3 URLs doing the heavy lifting |
| Source type mix | SaaS review site / blog listicle / Reddit / YouTube / company page / forum / news |
| What Distribb needs to be included or rank higher | Concrete gap: missing from listicle X, no Reddit mention, no comparison page, no G2 profile, etc. |
Hard rules for Phase 2:
unverified in the cell and explain why in a footnote.For every Phase 2 prompt where Distribb should appear but does not, find the third-party pages already being cited or ranking. Prioritize listicles, round-ups, comparison posts, and directories over competitor homepages. Page archetypes to hunt for:
For each target page, capture:
| Column | Notes |
|---|---|
| Article title | Exact title |
| URL | Full URL |
| Website / domain | Root domain |
| Article category | One of the archetypes above |
| Why it matters | Which AI answer or SERP it currently shapes |
| Prompt(s) it could influence | Reference Phase 1 prompt numbers |
| Current tools mentioned | The 5-15 tools already in the listicle |
| Distribb currently included? | Yes / No / Briefly mentioned |
| Outreach priority | High / Medium / Low |
| Suggested pitch angle | One specific reason to add Distribb (e.g. "you cover Surfer + Frase but no tool in your list does the backlink exchange piece") |
| Contact info | Contact page URL, author name, author email, or the "submit a tool" form URL, verified, not invented |
| Personalization notes | Recent post by the author, the year of the listicle, the angle of their site, anything a VA can use in the first line |
unverified and explain.POST /articles, POST /articles/generate, etc.) during this workflow. Output the tables to the user; let them decide what to do next (pitch the listicles manually, or feed them into a separate outreach workflow).WebSearch for finding listicles and running buyer-intent queries.WebFetch for reading the actual content of each candidate listicle (to confirm tools mentioned, find author/contact info, and check freshness).GET /business-context?project_id=... if running this for a non-Distribb project, so competitor exclusions are respected.This skill ships a set of slash commands in its commands/ folder so the user can drive the whole workflow with /. Each command is a thin entry point that loads this skill and the matching reference, then runs the workflow against $ARGUMENTS.
| Command | Argument | Runs |
|---|---|---|
/distribb |
(none) | Overview, account status, and the proper SEO process |
/distribb-setup |
(none) | Validate the API key, confirm website + GSC are connected, register the other commands |
/gsc-audit |
<domain> |
Full audit (references/audit-playbook.md) |
/keyword-research |
<seed keyword> |
Keyword ideas with volume + difficulty |
/write-article |
<keyword> |
Research, write, link, backlink, and publish one article |
/optimize |
(none) | GSC-driven rewrites of pages stuck on page 2+ |
/backlinks |
(none) | Credits, targets, and how the exchange works |
/content-calendar |
(none) | List / schedule / manage articles |
/ai-visibility |
(none) | AI-search visibility + listicle outreach research |
/news-writer |
<site-url-or-niche> |
Newsjack: find fresh news, write grounded drafts, queue in Distribb |
/statistics-page-writer |
<industry-or-topic> |
Deep-research and publish a journalist-ready statistics page |
Enabling the commands. Depending on how the skill was installed, the commands may already be live. If a command is not recognized, register them once by copying this skill's command files into the project's command folder:
# From the project root, with <skill_dir> = where this skill is installed
mkdir -p .claude/commands
cp <skill_dir>/commands/*.md .claude/commands/
/distribb-setup does this automatically (it locates the skill directory and copies the files for you), then the commands are available after the next message. Power users can also work entirely through the API sections in this file without any slash commands.
This skill ships with structured sub-workflows for opinionated multi-week SEO programs. Load the matching sub-skill's SKILL.md instead of trying to run the workflow from this top-level file.
| Sub-skill folder | When to invoke |
|---|---|
90-day-seo-sprint/ |
User asks for an SEO sprint, a 90-day SEO plan, an SEO tracker / roadmap, "where do I start with SEO", "how do I get my first 1,000 organic visitors", or anything similar. Sub-skill opens the Distribb tracker Google Sheet in their browser and walks them through 4 phases (Pre-launch / Foundation / Content Engine / Authority) using the API endpoints below. |
If a sub-skill applies, read its SKILL.md first before calling any endpoint. Each sub-skill assumes you already have a Distribb API key set and the parent skill loaded for the actual API surface, sub-skills only add structure, content, and execution discipline.
All error responses return JSON:
{"error": "Description of what went wrong"}
| Status Code | Meaning |
|---|---|
| 400 | Bad request. Missing or invalid parameters. |
| 401 | Unauthorized. Invalid or missing API key. |
| 404 | Not found. Resource does not exist or does not belong to your account. |
| 429 | Rate limited. Too many requests -- wait and retry with exponential backoff (see below). |
| 500 | Server error. Something went wrong on our end. Retry once after 5 seconds. |
| 202 | Accepted but not fully completed. Only returned by POST /articles/:id/publish when CMS publishing was queued but not confirmed. The article status was set to Planned and will be retried automatically. |
| 503 | Service temporarily unavailable. External service (DataForSEO, CMS) is down. Retry after 30 seconds. |
When you get a 429, use exponential backoff:
# Wait 10 seconds, then retry. If still 429, wait 20s, then 40s.
sleep 10
Do NOT hammer the API in a loop. Space out requests by at least 2 seconds when making multiple sequential calls.
| Endpoint | Limit |
|---|---|
GET /projects, GET /projects/:id, GET /articles, GET /articles/:id, GET /business-context, GET /integrations, GET /backlinks/status |
30 req/min |
POST /keywords/search, POST /keywords/research |
5 req/min |
GET /internal-links, GET /backlink-targets, GET /search-console |
10 req/min |
GET /suggestions, GET /suggestions/:id, GET /suggestions/:id/diff |
30 req/min |
POST /articles, PUT /articles/:id, DELETE /articles/:id, PUT /projects/:id, POST /projects, POST /projects/:id/wordpress |
10 req/min |
POST /suggestions/:id/approve, POST /suggestions/:id/reject, POST /suggestions/:id/regenerate |
10 req/min |
POST /articles/:id/publish, POST /suggestions/:id/publish, POST /projects/:id/onboarding |
5 req/min |
POST /suggestions/run |
3 req/min |
/business-context first to understand the brand voice, competitors, and custom instructions./internal-links response tells you exactly how many links to include (num_links_recommended)./backlinks/status to see how many credits the project has. More credits = more backlinks received./backlink-targets when BecklinksNetworkParticipation is "Yes". This is the single most impactful SEO feature for the user. Articles without network backlinks do not earn credits.scheduled_date promotes a Draft to Planned automatically; omit the date to keep it a Draft for review. Whether a scheduled article goes live or waits as a draft on its date is set by the project's PublishingStatus (Publish Immediately vs Save as Drafts/Send as Drafts), so always check that field before telling a user their article will publish.jq to extract IDs, URLs, and data for the next step.jq -n --arg content "$(cat article.html)" to safely encode.Sign up for Distribb Agentic Mode: https://distribb.io/agentic 3-day free trial, $49/mo. Your API key will be in Settings after signup.
npx skills add Bomx/distribb-skill
SEO automation for AI agents. Use any AI model you want. Distribb provides the infrastructure: real keyword data, backlinks from real businesses, a Google Search Console audit, CMS publishing, content calendar, social repurposing, Microworkers campaign management, and analytics.
export DISTRIBB_API_KEY=your_key_here
No installation required for the API. The skill uses curl and jq. The first time it loads, it walks the user through the proper SEO process: account + onboarding, connect website + Google Search Console, audit, topic clusters, write + backlink, optimize.
/gsc-audit). Available on every plan, including Free./optimize).| Command | What it does |
|---|---|
/distribb |
Overview, account status, and the proper SEO process |
/distribb-setup |
Check the API key, confirm website + GSC are connected, enable the commands |
/gsc-audit <domain> |
Full SEO audit (CTR, decay, page-2, cannibalization, topic clusters, competitor, on-page) |
/keyword-research <seed> |
Keyword ideas with volume and difficulty |
/write-article <keyword> |
Research, write, link, backlink, and publish one article |
/optimize |
Rewrite pages stuck on page 2+ from GSC data |
/backlinks |
Check credits and targets, explain the exchange |
/content-calendar |
List, schedule, and manage articles |
/ai-visibility |
Find where AI engines should recommend you, and which listicles to pitch |
/news-writer <site-url-or-niche> |
Turn fresh news in your niche into grounded drafts and queue them in Distribb to autopublish |
/statistics-page-writer <topic> |
Deep-research and publish a sourced statistics page journalists love to link to |
Command files live in commands/. If they are not auto-registered by your installer, run /distribb-setup or copy commands/*.md into your project's .claude/commands/ folder.
| Plan | Keyword data | Backlinks | Who writes |
|---|---|---|---|
| Free Agentic ($0/mo) | Bring your own DataForSEO or Ahrefs key | 1 backlink/month | You (the agent) |
| Agentic Mode ($49/mo, 3-day trial) | Distribb-provided | Unlimited exchange | You (the agent) |
| Pro | Distribb-provided | Unlimited exchange | Distribb writes + publishes for you |
| Accelerator | Distribb-provided | Unlimited exchange | You + done-for-you AI-search distribution |
Every plan, including Free, can run the audit and use the content calendar. See references/plans-and-backlinks.md for full detail. Current pricing is at distribb.io.
# Projects
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/projects | jq .
# Business context (brand voice, competitors, custom instructions)
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/business-context?project_id=42" | jq .
# Google Search Console (powers the audit + optimizations)
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/search-console?project_id=42&days=90&limit=100" | jq .
# Keyword research
# Free Agentic plan: returns HTTP 402 with `error: "byo_keys_required"` until
# the user saves their own DataForSEO or Ahrefs API key in Settings.
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword": "crm software", "project_id": 42}' \
https://distribb.io/api/v1/keywords/search | jq .
# Internal links
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/internal-links?project_id=42&keyword=crm+software" | jq .
# Backlink targets
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/backlink-targets?project_id=42&keyword=crm+software" | jq .
# Create article
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id": 42, "keyword": "best crm", "title": "Best CRM", "content": "<h2>...</h2>", "status": "Draft"}' \
https://distribb.io/api/v1/articles | jq .
# Optimization suggestions (rewrite page-2 pages)
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id": 42}' \
https://distribb.io/api/v1/suggestions/run | jq .
# Publish to CMS
curl -s -X POST -H "Authorization: Bearer $DISTRIBB_API_KEY" \
https://distribb.io/api/v1/articles/123/publish | jq .
# Integrations
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/integrations?project_id=42" | jq .
# Microworkers campaigns
curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \
"https://distribb.io/api/v1/microworkers/campaigns?project_id=42" | jq .
Real SEO starts with an audit, not with publishing. /gsc-audit <domain> (or references/audit-playbook.md) runs nine analyses from Distribb's own Search Console connection and a live crawl: CTR optimization, content decay, striking-distance / page-2 keywords, keyword cannibalization, dead pages, brand vs non-brand health, topical authority clusters (topic cocoons), competitor gaps, and basic on-page checks. It ends with a prioritized action plan wired into Distribb. Works on every plan.
Distribb connects real businesses that exchange backlinks. When your article includes a link to a network partner, Distribb detects it on submission and credits your project. More given = more received. Free plans receive 1 backlink/month; paid plans get unlimited exchange access. These are high-DR links from legitimate business websites.
The Free Agentic plan does not bundle keyword data. Users save their own DataForSEO or Ahrefs API keys at distribb.io/settings#seo-keys. All other endpoints (articles, integrations, backlinks, audit) work normally without any keys.
When /api/v1/keywords/search is called by a Free Agentic user with no keys saved, the response is HTTP 402 with "error": "byo_keys_required" and an instructions_for_agent string. Surface that string to the user verbatim and do not retry until they have saved credentials.
Distribb can create/register project-scoped Microworkers Basic Campaigns, list worker slots/submissions, and rate submissions as OK, NOK, or REVISE. Campaign creation requires project_id, title, description, and template_html; optional fields include platform, campaign_type, category_id, available_positions, payment_per_task, proof settings, and timing controls.
| File | What it covers |
|---|---|
references/audit-playbook.md |
The full SEO audit workflow |
references/onboarding-guide.md |
Everything onboarding collects + the website + GSC connections |
references/platform-guide.md |
Where things live in the app (calendar, settings, backlinks, optimizations) |
references/plans-and-backlinks.md |
Plans, the backlink exchange, and the Accelerator |
references/statistics-page-playbook.md |
How /statistics-page-writer deep-researches and builds a journalist-ready statistics page |
| Folder | What it does |
|---|---|
90-day-seo-sprint/ |
Run the Distribb 90-Day SEO Sprint: a phased program (Pre-launch / Foundation / Content Engine / Authority) built on the endpoints in this skill. Use when the user asks for an "SEO sprint", "90-day SEO plan", or "where do I start with SEO". |
The skill works fully with curl + jq (no install). These Python helpers ship as optional conveniences:
| File | What it is |
|---|---|
distribb_cli.py |
A thin CLI over the same API (projects:list, articles:create, keywords:search, suggestions:list, etc.). pip install requests python-dotenv, then export DISTRIBB_API_KEY=.... |
distribb_research.py |
A standalone original-data research pipeline (plan -> scrape -> analyze) that produces a sourced hook + data table to weave into articles. Uses your own AI key; never invents data. |
distribb_writer.py |
A reference implementation showing how to write an SEO article locally with your own AI and submit it via the API. Meant to be modified or swapped out. |
news_topics.py |
Used by /news-writer. A stdlib-only Google News RSS scraper (no API key, no install) that surfaces fresh, recent headlines for a niche and writes news_topics_export.csv next to itself. |
The MCP server exposes every Distribb endpoint as a native tool. See the API docs for setup.
Sign up at distribb.io. Your API key is in Settings after you complete onboarding.