Services

The Content Engine already generates routes for creating, reading, updating, deleting and publishing records. A service is what you use when you need something those routes don't do, such as "the three newest articles in one category" or "create an article from a cron job". It is a typed object with methods like findMany, create and publish, and you get it from the model createContentModel returns.

Every example on this page uses the example plugin's article model:

import { createContentModel } from "@vitnode/core/content/server";

import { articleContentType } from "@/content/article";

import { example_categories } from "./categories";

export const articleContent = createContentModel(articleContentType, {
  references: { category: () => example_categories.id },
});

The short versionCopy Anchor Link

Inside any Hono handler, call a service with the request context c:

const article = await articleContent.service(c).findById(1);

article is fully typed: article.title is a string, article.featured is a boolean, and a typo is a compile error. There are three services, and the only question is which one fits your task:

The three sections below build one real example for each.

Example 1: the newest articles in a categoryCopy Anchor Link

Goal: a public endpoint, GET /api/@vitnode/example/articles/by-category/1, that returns the three newest published articles in category 1. Drafts must never appear, and neither may private fields.

publicService guarantees exactly that. It returns what the public API would, so you cannot leak a draft by accident.

import { buildRoute } from "@vitnode/core/api/lib/route";
import { z } from "zod";

import { CONFIG_PLUGIN } from "@/const";
import { articleContent } from "@/database/articles";

export const articlesByCategoryRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: {
    method: "get",
    path: "/by-category/{categoryId}",
    description: "Published articles in one category, newest first",
    request: {
      params: z.object({ categoryId: z.coerce.number().int().positive() }),
    },
    responses: {
      200: {
        content: {
          "application/json": {
            schema: z.array(
              z.object({
                publishedAt: z.date().nullable(),
                slug: z.string(),
                title: z.string(),
              }),
            ),
          },
        },
        description: "Up to three articles",
      },
    },
  },
  handler: async c => {
    const { publicService } = articleContent;
    if (!publicService) throw new Error("Articles have no public API.");

    const { categoryId } = c.req.valid("param");
    const { edges } = await publicService(c).findMany({
      filters: { category: categoryId },
      orderBy: { column: "publishedAt", order: "desc" },
      query: { first: "3" },
    });

    return c.json(
      edges.map(({ publishedAt, slug, title }) => ({
        publishedAt,
        slug,
        title,
      })),
      200,
    );
  },
});

import { buildModule } from "@vitnode/core/api/lib/module";

import { CONFIG_PLUGIN } from "@/const";

import { articlesByCategoryRoute } from "./by-category.route";

export const articlesModule = buildModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  name: "articles",
  routes: [articlesByCategoryRoute],
});

modules: [adminModule, articlesModule],

curl http://localhost:8000/api/@vitnode/example/articles/by-category/1

[
  {
    "publishedAt": "2026-08-03T08:47:00.000Z",
    "slug": "jbbjk-1",
    "title": "old article, example"
  }
]

Need one record instead of a list? publicService(c).findBySlug("jbbjk-1") and findById(1) return one published record, or null.

Example 2: create and publish an article from a jobCopy Anchor Link

Goal: a cron job that publishes a "Weekly digest" article every Monday at 8:00.

There is no visitor and no staff member here, so you want the plain service. It sees every record and every field, including drafts, and it checks no permissions. That makes it the right tool for jobs and scripts, and the wrong one for a public route.

import { buildCron } from "@vitnode/core/api/lib/cron";

import { articleContent } from "@/database/articles";

export const weeklyDigestCron = buildCron({
  name: "weekly-digest",
  description: "Publish the weekly digest article",
  schedule: "0 8 * * 1",
  handler: async c => {
    const service = articleContent.service(c);

    const article = await service.create({
      title: "Weekly digest",
      code: `digest-${Date.now()}`,
      category: 1,
      gallery: [21],
    });

    await service.publish(article.id);
  },
});

Add it to a module's cronJobs, for example cronJobs: [weeklyDigestCron] in the articles module from Example 1.

create checks the values against the same rules as the AdminCP form: title is required and at least 3 characters, gallery needs at least one image, and so on. Values that break a rule throw a ZodError before anything is written. slug is filled from the title automatically.

To make several writes succeed or fail together, run them in one transaction by passing { tx } as the last argument:

