Blogo API & MCP

Principles

• The API saves you clicks. It does not skip quality: every article goes through the same plan confirmation, fact-checks, and readiness checks as in the app.
• Drafts are never published automatically. There is no publish endpoint or tool. Saving to WordPress (as a draft) is always a person's choice in Blogo.
• One new article costs 10 credits, charged once when the draft is written. API and MCP calls are free.
• API keys are server-side secrets. Never put them in browser code.

Authentication

Create a key in Settings → API Keys. Send it on every request using either header. Browser sessions (cookies) are not accepted by the API or the MCP server.

Authorization: Bearer sk_your_key
# or
x-api-key: sk_your_key

Responses

Every response is JSON. Successful responses have a data object. Errors have an error object with a stable code:

{ "data": { ... } }

{ "error": { "code": "ARTICLE_CREDITS_REQUIRED", "message": "Not enough credits: ..." } }

Endpoints

• GET /api/v1/sites: your websites.
• GET /api/v1/articles?siteId=…: your articles, newest first (up to 200).
• POST /api/v1/articles: start an article { siteId, topic, audience? }. Free.
• GET /api/v1/articles/{id}: status, checks, plan, progress and the Markdown draft (?includeMarkdown=false to omit it).
• POST /api/v1/articles/{id}/plan: draft the writing plan.
• POST /api/v1/articles/{id}/plan/confirm: confirm the plan, optionally with edits.
• POST /api/v1/articles/{id}/advance: run the next step.

No website yet? Add it in the app first. Onboarding confirms your company, products and brand rules, and the writer relies on them.

1. Pick a site and start an article

curl https://www.blogo.ai/api/v1/sites \
  -H "Authorization: Bearer sk_your_key"

curl -X POST https://www.blogo.ai/api/v1/articles \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"SITE_ID","topic":"how to choose an industrial gasket supplier"}'

The response has data.article.id and data.article.nextAction ("plan").

2. Draft and confirm the writing plan

The plan decides the page type, target query, audience, scope and required elements. Drafting it uses AI research. Calling it again returns the same draft at no extra cost. Show the draft to a person. If it comes back with warnings or advisories, a person must review them, and you confirm with acknowledgeWarnings: true.

curl -X POST https://www.blogo.ai/api/v1/articles/ARTICLE_ID/plan \
  -H "Authorization: Bearer sk_your_key"

curl -X POST https://www.blogo.ai/api/v1/articles/ARTICLE_ID/plan/confirm \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"overrides":{"audience":"procurement managers","productScope":["PTFE gaskets"]}}'

Editable fields: action, targetQuery, audience, readerJob, pageGoal, cta, productScope, mustInclude, mustAvoid, evidencePlan, linkPlan. A plan the writer cannot safely follow is rejected with 422 PLAN_BLOCKED and the reasons. Confirming is free.

3. Run the steps

Each advance call runs exactly one step (research, keywords, title, outline, write, images, fact-check, links, readiness) and returns the article with its nextStep and nextAction. Keep calling while nextAction is "advance". One step per request stays well inside serverless time limits. Repeating a finished step never pays for it twice.

while true; do
  NEXT=$(curl -s -X POST https://www.blogo.ai/api/v1/articles/ARTICLE_ID/advance \
    -H "Authorization: Bearer sk_your_key" | jq -r '.data.article.nextAction // .error.code')
  echo "$NEXT"
  [ "$NEXT" = "advance" ] || break
done

Optional body {"step":"write"} is a guard: the call fails with 409 STEP_NOT_NEXTunless that is the next step, so a retried loop never runs a step twice. If a paid step ends without usable output, nextAction becomes "retry_in_app". Running it again would be new paid work, so only a person can retry it, from reviewUrl. Before writing, nextAction is "answer_in_app" until the site owner answers at least one interview question in Blogo; the answers are the first-hand part of the article, so the API never fills them in. When nextAction is "review_in_app", the article is written and checked. Fetch it with GET /api/v1/articles/{id}, then open reviewUrl to review it. Saving to WordPress (as a draft) happens there.

Credits

• One new article = 10 credits, reserved when the write step starts and kept once the draft is saved.
• If no draft is delivered, the credits are returned automatically.
• Every other step, and every API and MCP call, is free. Planning needs an account that can write (at least 10 credits while billing is on) but does not charge.
• A rewrite or a second repair pass is never started automatically. Those are explicit choices in the app.
• During the controlled pilot, API access is invite-only and your writing allowance is set by the Blogo team. Credits cannot be bought yet.

Rate limits

60 requests per minute per API key, shared by REST and MCP. Going over returns 429 RATE_LIMITED with a Retry-After header. Separately, 429 USAGE_LIMIT_REACHED means a writing usage limit was reached and no new work was started.

MCP server

Blogo is also an MCP server (Streamable HTTP, JSON responses, protocol 2025-06-18) at https://www.blogo.ai/api/mcp. Add it to any MCP client that supports remote servers with headers:

{
  "mcpServers": {
    "blogo": {
      "url": "https://www.blogo.ai/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_key" }
    }
  }
}

Tools (each maps to the REST endpoint of the same name):

• list_sites, list_articles, get_article: read-only.
• create_article: start an article (free).
• plan_article, confirm_plan: draft and confirm the writing plan.
• advance_article: run one step. The agent loops while nextAction is "advance".

Problems such as missing credits, a busy article, or a plan that needs review come back as tool results with isError: true and the same code as REST, so the agent can explain them. There is no publish tool.

curl -X POST https://www.blogo.ai/api/mcp \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_sites","arguments":{}}}'

Errors

• 400 INVALID_REQUEST / INVALID_JSON: fix the request. MCP returns JSON-RPC -32602.
• 401 API_KEY_REQUIRED / UNAUTHORIZED: missing, invalid, or revoked key.
• 402 ARTICLE_CREDITS_REQUIRED: not enough credits to write a new article (10 needed).
• 403 PILOT_ACCESS_REQUIRED: this account does not have pilot access.
• 404 ARTICLE_NOT_FOUND / SITE_NOT_FOUND: missing, or owned by another account.
• 409 PLAN_REQUIRED, PLAN_CONFIRMATION_REQUIRED, PLAN_REVIEW_REQUIRED, PLAN_ALREADY_CONFIRMED, STEP_NOT_NEXT: follow nextAction.
• 409 STEP_RETRY_REQUIRES_REVIEW, PREFILL_FORCE_REQUIRED, PAID_CORE_FORCE_REQUIRED, PAID_ENRICHMENT_FORCE_REQUIRED, VERIFY_FORCE_REQUIRED: an earlier paid call may already have been charged. The API never retries it automatically. Open the article in Blogo to approve a retry.
• 409 PLAN_CONFLICT, ARTICLE_CONFLICT, SITE_CONFLICT, VERIFICATION_STALE: something changed in the meantime. Reload the article and continue.
• 422 PLAN_BLOCKED: the plan needs edits. See details.blockers.
• 423 ARTICLE_BUSY / SITE_BUSY / ACCOUNT_BUSY: another step is running. Retry shortly.
• 429 RATE_LIMITED / USAGE_LIMIT_REACHED: see Rate limits.
• 503 PAID_EXECUTION_DISABLED: writing is paused for this deployment or account.
• 500 INTERNAL_ERROR: nothing was retried automatically. Check the article's state before trying again.