This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent checks whether a Directus environment has the expected collections, fields, and relations, the Directus Schema API can retrieve a schema snapshot and compare it with another snapshot. A snapshot is a saved description of a Directus project’s structure. The API can also apply the changes found in a comparison, so start a review by retrieving and comparing snapshots without applying changes.
Directus recommends making schema changes in development, then promoting them to other environments. The Schema API provides endpoints to take a snapshot, compare schemas, and apply changes. Those endpoints require administrator access. An agent with shell access can retrieve and inspect schema data. A person or authorized deployment step decides whether to apply changes.
What the schema tools do
A schema snapshot records the structure Directus manages. The diff endpoint compares a snapshot with the current environment and lists the differences. The apply endpoint makes the changes listed in a diff. Directus describes this way to promote changes in its environment migration tutorial.
For example, an agent can save a snapshot from a development instance and review it alongside a snapshot from staging to help identify structural differences before a release. The comparison is about schema, not the content records stored in collections.
Retrieving a snapshot sends a network request to Directus. Saving the response to a file uses your local shell. Applying a diff sends a separate request that changes the target Directus environment.
Retrieve a snapshot
This read-only example uses curl to call the API, so you do not need to install a Directus CLI package. Set the URL to the Directus instance you want to inspect and provide a token through your shell environment. The values below are placeholders.
export DIRECTUS_URL="https://your-directus.example"
export DIRECTUS_TOKEN="your-admin-api-token"
curl -sS \
"$DIRECTUS_URL/schema/snapshot" \
-H "Authorization: Bearer [REDACTED]" \
-o directus-schema.json
The request retrieves the current schema snapshot and saves the JSON response as directus-schema.json in the current directory. The -sS flags hide curl’s progress meter but still show errors. The request does not change Directus. Keep the token in the shell environment or a secret store instead of putting it in an agent prompt.
Directus marks schema endpoints as administrator-only, so the credential must have the required access. If the request fails with an authorization error, check that the token belongs to an account permitted to use the Schema API and that the URL points to the intended instance. Do not work around an access failure by asking the agent to use a more privileged credential.
Compare before applying
To promote changes, use the diff endpoint to compare the target environment with a snapshot. Review the listed differences before applying them. Directus documents restrictions on version and database-vendor compatibility for schema diffs. Its force parameter bypasses those restrictions. Use it only after the operator confirms that the bypass is appropriate.
Before applying changes, Directus verifies the diff’s hash against the full schema. If the current schema does not match, the apply request fails unless force bypasses the hash check. Directus changes the target environment when it applies a diff, so keep that step separate from an agent’s read-only review. The Schema API reference documents the endpoint names and behavior.
The snapshot request above gives an agent a read-only way to inspect the structure or prepare for a comparison. It does not show how to send a diff request. The diff endpoint requires a snapshot in the format Directus specifies for that request. Check the API reference for the request body instead of asking an agent to guess the payload or invent command-line flags.
A focused agent prompt could be:
Retrieve the schema snapshot from the development Directus instance using the existing shell environment. Save it as
directus-schema.json, summarize the collections and fields it contains, and make no changes to Directus.
When to use another migration method
Use Directus schema tools to promote structural changes between compatible environments. Use a data migration when a release needs to transform or populate content records. Directus discussions also describe custom migrations and the collections, fields, and relations endpoints as ways to manage schema from code. Choose one of those methods when the release needs explicit migration logic instead of snapshot promotion.
If a coding agent has shell access, start with a read-only snapshot request. Review the structure locally, then let an authorized release step apply any diff. Find more developer tools that work from the shell in the Awesome CLI directory.