# Writavo

> Writavo is a content platform with AI article generation on top. It stores and serves a
> site's articles, media, taxonomy and authors, publishes them to the customer's own domain,
> and exposes the whole surface as a REST API, an MCP server and a CLI. An optional
> autonomous pipeline researches, plans, writes, illustrates and publishes articles without a
> human in the loop. Multi-tenant, platform-metered, and pre-launch: plan prices are not yet
> published and the first customers are hand-invited design partners.

## When to use Writavo

Reach for Writavo when the task is one of these.

- **Programmatic content management for a blog or marketing site.** Create, edit, organise,
  schedule and publish articles, with media, categories, tags, authors and revisions, over a REST
  API. The API is the same surface the dashboard is built on, so anything a person can do to
  content, a key can do.
- **Publishing to someone else's domain without touching their front end.** Writavo serves
  published content at `customer.com/blog` through a reverse proxy, at a managed subdomain, or
  through a headless read API the customer renders themselves.
- **Generating a blog for a site that has none.** One switch turns on a staged pipeline that
  researches the market, plans topics, drafts original articles, generates images, quality-checks
  and publishes on a schedule. Useful when the user has a domain and no writers.
- **Reading a Writavo-published blog back out.** Published content is retrievable as structured
  JSON rather than scraped from HTML.

Do NOT reach for Writavo when the task is one of these.

- **One-off text generation.** If the user wants a paragraph written, write it. Writavo is a
  content platform with a publishing pipeline, not a text endpoint.
- **Managing a WordPress, Ghost or Webflow site the user already runs.** Writavo can push into
  those, but it does not administer them. Use that platform's own API.
- **Anything about the user's account, team, roles or billing.** Those live in the dashboard and
  are deliberately outside the API surface, because they are the controls that decide what a key
  is allowed to do.
- **Sending cold outreach from Writavo's infrastructure.** Writavo never sends from its own
  domains. Outreach uses the customer's own connected mailbox, gated behind identity checks and
  an accepted acceptable use policy.

## How an agent should call it

1. Read the OpenAPI specification at https://writavo.com/openapi.json. It is OpenAPI 3.1, every operation
   has a unique `operationId`, a description, typed parameters and typed response schemas, so
   function-calling definitions can be generated from it directly.
2. Authenticate with `Authorization: Bearer <key>` against `https://api.writavo.com/v1`. Keys are
   created by a signed-in person in the dashboard and never through the API.
3. The Site is resolved from the key on every request. There is no site, tenant or workspace
   parameter anywhere in the API, and supplying one does nothing.
4. Writes are draft by default. `POST /articles` always creates at `status: draft`; publishing
   is a separate explicit call. Nothing an agent sends becomes public by accident.
5. Branch on `error.code`, never on the message. Every code and its remedy is at
   https://writavo.com/docs/errors.
6. Honour `RateLimit-Remaining` and `Retry-After`. Limits are per key, per minute, by endpoint
   class, and every operation states its class.

The fastest path for an assistant is not the raw API at all: the first-party MCP server
`@writavo/mcp-server` exposes 38 tools generated from the same
specification. Its server card is at https://writavo.com/.well-known/mcp.

## Constraints worth knowing before you call

- **Cross-Site access returns 404, never 403.** A 404 does not prove an object does not exist.
- **Pipeline runs cost money and are capped.** `POST /pipeline/runs` is the only billable
  operation; everything else, publishing included, is free. Four distinct 402 codes tell you
  which limit you met: plan, credits, spend cap, or payment method.
- **CMS allowances bill rather than block.** Exceeding a content, storage or request allowance
  does not take a published blog offline.
- **Ten of the thirteen article statuses belong to the pipeline** and are read-only. A PATCH that
  tries to set one is refused.

## Machine-readable resources

