API Documentation

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.

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

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.

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

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

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. Free and Agentic plans bring their own keywords, so research is skipped and the response says so.

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.

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

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.

Send only the fields you want to update. If content is updated and the project participates in the backlink network, backlinks are re-scanned.

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

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.

Search for keyword ideas with search volume and difficulty data. Agentic Mode uses 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).

The Free Agentic plan is deprecated and no longer offered to new users. Current plans are Agentic Mode at $49/month and Pro at $97/month. 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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

List project-scoped Microworkers campaigns registered through Distribb.

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.

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.

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.

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.

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.

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.

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.

• 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.