Connect an AI agent

Confirms which RankBull workspace this API key belongs to, lists the key's permissions, and (when the key has sites:read) the workspace's sites with their siteIds. Free to call — start every session here to discover siteIds for the other tools.

No arguments.

Lists every active site in the key's workspace with siteId, domain, status, language, and sitemap URL. Use the returned siteId for all site-scoped tools.

No arguments.

Fetches one site's full record: domain, status, language, sitemap URL, target countries, and analysis state. Prefer list_sites first when you only need a siteId.

Lists AI-visibility monitors for a site (monitorId, cadence, status, engines). Needed before add_prompt.

Daily AI-search visibility aggregates for a site: visibility score, presence rate, share of voice, citation rate, and run counts per engine/brand/day. Rows cover the site's own brand and tracked competitors (distinguish by brandId). Free to call.

Lists the AI-search prompts tracked for a site (across its monitors) with promptId, text, intent, funnel stage, locale, and status. Pass a promptId to get_prompt_answers for the underlying runs and citations.

The receipts for one tracked prompt: real AI-engine runs (mention/citation counts per run) plus every source URL those answers cited, flagged is_your_domain when the citation points at the site. Use this to prove or debug why a prompt does/doesn't surface the brand.

Scored AI-visibility opportunities for a site (content gaps, competitor wins, citation gaps) with a recommended action each. Highest composite score first — start at the top.

Domains AI engines cite most when answering this site's tracked prompts, with citation counts, engine spread, and share of total. Use it to find the publications and directories worth earning mentions on.

Citation rows for a site (host, title, url, engine). Optional host or engineKey filter. Read-only.

Tracked competitor brands for a site (linkId, name, domain, source). Use linkId with remove_competitor.

Adds a manual competitor brand. Enforces the plan's per-site competitor cap (same error as the dashboard).

Removes a competitor link from the site. Frees a cap slot. Use linkId from list_competitors.

Domains that rank in stored Google SERP snapshots where this site does not. Read-only — does not spend a SERP refresh. Empty until keyword research has stored SERPs. For AI-answer competitors use list_competitors.

Latest site-health scan: score, status, summary, pages scanned, and recent score trend. Read-only — does not start a new crawl.

Google Search Console performance for a site: total clicks, impressions, CTR, and average position, plus top queries and a daily series. GSC data lags ~2 days behind real time. Returns connected:false when Search Console isn't linked — point the user at Settings → Analytics.

Google Analytics 4 traffic for a site: page views, sessions, users, engagement, top pages, traffic sources, and a daily series. GA4 data lags ~1 day. Returns connected:false when GA4 isn't linked — point the user at Settings → Analytics.

Bing Webmaster Tools performance for a site: total clicks, impressions, CTR, and average position, plus top queries, top pages, and a daily series. Bing data lags ~2 days. Returns connected:false when Bing isn't linked — point the user at Settings → Analytics.

One snapshot of the site: GSC clicks/impressions/avg position (if connected) and latest site-health score. Does not call DataForSEO. Pair with visibility_overview for AI scores.

Google index coverage for a site's watched pages: counts per bucket (indexed, not_indexed, pending, blocked, error, excluded), pages due for re-inspection, last inspection time, IndexNow key status, and the sitemap URL. Use list_indexing_pages to drill into one bucket.

Lists the watched pages for a site with their index bucket, Google verdict, coverage state, and crawl/inspection timestamps, newest first. Filter by bucket (e.g. not_indexed) to find the pages that need fixing; paginate with the returned continueCursor.

Pulls one watched page's next Google inspection to now. Same cap as the dashboard: 20 manual inspects per site per day. Get pageId from list_indexing_pages.

Lists a site's articles (latest 100) with articleId, target keyword, status (queued/drafting/draft/published/failed…), current title, and published URL.

Fetches one article's full record plus its latest version summary (title, slug, version number). Includes scheduling and publish state.

Returns the current article body HTML plus title/slug/meta/status/schedule so an agent can edit or review without the dashboard.

Lists reserved/failed scheduled publishes for a site (keyword, when, articleId). Use schedule_article / reschedule_article / cancel_article_schedule to change it.

Researched keyword ideas for a site ranked by opportunity score, with search volume, difficulty, intent, and — when an article already targets the keyword — its articleId/status so you don't generate duplicates.

Status of a background job (article generation, publish, site analysis) with its latest run and any error. Poll this after generate_article; generation typically takes a few minutes — do not poll more than once every 30 seconds.

Imports a finished article you (or the agent) wrote. Does NOT consume an article credit and does NOT call the RankBull writer. contentHtml MUST be publish HTML — the same article.content_html the publisher webhook sends (p, h2–h6, ul/ol, a, img, table). Markdown is rejected. Creates a review-status article you can schedule or publish_now.

Replaces the body of a draft/review/scheduled/published article with publish HTML (same sanitizer as the webhook). Does not consume an article credit. Cannot edit an article that is still generating.

Puts a review/draft article on the publish calendar at scheduledForIso. Same overlap checks as the dashboard. Does not consume an article credit. If duplicate_warning is returned, confirm with the user and retry with duplicateOverrideConfirmed=true.

Moves an already-scheduled article to a new ISO datetime. Fails if nothing is scheduled or it is currently dispatching.

Removes the article from the calendar and returns it to review. Does not delete the article.

Publishes a draft/review article immediately through the site's connected destination (same job as the dashboard Publish button). Does not consume an extra article credit. Poll get_job_status with the returned jobId.

SPENDS MONEY: creates an article for the keyword and queues AI generation. This consumes one article credit from the workspace's plan and real LLM budget — always confirm with the user before calling, and never call it in a loop. Check list_articles/list_keyword_candidates first to avoid duplicate keywords. Generation quality mode comes from the site's settings. Returns articleId + jobId; poll get_job_status for progress.

Read-only dump of this site's keyword research (candidates with volume, difficulty, opportunity, intent, linked article). Does NOT trigger DataForSEO. For keywords you typed in yourself, use list_target_keywords.

Read-only topic clusters from prior keyword research. Does NOT trigger DataForSEO.

Keywords you (or an agent) added by hand. Not a DataForSEO run.

Adds keywords you supply to the site's target list. Does NOT call DataForSEO and does not consume keyword-research credits. Duplicates are skipped.

Removes one hand-added target keyword by keywordId from list_target_keywords.

Queries this site already ranks for in Google Search Console (clicks, impressions, CTR, position). Free. GSC lags ~2 days. If connected:false, tell the user to connect Search Console in Settings → Analytics.

Read the latest keyword-ideas result. Does not call DataForSEO. Use run_keyword_ideas to spend a credit and fetch new ideas.

Spends one keyword-ideas credit (hosted: 1/2/4 per month on Starter/Growth/Scale) and calls DataForSEO once. Confirm with the user before calling. Seed with a topic or brand term. Poll list_keyword_ideas until status is ready or failed.

Adds one prompt to a monitor. Enforces the plan's per-site prompt cap (same error as the dashboard). Default status is active.

Sets one prompt to active, paused, or archived. Un-archiving an archived prompt re-checks the plan prompt cap.

Current automation policy for the site (mode, enabled, cadence, autoPause).

Pauses site automation (same as the dashboard pause). Generation/publish robots stop until resume_automation.

Clears auto-pause so automation can run again.