---
title: "Replace a site's redirects"
url: https://docs.corefinity.com/api/reference/site-settings/replace-site-redirects
type: endpoint
last_updated: 2026-11-13
feature: redirects
related:
  - https://docs.corefinity.com/guides/sites/site-settings/redirects.md
  - https://docs.corefinity.com/mcp/tools/corestack_redirects_update.md
---
# Replace a site's redirects

Replaces the whole table: send the `version` from the last read and every rule to keep, in the order they
should be tried. A rule left out is removed.

```http
PUT /api/corestack/sites/{site}/redirects
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 10 a minute
- Long-running: answers with an operation to poll
- Try it in the console: off. It overwrites data that cannot be brought back. Copy the request and run it yourself when you are sure.

## Path parameters

- `site` (integer, required): The id of a site row. A website's production site and each of its environments has its own id. Digits only.

## Body

- `rules` (array of objects, required): Every rule to keep, in the order they are tried. At most 2,000 rules, of which at most 500 are `prefix` or `regex` rules.
  - `enabled` (boolean) Defaults to `true`.
  - `from` (string, required): The path to redirect, without a query string. For a `regex` rule, the pattern, at most 256 bytes.
  - `hosts` (array of strings or null): Limit the rule to some of the site's own domains. Null or left out on a new rule means every domain; left out on a saved rule keeps what it has.
  - `id` (integer or null): A saved rule's id, to keep it. Leave it out, or send null, for a new rule.
  - `keep_query` (boolean): Whether the request's query string is carried over to the target. Send `false` when the target has a query string of its own. Defaults to `true`.
  - `note` (string or null)
  - `status` (integer) One of `301`, `302`. Defaults to `301`.
  - `to` (string, required): A path or an `https://` address. A `regex` rule may use `$1` to `$9`. A target with a query string of its own is taken only with `keep_query` sent as `false`, and never on a `prefix` rule, where the rest of the path is added at its end. The limit is 2,000 bytes of the target as it is stored, not 2,000 characters as sent. The host is written in lower case and each character outside ASCII is percent-encoded, so `é` counts as six bytes (`%C3%A9`).
  - `type` (string, required) One of `exact`, `prefix`, `regex`.
- `version` (integer, required): The `version` of the last read. A save with an older version is refused `409` `stale`.

## Request

### curl

