wp dbtk api edit attaches structured metadata to any registered REST route: a plain-text description, safety classification, auth note, return summary, tags, and more. WP Debug Toolkit (WPDT) stores annotations in a dedicated JSON file that is completely separate from the route schema, so running wp dbtk api discover again never overwrites them. Annotate once, and the metadata persists across every future discovery run.
WordPress REST APIs grow large fast. If, for example, your site is running WooCommerce, Rank Math, and a custom plugin, it can expose hundreds of routes, and none of them tell you whether a given endpoint is safe to call in production, what authentication it requires beyond a basic permission callback, or what shape of data it returns. That information is not in the schema.
Annotations add a persistent documentation layer on top of the discovered route inventory. Each annotation attaches to a specific route path and, optionally, to a specific HTTP method.
WPDT stores all annotations in a separate annotations.json file in the schema directory, independent of the route schema itself. Running wp dbtk api discover updates the schema while leaving annotations completely untouched.
Run wp dbtk api discover once before you begin annotating to populate the schema store. You do not need to repeat discovery before each annotation. If you have not run discovery yet, see Discovering Registered Routes before continuing.
Use wp dbtk api edit with the route path and any combination of annotation flags. Omit --method to annotate at the route level, which applies to all methods on that route. Include --method to target a specific HTTP method.
bash
# Omit --method to annotate at the route level (applies to all methods)
# --safety accepts: read-only | mutates-data | destructive | unknown
# --tag accepts comma-separated values in a single flag
wp dbtk api edit /wp/v2/posts \
--method=GET \
--description="Returns a paginated list of published posts" \
--safety=read-only \
--auth-note="Public by default; private posts require subscriber role or higher" \
--returns="Array of WP_Post objects matching query args" \
--tag=content,public✅ What You Should See: The terminal returns Success: Annotation saved for /wp/v2/posts. WPDT writes the annotation to annotations.json immediately without requiring any page reload or cache clearing.
Run wp dbtk api show to confirm what was saved. Add --method to narrow the output to a specific method’s annotations.
bash
# View all annotations for the route
wp dbtk api show /wp/v2/posts
# View GET-specific annotations only
wp dbtk api show /wp/v2/posts --method=GETThen confirm the route appears in the annotated inventory:
bash
wp dbtk api list --annotated-onlywp dbtk api list --tag retrieves every route that carries a specific tag, at either the route or method level.
bash
# Retrieve all routes tagged "public"
wp dbtk api list --tag=publicTagging related routes, for example, all WooCommerce routes, all routes that require editor access, or all endpoints safe to call in staging, lets an AI coding agent batch-retrieve exactly the context it needs before writing integration code.
| Field | What It Stores |
|---|---|
--description | A plain-text summary of what the route does. This is the first field an AI agent or developer reads when encountering an unfamiliar route. Stored internally as summary. |
--safety | The safety classification for this route or method. Accepts exactly one of four constrained values: read-only, mutates-data, destructive, or unknown. The command throws an error immediately if the value does not match one of these four strings. |
--auth-note | A human-readable note about authentication or authorization requirements beyond what the schema shows. For example, “requires editor role or higher.” |
--returns | A plain-text summary of what the route returns, especially useful when the response schema is absent or only partially documented. |
--tag | One or more comma-separated tags for grouping related routes. Enables batch retrieval via wp dbtk api list --tag=tagname. Tags apply at whichever level the --method flag targets. |
--purpose | When and why to call this endpoint, distinct from the description. Useful when multiple routes cover similar resources but serve different use cases. |
--verification | The confidence level behind this annotation. Accepts: inferred, verified-source, verified-runtime, or verified-docs. |
--example-params | Example request parameters as a valid JSON object. For example, '{"per_page":5,"status":"publish"}'. |
To clear any individual field, pass an empty string for that flag: wp dbtk api edit /wp/v2/posts --description="". WPDT removes that field from the annotation without affecting any others.
wp dbtk api bootstrap generates a compact Markdown brief for a plugin’s entire API surface. The output lists route paths, summaries, safety classifications, and verification states. Pass this brief to an AI coding agent at the start of a session so the agent understands what routes exist and what they do before writing any integration code.
To find the correct source slug for any plugin, run wp dbtk api list and read the Source column. WPDT derives slugs from REST namespace names, not plugin display names. WooCommerce’s wc/v3 namespace produces the slug wc, for example. You can use --namespace instead of --source if you know the namespace but not the slug.
bash
# Generate a Markdown brief using the source slug (derived from the REST namespace)
wp dbtk api bootstrap --source=wc
# Or identify the source by its REST namespace instead
wp dbtk api bootstrap --namespace=wc/v3
# JSON output for programmatic consumption
wp dbtk api bootstrap --source=wc --format=json
# Limit to annotated routes, max 20
wp dbtk api bootstrap --source=wc --annotated-only --max-routes=20Either --source=<slug> or --namespace=<ns> is required. The command throws an error if neither is supplied.
You can export annotations to a JSON pack file to share with teammates, commit to version control, or migrate to another environment.
bash
# Export all annotations for a source
wp dbtk api export --source=wc > /tmp/wc-annotations.json
# Export annotated routes only
wp dbtk api export --source=wc --annotated-only > /tmp/wc-annotations.jsonEither --source=<slug> or --namespace=<ns> is required. WPDT does not support exporting all annotations across all namespaces in a single command without specifying a source.
Additionally, you can import the file on the target site:
bash
# Default: merge new annotations with existing ones
wp dbtk api import /tmp/wc-annotations.json
# Preview what would change without writing anything
wp dbtk api import /tmp/wc-annotations.json --dry-run
# Replace all annotations for every route in the source's namespace
wp dbtk api import /tmp/wc-annotations.json --mode=replace-source⚠️ Warning: --mode=replace-source deletes all existing annotations for every route that belongs to the source’s REST namespace before applying the imported data. Run with --dry-run first to confirm the scope. The default --mode=merge adds and updates fields without removing any annotations the target site already holds.
wp dbtk api edit Saves Successfully but the Route Does Not Appear in wp dbtk api list --annotated-onlyLikely cause: The route path passed to wp dbtk api edit does not match the exact path recorded during discovery.
Fix: Run wp dbtk api list and copy the route path character for character from the output, including the leading slash. Bear in mind that route paths are case-sensitive. Re-run wp dbtk api edit with the exact path.
wp dbtk api discover AgainThis should not happen. WPDT stores annotations in annotations.json, a file that wp dbtk api discover never writes or overwrites. Discovery reads the file each run to fold existing annotations back into the rebuilt schema, but it never modifies it. If annotations disappear after a discovery run, check whether a deployment script, server migration, or file sync process deleted or replaced the WPDT schema directory. The annotations file and the route schema file are independent of each other but live in the same schema directory.
wp dbtk api discover?Yes. WPDT stores annotations in annotations.json, a file that is entirely separate from the route schema. Running wp dbtk api discover only updates the schema store. Annotations persist across discovery runs, WordPress core updates, and plugin updates.
Yes. Run wp dbtk api export --source=<slug> on the source site to produce a JSON pack file, then run wp dbtk api import <file> on the target site. The default mode is merge, which adds and updates annotation fields without removing anything the target site already has. Use --mode=replace-source only when you want to fully replace all annotations for that source’s namespace on the target site.
Yes. Run wp dbtk api bootstrap --source=<slug> to produce a Markdown brief covering route paths, descriptions, safety classifications, and verification states for a specific plugin’s API surface. Paste that output into the agent’s context at the start of a development session. For the full agent integration workflow, see How to Use WP Debug Toolkit with AI Coding Assistants.
Discovering Registered Routes – Run discovery first to build the route inventory that wp dbtk api edit annotates.
Profiling Endpoint Performance – After classifying a route’s safety level with --safety, use profiling to verify whether its runtime performance matches that classification.
How to Use WP Debug Toolkit with AI Coding Assistants – Covers how AI coding agents consume WPDT annotations via wp dbtk api bootstrap to understand your site’s API surface before writing integration code.
