REST API Support

Permalink Manager integrates directly with the WordPress REST API so you can read and edit custom permalinks & redirects programmatically, using WordPress's built-in endpoints.

The plugin registers a single permalink_manager field on every REST-enabled post type and taxonomy that Permalink Manager supports. Instead of a flat value, this field is an object that groups all of an element's Permalink Manager data in one place:

• GET requests:
  Retrieve the current custom permalink, redirects, external redirect, permastructure and auto-update value.
• POST/PUT requests:
  Set or update the custom permalink, redirects, external redirect and auto-update value.

The Field Schema

Getting Data

Make a standard GET request for a post, page, custom post type item or term. The permalink_manager object appears alongside the other fields in the JSON response.

The same applies to taxonomies. Term permalinks can be managed through the taxonomy endpoints in the same way.

GET: https://example.com/wp-json/wp/v2/<POST_TYPE>
GET: https://example.com/wp-json/wp/v2/<POST_TYPE>/<POST_ID>
GET: https://example.com/wp-json/wp/v2/<TAXONOMY>/
GET: https://example.com/wp-json/wp/v2/<TAXONOMY>/<TERM_ID>

Make a standard GET request for a post, page, custom post type item or term. The permalink_manager object appears alongside the other fields in the JSON response.

{
...
"permalink_manager": {
	"custom_permalink": "poland/wroclaw/jan-kowalski",
	"redirects": [
		"team/jan-kowalski",
		"authors/jan-kowalski"
	],
	"external_redirect": "",
	"permastructure": "%__country%/%__city%/%postname%",
	"auto_update": 0
}
...
}

Updating Data

Send the permalink_manager object in the body of a POST (create) or POST/PUT (update) request. Include only the properties you want to change. Any property you leave out will remain unchanged.

POST/PUT: https://example.com/wp-json/wp/v2/<POST_TYPE>/<POST_ID>
POST/PUT: https://example.com/wp-json/wp/v2/<TAXONOMY>/<TERM_ID>
{
...
"permalink_manager": {
	"custom_permalink": "cars/porsche-macan",
	"redirects": ["old-cars/macan"],
	"external_redirect": "https://loremipsum.com",
	"auto_update": 1
}
...
}

Custom Permalinks

The custom_permalink value should be a relative URI, not a full URL.

When the property is present but empty, Permalink Manager generates the default permalink based on the current Permastructure settings for the content type, regardless of whether you are creating or updating the record.

{
	"permalink_manager": {
		"custom_permalink": "new-custom-permalink" // 1. Set your own custom permalink
		"custom_permalink": "" // 2. Generate the new custom permalink
	}
}

Redirects

Redirects must be provided as an array of relative URIs. Duplicate redirects are removed automatically. To clear all additional redirects from the element, send an empty array.

{
	"permalink_manager": {
		"redirects": ["old-url/porsche-macan", "promo/macan-2024"]
	}
}

External redirect

The field accepts a full, valid URL. Use an empty string to clear the existing redirect.

{
	"permalink_manager": {
		"external_redirect": "https://another-domain.com/landing-page"
	}
}

Auto-update setting

Use this field to decide whether the custom permalink is regenerated when the element is saved. The value 0 follows the global setting. Any other accepted value overrides that setting for the current element.

{
	"permalink_manager": {
		"auto_update": 1
	}
}

FAQ

Do I need authentication to use the REST API endpoints?

Yes, updating custom URIs requires appropriate authentication and capabilities (typically editor or administrator roles).

Can I bulk update custom URIs through the REST API?

Currently, URIs must be updated individually through separate API requests.