Public write API

This page lists everything publicWrite accepts and everything its routes answer. For a guided setup, follow Public write. Examples use example.discussion from the example plugin, whose write routes live at /api/@vitnode/example/content/discussions.

publicWrite optionsCopy Anchor Link

publicWrite is a block of defineContentType from @vitnode/core/content. Leave it out, or set it to false, to keep public writing off.

publicWrite: {
  ownership: { field: "author" },
  create: { fields: ["title", "body"], status: "published" },
  update: { fields: ["title", "body"] },
},

The content type also needs:

• publicApi, and therefore publication. Without it, publicWrite only accepts false at the type level and throws when the definition loads.
• No localized fields. Public writes do not create translations yet, so a content type with localization cannot use publicWrite.

The read and write allowlists are independent. A field can be writable without being in publicApi.fields, and the other way around.

Writable fieldsCopy Anchor Link

create.fields and update.fields accept top-level, shared fields of these kinds, from CONTENT_PUBLIC_WRITABLE_KINDS:

boolean, container, dateTime, enum, number, relation, richText, slug, text, textarea

They never accept:

A relation is writable only when its target content type has a publicApi. On each request, every referenced record must also be published and not hidden.

A container is writable in create.fields only. A member picks the container once, when they create the record; moving it later is a staff edit, so an author cannot drop their record into a container they could not post in. On each create, the server reads the container back inside the write's transaction and checks that it belongs to the field's collection. A missing or foreign container answers 400 with an unavailable issue on that field. See Containers on the frontend.

Moderator permissionCopy Anchor Link

A content type with update adds can_edit to its plugin's moderator permissions, under the content type's permission module, such as discussion. It shares the @vitnode/example:discussion:can_edit label with the admin permission. If the plugin declares that module under permissionStaff.moderator itself, the declared list wins.

When the content type lives in a container collection with publishing policies, can_edit is scoped by that collection and can_approve is added next to it. See Container-scoped permissions.

Generated routesCopy Anchor Link

The routes live in the public module, under /api/{pluginId}/content/{publicApi.path}, next to the public read routes. Only the ones publicWrite enables are mounted, and the fetcher types them the same way: a post to a content type without create is a compile error.

GET /{id}/edit and PATCH /{id} answer only for the owner and for moderators. There is no public delete, publish or hide route.

GET /permissions takes up to 50 comma-separated ids and answers for guests too. canEdit follows the same rules as PATCH; canReport is true for a public record, with reports on, that the visitor did not write. A record the visitor can neither read nor edit is left out of items, so the route never confirms a draft exists.

A request passes these checks in order: the rate limit, the captcha (create only), the session, the body, then for an edit the owner or moderator check and the relation targets, all before anything is written.

Request bodiesCopy Anchor Link

Both bodies are strict JSON objects. A key outside the allowlist is refused, never dropped.

Each value uses the field's own validation, the same as in the AdminCP. A rich text field takes a ProseMirror document, and a relation takes an id, or an array of ids for multiple: true.

PATCH /api/@vitnode/example/content/discussions/1
Content-Type: application/json
Cookie: vitnode_auth=<session>

{ "values": { "title": "How do I add a widget zone below an article?" }, "expectedVersion": 2 }

Response recordCopy Anchor Link

Every successful response is the same record shape:

{
  "approval": null,
  "id": 1,
  "slug": "how-do-i-add-a-widget-zone-below-an-article",
  "status": "published",
  "publishedAt": "2026-10-13T09:12:44.512Z",
  "version": 3,
  "values": {
    "title": "How do I add a widget zone below an article?",
    "body": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "I want one under my article." }
          ]
        }
      ]
    }
  }
}

Status codesCopy Anchor Link

Validation failures are 400, the status every VitNode input error uses, not 422.

RejectionCopy Anchor Link

400, 401, 403 and 404 answer with one JSON shape, zodContentPublicWriteRejection from @vitnode/core/content:

type ContentPublicWriteRejection = {
  code:
    | "CONTENT_FORBIDDEN"
    | "CONTENT_INVALID_INPUT"
    | "CONTENT_NOT_FOUND"
    | "CONTENT_UNAUTHENTICATED";
  contentTypeId: string;
  issues: { code: string; field: string | null; message: string }[];
};

issues is empty for 401 and 404, and for 403 unless a container policy refused the write. For 400, each issue names the field it belongs to, or null for the request as a whole. Translate an issue by its code; message is English text for developers.

A title that is too short and an owner the client tried to set:

{
  "code": "CONTENT_INVALID_INPUT",
  "contentTypeId": "example.discussion",
  "issues": [
    {
      "code": "too_small",
      "field": "title",
      "message": "Too small: expected string to have >=3 characters"
    },
    {
      "code": "not_writable",
      "field": "author",
      "message": "This field cannot be written."
    }
  ]
}

A body that is not JSON:

{
  "code": "CONTENT_INVALID_INPUT",
  "contentTypeId": "example.discussion",
  "issues": [
    {
      "code": "invalid_json",
      "field": null,
      "message": "The body must be JSON."
    }
  ]
}

If discussions had a category relation, a draft, hidden or missing category would all get the same answer:

{
  "code": "CONTENT_INVALID_INPUT",
  "contentTypeId": "example.discussion",
  "issues": [
    {
      "code": "unavailable",
      "field": "category",
      "message": "The selected record is not available."
    }
  ]
}