```bash
curl -X PUT https://manage.corefinity.com/api/corestack/sites/1042/redirects \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "enabled": true,
        "from": "/about-us.html",
        "id": 41,
        "keep_query": true,
        "note": "Old brochure page",
        "status": 301,
        "to": "/about",
        "type": "exact"
      },
      {
        "enabled": true,
        "from": "/blog",
        "hosts": [
          "www.harbourandfinch.example.com"
        ],
        "keep_query": true,
        "status": 301,
        "to": "/news",
        "type": "prefix"
      }
    ],
    "version": 12
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->put('https://manage.corefinity.com/api/corestack/sites/1042/redirects', [
        'rules' => [
            [
                'enabled' => true,
                'from' => '/about-us.html',
                'id' => 41,
                'keep_query' => true,
                'note' => 'Old brochure page',
                'status' => 301,
                'to' => '/about',
                'type' => 'exact',
            ],
            [
                'enabled' => true,
                'from' => '/blog',
                'hosts' => [
                    'www.harbourandfinch.example.com',
                ],
                'keep_query' => true,
                'status' => 301,
                'to' => '/news',
                'type' => 'prefix',
            ],
        ],
        'version' => 12,
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/redirects', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    rules: [
      {
        enabled: true,
        from: '/about-us.html',
        id: 41,
        keep_query: true,
        note: 'Old brochure page',
        status: 301,
        to: '/about',
        type: 'exact',
      },
      {
        enabled: true,
        from: '/blog',
        hosts: [
          'www.harbourandfinch.example.com',
        ],
        keep_query: true,
        status: 301,
        to: '/news',
        type: 'prefix',
      },
    ],
    version: 12,
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.put(
    "https://manage.corefinity.com/api/corestack/sites/1042/redirects",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "rules": [
            {
                "enabled": True,
                "from": "/about-us.html",
                "id": 41,
                "keep_query": True,
                "note": "Old brochure page",
                "status": 301,
                "to": "/about",
                "type": "exact",
            },
            {
                "enabled": True,
                "from": "/blog",
                "hosts": [
                    "www.harbourandfinch.example.com",
                ],
                "keep_query": True,
                "status": 301,
                "to": "/news",
                "type": "prefix",
            },
        ],
        "version": 12,
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The table sent is the table the site already has. Nothing was started and `operation` is null.

```json
{
  "operation": null,
  "redirects": {
    "apply": {
      "applied_at": "2026-11-02T15:41:09Z",
      "error": null,
      "operation": null,
      "state": "applied",
      "state_label": "Applied"
    },
    "available_hosts": [
      {
        "host": "harbourandfinch.example.com",
        "role": "primary"
      },
      {
        "host": "www.harbourandfinch.example.com",
        "role": "alias"
      }
    ],
    "formats": [
      "nginx",
      "apache",
      "csv"
    ],
    "host_scoping": true,
    "hosts": [
      "harbourandfinch.example.com",
      "www.harbourandfinch.example.com"
    ],
    "limits": {
      "from_max": 2000,
      "import_max_bytes": 524288,
      "regex_max": 256,
      "rules_max": 2000,
      "to_max": 2000
    },
    "rules": [],
    "version": 12
  }
}
```

### 201 The table was saved and is being applied. Follow `operation.id` until it completes.

```json
{
  "operation": {
    "applied_at": null,
    "can_retry": false,
    "cluster": {
      "id": 1017,
      "name": "Northwind UK 1"
    },
    "committed_at": "2026-11-06T09:16:42Z",
    "completed_at": null,
    "created_at": "2026-11-06T09:16:40Z",
    "environment": {
      "env_id": "rs-harbourandfinch-example-com",
      "hostname": "harbourandfinch-example-com.northwind.cfstack.example.net",
      "id": 1042,
      "name": "Production",
      "role": "production",
      "role_label": "Production",
      "slug": "production"
    },
    "error": null,
    "failure_reason": null,
    "from_version": null,
    "hot": true,
    "id": 142,
    "install": null,
    "label": "Picked up by the platform",
    "notes": [],
    "parent_operation_id": null,
    "requested_by": {
      "id": 2041,
      "name": "Eleanor Finch"
    },
    "reset_target": null,
    "result": null,
    "result_state": "none",
    "retried_by_operation_id": null,
    "retries_operation_id": null,
    "retry_requires": null,
    "revealed": null,
    "scope": "site",
    "site": {
      "domain": "harbourandfinch.example.com",
      "id": 1042
    },
    "status": "committed",
    "status_label": "Waiting for the platform",
    "step": "applied",
    "steps": [
      {
        "key": "saved",
        "label": "Saved",
        "state": "done"
      },
      {
        "key": "applied",
        "label": "Picked up by the platform",
        "state": "current"
      },
      {
        "key": "live",
        "label": "Live",
        "state": "todo"
      }
    ],
    "subject": null,
    "summary": "1 redirect rule",
    "to_version": null,
    "type": "redirects_change",
    "type_label": "Redirects"
  },
  "redirects": {
    "apply": {
      "applied_at": "2026-11-02T15:41:09Z",
      "error": null,
      "operation": {
        "id": 142,
        "scope": "site",
        "status": "committed",
        "status_label": "Waiting for the platform",
        "summary": "1 redirect rule",
        "to_version": null,
        "type": "redirects_change",
        "type_label": "Redirects"
      },
      "state": "applying",
      "state_label": "Applying"
    },
    "available_hosts": [
      {
        "host": "harbourandfinch.example.com",
        "role": "primary"
      },
      {
        "host": "www.harbourandfinch.example.com",
        "role": "alias"
      }
    ],
    "formats": [
      "nginx",
      "apache",
      "csv"
    ],
    "host_scoping": true,
    "hosts": [
      "harbourandfinch.example.com",
      "www.harbourandfinch.example.com"
    ],
    "limits": {
      "from_max": 2000,
      "import_max_bytes": 524288,
      "regex_max": 256,
      "rules_max": 2000,
      "to_max": 2000
    },
    "rules": [
      {
        "enabled": true,
        "from": "/about-us.html",
        "hosts": null,
        "id": 41,
        "keep_query": true,
        "note": "Old brochure page",
        "position": 1,
        "shadowed_by": null,
        "status": 301,
        "to": "/about",
        "type": "exact"
      }
    ],
    "version": 13
  }
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), your company requires two-factor authentication and you have not set it up, or your account has no company that can use Managed Clusters, for example because the company was closed (`company_unavailable` or `company_not_enabled`, whichever the route checks first). For Managed Clusters routes; any other route uses `ForbiddenScopeOrTwoFactor`.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The id does not exist or is something you cannot see, or the feature is not on for your company (`feature_off`).

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 409 The save was refused because of the site's state. `reason` says why: `stale` (the table changed since your read, or a rule `id` is not one of this site's), `busy` (another change is running), `restore_running`, `conflict` (another change to the platform landed first: send the request again), `cluster_paused` (Corefinity has paused changes for planned maintenance: the message says until when, if that is known), `deleted`, `provisioning`, `removed` or `managed_elsewhere`. A site whose files the Control Panel cannot write answers a sentence only, with no `reason`.

```json
{
  "code": "busy",
  "message": "Another change to this site is in progress. Wait for it to finish.",
  "reason": "busy"
}
```

### 422 A field is missing or wrong. A rule's fields are named by position, such as `rules.1.from`, and each message starts with the rule's number.

```json
{
  "code": "invalid",
  "errors": {
    "rules.1.status": [
      "Rule 2: The status is 301 or 302"
    ]
  },
  "field": "rules.1.status",
  "message": "Rule 2: The status is 301 or 302",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 502 The platform did not answer, or did not save the change. Nothing was changed; try again shortly. The answer is a sentence only, with no `reason`.

```json
{
  "message": "The platform returned an error (HTTP 503). Try again shortly."
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 409 | `busy` | Another operation is running on the site. Wait for it to finish. |
| 409 | `cluster_paused` | Changes on this site are paused for planned maintenance; please try again later. |
| 409 | `conflict` | The action conflicts with the object's present state. Read the message. |
| 409 | `deleted` | The site, environment or copy has been deleted, or is being deleted. Nothing can be changed on it. Restore a deleted site first if it can still be restored. |
| 409 | `managed_elsewhere` | This site is read-only here. Change it in the control panel that manages it. |
| 409 | `provisioning` | The site is still being created. Try again in a few minutes. |
| 409 | `removed` | The site or environment is being removed, or has been. Nothing can be changed on it. |
| 409 | `restore_running` | A restore is running on the site. Wait for it to finish, then try again. |
| 409 | `stale` | What you read has changed since you read it. Read it again, then send the change with its new version or quote. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |

## The same task elsewhere

- Guide: [Redirects](https://docs.corefinity.com/guides/sites/site-settings/redirects.md)
- MCP tool: [`corestack_redirects_update`](https://docs.corefinity.com/mcp/tools/corestack_redirects_update.md)
