fix(specs): track OpenAPI spec drift for undocumented endpoints and missing methods

Author: kheinerCreated Jun 9, 2026Updated Sep 17, 2026

LabelsChore

Background

During the audit performed for PR directus/directus#27316, a significant number of gaps were found between the @directus/specs package and the actual REST API surface of @directus/api. This issue is being created to better manage the process of addressing what gaps were discovered and make it easier to chunk the changes.

This issue catalogs every gap found so far. It may not be exhaustive of every possible spec issue, but it covers all cases identified during a systematic review of the controller routes against the spec paths in packages/specs/src/paths/. I hope this catches the project up to a manageable state for future contributions.

Related: directus/directus#20972, directus/directus#26539, directus/directus#25179

Currently Undocumented Paths

Always On

Document /dashboards and /panels directus/directus#27701

Both manage Insights records (directus_dashboards, directus_panels) and follow the same shape. Bundling them in one PR is reasonable. Routes: GET, POST, GET /{id}, PATCH, PATCH /{id}, DELETE, DELETE /{id} for each. Source: api/src/controllers/dashboards.ts, api/src/controllers/panels.ts.
Document /notifications and /translations directus/directus#27764

Manages in-app notification records (directus_notifications). Routes: GET, POST, GET /{id}, PATCH, PATCH /{id}, DELETE, DELETE /{id}. Source: api/src/controllers/notifications.ts.
Manages custom translation records (directus_translations). Routes: GET, POST, GET /{id}, PATCH, PATCH /{id}, DELETE, DELETE /{id}. Source: api/src/controllers/translations.ts.
Document /deployments directus/directus#27767

Provider-scoped deployment management. Routes: GET /deployments, GET/PATCH/DELETE /deployments/{provider}, GET /deployments/{provider}/projects, GET/PATCH /deployments/{provider}/projects/{id}, GET /deployments/{provider}/projects/{id}/runs, GET /deployments/{provider}/projects/{id}/runs/stats, POST /deployments/{provider}/projects/{id}/deploy, GET /deployments/{provider}/runs/{id}, POST /deployments/{provider}/runs/{id}/cancel, GET /deployments/{provider}/dashboard. Source: api/src/controllers/deployment.ts.
Document /shares directus/directus#27763

Manages content share records (directus_shares). Includes three special-purpose endpoints beyond the standard CRUD set. Routes: GET, POST, GET /{id}, PATCH, PATCH /{id}, DELETE, DELETE /{id}, POST /shares/auth (no user credential required, accepts optional password), POST /shares/invite (send email invitations), GET /shares/info/{id} (public endpoint, no authentication required, validates expiry and usage limits). Source: api/src/controllers/shares.ts.
Document /extensions/registry, /extensions/registry/account/{pk}, /extensions/registry/extension/{pk}, /extensions/registry/install, /extensions/registry/reinstall, /extensions/registry/uninstall/{pk}, /extensions/{pk} (DELETE), and /extensions/sources/{chunk}

Only GET /extensions, PATCH /extensions/{name}, and PATCH /extensions/{bundle}/{name} are currently documented (packages/specs/src/paths/extensions/). The registry browse/install/uninstall routes and the DELETE /extensions/{pk} / GET /extensions/sources/{chunk} routes have no spec coverage at all. Source: api/src/controllers/extensions.ts.

ENV Gated

Document ENV-gated subsystems: /files/tus, /mcp, /mcp-oauth/clients directus/directus#27766

Use the same env-gating pattern introduced for /metrics in PR directus/directus#27316.

/files/tus (requires TUS_ENABLED=true): POST /files/tus, HEAD /files/tus/{id}, OPTIONS /files/tus/{id}, PATCH /files/tus/{id}, DELETE /files/tus/{id}. Source: api/src/controllers/tus.ts.

/mcp (requires mcp_enabled system setting): GET /mcp, POST /mcp. Source: api/src/controllers/mcp/index.ts.

/mcp-oauth/clients (requires MCP_OAUTH_ENABLED=true): GET, POST, GET /{id}, DELETE, DELETE /{id}. Source: api/src/controllers/mcp/oauth-clients.ts.

Paths with incorrect documentation

Add missing methods to /server, /files, and /flows directus/directus#27765

/server: GET /server/health (200 or 503, requires HEALTHCHECK_ENABLED != false)

/files: POST /files/import (import file from remote URL, accepts url, optional data and filterMimeType).

/flows: GET /flows/trigger/{id} and POST /flows/trigger/{id}.
Add missing methods to /users directus/directus#27761

/users: POST /users/register (public self-registration, rate-limited, accepts email, password, optional first_name, last_name, verification_url), GET /users/register/verify-email (email verification redirect), POST /users/me/tfa/generate (returns secret and QR code URI), POST /users/me/tfa/enable (requires secret and otp). Note: /users/me/tfa/disable and /users/{id}/tfa/disable are already documented.
Remove incorrect query parameters from /collections and /fields directus/directus#27762

