Developers & agents

API & MCP

Everything Bottally produces for your brand is readable with one key: the articles, the keyword research, and the AI-visibility measurements. Your site pulls it. Your agents read it. Nothing is pushed at you.

1. Get a key

In the dashboard open Integrations and press Onboard your agent to Bottally at the top right. You get an API key, the prompt below with your key already filled in, and the MCP config. The key is shown once; you can rotate it any time from the same place. Works with any framework and any AI agent.

2. One prompt, any agent

Paste this into whatever builds your site — Cursor, Claude Code, v0, Lovable, Bolt, Replit — and it adds the blog index and article pages, styled like the rest of your site, with ISR so new articles appear within an hour of publishing. No webhook, no database, no cron. Paste the same prompt into any other agent and it can read your articles, keywords and AI-visibility data. Replace YOUR_BOTTALLY_API_KEY with your key (the dashboard version has it filled in).

You have access to my Bottally account — an SEO autopilot that researches keywords, writes and publishes articles, and measures whether AI engines (ChatGPT, Perplexity, Google AI Mode, AI Overviews) mention the brand. Everything is readable with one API key. Use it for two things: (A) if you are working on the website's codebase, add the self-updating blog described below; (B) whenever asked about SEO, content, keywords or AI visibility, read the live data instead of guessing.

## Access
- API key: YOUR_BOTTALLY_API_KEY — treat it as a secret. In a codebase put it in an environment variable BOTTALLY_API_KEY (.env.local and the hosting provider's env settings), never in source, never in browser code.
- REST base URL: https://www.bottally.com/api/v1. Every request: header `Authorization: Bearer <key>`. All endpoints are GET and return JSON. 120 requests/minute.
- MCP (optional, if you support it): stateless Streamable HTTP at https://www.bottally.com/api/mcp with the same bearer header. Tools: get_brand, list_articles, get_article, list_keywords, get_visibility. Client config:
  { "mcpServers": { "bottally": { "type": "http", "url": "https://www.bottally.com/api/mcp", "headers": { "Authorization": "Bearer <key>" } } } }

## Endpoints
- GET https://www.bottally.com/api/v1/brand → { name, domain, description, services, business_type, country, language, logo_url, brand_colors, blog: { base_url }, counts }
- GET https://www.bottally.com/api/v1/articles?limit=100&offset=0&updated_since=ISO8601 → { articles: [{ slug, title, excerpt, tags, cover_image_url, keyword, reading_minutes, published_at, updated_at, url }], total, has_more }
- GET https://www.bottally.com/api/v1/articles/{slug} → the same fields plus content_markdown, content_html (safe, pre-rendered), media, sources, brand
- GET https://www.bottally.com/api/v1/keywords?status=pool|planned|published&include_serp=true&limit=300 → the researched keyword pool: volume, difficulty, cpc, intent, priority, status, parent_keyword (long-tail parent), our_position on Google, serp_top (page one: position, domain, url, title)
- GET https://www.bottally.com/api/v1/visibility?period=7d|30d|90d|1y|all → summary { questions, answers, mentions, mention_rate, avg_visibility_score, engines[] } and per tracked question: for each engine whether the brand was mentioned, visibility_score, sentiment_score, sources cited, google_position, competitors_mentioned

## (A) If this is the website's codebase: add the blog
Works with any framework that renders on the server or at build time (Next.js, Astro, Nuxt, SvelteKit, Remix, Gatsby, Hugo, Rails, Django, Laravel, …) — use this project's own conventions. Only published articles are returned, so the site can render everything the API gives it. The blog belongs at /blog. If this site already has a blog at a different path, merge into it there instead and tell me the path — Bottally records article URLs under /blog and needs to know. Steps:
1. Store the key as BOTTALLY_API_KEY. All API calls run on the server, never in the browser.
2. Create a server-only module (e.g. lib/bottally.ts) with typed helpers listArticles() and getArticle(slug). Fetch with an hourly cache so pages refresh on their own — no cron, no webhook, no database. In Next.js that is `fetch(url, { next: { revalidate: 3600 } })`; in a static-site generator, a scheduled rebuild or ISR equivalent; elsewhere, server-side caching with a one-hour TTL.
3. Pages (the Next.js App Router names below are an example — map them to this framework):
   - /blog: index — cover image, title, excerpt, date, reading time; newest first; paginate or "load more" past 20.
   - /blog/[slug]: the article — render content_html inside an article element with the site's existing typography; title, date, cover image, tags; "Back to blog" link; "More articles" with 3 other posts.
   - Export `revalidate = 3600` from both. In [slug] implement generateStaticParams() from the article list AND set `dynamicParams = true` so a new article renders on first request instead of 404ing until the next deploy. Return notFound() on a 404 from the API.
   - Reuse the site's layout, header, footer, fonts and colors. Do not introduce a new design system.
4. SEO, all of it: generateMetadata() on both pages (title, description from excerpt, canonical, openGraph with cover image, twitter card); JSON-LD Article schema per post (headline, datePublished, dateModified, image, author and publisher = the brand); add /blog and every article to the sitemap (create app/sitemap.ts if missing); make sure robots allow /blog; add a "Blog" link to the main navigation and the footer.
5. Finish: run the type checker and a production build and fix anything that fails; load /blog and one article locally to confirm; then list the files you created, remind me that BOTTALLY_API_KEY must be set in the hosting provider's environment before deploying, and tell me to press "Check setup" in Bottally's Integrations page once the site is deployed so it can verify the blog is live.

## (B) Whenever asked about SEO, content or AI visibility
Read /brand first, then the relevant endpoint. Typical uses: which questions the brand is NOT mentioned for and which competitors are (visibility); which keywords are planned vs already published and where we rank (keywords); what has been published and what to link to (articles). Quote the numbers you read; do not invent data the API did not return.

3. Connect any agent over MCP

Claude Desktop, Claude Code, Cursor, and any MCP client. Stateless Streamable HTTP with a bearer key — add this to your client's MCP config (the prompt above already contains it). Tools: get_brand, list_articles, get_article, list_keywords, get_visibility.

{
  "mcpServers": {
    "bottally": {
      "type": "http",
      "url": "https://www.bottally.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BOTTALLY_API_KEY"
      }
    }
  }
}

