Custom endpoints

Any custom Payload endpoint that carries custom.openapi metadata is picked up automatically. The metadata is a standard OpenAPI Operation Object — summary, tags, parameters, requestBody, responses, and so on. Endpoints without it are skipped, so nothing internal leaks into the spec by accident.

payload.config.ts

import type { Endpoint } from 'payload'

const healthEndpoint: Endpoint = {
  path: '/health',
  method: 'get',
  handler: () => Response.json({ ok: true }),
  custom: {
    openapi: {
      summary: 'Health check',
      tags: ['System'],
      responses: {
        '200': { description: 'Service is healthy' },
      },
    },
  },
}

This is the same custom.openapi convention that Payload’s own agent skills document. The plugin reads exactly that shape — no plugin-specific wrapper, no separate registry to keep in sync. Endpoints already documented this way show up with zero changes.

Where endpoints are collected from

The plugin walks every endpoint list in the sanitized config:

Source	Spec path
Top-level `config.endpoints`	`/api/...`
Collection `endpoints`	`/api/<slug>/...`
Global `endpoints`	`/api/globals/<slug>/...`

The /api segment follows your routes.api setting. Path params written Express-style (:id) are normalized to OpenAPI placeholders ({id}), so a collection endpoint at /:id/tracking on posts is documented as /api/posts/{id}/tracking.

Custom endpoints are documented only while filters.includeCustom stays on. It defaults to true; turning it off drops every custom.openapi endpoint from the spec. See Filters.

Examples

Request body

collections/Posts.ts

import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  endpoints: [
    {
      path: '/import',
      method: 'post',
      handler: importHandler,
      custom: {
        openapi: {
          summary: 'Bulk import posts',
          requestBody: {
            required: true,
            content: {
              'application/json': {
                schema: {
                  type: 'array',
                  items: { $ref: '#/components/schemas/PostsCreate' },
                },
              },
            },
          },
          responses: {
            '202': { description: 'Import queued' },
          },
        },
      },
    },
  ],
  fields: [{ name: 'title', type: 'text', required: true }],
}

Path parameters

Declare params under parameters exactly as in any OpenAPI operation. The :id in the Payload path and the {id} in the parameter refer to the same thing:

collections/Posts.ts

{
  path: '/:id/tracking',
  method: 'get',
  handler: trackingHandler,
  custom: {
    openapi: {
      summary: 'Tracking events for a post',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'string' },
        },
      ],
      responses: {
        '200': { description: 'Tracking events' },
      },
    },
  },
}

Filters

Control which entities and operations end up in the spec, including includeCustom.

For plugin authors

Ship documented endpoints from your own plugin with no dependency on this package.

Documentation

Configuration

CLI

Guides

Reference

Where endpoints are collected from

Examples

Request body

Path parameters

Tags

Filters

For plugin authors

​Where endpoints are collected from

​Examples

​Request body

​Path parameters

​Tags

​Related

Filters

For plugin authors

Where endpoints are collected from

Examples

Request body

Path parameters

Tags

Related