> ## Documentation Index
> Fetch the complete documentation index at: https://payload-plugin-openapi.seshuk.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters

> Control what ends up in the spec: which entities are documented, which internal endpoints appear, and which operations are dropped.

`filters` decides what the spec contains: which collections and globals are documented, which Payload-internal collections show up, which extra endpoint groups are generated, and which individual operations are dropped. It's one flat object.

| Option | Type | Default | Description |
| - | - | - | - |
| `include` | `EntityMatcher[]` | `[]` | Allowlist. When non-empty, only matching entities are documented |
| `exclude` | `EntityMatcher[]` | `[]` | Entities to leave out entirely (schemas and paths) |
| `includeHidden` | `boolean` | `false` | Include collections flagged `hidden` / `admin.hidden` |
| `includeSystem` | `boolean` | `false` | Include Payload-internal collections and globals (`payload-jobs`, `payload-jobs-stats`, …) |
| `includeCustom` | `boolean` | `true` | Document endpoints carrying `custom.openapi` metadata |
| `includeAuth` | `boolean` | `true` | Document auth operations (login / logout / me / …) |
| `includeAdminAuth` | `boolean` | `false` | Document admin endpoints (`/init`, first-register, `/api/access`, document access) |
| `includeVersions` | `boolean` | `true` | Document version operations (`/versions`, `/versions/{id}`) |
| `includeJobs` | `boolean` | `true` | Document jobs endpoints (`/payload-jobs/run`, `/handle-schedules`) |
| `excludeOperations` | `Array<OperationRule \| (ctx) => boolean>` | `[]` | Rules and functions that drop single operations |

`includeSystem` covers these collections: `payload-jobs`, `payload-kv`, `payload-llm-instructions`, `payload-locked-documents`, `payload-migrations`, `payload-preferences` and `payload-query-presets`. It also covers the `payload-jobs-stats` global.

See [Endpoints](/v1/reference/endpoints) for the full list of endpoints and the option that controls each one.

## Choosing entities with `include` and `exclude`

These two lists pick which collections and globals are documented. Each entry is an `EntityMatcher` — one of three shapes:

| Matcher | Matches | Example |
| - | - | - |
| a string | one entity by its exact slug | `'posts'` |
| a `RegExp` | every entity whose slug matches the pattern | `/^marketing-/` |
| `{ kind, slug }` | one entity, when a collection and a global share the same slug | `{ kind: 'global', slug: 'nav' }` |

Two rules govern how the lists combine:

* `include` is an allowlist. Leave it empty and everything is documented; add anything and only matching entities survive.
* `exclude` always wins. An entity matching both lists is dropped.

### Document only a few collections

Once `include` has entries, everything else stays out of the spec:

```ts payload.config.ts theme={null}
filters: {
  include: ['posts', 'media', 'categories'],
}
```

### Document everything except a few entities

```ts payload.config.ts theme={null}
filters: {
  exclude: ['audit-log', 'internal-settings'],
}
```

### Match a group of slugs with a regular expression

The pattern is tested against the slug. This keeps every collection whose slug starts with `public-` and drops everything else:

```ts payload.config.ts theme={null}
filters: {
  // public-posts, public-media, public-authors … all kept; everything else dropped.
  include: [/^public-/],
}
```

Common patterns, for reference:

* `/^public-/` — slug starts with `public-`
* `/-draft$/` — slug ends with `-draft`
* `/^(posts|pages)$/` — slug is exactly `posts` or `pages`
* `/internal/i` — slug contains `internal`, case-insensitive

### Disambiguate a collection from a global

A plain string matches any entity with that slug. When a collection and a global share one, use `{ kind, slug }` to target just one of them:

```ts payload.config.ts theme={null}
filters: {
  // Keep the `settings` collection, drop the `settings` global.
  exclude: [{ kind: 'global', slug: 'settings' }],
}
```

### Mix them

`include` narrows the set first, then `exclude` removes from what's left:

```ts payload.config.ts theme={null}
filters: {
  // Document every `public-*` collection, but never the drafts one.
  include: [/^public-/],
  exclude: ['public-drafts'],
}
```

<Note>
  `include` and `exclude` only apply to your own collections and globals. Hidden and Payload-internal collections are
  governed by `includeHidden` and `includeSystem`, which run **first** — adding `payload-jobs` to `include` won't
  surface it unless `includeSystem` is on.
</Note>

## Dropping individual operations

`include` / `exclude` work at the entity level. To remove specific operations — one method on one collection, every `DELETE`, anything under a path prefix — use `excludeOperations`. It applies to every operation in the spec: collection, global, custom, jobs and system (upload instructions, `/api/access`) operations.

### Rules

Each rule is a set of conditions. Within one rule, every field you set must match (**AND**). Across rules, an operation is dropped if **any** rule matches it (**OR**). A field you leave out matches anything.

| Field | Type | Matches |
| - | - | - |
| `method` | `HttpMethod \| HttpMethod[]` | The HTTP method(s); omit to match any |
| `slug` | `string \| RegExp` | The collection or global slug, exact string or pattern; omit to match any |
| `kind` | `OperationKind` | Restrict to one group; omit to match all |
| `path` | `RegExp` | Tested against the final route path (e.g. `/api/posts/{id}`) |

`kind` is one of `'collection'`, `'global'`, `'custom'` (endpoints with `custom.openapi`), `'jobs'` or `'system'`. Custom, jobs and system operations have no slug, so a rule with `slug` never matches them.

```ts payload.config.ts theme={null}
filters: {
  excludeOperations: [
    // Drop every DELETE, on any entity.
    { method: 'delete' },
    // Drop writes to `posts`, but leave its reads alone.
    { slug: 'posts', method: ['post', 'patch', 'put'] },
    // Drop anything matching a path, regardless of method or entity.
    { path: /\/preview$/ },
  ],
}
```

### Functions

For logic that doesn't fit a rule, put a function in the same list. It receives the `method`, `path`, `slug` and `kind` of every operation. The operation is dropped only when the function returns `true`. An `async` function is awaited:

```ts payload.config.ts theme={null}
filters: {
  excludeOperations: [
    { method: 'delete' },
    ({ path, method }) => path.includes('/internal/') || method === 'put',
  ],
}
```

<Tip>
  Filters only remove things from the document. To change how a kept operation is marked (public vs. secured), see
  [Security marking](/v1/configuration/security-marking).
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.