Find and Replace - Plugixa Permalink Manager for WordPress

POST /plugixa-permalink-manager/v1/tools/find-replace

Start a job that replaces text inside stored custom addresses, optionally with a regular expression.

Needs Plugixa Permalink Manager Pro and the plugixa_permalink_manager_tools capability. On the free build this route answers 404 with plugixa_permalink_manager_unknown_tool.

Every tool is a preview unless you send "dry_run": false. Leaving dry_run out previews.

Starting it returns a job and changes nothing yet: call Tick Job until its status is no longer queued or running. See jobs.

Request

POST https://your-site.example/wp-json/plugixa-permalink-manager/v1/tools/find-replace

Request body

Content type: application/json

Field	Type	Required	Description
`dry_run`	`boolean`	No	Defaults to `true`.
`find`	`string`	Yes	The text to find, 1 to 200 characters. With `regex`, a pattern written without delimiters.
`replace`	`string`	No	What to put instead. Empty removes the match. With `regex`, `$1` and the like refer to groups.
`regex`	`boolean`	No	Treat `find` as a regular expression. Defaults to `false`.
`case_sensitive`	`boolean`	No	Defaults to `false`.
`kind`	`string`	No	`post` (the default) or `term`.
`type`	`string`	No	One post type or taxonomy. Empty covers every type of that kind.

Only stored custom addresses are searched. Each result goes through the same checks as a typed address: it is cleaned, refused if taken, recorded, and the old address keeps redirecting. Items in mode -2 or 2 are skipped. The run can be undone. See Find and replace.

{
  "dry_run": true,
  "find": "journal/",
  "replace": "blog/",
  "kind": "post",
  "type": "post"
}

Responses

`201` Created. `data` is the new job.

{
  "success": true,
  "data": {
    "id": 60,
    "type": "find-replace",
    "status": "queued",
    "dry_run": true,
    "params": {
      "find": "journal/",
      "replace": "blog/",
      "regex": false,
      "case_sensitive": false,
      "kind": "post",
      "type": "post"
    },
    "total": 24,
    "processed": 0,
    "changed": 0,
    "skipped": 0,
    "failed": 0,
    "samples": [],
    "undoable": false,
    "last_error": null,
    "created_at": "2026-11-12 09:30:00",
    "finished_at": null
  }
}

Field	Type	Meaning
`data.id`	`integer`	The job id: tick it with Tick Job
`data.type`	`string`	What the job does
`data.status`	`string`	`queued`, `running`, `done`, `failed` or `cancelled`
`data.dry_run`	`boolean`	`true` for a preview that changes nothing
`data.params`	`object`	The parameters as the job will use them, after cleaning
`data.total`	`integer`	Items the job expects to go through, counted when it was created
`data.processed`	`integer`	Items gone through so far
`data.changed`	`integer`	Items changed, or that a preview would change
`data.skipped`	`integer`	Items left alone
`data.failed`	`integer`	Items that could not be changed
`data.samples`	`array`	Up to 500 changed or failed items: `status`, `kind`, `id`, `title`, `before`, `after` and `message`
`data.undoable`	`boolean`	Whether Undo Job will accept it
`data.last_error`	`string\|null`	Why a `failed` job stopped
`data.created_at`	`string`	UTC datetime
`data.finished_at`	`string\|null`	UTC datetime, once it has stopped

Errors

Status	Code	When
`422`	`plugixa_permalink_manager_invalid`	`find` is empty or longer than 200 characters.
`422`	`plugixa_permalink_manager_bad_regex`	`regex` is on and `find` is not a valid regular expression.
`404`	`plugixa_permalink_manager_unknown_tool`	The site runs the free build.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-permalink-manager/v1/tools/find-replace" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"dry_run":true,"find":"journal/","replace":"blog/","kind":"post","type":"post"}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-permalink-manager/v1/tools/find-replace');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'admin:' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'dry_run' => true,
        'find'    => 'journal/',
        'replace' => 'blog/',
        'kind'    => 'post',
        'type'    => 'post',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const auth = 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`);
const response = await fetch('https://your-site.example/wp-json/plugixa-permalink-manager/v1/tools/find-replace', {
  method: 'POST',
  headers: {
    'Authorization': auth,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dry_run: true,
    find: 'journal/',
    replace: 'blog/',
    kind: 'post',
    type: 'post',
  }),
});
const { data } = await response.json();