---
title: "Settings and administration"
description: "Site settings, the pipeline, delivery and domains, SEO, outreach, visitor analytics, reader comments, the team, billing and reports: what each costs, what needs approval, and the next step for every refusal."
canonical: "https://writavo.com/docs/administration"
last-updated: "2026-09-30"
---

# Settings and administration

Everything beyond content, from an API key or an AI assistant. Each area needs its own scope; paid operations and the ones that need a person's approval are marked.

## If you are an AI assistant

1. **Read first.** `getSiteSettings`, `getOrganisation` (the person's role), `getDelivery`, `getPipelineConfig` and `getBillingSummary` change nothing.
2. **Find the operation.** Over MCP, `search_writavo_actions` (for example "connect a custom domain") returns inputs, cost and approval. Over REST, use the tables below and the [API reference](/docs/api).
3. **Confirm any cost with the person first.** In plain words: this scan uses about 27 credits.
4. **Run it.** Over MCP: reads via `read_writavo_action`, the rest via `run_writavo_action`. Given an approval link, pass it on, wait, then rerun with `approval_id`.
5. **If refused, follow the message.** See [Refusals and what to do](#refusals). Never retry in a loop.

## Which permission each area needs

A key only reaches areas its scopes allow (for an assistant, the rows the person picked when connecting), and never does more than the person who approved it.

| Picker row | Read | Read and write adds (* only if the person may grant it) |
|---|---|---|
| Articles | `articles:read` | `articles:write`, `engagement:write`* |
| Content types and entries | `entries:read` | `entries:write`, `content_types:write`* |
| Categories, tags and authors | `taxonomy:read`, `authors:read` | `taxonomy:write`, `authors:write` |
| Media | `media:read` | `media:write` |
| AI pipeline | `pipeline:read` | `pipeline:run`, `plan:write`, `pipeline:config`*, `prompts:write`* |
| Site settings and design | `site:read` | `site:write` |
| Publishing and domains | `delivery:read` | `delivery:write`, `integrations:write`* |
| SEO | `seo:read` | `seo:write` |
| Outreach contacts | `outreach:read` | (read only) |
| Reader comments | `comments:read` | `comments:write` (shown as Read and moderate) |
| Team and organisation | `team:read` | `team:write`, `roles:write`*, `org:write`* |
| Billing | `billing:read` | `billing:write` |
| Reports and logs (includes visitor analytics) | `insights:read`, `logs:read` | (read only) |

- `meta:read` is always included. An assistant can never hold `keys:read`, `keys:write`, `webhooks:read` or `webhooks:write`.
- Default connection: Read everywhere except Outreach contacts and Reader comments (other people's personal data), plus write for articles, content types and entries, categories, tags and authors, media, and Site settings. Nothing that spends money or changes the team.
- Reader comments also needs the person's `comments.moderate` permission (owners, admins, editors). Older connections lack the row: add it in Settings > AI agents.
- Missing a permission? The error names the row; the person reconnects with it, then revokes the old connection.

## Organisations and Sites

An organisation is the account (people, billing, plan). A Site is one website or blog in it, with its own content, settings, domain and API keys.

- **Add a Site:** a person uses the Site switcher (top of the dashboard sidebar), then Add a Site. Needs `website.manage` (owners and admins by default). Not possible through the API or an assistant.
- The first Site is included; extra Sites are billed pay-as-you-go (same on every plan) and need a card or funds in your balance.
- An API key belongs to one Site; an assistant's connection can reach several (Settings > AI agents).
- AI credits belong to the organisation. Each Site can have a monthly credit cap (`updateSiteCreditCap`).

## Site settings and the knowledge profile

| Operation | Does | Scope |
|---|---|---|
| `getSiteSettings`, `updateSiteSettings` | Name, primary domain, locale, niche, timezone (status and live URL are read only) | `site:read`, `site:write` |
| `getKnowledgeProfile`, `updateKnowledgeProfile` | Brand voice, product and audience the AI writes for (update with `If-Match`) | `site:read`, `site:write` |
| `getOrganisation` | Name, the person's role, whether agent access and approvals are on | `meta:read` |
| `renameOrganisation` | Rename the organisation (owners by default) | `org:write` |

- `primary_domain` is what the SEO suite measures; it does not change where the blog is served ([delivery](#delivery)).
- The timezone is informational: a schedule time without an offset is UTC. A suspended Site is resolved with Writavo support.
- Every generated article is written from the knowledge profile. Set it before turning the pipeline on.

## The AI pipeline, the content plan, formats and prompts

| Operation | Does | Scope | Cost and approval |
|---|---|---|---|
| `getPipelineConfig` | On or off, publish mode, batch size, limits | `pipeline:read` | free |
| `updatePipelineConfig` | Turn on or off, change how much it does | `pipeline:config` | on or up: credits, always approval; off or down: free |
| `listPipelineQueue`, `getPlanItem` | Read the content plan | `pipeline:read` | free |
| `createPlanItem`, `updatePlanItem`, `deletePlanItem`, `reorderPlanItems` | Add, change, park (`skipped`), remove, reorder topics | `plan:write` | free (writing a topic spends credits) |
| `requeueArticle` | Send an article back to `improve`, `images` or `publish` | `pipeline:run` | `improve`, `images`: credits, always approval; `publish`: free |
| `listPrompts`, `setPromptOverride`, `resetPrompt` | A stage's prompt | `prompts:write` | free |
| `listFormats`, `getFormat`, `createFormat`, `updateFormat`, `deleteFormat` | Article formats | `meta:read` to read, `prompts:write` to change | delete: always approval |

- While on, it writes up to `batch_size` `planned` topics every 10 minutes. In `auto` mode they go live without review, up to `articles_per_day`.
- Turning it on needs a plan with AI generation, else `402 NOT_ENTITLED` (upgrade via `start_plan_purchase`).
- Keep the default's `{{placeholders}}` in a prompt override; dropped ones are listed in `missing_placeholders`.

## Delivery and domains

Start with `getDelivery`: every route the blog is served on, and the next step.

| Goal | Steps | Cost |
|---|---|---|
| `example.com/blog` (best for SEO) | `setupReverseProxy` (always approval; only for a domain you control); the person installs a returned snippet; `runDeliveryHealthCheck` with `method: subdirectory_proxy` until it finds this Site's own marker | free |
| `blog.example.com` | `connectCustomDomain` (always approval); the person adds every record in `dns_records`; `getDelivery` until `verified` (checked every 10 minutes); `runDeliveryHealthCheck` with `method: subdomain` | 5 US dollars a month once verified |
| A Writavo address | `updateHostedSiteBranding`, then `publishHostedSite` (always approval) | free |
| Customer renders it | `setupHeadlessDelivery` (if it reports no publishable key, a person creates one at https://app.writavo.com/settings/api-keys) | free |
| Also WordPress or Ghost | `connectCms` (the person enters the credential at its link), `pushToCms` (always approval), `listCmsPushLog` | free |

- Ownership TXT record: `_writavo.<the hostname>` = `writavo-verify=<token>`; keep it after verifying. If your DNS provider appends the zone, enter only `_writavo.blog`. Unverified after 14 days, the domain is released.
- `409 CONFLICT`: another site claimed the domain without verifying. Add the TXT record named and connect again (a verified domain is never moved).
- No card past the included allowance: `402 PAYMENT_METHOD_REQUIRED` (add one at https://app.writavo.com/billing?action=add-card). Never a plan limit.
- Comment limits behind a proxy apply per reader with the Cloudflare Worker and nginx snippets (they send `X-Writavo-Reader-IP`, trusted only with `X-Writavo-Proxy-Key`), and per Site with Next.js rewrites. Proxies from before 2026-10-04 still work; copy the new snippet for per-reader limits.
- `removeCustomDomain` and `disconnectCms` always need approval. CMS credentials never pass through an assistant (for WordPress, suggest a dedicated application password).

## SEO

Reads and list changes are free. The seven scans below cost money, need approval when an assistant asks, run in the background, and are refused if run in the last 10 minutes.

| Scan | Operation | Costs about | Needs | Result in |
|---|---|---|---|---|
| Site metrics | `refreshSiteMetrics` | 27 credits | primary domain | `getSeoOverview` |
| Keyword positions | `runRankCheck` | no credits; a vendor fee per keyword | a tracked keyword (`trackKeyword`) | `listTrackedKeywords` |
| Content gaps | `scanContentGaps` | one charge per active competitor (max 10) | primary domain, a competitor (`addCompetitor`) | `listContentGaps` |
| LLM mentions | `checkLlmMentions` | up to 20 checks | primary domain | `listLlmMentions` |
| Backlink profile | `scanBacklinkProfile` | one charge per domain | primary domain | `getBacklinkOverview` |
| Backlink detail | `pullBacklinkDetail` | one charge per 1,000 links | the Site's domain or a tracked competitor | `listBacklinks` |
| Link intersect | `scanLinkIntersect` | one charge per active competitor | two competitors | `listLinkOpportunities` |

- Backlink scans answer `409 FEATURE_UNAVAILABLE` while paid backlink data is off (`paid_data_available: false`). Free sources: `importBacklinksCsv` (a Google Search Console export, in pieces of at most 900,000 characters) and Bing (`connectBing`, then `syncBing`).
- Also free: `verifyBacklinks`, `rescanInternalLinks`, link exchanges (`inspectLinkProspect`, `createLinkExchange`, `listLinkExchanges`, `checkLinkExchange`) and link lists (`listArticleLinks`, `listOutboundLinkDomains`, `listOutboundLinks`).
- `planContentGap` and `planLinkOpportunity` add a topic to the plan (need `plan:write` too).
- Follow rule: a link's own setting wins, else links to your own pages are followed, else the Site's `external_link_rel` applies (`follow` by default). `setArticleLinkRel` sets one link; it is stored in the Markdown title (`[text](https://example.com "rel:nofollow")`) and removed at render (if you render `content` yourself, read it the same way).
- The plan limits tracked keywords across all Sites (`402 NOT_ENTITLED` past it).
- `getDisavowFile` builds the file; the person uploads it to Google Search Console.

## Outreach (read only)

`getOutreachReadiness`, `getOutreachMailbox`, `listOutreachContacts`, `listOutreachCampaigns`, `listOutreachThreads`. They hold other people's personal data: show it only to the person. No message bodies.

> Setup (policy, identity check, mailbox) is done by a person at https://app.writavo.com/outreach; `next_steps` says what is missing.

## Visitor analytics

| Operation | Does | Scope |
|---|---|---|
| `getAnalyticsSetup` | Site id, script tag, counted domains, last event, hosts turned away | `insights:read` |
| `updateAnalyticsSettings` | On or off; up to 20 extra domains (replaces the list) | `site:write` |
| `getVisitorAnalytics` | Visitors, pageviews, breakdowns, up to 400 days | `insights:read` |
| `checkAnalyticsInstall` | Fetch a live page and say what is wrong | `insights:read` |

Free, no approval. Hosted blogs already have the script. Elsewhere: paste the `snippet` unchanged, deploy, run `checkAnalyticsInstall`, and ask the person to open the page once in a normal browser (the script ignores localhost and automated browsers). See [Visitor analytics](/docs/analytics).

## Reader comments

| Operation | Does | Scope |
|---|---|---|
| `getCommentSettings`, `updateCommentSettings` | On or off, moderation mode | `comments:read`, `comments:write` |
| `listComments`, `getComment` | The queue, with emails | `comments:read` |
| `updateComment` | Approve, spam, or back to waiting | `comments:write` |
| `replyToComment` | Reply as the team (approves a waiting comment) | `comments:write` |
| `deleteComment` | Delete a comment and its replies for good | `comments:write` |
| `eraseCommenter` | Delete everything one email address wrote | `comments:write` |

- Off until a person turns them on (ask first: it changes the live blog). Free.
- Needs `comments.moderate` as well as the scope. Moderate only when told to; never repeat a commenter's email anywhere public.
- Showing and submitting comments on your own site: [Reader comments](/docs/comments).

## The team

| Operation | Does | Scope | Approval |
|---|---|---|---|
| `listTeamMembers`, `getTeamMember`, `listTeamInvites`, `getMemberPermissions`, `getRoleMatrix`, `listPermissionCatalog` | Members, roles, permissions, invites | `team:read` | none |
| `inviteTeamMember` | Invite an admin, editor or viewer | `team:write` | always |
| `revokeTeamInvite` | Cancel an invite | `team:write` | none |
| `updateMemberRole`, `removeTeamMember` | Change a role, remove a member | `team:write` | always |
| `updateMemberPermissions`, `updateRolePermissions` | Change a member's or a role's permissions | `roles:write` | always |

- Invites are not emailed: `inviteTeamMember` returns `accept_url` once, for the person to forward (single use, 7 days).
- Only the person whose assistant asked can approve a team change, never the member affected.
- Admins manage editors and viewers; only an owner makes or changes an admin.
- A member who owns live API keys cannot be removed (`409 CONFLICT`) until the keys are revoked or reassigned.

## Billing

| Operation | Does | Scope | Cost and approval |
|---|---|---|---|
| `getBillingSummary`, `listInvoices`, `listCreditPacks`, `getBillingLinks` | Plan, credits, allowances, invoices, packs, billing links | `billing:read` | free |
| `startCreditPurchase` | Stripe Checkout link for a credit pack | `billing:write` | charged only when the person pays; no approval |
| `updateAutorefill` | Auto-refill on, off or changed | `billing:write` | on charges the saved card later, always approval; off: free |
| `updateSiteCreditCap` | This Site's monthly credit cap | `billing:write` | raise or remove: always approval; lower: free |
| `keepCurrentPlan` | Cancel a scheduled downgrade | `billing:write` | keeps the current price; always approval |

- The API never changes the plan or takes card details ([see below](#never)). Invoice links are private: show them only to the person.
- CMS allowances (storage, documents, seats, Sites, domains, requests) are pay-as-you-go and the same on every plan: going past one bills, never blocks. Never call them plan limits or suggest upgrading.

## Reports and logs

| Operation | Does | Scope |
|---|---|---|
| `getSiteOverview` | Last 30 days, status counts, recent runs | `insights:read` |
| `getSiteCosts`, `getArticleCosts` | AI and data costs by stage and provider | `insights:read` |
| `getTaxonomyCounts` | Articles per category, tag and author | `insights:read` |
| `listFunctionLogs` | Pipeline and job logs | `logs:read` |
| `listAuditLog` | Who changed what, API included | `logs:read` |
| `listAgentCalls` | Every AI assistant request, refusals included | `logs:read` |

## What needs a person's approval

The first attempt returns a link instead of acting; once a person approves, the assistant repeats the identical request. This applies to every MCP request, even with a hand-made key. If the outcome changes before the retry, it is `409 APPROVAL_INVALID`: ask again.

- **Always, even with approvals off:** requesting a pipeline run, the paid SEO scans, and everything marked "always" above.
- **While the organisation requires approvals (the default):** deleting an article, category, tag, author or media file, and unpublishing an article.

## What an AI assistant can never do

The server refuses these whatever the permissions. Give the person the next step. Links from the API carry a `site` parameter so they open on the right Site.

| Never through an assistant | Next step |
|---|---|
| Change the agent switch, approvals switch or default permissions | https://app.writavo.com/settings/agents |
| Approve its own requests or give itself more access | The person approves, or reconnects with more permissions. |
| Change the access of the person it acts for | That person, or another owner or admin, at https://app.writavo.com/team |
| Add a Site | A person, in the dashboard ([Organisations and Sites](#sites)) |
| Delete a Site or the organisation | https://writavo.com/support |
| Enter or change card details | https://app.writavo.com/billing?action=add-card |
| Change the plan | `start_plan_purchase`, or https://app.writavo.com/billing |
| Transfer ownership or make anyone an owner | The owner, at https://app.writavo.com/team |
| Outreach policy, identity check, mailbox | https://app.writavo.com/outreach |
| Enter a WordPress, Ghost or Bing credential | https://app.writavo.com/delivery?connect=wordpress, https://app.writavo.com/delivery?connect=ghost, https://app.writavo.com/seo/backlinks?connect=bing |
| API keys and webhooks | https://app.writavo.com/settings/api-keys, https://app.writavo.com/settings/webhooks |

## Refusals and what to do

| Answer | Means | Do this |
|---|---|---|
| `403 INSUFFICIENT_SCOPE` | Missing permission (row named) | The person reconnects with that row. |
| `403 FORBIDDEN` | No permission allows it (own access, ownership, a higher role) | A person does it on the page named. |
| `428 APPROVAL_REQUIRED` | Needs approval | Give the link, wait, rerun with `approval_id`. |
| `409 APPROVAL_INVALID` | Expired, used, other arguments, or the outcome changed | Rerun without `approval_id`; say what changed. |
| `409 PREREQUISITE_MISSING` | Not set up; names the operation that sets it up | Run it (or ask the person), then retry. Nothing charged. |
| `409 FEATURE_UNAVAILABLE` | Paid backlink data off, or "Spending is paused" (no daily spend cap on the plan) | Use the free alternative named, or contact https://writavo.com/support. Do not retry. |
| `409 CONFLICT` "already running" | Same scan in the last 10 minutes | Wait, then read the result. |
| `402 NOT_ENTITLED` | Plan lacks this AI or SEO feature, or the keyword limit | Upgrade via `start_plan_purchase`. |
| `402 INSUFFICIENT_CREDITS`, `SPEND_CAP_REACHED` | No credits, or the Site's monthly cap | `startCreditPurchase`, or raise the cap (approval). |
| `402 PAYMENT_METHOD_REQUIRED` | Past a CMS allowance, no card | Add a card at https://app.writavo.com/billing?action=add-card. Not a plan limit. |
| `422 VALIDATION_FAILED` | `error.fields` names the field | Fix it. |

All codes: the [errors page](/docs/errors). The owner's side: [AI agent access](/docs/agents).
