---
title: "Headless sites and content types"
description: "Render your site with plain fetch calls: entries, expand and filters, TypeScript from your own schema, schema files, and exporting a whole Site."
canonical: "https://writavo.com/docs/headless"
last-updated: "2026-09-29"
---

# Headless sites and content types

No SDK needed: the API is plain HTTP and JSON, a publishable key is safe in a browser, and your content types generate their own TypeScript.

## Read published content

Use a publishable key (wv_pub_) in a browser or at build time; it only sees published content. A secret key (wv_sk_) also sees drafts and belongs on a server.

- Lists are cursor paged: pass `next_cursor` back as `cursor` until it is null. Sparse fields, `updated_since` sync and safe retries are in [Paging and retries](/docs/pagination).
- Optional extras: [Visitor analytics](/docs/analytics) (one script tag) and [Reader comments](/docs/comments) (read with this key, submitted from your server).

## Views, reactions and comment counts

Read the counters of up to 50 published posts in one request: GET /engagement/posts with a comma-separated slugs list. It needs articles:read, so a publishable key works.

curl:

```bash
curl -s "https://api.writavo.com/v1/engagement/posts?slugs=hello-world,second-post,gone-post" \
  -H "Authorization: Bearer $WRITAVO_PUBLISHABLE_KEY"
```

200 response:

```json
{
  "ok": true,
  "data": {
    "posts": [
      {
        "slug": "hello-world",
        "views": 1840,
        "reactions": { "useful": 12, "mind_blown": 3, "insightful": 7, "skeptical": 1, "loved": 9, "hot_take": 0 },
        "shares": { "x": 4, "linkedin": 6, "facebook": 1, "other": 2, "total": 13 },
        "user_reaction": null,
        "comments": 2
      },
      {
        "slug": "second-post",
        "views": 412,
        "reactions": { "useful": 2, "mind_blown": 0, "insightful": 1, "skeptical": 0, "loved": 1, "hot_take": 0 },
        "shares": { "x": 0, "linkedin": 1, "facebook": 0, "other": 0, "total": 1 },
        "user_reaction": null,
        "comments": 0
      }
    ],
    "missing": ["gone-post"]
  }
}
```

- `posts` and `missing` keep your order; a repeated slug appears once. Each entry matches `GET /engagement/posts/{slug}`.
- An unknown or unpublished slug goes in `missing`, never an error. Send 1 to 50 unique slugs of up to 200 characters each, or get `422 VALIDATION_FAILED` on `slugs`.
- `user_reaction` is always `null` here; for one reader's reaction, use the single-post read with `visitor_id`.
- `comments` counts approved [reader comments](/docs/comments) (0 while the Site has comments off).

## Content types and entries

A content type is a model you define (Product, Homepage); an entry is one item of it. expand resolves reference and media ids one level deep; filter matches a field exactly.

entries:

```
// Every published product, newest first, with related products and the photo expanded
const products = await writavo("/entries/product?order=-published_at&status=published&expand=related,photo");

const one = await writavo("/entries/product/blue-widget");
const pro = await writavo("/entries/product?filter[tier]=pro");

const home = (await writavo("/entries/homepage")).items[0];
```

- An entry is { id, type, slug, external_id, title, status, data, published_at, ... }; data holds values by field API id.
- A publishable key never sees draft or scheduled entries; an expanded reference to one is null.
- Rebuild on the entry.published, entry.updated, entry.unpublished and entry.deleted webhooks.

## TypeScript from your own schema

GET /content-types/typescript returns an interface per type and component, ContentTypes (API id to interface) and a generic Entry. Regenerate when schema_version changes.

typed reads:

```
import type { Entry, ContentTypes } from "./writavo-types";

async function entries<T extends keyof ContentTypes>(type: T): Promise<Entry<T>[]> {
  return (await writavo<{ items: Entry<T>[] }>(`/entries/${type}?status=published`)).items;
}

const products = await entries("product"); // products[0].data.name is a string
```

> For a client for the whole API, use /openapi.json with any generator, such as openapi-typescript.

## Keep your schema in a file

Keep content types in your repository and push them with POST /content-types/apply (the shape GET /content-types returns). It applies only the differences and leaves other types alone unless you set delete_missing. Dry run first: it returns the plan and every problem and writes nothing.

shell:

```
# schema.json: { "types": [ { "api_id": "product", "name": "Product", "fields": [ ... ] } ], "dry_run": true }
writavo apply-content-schema --body-file schema.json

# happy with the plan? set "dry_run": false and run it again
```

- Schema changes never rewrite entries. To rename a field and keep its values, set renamed_from to the old API id.
- A removed field's values stay stored but are not returned. A type with entries cannot be deleted.
- required is enforced on publish, so drafts can be half-finished.

## Export a whole Site

GET /export returns the Site in Writavo Import Format: articles, pages, authors, categories, tags, content types, entries, custom fields, redirects, engagement history and reader comments, with media as links.

- Comments come as a top-level comments array that POST /comments/import reads. Leave them out with ?comments=false.
- Volumes are about 8 MB. The Writavo-Export-Next header (and source.export.next in the file) is the cursor for the next one.
- Import the files in order, into this Site or another, with POST /imports or the MCP server's import_content.

shell:

```
writavo export-site --raw > part-1.json
# more to come? read .source.export.next and pass it on
writavo export-site --cursor "$(jq -r .source.export.next part-1.json)" --raw > part-2.json
```

References travel by external id or slug, so they resolve on any Site. One whose target is in a later file is reported; importing that file again at the end fills it in.