await c.get("db").transaction(async tx => {
  const article = await service.create(
    { title: "Weekly digest", code: "digest-41", category: 1, gallery: [21] },
    { tx },
  );
  await service.publish(article.id, { tx });
});

Example 3: a "Feature this article" buttonCopy Anchor Link

Goal: a staff endpoint, POST /articles/1/feature, that marks an article as featured, exactly as if someone had ticked Featured in the AdminCP and pressed Save. That means a revision in the history, the updated event, a search index update and protection against overwriting someone else's save.

That is the editorialService (available with editorial). It needs one extra input, expectedVersion: the version of the article the button's page loaded. If somebody saved the article in the meantime, the versions differ and the request fails with 409 instead of silently overwriting their work.

import { buildRoute } from "@vitnode/core/api/lib/route";
import {
  contentEditorialEffects,
  resolveContentActor,
  withHttpErrors,
} from "@vitnode/core/content/server";
import { HTTPException } from "hono/http-exception";
import { z } from "zod";

import { CONFIG_PLUGIN } from "@/const";
import { articleContent } from "@/database/articles";

export const featureArticleRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  adminStaffPermission: { module: "article", permission: "can_edit" },
  route: {
    method: "post",
    path: "/articles/{id}/feature",
    description: "Mark an article as featured",
    request: {
      params: z.object({ id: z.coerce.number().int().positive() }),
      body: {
        required: true,
        content: {
          "application/json": {
            schema: z.object({ expectedVersion: z.number().int().positive() }),
          },
        },
      },
    },
    responses: {
      200: {
        content: {
          "application/json": { schema: articleContent.schemas.select },
        },
        description: "The featured article",
      },
      404: { description: "Article not found" },
      409: { description: "Someone saved the article first" },
    },
  },
  handler: async c => {
    const { editorialService } = articleContent;
    if (!editorialService) throw new Error("Articles have no editorial.");

    const { id } = c.req.valid("param");
    const { expectedVersion } = c.req.valid("json");
    const pluginId = CONFIG_PLUGIN.pluginId;

    const outcome = await withHttpErrors(
      "update",
      async () =>
        await editorialService(c, { pluginId }).update(
          id,
          { featured: true },
          { actor: resolveContentActor(c), expectedVersion },
        ),
      {
        contentTypeId: articleContent.definition.id,
        itemId: id,
        structured: true,
      },
    );
    if (!outcome) throw new HTTPException(404);

    await contentEditorialEffects(c, articleContent.definition, outcome, {
      model: articleContent,
      pluginId,
    });

    return c.json(outcome.row, 200);
  },
});

Reading the handler top to bottom:

1. adminStaffPermission lets in only staff who may edit articles, the same check as the AdminCP's own edit route. Put the route in your plugin's admin module.
2. editorialService(...).update saves featured: true and writes a revision. resolveContentActor(c) puts the signed-in staff member's name on that revision.
3. withHttpErrors turns a version mismatch into a 409 response the AdminCP understands, instead of a crash.
4. contentEditorialEffects does everything that should happen after a save: it emits content.example.article.updated, updates the search index and handles URL changes. Skip it and the save is still stored, but nothing else hears about it.

The route lives in the admin module, so it answers at POST /api/@vitnode/example/admin/articles/1/feature and only to a signed-in AdminCP session. The body carries the version the page loaded:

{ "expectedVersion": 3 }

If someone saved the article after version 3 was loaded, the answer is a 409:

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

Load the article again, take the new version, and retry. A job without a signed-in user passes CONTENT_SYSTEM_ACTOR instead of resolveContentActor(c).

ReferenceCopy Anchor Link

Service methodsCopy Anchor Link

publicService only reads: findMany({ filters, orderBy, query }), findById(id) and findBySlug(slug), each limited to published records and public fields. editorialService only writes: create, update, delete, publish, unpublish, restore, plus relations and repeatable. service has everything below:

On service, every write and every single-record read accepts { tx } as its last argument. On editorialService, every write takes an options object with actor; update, delete and restore also take expectedVersion, which publish and unpublish treat as optional. A localized content type also has localizedService for writing translations.

SchemasCopy Anchor Link

articleContent.schemas holds the Zod schemas the generated routes validate with. Reuse them so a custom route accepts and returns exactly what the built-in ones do, as Example 3 does with select:

To react to writes instead of making them, see Events.