A member editing somebody else's published discussion:

{
  "code": "CONTENT_FORBIDDEN",
  "contentTypeId": "example.discussion",
  "issues": []
}

The same member editing somebody else's draft gets 404 with "code": "CONTENT_NOT_FOUND", so the answer never confirms that the draft exists.

ConflictCopy Anchor Link

409 answers with zodContentConflict, the same shape the AdminCP's editorial routes use:

{
  "code": "CONTENT_VERSION_CONFLICT",
  "contentTypeId": "example.discussion",
  "currentVersion": 4,
  "expectedVersion": 3,
  "itemId": 1
}

{
  "code": "CONTENT_UNIQUE_CONFLICT",
  "contentTypeId": "example.discussion",
  "itemId": null
}

itemId is null for a unique conflict on create. On example.discussion, a unique conflict means the slug derived from the title is taken.

Rate limitCopy Anchor Link

POST and PATCH requests to a path containing /content/, outside /admin/, share a budget of 20 requests per 60 seconds, on top of the write budget every mutation spends. Change it with rateLimiter.contentWrite in apps/api/src/vitnode.api.config.ts. The budget counts per signed-in user when the request carries a session cookie, and per IP otherwise (rateLimiter.perUser, on by default). It is off when NODE_ENV=development. See Rate limiter for the 429 body and Redis-backed counters.

CodesCopy Anchor Link

Issue codes:

parseContentPublicWriteRejection(body) takes the parsed JSON body and returns the rejection, or null for any other shape. Unlike parseContentConflict, it does not take a string.

import { parseContentPublicWriteRejection } from "@vitnode/core/content";

const rejection = parseContentPublicWriteRejection(
  await res.json().catch(() => null),
);

Frontend helpersCopy Anchor Link

From @vitnode/core/tanstack/content, for pages in the browser.

useContentPermissionsCopy Anchor Link

const permissions = useContentPermissions({ fetch, ids, queryKey });
permissions.of(id); // { canEdit, canReport }

of(id) returns all false until the answer arrives and for a record left out. The hook waits for the session and asks again when somebody signs in or out.

useContentPublicWriteCopy Anchor Link

const write = useContentPublicWrite({ fields, latestVersion, uniqueField, version });
const record = await write.submit(form, async expectedVersion => await fetcher(/* ... */));

submit returns the record on a 2xx and null otherwise, after showing the reason. It passes the current expectedVersion to request and stores the new one after each save. write.conflict is the version-conflict alert, or null; render it above the form. Messages come from core.global.content_write and follow the reader's language.

Server APICopy Anchor Link

Use these from @vitnode/core/content/server when a plugin needs its own write route, such as "start a discussion from a question", with the same ownership, authorization and effects as the generated routes.

createContentPublicWriteServiceCopy Anchor Link

createContentPublicWriteService({ c, model, pluginId });

c is the Hono context, model is the content model, such as discussionContent, and pluginId is the plugin that owns the content type. The service acts as the user session of c, never as an AdminCP session.

The methods throw instead of answering:

A route that starts a discussion from a single question. withHttpErrors turns a unique conflict into the structured 409, and the catch maps a refusal to its status:

import { ContentPublicWriteDenied } from "@vitnode/core/content";
import {
  createContentPublicWriteService,
  withHttpErrors,
} from "@vitnode/core/content/server";
import { HTTPException } from "hono/http-exception";
import { z } from "zod";

import { buildRoute } from "@/api/builders";
import { discussionContent } from "@/database/discussions";
import { manifest } from "@/manifest.gen";

export const askRoute = buildRoute({
  route: {
    method: "post",
    path: "/ask",
    description: "Start a discussion from a question",
    withCaptcha: true,
    request: {
      body: {
        required: true,
        content: {
          "application/json": {
            schema: z.object({ question: z.string().trim().min(3).max(200) }),
          },
        },
      },
    },
    responses: {
      201: {
        content: {
          "application/json": {
            schema: z.object({ id: z.number(), slug: z.string().nullable() }),
          },
        },
        description: "Discussion started",
      },
      401: { description: "Not signed in" },
      409: { description: "A discussion with this title exists" },
    },
  },
  handler: async c => {
    const { question } = c.req.valid("json");
    const service = createContentPublicWriteService({
      c,
      model: discussionContent,
      pluginId: manifest.id,
    });

    try {
      const record = await withHttpErrors(
        "create",
        async () =>
          await service.create({
            title: question,
            body: {
              type: "doc",
              content: [
                {
                  type: "paragraph",
                  content: [{ type: "text", text: question }],
                },
              ],
            },
          }),
        { contentTypeId: discussionContent.definition.id, structured: true },
      );

      return c.json({ id: record.id, slug: record.slug }, 201);
    } catch (error) {
      if (error instanceof ContentPublicWriteDenied) {
        throw new HTTPException(error.reason === "unauthenticated" ? 401 : 404);
      }
      throw error;
    }
  },
});

A route outside /content/ only gets the general write budget, which is why this one asks for a captcha.

HelpersCopy Anchor Link

Definition errorsCopy Anchor Link

defineContentType checks publicWrite when the definition loads and throws a ContentEngineError that starts with [Content Engine] <id>:. Relation targets that were still loading are checked again when the routes are built at boot.

The field-list errors read publicWrite.update.fields for the update list.