Update Address - Plugixa Permalink Manager

PUT /plugixa-permalink-manager/v1/uris/{kind}/{id}

Set an item’s custom address, give it back its default address, or change its update mode.

Needs the plugixa_permalink_manager_edit capability, and the WordPress permission to edit that post or term. POST and PATCH are accepted too.

Note. Only what you send changes: leave out uri and the address stays, leave out mode and the mode stays. A body with none of uri, mode or reset changes nothing and answers 200 with meta.status set to unchanged.

Request

PUT https://your-site.example/wp-json/plugixa-permalink-manager/v1/uris/post/36

Path parameters

Request body

Content type: application/json

• mode: 2 wins over anything sent with it: the custom address is removed and the item goes back to its WordPress address.
• Setting a uri on an item in mode 2 switches it back to 0.
• Choosing -2, -1 or 1 for an item that has no stored address gives it its default address first.
• When the address changes, the old one keeps working as a redirect to the new one, and the change is written to the history.
• An address that is already taken is refused, never suffixed: the error carries a free suggestion. A reset takes the nearest free address instead.

Note. A reset is not checked against the exclusions. A typed uri on an excluded item, or on the front page, is refused with plugixa_permalink_manager_not_managed, but reset: true (or an empty uri) on the same item stores its default address.

Note. expected_modified_at is compared as text, character for character. Send back exactly the modified_at you read. An item with no stored address has modified_at: null: send null or leave the field out, because any string is then refused as stale.

{
  "uri": "shop/tents/skyline-2",
  "mode": -1,
  "expected_modified_at": "2026-11-12 09:30:00"
}

Responses

200 OK. data is the item after the change.

{
  "success": true,
  "data": {
    "kind": "post",
    "id": 36,
    "key": "post:36",
    "type": "product",
    "title": "Skyline 2 Tent",
    "slug": "skyline-2",
    "status": "publish",
    "uri": "shop/tents/skyline-2",
    "native_uri": "product/skyline-2",
    "is_custom": true,
    "mode": -1,
    "source": "manual",
    "lock": null,
    "permalink": "https://your-site.example/shop/tents/skyline-2/",
    "edit_url": "https://your-site.example/wp-admin/post.php?post=36&action=edit",
    "redirects_count": 1,
    "modified_at": "2026-11-12 10:15:00"
  },
  "meta": {
    "status": "saved"
  }
}

Errors

Plus the errors every endpoint can return.

Examples

curl -s -X PUT "https://your-site.example/wp-json/plugixa-permalink-manager/v1/uris/post/36" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"uri":"shop/tents/skyline-2","mode":-1,"expected_modified_at":"2026-11-12 09:30:00"}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-permalink-manager/v1/uris/post/36');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'admin:' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'uri'                  => 'shop/tents/skyline-2',
        'mode'                 => -1,
        'expected_modified_at' => '2026-11-12 09:30:00',
    ]),
]);
$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/uris/post/36', {
  method: 'PUT',
  headers: {
    'Authorization': auth,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    uri: 'shop/tents/skyline-2',
    mode: -1,
    expected_modified_at: '2026-11-12 09:30:00',
  }),
});
const { data } = await response.json();