# bot.seo API

Base URL: https://bot.seo.w3bs.org/api/v1. Authenticate with `Authorization: Bearer bs_...` (make a key with `key` in the web terminal, `botseo login`, or `POST /api/v1/keys` while signed in).

Pricing: the first 30 days are free. After that you pay as you go from a prepaid balance: every model call is charged at its c0mpute cost plus 20%. Audits are free. Top up with CoinPay (any coin or PayPal).

## Pipeline

1. **Audit** (free, minutes): every pasted site gets a technical SEO audit and a read of its home page.
2. **Analyze** (c0mpute): profile, keywords, quick wins and an 18-item content plan. Sites wait in one line for a free c0mpute node; `GET /overview` shows the ETA.
3. **Write** (c0mpute): approved items become Markdown articles, shaped by the site's settings.
4. **Publish**: written articles go live on the site's schedule (Settings → Advanced) through the blog API, RSS and webhooks.

## Account and sites

| Method | Path | Does |
| --- | --- | --- |
| POST | /auth/link `{email}` | email a sign-in link (the link is the signup) |
| GET | /me | plan, trial, balance, spend, autopilot, profile |
| PATCH | /me `{autopilot}` | turn autopilot on or off |
| GET PUT PATCH | /me/profile | your profile |
| GET | /overview | counts by status, published count, c0mpute status, ETA |
| POST | /sites `{domains: "a.com\nb.com" or [...]}` | add domains |
| GET | /sites | sites with status, score, queue position and ETA |
| POST | /sites/approve-all | approve every proposed item on every site |
| POST | /sites/retry-failed | retry failed sites and items |
| GET | /sites/:id | profile, audit, settings, blog sync and the plan |
| GET PUT | /sites/:id/settings | General, audience, competitors, CTA, prompts, advanced (schedule, URL shape, length) |
| POST | /sites/:id/reanalyze | audit and analyze again |
| POST | /sites/:id/approve-all | approve the site's proposed items |
| POST | /sites/:id/ideas `{kind: article|pseo|tool, count}` | more ideas from c0mpute (async) |
| POST | /sites/:id/items `{kind, title, keyword?, brief?}` | add your own item |
| POST | /sites/:id/blog-key | create or rotate the public read-only blog key |
| GET | /sites/:id/export.md | every written article as one Markdown file |
| DELETE | /sites/:id | remove a site and its plan |

## Items

| Method | Path | Does |
| --- | --- | --- |
| GET | /items?status=&site= | plan items across sites |
| GET | /items/:id (`?format=md`) | one item, with rendered html |
| PATCH | /items/:id `{title, keyword, brief, week, kind, article_md}` | edit |
| POST | /items/:id/approve, /decline, /retry | change status (retry on a written item rewrites it) |
| POST | /items/:id/publish, /unpublish | publish now, or take it down |

## Money and webhooks

| Method | Path | Does |
| --- | --- | --- |
| GET | /usage | every metered call with cost and price |
| POST | /billing/topup `{amountUsd}` | CoinPay checkout URL ($5 to $2,000) |
| GET | /billing/topups | top-up history |
| GET POST | /webhooks | your endpoints; events: site.analyzed, article.written, article.published, balance.topped_up |
| PATCH DELETE | /webhooks/:id | change or remove; POST /webhooks/:id/test sends a test |

## Public blog API (per-site key, no auth, CORS open)

| Path | Returns |
| --- | --- |
| /blog/:key/articles.json?limit=&offset=&full=1 | published articles (full=1 adds markdown and html) |
| /blog/:key/articles/:slug | one article as JSON with html; `:slug.md` for Markdown |
| /blog/:key/feed.xml | RSS 2.0 with content:encoded |
| /blog/:key/sitemap.xml | sitemap of the article URLs on your own domain |

## CLI, TUI and MCP

```sh
npx @profullstack/bot.seo login
botseo add domains.txt         # or: botseo add a.com b.com
botseo status                  # progress and ETA
botseo sites | botseo plan a.com | botseo approve all | botseo ideas a.com
botseo read <item-id> > post.md
botseo tui
claude mcp add botseo -e BOTSEO_API_KEY=bs_... -- npx -y @profullstack/bot.seo mcp
```