Confirmed by @ComfortablyCoding during review of PR directus/directus#27316 with references to the relevant controller lines.

GET /collections: remove Offset and Meta (API accepts no query parameters on this endpoint).

GET /fields: remove Limit, Page, and Sort (API accepts no query parameters on this endpoint).

GET /fields/{collection}: remove Sort (API accepts no query parameters on this endpoint).
Add SEARCH method to all affected endpoints directus/directus#27760

The API implements the SEARCH HTTP method as an alternative to GET for complex filtered queries. It is not documented on any endpoint. Affected paths (at minimum): /collections, /comments, /dashboards, /files, /folders, /items/{collection}, /notifications, /operations, /panels, /permissions, /presets, /revisions, /roles, /shares, /translations, /users, /versions.

Validation warnings

When loading the generated OAS from GET /server/specs/oas without an authentication token, two pre-existing validation warnings appear for the Query and x-metadata schema references. They do not appear when the spec is generated with an authenticated token. These are not introduced by any of the changes in PR directus/directus#27316 and may resolve as spec coverage catches up.

Known exclusions

/license is intentionally not exposed in the public spec (confirmed as internal use only by @ComfortablyCoding during review of PR directus/directus#27316).

/ai/chat, /ai/object, and /ai/files (all under the AI_ENABLED=true gate) are intentionally not exposed in the public spec. All three check req.accountability?.app and reject non-studio sessions with a 403. They are studio-internal tooling, not a public API surface. Confirmed by PR descriptions: #26259 ("intended for in-studio use only"), #26862 ("requires app: true accountability"), #26722 (server-side proxy for the studio file-attachment feature). Source: api/src/ai/chat/controllers/chat.post.ts, api/src/ai/chat/controllers/object.post.ts, api/src/ai/files/controllers/upload.ts.

Testing note

All gaps above were identified by comparing controller route registrations in api/src/controllers/ against the path directories in packages/specs/src/paths/. Testing was performed against a bare database. Validation of response shapes against real data should use the simple-website-cms template to populate realistic content before verifying spec accuracy end-to-end.

Test Against CMS Template - Close this issue once all above checks are done and the CMS issue is verified.

GENERAL CLEANUP

Responses should match the appropriate StatusCode
- '204': response will be a ref per https://github.com/directus/directus/pull/27857#discussion_r3539779409
/auth/logout responds 204 (currently documented as 200)
/utils/{collection}/export responds 204 (currently documented as 200)
/schema/diff has a non-standard 204
- '403': response is now a ref, many paths are undocumented for 403 but it is a meaningful response. It is distinct from 401 (unauthenticated) per https://github.com/directus/directus/pull/27316#issuecomment-4918300427
items.yaml schema: intentionally blank per https://github.com/directus/directus/pull/27316#issuecomment-4908405007
items.yaml still has an empty schema (intentional from directus/directus#16294). I'm not sure I understand it well enough to know that adding an empty object schema will allow tests to pass natively and not create any issues.
https://github.com/directus/directus/blob/e86e4a60c9d7efa2b84a2b76dc43769f766b6651/packages/specs/src/paths/items/items.yaml#L38-L49
diff
```
# I think the fix is to...
- schema:
+ schema: {}
```
~~I want to get around the swagger-cli validate error that "schema must be object". More research to be done on the OpenAPI Spec versions; my guess is the version is important with this fix.~~ Research complete, this is the confirmed fix.
ensure punctuation usage is consistent per https://github.com/directus/directus/pull/27857#issuecomment-4909775612
- Currently there are inconsistencies with punctuation usage in summary/description fields. After everything is fixed we should nit the punctuation so it's all consistent.
- legacy @directus/specs package info uses the "admin app" language but it should be updated to "Data Studio" where relevant.
directus/directus#27890 for writeOnly and readOnly fields (not needed, marked as done & closed issue as not planned)
directus/directus#27900 for missing objects in query.yaml and paramters/*.yaml PR directus/directus#27938

Deferred

I'm unable to see Directus team LINEAR or project boards; it may make sense to add these somewhere or provide guidance on the following:

Configuring the build/release CICD Pipeline to generate a OASSpec to ensure that the documentation on http://directus.com/docs/api always matches the current release.
Addressed ✅ via directus/directus#27856 ~~Update the PR Template to clarify that the SPECS package should be reviewed for any changes to API package; I think this is the cause of a lot of the drift.~~
directus/directus#25179 has an open Linear Ticket related to SEO plugin that I'm not even sure how I'd begin to introduce a fix for but I'm interested in potentially exploring this as well.
Addressed ✅ via directus/directus#27883 ~~Add some sort of readme.md or contributing.md to the package/specs to explain some of the lesser understood or customized elements of the specs package (i.e. ENV gating, x-metadata)~~

tagged per previous comments in related issues

@phazonoverload - https://github.com/directus/directus/issues/20972#issuecomment-2231675137
@ANKANJAGTAP - https://github.com/directus/directus/issues/26539#issuecomment-3817646499

Source: directus/directus

View original on GitHub View discussion on GitHub