# RankOrg — Developer Docs (Integrations, API & MCP)

> RankOrg is a multi-tenant SEO automation platform. It publishes generated SEO articles to a hosted subdomain, a custom domain, WordPress, or any endpoint via signed webhooks — and exposes the whole engine to AI assistants (Claude, ChatGPT, Cursor) through a Model Context Protocol (MCP) server.

## Publishing destinations

Every RankOrg site publishes to one of these; the canonical URL points at the chosen destination.

- **Hosted subdomain** (All plans, e.g. `yourname.rankgt.com`): The fastest path — a RankOrg-hosted blog on a *.rankgt.com subdomain with automatic TLS. Live in seconds, no DNS changes.
- **Custom domain** (Lite and up, e.g. `blog.yourdomain.com`): Point a subdomain at RankOrg with a single CNAME. RankOrg issues TLS automatically and sets the canonical URL to your domain so there's no duplicate indexing.
- **Proxy subpath** (Advanced, e.g. `yourdomain.com/blog/*`): Serve the blog under a path on your existing root domain (e.g. /blog) via a reverse proxy, so the content ranks on your primary domain's authority.

## WordPress integration

Publish generated articles straight into a self-hosted or WordPress.com site via the WordPress REST API. RankOrg creates each post with status 'publish'.

- Connect fields:
  - `siteUrl`: Your WordPress site URL, e.g. https://mysite.com.
  - `username`: A WordPress user with permission to publish posts.
  - `appPassword`: A WordPress Application Password (Users → Profile → Application Passwords). Not your login password.
- Auth: HTTP Basic (username + application password), sent to /wp-json/wp/v2/posts.
- Credentials are verified against /wp-json/wp/v2/users/me at connect time and stored encrypted.

## Webhooks

RankOrg POSTs a signed JSON event to your endpoint every time an article publishes, so you can sync content into any CMS, cache, or pipeline.

- Event: `article.published` (version 2026-06-09)
- Request headers:
  - `X-RankOrg-Event`: The event type, e.g. article.published.
  - `X-RankOrg-Delivery`: Unique delivery id (matches payload.id).
  - `X-RankOrg-Timestamp`: Unix seconds when the request was signed.
  - `X-RankOrg-Signature`: sha256=<hex HMAC> — see verification below.
- Signature: HMAC-SHA256 over the string `{timestamp}.{rawRequestBody}` using your webhook secret (whsec_…). Recompute it and compare in constant time; reject if it doesn't match or the timestamp is stale.
- Delivery: Up to 3 attempts. Retried on HTTP 408, 425, 429, or any 5xx; a 2xx marks the delivery successful.

Example `article.published` payload:

```json
{
  "id": "evt_...",
  "version": "2026-06-09",
  "event": "article.published",
  "createdAt": "2026-07-03T09:00:00.000Z",
  "site": {
    "id": "site_...",
    "name": "Acme Blog",
    "slug": "acme",
    "canonicalHost": "blog.acme.com",
    "blogUrl": "https://blog.acme.com/blog"
  },
  "article": {
    "id": "art_...",
    "title": "…",
    "slug": "my-post",
    "url": "https://blog.acme.com/blog/my-post",
    "canonicalUrl": "https://blog.acme.com/blog/my-post",
    "metaDescription": "…",
    "contentHtml": "<h1>…</h1>",
    "heroImage": "https://…",
    "keywords": ["…"],
    "status": "published",
    "publishAt": "2026-07-03T09:00:00.000Z",
    "publishedAt": "2026-07-03T09:00:00.000Z"
  }
}
```

## MCP endpoint

- MCP server: `https://rankorg.com/api/mcp`
- Transport: Streamable HTTP (MCP). SSE disabled.
- Auth: personal access token (created/revoked at https://rankorg.com/settings), supplied either as `Authorization: Bearer rankorg_...` OR as a `?token=rankorg_...` query param on the URL. Requests with no token return 401 with a `WWW-Authenticate: Bearer` challenge. RankOrg does NOT require OAuth.
- Gating: read tools are always available; write tools (edit, research, generate, publish) require an active subscription.

## How to connect

1. Create a token at https://rankorg.com/settings (API access / MCP). It is shown once.
2. Add the connector in your AI client:
   - Claude / ChatGPT web "Add custom connector": paste `https://rankorg.com/api/mcp?token=YOUR_TOKEN` as the Remote MCP server URL and leave the OAuth Client ID/Secret fields blank.
   - Cursor / Claude Desktop (support custom headers): use `https://rankorg.com/api/mcp` with header `Authorization: Bearer YOUR_TOKEN`.
3. Ask in natural language, e.g. "What's scheduled today?" or "Research keywords and write my next article."

## Tools

### `getSiteContext` (read, free)

Returns the user's site (domains), business/niche profile, plan, and whether their subscription is active. Agents should call this first to ground everything else.

- Parameters: none

Example prompt: "What business is my RankOrg account set up for?"

### `listContent` (read, free)

Lists the user's articles. Use filter='today' to see what publishes today, 'scheduled' for upcoming, 'published' for live posts, or 'all'.

- Parameters:
  - `filter` ("today" | "scheduled" | "published" | "all") — optional: Which slice of content to return. Defaults to 'all'.

Example prompt: "What content is scheduled to publish today?"

### `getContent` (read, free)

Returns a single article's full HTML content, title, meta description, status and schedule by id. Call before editing so you have the current draft.

- Parameters:
  - `id` (string) — required: The article id.

Example prompt: "Show me the draft titled '…' so I can review it."

### `updateContent` (write, requires active subscription)

Edits an article's title, HTML content, and meta description. The title cannot change once an article is published (SEO stability).

- Parameters:
  - `id` (string) — required: The article id.
  - `title` (string) — required: New title.
  - `content` (string) — required: Full article body as HTML.
  - `metaDescription` (string) — required: New meta description.

Example prompt: "Tighten the intro of that draft and update the meta description."

### `researchKeywords` (write, requires active subscription)

Generates a keyword profile — head keywords plus specific long-tail search phrases — from the user's business profile, and saves it to their account.

- Parameters: none

Example prompt: "Research keywords for my business."

### `generateArticle` (write, requires active subscription)

Generates the next SEO article, picking the highest-priority keyword from the topical map and scheduling it into the next open publish slot.

- Parameters: none

Example prompt: "Write and schedule my next article."

### `publishContent` (write, requires active subscription)

Publishes a scheduled article live immediately. This is public and irreversible-ish — only call after the user explicitly confirms.

- Parameters:
  - `id` (string) — required: The article id to publish now.

Example prompt: "Publish that article now."

## Public web endpoints (no auth)

- `/llms.txt` — AI discovery file — what RankOrg is, its pages, tools, and this API.
- `/robots.txt` — Crawler directives, including AI crawler access.
- `/sitemap.xml` — Full URL index for search engines.
- `/index.md` — Markdown twin of the homepage for AI answer engines.

## Internal routes

RankOrg's other `/api/*` routes (authentication, billing webhooks, cron publishers, tenant resolution) are internal infrastructure secured by their own secrets. They are NOT part of the public API. Integrate via the MCP endpoint above.