Custom endpoints – fluent-wp-client

Overview

Content type	API
Custom post type in wp/v2	content('resource')
Custom taxonomy in wp/v2	terms('resource')
Plugin/custom namespace	request({ endpoint: '/wp-json/...' })
Full transport control	request(...)

Custom post types

Assume a CPT with rest_base: 'books'.

Reads

const books = wp.content('books');

const list = await books.list({ perPage: 20 });
const allBooks = await books.listAll();
const paged = await books.listPaginated({ page: 2, perPage: 25 });
const book = await books.item('my-book');
const embedded = await books.item('my-book', { embed: true });

Note

CPT clients follow the same rules as core content builders: plain DTO reads stay lean, and embed opts into _embed on request.

CRUD

CPT CRUD

const created = await books.create({ title: 'Book title', status: 'draft' });
await books.update(created.id, { status: 'publish' });
await books.delete(created.id, { force: true });

Response validation

Validate custom endpoint payloads in application code after the request resolves:

Validate a CPT response in app code

import { z } from 'zod';

const bookSchema = z.object({
  id: z.number(),
  slug: z.string(),
  status: z.string(),
  type: z.literal('book'),
});

const rawBook = await wp.content('books').item('my-book');
const book = bookSchema.parse(rawBook);

Sparse CPTs

Use WordPressCustomPost<T> or postLikeWordPressSchema when a CPT may omit title, content, or excerpt.

import type { WordPressCustomPost } from 'fluent-wp-client';
import { postLikeWordPressSchema } from 'fluent-wp-client/zod';

const rawArtifact = await wp.content('artifacts').item('test-artifact-001');
const artifact = postLikeWordPressSchema.parse(rawArtifact);

Tip

Use contentWordPressSchema instead to fail fast when content fields are missing.

Embed and extraction

Extract custom taxonomy terms from an embedded CPT

import { getEmbeddedTerms, getEmbeddedAuthor } from 'fluent-wp-client';

const book = await books.item('test-book-001', { embed: ['author', 'wp:term'] });
const author = getEmbeddedAuthor(book);
const genres = getEmbeddedTerms(book, 'genre');

Gutenberg blocks

Use fluent-wp-client/blocks when the CPT exposes content.raw:

import { withBlocks } from 'fluent-wp-client/blocks';

const wpBlocks = withBlocks(wp);
const blocks = await wpBlocks.content('books').item('test-book-001').blocks().get();

Caution

CPTs without editor support cannot provide a block tree.

Custom taxonomies

Assume rest_base: 'genre'.

Reads and CRUD

const genres = wp.terms('genre');

const list = await genres.list({ perPage: 100 });
const allGenres = await genres.listAll();

const created = await genres.create({ name: 'Science Fiction' });
await genres.update(created.id, { name: 'Sci-Fi' });
await genres.delete(created.id, { force: true });

Low-level requests

Direct transport

const { data, response } = await wp.request({
  endpoint: '/wp-json/my-plugin/v1/sync',
  method: 'POST',
  body: { mode: 'delta' },
});

Auth

Use the same auth approach as core endpoints. See the auth guide.

Tip

Prefer a separate WordPressClient when auth differs per route. Use per-request auth on request() only when it truly varies call-by-call.

Pagination

WordPress caps per_page at 100

Use .listAll() for complete datasets.

Error handling

• WordPressClientError — base class for all runtime failures with kind, operation, endpoint, retryable
• WordPressHttpError — HTTP failures with status, wpCode, wpMessage, responseBody
• Use instanceof to narrow, or error.kind for serialization
• Prefer schema validation for writes so regressions fail fast