4. REST reference

Base URL https://www.bottally.com/api/v1. Send Authorization: Bearer btl_…. All endpoints are GET, return JSON, allow CORS, and are limited to 120 requests per minute per key. Only published articles are ever returned.

curl -H "Authorization: Bearer YOUR_BOTTALLY_API_KEY" https://www.bottally.com/api/v1/articles?limit=3

Endpoint	Returns	Query
GET /api/v1/brand	Who the brand is: name, domain, services, market, logo and colors, blog location, counts.	—
GET /api/v1/articles	Published articles, newest first — slug, title, excerpt, tags, cover image, dates, reading time.	limit (≤100), offset, updated_since (ISO 8601)
GET /api/v1/articles/{slug}	One article with content_markdown, content_html, media and sources.	—
GET /api/v1/keywords	The researched keyword pool with volume, difficulty, CPC, intent, priority, status, our Google position.	status = pool \| planned \| published, include_serp = true, limit (≤1000)
GET /api/v1/visibility	Per tracked question and AI engine: mentioned or not, scores, cited sources, competitors named instead — plus a summary.	period = 7d \| 30d \| 90d \| 1y \| all

GET /api/v1 (no key) lists these endpoints, so an agent given only the base URL can discover them. Errors come back as { error: { status, code, message } }.

How publishing works with a pull channel

Articles are written and scheduled by the autopilot as usual. At the daily publish slot an article becomes visible in /api/v1/articles, and Bottally records its URL as your-site/blog/slug. Your site's ISR pages pick it up on the next revalidation — within an hour, triggered by the first visitor, with no work on your side.

Prefer a plugin, a CMS, or a push webhook instead? Those connectors are in the same Integrations page. Pricing