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. Paid Agentic Mode uses Distribb's keyword data; the Free Agentic plan uses your own DataForSEO or Ahrefs keys (see BYO Keys below). Also available at the alias POST /keywords/research (identical behavior).

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

If you connect a custom Webhook integration (instead of WordPress / Webflow / Shopify / Ghost / Wix / Notion / Framer), Distribb posts each finished article to your URL. The payload is wire-compatible with Outrank’s webhook spec, so any receiver written for Outrank works against Distribb with zero changes. Your endpoint must accept this JSON shape, validate the bearer token, and respond with 200 within 30 seconds.

If you return a published_url in the response body, Distribb will store it and link to it from your dashboard. Any non-2xx response triggers up to 3 retries with exponential backoff.

When the user clicks Sync to CMS on an article that has already been published, Distribb sends the same payload shape but with event_type: "update_articles" and is_update: true. Implement upsert on your side — resolve the existing post by slug (or by storing Distribb’s id on first publish), then update its title, body, meta, image, and status in place rather than creating a new post.

If your receiver ignores event_type and always inserts, sync events will create duplicate posts. Always branch on event_type or store Distribb’s id on first publish.

• 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 → your handler always inserts and ignores event_type. Branch on "update_articles" to upsert by slug.