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

# Settings and administration

Everything a person can see or change in the dashboard beyond content, available to an API key or an AI assistant: settings, the pipeline, delivery, SEO, outreach status, the team, billing and reports. Each area has its own permission, the operations that cost money are marked, and the handful of things only a person may do say where they do it.

## If you are an AI assistant

1. **Read before you change anything.** `getSiteSettings`, `getOrganisation` (it tells you the person's role), `getDelivery`, `getPipelineConfig` and `getBillingSummary` answer most questions without changing a thing.
2. **Find the operation.** Over MCP, call `search_writavo_actions` with what you want to do (for example "connect a custom domain"). It returns the matching operations with their inputs, their cost and whether they need a person's approval. Over REST, use the tables below and the [API reference](/docs/api).
3. **Check the cost and the approval before you run it.** An operation marked as spending credits or money is always confirmed with the person first. Tell them what it costs in their words, for example: this scan uses about 12 credits.
4. **Run it.** Over MCP, a read (a GET) goes through `read_writavo_action`, which never changes anything; everything else goes through `run_writavo_action`. Pass the operationId and the arguments. If it answers with an approval link, give the person the link, wait for them to approve, and run the same action again with the same arguments plus `approval_id`. If what the action would do changes in the meantime, the approval no longer applies and you ask again.
5. **If it is refused, do what the message says.** Every refusal names its next step. The common ones are listed under [Refusals and what to do](#refusals). Never retry a refusal in a loop.

## Which permission each area needs

A key reaches an area only with its scope. For an AI assistant these are the rows of the permission picker the person chose when connecting; for a key made by hand they are the scopes it was created with. Either way a key never does more than the person who approved it.

| Picker row | Read | Read and write adds |
|---|---|---|
| Articles | `articles:read` | `articles: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`, and when the person may grant them `pipeline:config`, `prompts:write` |
| Site settings and design | `site:read` | `site:write` |
| Publishing and domains | `delivery:read` | `delivery:write`, and when the person may grant it `integrations:write` |
| SEO | `seo:read` | `seo:write` |
| Outreach contacts | `outreach:read` | (read only) |
| Team and organisation | `team:read` | `team:write`, and when the person may grant them `roles:write`, `org:write` |
| Billing | `billing:read` | `billing:write` |
| Reports and logs | `insights:read`, `logs:read` | (read only) |

- `meta:read` (Site name, domain, the organisation) is always included.
- An AI assistant's key can never hold `keys:read`, `keys:write`, `webhooks:read` or `webhooks:write`.
- The default for a new connection is Read everywhere except Outreach contacts, plus Read and write for articles, categories, tags and authors, media, and Site settings. Nothing that spends money or changes the team is in the default, and outreach contacts (other people's names and email addresses) are only ever included when the person chooses that row.
- Missing a permission? The error names the row. The person connects the assistant again with that row set to Read and write, then revokes the old connection.

## Site settings and the knowledge profile

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

- `primary_domain` is what the SEO suite measures, and most paid scans need it. It does not change where the blog is served: that is [delivery](#delivery).
- The timezone is informational. Schedule times are absolute ISO 8601 timestamps, and one without an offset is read as UTC.
- `status` cannot be changed through the API. A suspended Site is resolved with Writavo support.
- The knowledge profile is what every generated article is written from. Getting it right is the most effective thing to do before turning the pipeline on.

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

| Operation | Does | Scope | Cost and approval |
|---|---|---|---|
| `getPipelineConfig` | Whether the pipeline runs, publish mode, batch size, limits | `pipeline:read` | free |
| `updatePipelineConfig` | Turn it on or off, change how much it does | `pipeline:config` | turning it on or up spends credits and always needs approval; off or down is free |
| `listPipelineQueue`, `getPlanItem` | Read the content plan | `pipeline:read` | free |
| `createPlanItem`, `updatePlanItem`, `deletePlanItem`, `reorderPlanItems` | Add, change, park (`skipped`), remove and reorder topics | `plan:write` | free to change; a planned topic is written (and spends credits) while the pipeline is on |
| `requeueArticle` | Send a pipeline article back to `improve`, `images` or `publish` | `pipeline:run` | `improve` and `images` spend credits and always need approval; `publish` is free |
| `listPrompts`, `setPromptOverride`, `resetPrompt` | Read, override or reset the prompt of a pipeline stage | `prompts:write` | free |
| `getContentType`, `createContentType`, `updateContentType`, `deleteContentType` | Read and define article formats and their blueprints | `meta:read` to read, `prompts:write` to change | deleting always needs approval |

- While the pipeline is on it writes from the content plan every 10 minutes, up to `batch_size` articles, each spending credits. In `auto` mode finished articles go live without review, up to `articles_per_day` a day.
- Turning the pipeline on needs a plan with AI generation (`402 NOT_ENTITLED` otherwise). The person upgrades with the link from `start_plan_purchase`.
- To keep a topic without it being written, set it to `skipped`. The pipeline only takes `planned` topics.
- A prompt override should keep the default's `{{placeholders}}`; any it drops are listed in `missing_placeholders`.

## Delivery and domains

Start with `getDelivery`: it shows every route the blog is served on and names the next step. Then pick one of these.

| Goal | Steps | Costs |
|---|---|---|
| The blog at `example.com/blog` (best for SEO) | `setupReverseProxy` with the domain (always needs approval: only approve it for a domain you control); the person installs one of the three snippets it returns; `runDeliveryHealthCheck` with `method: subdirectory_proxy` until it passes (it checks the page carries this Site's own Writavo marker, so a snippet pointed at another Site never verifies) | free |
| The blog at `blog.example.com` | `connectCustomDomain` (always needs approval); the person adds the CNAME record it returns; `getDelivery` until it is `verified` (checked every 10 minutes); `runDeliveryHealthCheck` with `method: subdomain`. A domain still not verified after 14 days is removed and released automatically; fix the DNS record and connect it again | 5 US dollars a month from the day it verifies |
| A Writavo address, no DNS work | `updateHostedSiteBranding` to set the look; `publishHostedSite` (always needs approval) | free |
| The customer renders it themselves | `setupHeadlessDelivery`; if it says there is no publishable key, a person creates one at https://app.writavo.com/settings/api-keys | free |
| Also publish to WordPress or Ghost | `connectCms` returns a link where the person enters the credential; then `pushToCms` (always needs approval) and `listCmsPushLog` | free |

- `removeCustomDomain` stops serving the custom domain, and `disconnectCms` stops pushing and forgets the credential. Both always need approval.
- A custom domain is a pay-as-you-go resource: with no card on file past the included allowance it is `402 PAYMENT_METHOD_REQUIRED`, and the person adds a card at https://app.writavo.com/billing?action=add-card. It is never a plan limit.
- A CMS credential never passes through an assistant. For WordPress, suggest a dedicated application password for Writavo.

## SEO

Every read and every change to the lists (competitors, keywords, gaps, the disavow list, link opportunities) is free. Seven scans cost money: each always needs a person's approval when an assistant asks, runs in the background, and is refused if the same scan ran in the last 10 minutes.

| Scan | Operation | Costs about | Needs first | Read the result with |
|---|---|---|---|---|
| Site metrics | `refreshSiteMetrics` | 12 credits | a primary domain | `getSeoOverview` |
| Keyword positions | `runRankCheck` | no credits; a vendor fee per keyword | at least one tracked keyword (`trackKeyword`) | `listTrackedKeywords` |
| Content gaps | `scanContentGaps` | one charge per active competitor, at most 10 | a primary domain and a competitor (`addCompetitor`) | `listContentGaps` |
| LLM mentions | `checkLlmMentions` | up to 20 checks | a primary domain | `listLlmMentions` |
| Backlink profile | `scanBacklinkProfile` | one charge per domain | a 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` |

- The three backlink scans answer `409 FEATURE_UNAVAILABLE` while Writavo has paid backlink data switched off (`paid_data_available: false` in `getBacklinkOverview`). The free sources always work: `importBacklinksCsv` with a Google Search Console links export (split it into pieces of at most 900,000 characters), and Bing Webmaster Tools, which a person connects at the link `connectBing` returns, then `syncBing`.
- `verifyBacklinks` and `rescanInternalLinks` are free and run in the background.
- `planContentGap` and `planLinkOpportunity` add a topic to the content plan in one step. They need `plan:write` as well as `seo:write`.
- The plan limits how many keywords the organisation tracks across all its Sites; past it `trackKeyword` is `402 NOT_ENTITLED`.
- `getDisavowFile` builds the file for Google Search Console. Writavo never submits it: the person uploads it.

## Outreach (read only)

`getOutreachReadiness`, `getOutreachMailbox`, `listOutreachContacts`, `listOutreachCampaigns` and `listOutreachThreads` show where outreach stands. They contain personal data of people outside the organisation: show it to the person and do not copy it elsewhere. Message bodies are not available.

> Accepting the outreach policy, the identity check and connecting a mailbox are done by a person at https://app.writavo.com/outreach. `next_steps` in the readiness answer says which of them is missing.

## The team

| Operation | Does | Scope | Approval |
|---|---|---|---|
| `listTeamMembers`, `getTeamMember` | Members, their roles and the keys that block removing them | `team:read` | |
| `getMemberPermissions`, `getRoleMatrix`, `listPermissionCatalog` | Who can do what, and why | `team:read` | |
| `listTeamInvites` | Pending invites | `team:read` | |
| `inviteTeamMember` | Invite someone as admin, editor or viewer | `team:write` | always |
| `revokeTeamInvite` | Cancel a pending invite | `team:write` | none |
| `updateMemberRole` | Change a member's role | `team:write` | always |
| `removeTeamMember` | Remove a member | `team:write` | always |
| `updateMemberPermissions` | Grant or revoke individual permissions | `roles:write` | always |
| `updateRolePermissions` | Change what a role can do | `roles:write` | always |

- Writavo does not email an invite. `inviteTeamMember` returns `accept_url` once; give it to the person to forward to the invitee. It works once and lasts 7 days.
- Only the person whose assistant asked can approve a team change; the member it affects cannot approve their own promotion.
- An assistant can never change the access of the person it acts for, nor anything to do with ownership: that is `403 FORBIDDEN` before any approval is asked, and a person does it at https://app.writavo.com/team.
- An admin can manage editors and viewers; only an owner can make or change an admin.
- A member who still owns live API keys cannot be removed until a person revokes or reassigns them in Settings > API keys (`409 CONFLICT`).

## Billing

| Operation | Does | Scope | Cost and approval |
|---|---|---|---|
| `getBillingSummary` | Plan, credits, CMS overage, auto-refill, this Site's credit cap, every allowance | `billing:read` | free |
| `listInvoices`, `listCreditPacks` | Billing history and the packs on sale | `billing:read` | free |
| `getBillingLinks` | The dashboard pages for a plan change, a card and invoices | `billing:read` | free |
| `startCreditPurchase` | A Stripe Checkout link for one credit pack | `billing:write` | nothing is charged until the person pays on Stripe's page; no approval |
| `updateAutorefill` | Turn auto-refill on, off or change it | `billing:write` | turning it on charges the saved card later and always needs approval; off is free |
| `updateSiteCreditCap` | Set, lower, raise or remove this Site's monthly credit cap | `billing:write` | raising or removing always needs approval; lowering is free |
| `keepCurrentPlan` | Cancel a scheduled downgrade and stay on the current plan | `billing:write` | keeps paying the current price; always needs approval |

- The API never changes the plan and never takes card details. A plan change is `start_plan_purchase` (or https://app.writavo.com/billing); a card is https://app.writavo.com/billing?action=add-card.
- CMS allowances (storage, documents, seats, Sites, domains, requests) are pay-as-you-go and the same on every plan. Going past one bills; it never blocks. Never describe them as plan limits or suggest upgrading to lift one.
- Invoice links are private to the organisation. Show them only to the person.

## Reports and logs

| Operation | Does | Scope |
|---|---|---|
| `getSiteOverview` | The last 30 days at a glance, status counts, recent runs | `insights:read` |
| `getSiteCosts`, `getArticleCosts` | What AI and data work cost, by stage and provider | `insights:read` |
| `getTaxonomyCounts` | Articles per category, tag and author | `insights:read` |
| `listFunctionLogs` | This Site's pipeline and job log lines | `logs:read` |
| `listAuditLog` | Who changed what, including changes made through the API | `logs:read` |
| `listAgentCalls` | Every request an AI assistant made, refusals included | `logs:read` |

## What needs a person's approval

When an AI assistant asks for one of these, the first attempt returns a link instead of acting. A person approves or denies it in the dashboard, and the assistant repeats the identical request with the approval. This applies to every request an MCP client makes, even one using a key made by hand in the dashboard. An approval covers exactly what was shown: if what the request would do changes before the retry (the article moved on, a price changed), it is refused with `409 APPROVAL_INVALID` and the assistant asks again. A team change can only be approved by the person whose assistant asked, never by the member it affects.

| Always asked, even with approvals turned off | Asked while the organisation requires approvals (the default) |
|---|---|
| Requesting a pipeline run; turning the pipeline on or up; an AI rewrite or new images for an article | Deleting an article, category, tag, author or media file |
| The seven paid SEO scans | Unpublishing an article |
| Setting up the reverse proxy; connecting or removing a custom domain; publishing the hosted blog | |
| Disconnecting the external CMS; pushing articles to it | |
| Deleting an article format | |
| Turning on auto-refill; raising or removing the Site's credit cap; keeping the current plan | |
| Inviting someone; changing a role, a member's permissions or a role's permissions; removing a member | |

## What an AI assistant can never do

These are refused by the server whatever permissions a connection has. Tell the person the next step instead of trying.

Links the API and the tools hand out (approval pages, connect pages, billing pages) carry the Site id as a site parameter, so the dashboard opens on the right Site; if the person is looking at another Site, the page says which Site the link is for and offers a one-click switch. The plain links on this page work too; the person then picks the Site.

| Never through an assistant | The next step |
|---|---|
| Change the AI agent switch, the approvals switch or the default permissions | A person changes them at https://app.writavo.com/settings/agents. |
| Approve its own requests, or give itself more access | The person approves at the link, or connects the assistant again with more permissions. |
| Change the access of the person it acts for | That person, or another owner or admin, does it at https://app.writavo.com/team. |
| Delete a Site or the organisation | The person contacts 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 does it at https://app.writavo.com/team. |
| Accept the outreach policy, pass the identity check, connect a mailbox | A person does it at 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 |
| Create, rotate or revoke API keys; manage webhooks | https://app.writavo.com/settings/api-keys and https://app.writavo.com/settings/webhooks |

## Refusals and what to do

| Answer | Means | Do this |
|---|---|---|
| `403 INSUFFICIENT_SCOPE` | The connection lacks the permission; the message names the picker row | Tell the person which row needs Read or Read and write. They connect again with it. |
| `403 FORBIDDEN` | A change no permission allows: the person's own access, ownership, or a role above the person's | Tell them the message; a person makes that change in the dashboard page it names. |
| `428 APPROVAL_REQUIRED` | A person must approve | Give the link, wait, run it again with `approval_id`. |
| `409 APPROVAL_INVALID` | The approval expired, was used, was for other arguments, or what the request would do has changed since | Run it again without `approval_id` to get a new link, and tell the person what changed. |
| `409 PREREQUISITE_MISSING` | Something is not set up yet; the message names the operation that sets it up | Run that operation (or ask the person, if it is theirs to do), then retry. Nothing was charged. |
| `409 FEATURE_UNAVAILABLE` | Writavo has this switched off: paid backlink data, or all spending while the plan has no daily spend cap configured ("Spending is paused") | Use the free alternative the message names; for "Spending is paused", tell the person, who contacts https://writavo.com/support. Do not retry. |
| `409 CONFLICT` "already running" | The same scan ran in the last 10 minutes | Wait a few minutes and read the result. |
| `402 NOT_ENTITLED` | The plan does not include this AI or SEO capability, or its keyword limit is reached | The person upgrades with the link from `start_plan_purchase`. |
| `402 INSUFFICIENT_CREDITS` or `SPEND_CAP_REACHED` | No credits left, or this Site's monthly cap is reached | The person buys credits (`startCreditPurchase`) or raises the cap (`updateSiteCreditCap`, which needs their approval). |
| `402 PAYMENT_METHOD_REQUIRED` | Past an included CMS allowance with no card on file | The person adds a card at https://app.writavo.com/billing?action=add-card. Not a plan limit. |
| `422 VALIDATION_FAILED` | A field is wrong; `error.fields` names it | Fix that field. A field only a person may change says so. |

Every code, with the full explanation, is on the [errors page](/docs/errors). The owner's side of agent access is [AI agent access](/docs/agents).