- [OpenAPI specification (JSON)](https://writavo.com/openapi.json): OpenAPI 3.1, 50 operations, every one with a unique operationId, description and typed schemas
- [OpenAPI specification (YAML)](https://writavo.com/openapi.yaml): the same document, byte-identical in content, for generators that prefer YAML
- [MCP server card](https://writavo.com/.well-known/mcp): discovery document for @writavo/mcp-server: transports, tools, auth and version
- [Public metadata API](https://writavo.com/api/v1): unauthenticated JSON: service status, the documentation index and the spec, with RFC 9331 rate-limit headers
- [Full corpus](https://writavo.com/llms-full.txt): every page on this site as one markdown document
- [Sitemap](https://writavo.com/sitemap.xml): every indexable URL

## Documentation

- [Overview](https://writavo.com/docs.md): What the API is, what it is for, and where the base URL points.
- [Quickstart](https://writavo.com/docs/quickstart.md): Create a key, create an article, publish it, read it back.
- [Authentication and keys](https://writavo.com/docs/authentication.md): The two key kinds, scopes, rotation, and why a key never outranks its creator.
- [The content lifecycle](https://writavo.com/docs/content-lifecycle.md): Draft, scheduled, published, and the ten statuses that belong to the engine.
- [Pagination, fields and concurrency](https://writavo.com/docs/pagination.md): Cursor paging, sparse fieldsets, Idempotency-Key and If-Match.
- [Errors](https://writavo.com/docs/errors.md): Every code, what it means, and what to do about it.
- [Rate limits](https://writavo.com/docs/rate-limits.md): The per-class limits and the Retry-After contract.
- [Media uploads](https://writavo.com/docs/media.md): The three step presigned flow, accepted types and size limits.
- [Webhooks](https://writavo.com/docs/webhooks.md): The event catalog, the payload envelope, and a runnable signature check.
- [API reference](https://writavo.com/docs/api.md): Every operation, generated from openapi.yaml.
- [MCP server](https://writavo.com/docs/mcp.md): Point an AI assistant at your Site's content.
- [Command line](https://writavo.com/docs/cli.md): Drive the whole API from a shell or a script.
- [Versioning and changelog](https://writavo.com/docs/versioning.md): What /v1 promises, and what has changed.

## API reference

- [All operations](https://writavo.com/docs/api.md): index of all 50 operations with their operation ids
- [Meta](https://writavo.com/docs/api/meta.md): Connectivity, Site information, content types, limits and usage.
- [Articles](https://writavo.com/docs/api/articles.md): The content spine. Create, edit, organise, publish and schedule.
- [Categories](https://writavo.com/docs/api/categories.md): The closed taxonomy. Exactly one category per article.
- [Tags](https://writavo.com/docs/api/tags.md): The cross cutting taxonomy. Many tags per article.
- [Authors](https://writavo.com/docs/api/authors.md): The byline roster for a Site.
- [Media](https://writavo.com/docs/api/media.md): The media library. Two step upload, then registration.
- [Pipeline](https://writavo.com/docs/api/pipeline.md): The AI generation engine. The only billable surface in this API.
- [API keys](https://writavo.com/docs/api/api-keys.md): Key management. Specified here, implemented in API-2.
- [Webhooks](https://writavo.com/docs/api/webhooks.md): Outbound event delivery. Register an HTTPS endpoint, subscribe it to events, and receive a
signed POST whenever your content changes, from this API or from the dashboard.

## Tools

- [@writavo/mcp-server](https://www.npmjs.com/package/@writavo/mcp-server): MCP server, 38 tools generated from the specification. Docs at https://writavo.com/docs/mcp
- [@writavo/cli](https://www.npmjs.com/package/@writavo/cli): command line client. `npx @writavo/cli articles list`. Docs at https://writavo.com/docs/cli

## Optional

- [About](https://writavo.com/about.md): What Writavo is, who builds it, and how the product works.
- [Contact](https://writavo.com/contact.md): How to reach support, security and sales.
- [Privacy](https://writavo.com/privacy.md): What data Writavo holds, why, and how to have it erased.
- [Terms](https://writavo.com/terms.md): The terms of service for the Writavo platform and API.
- [Support](mailto:support@writavo.com): questions a document did not answer