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

Saves the hooks sent in `content` at the `version` you read: a hook left out stays as it is, and `""` or `null` clears it. The change is checked, tested, applied and verified against the site's health check and verify paths, and one that fails is put back automatically: follow the operation in the answer. `verify_paths` may be sent without `content`.

```http
PUT /api/corestack/sites/{site}/nginx-rules
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 60 a minute; 20 a minute for each environment
- 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

- `apply` (string): When the change applies, if it needs a one-time update of the site's runtime first. Most changes apply at once whatever is sent. When a change that needs a maintenance window is applied. `now` applies it at once. `tonight` queues it for the site's next window. `window` means the same as `tonight`. An endpoint that takes `window` only while maintenance windows are on for your company says so, and refuses it `422` on `apply` otherwise. One of `now`, `tonight`, `window`. Defaults to `now`.
- `content` (object): The text of each hook sent. `server` goes inside the site's `server` block (locations, `return`, `rewrite`), `headers` sets response headers for every page, `php` holds settings for PHP requests and `http` sits at the `http` level, for example a `map`.
  - `headers` (string or null)
  - `http` (string or null)
  - `php` (string or null)
  - `server` (string or null)
- `note` (string or null): Why, shown in the history.
- `path_apps` (array of objects or null): The whole list of path apps and gates: `[]` removes every one, and leaving it out or sending null keeps the saved list. It may be sent without `content`. A list whose labels alone changed answers a `revision` with `operation: null`. Refused `invalid` while path apps are not on for your company.
  - `hosts` (array of strings): Some of the site's hostnames. Empty means all of them.
  - `id` (string): `a1`, `a2` and so on for a PHP app, static folder, other site or closed path; `g1`, `g2` and so on for a gate. Keep it when you change a record. A new record may leave it out: it is given the next free number.
  - `ips` (array of strings): Addresses or networks admitted, up to 64. A gate needs at least one. A network of /8 or wider, an address in a special-purpose range (the documentation ranges among them) and the platform's own ranges are refused.
  - `label` (string): A note. Empty when left out. Null is refused. Defaults to ``.
  - `limits` (object): For a PHP app.
    - `body_size_mb` (integer or null): The largest request body in MB, at most the site's upload size. Null, the default, leaves the site's own limit in force. Defaults to `null`.
    - `timeout` (integer): The PHP time limit in seconds. Defaults to `300`.
  - `links` (array of objects): For a PHP app or static folder on a folder path: up to 4 folders of the path app that are served from the site's shared folder, such as its uploads. Left out of a saved record when there are none.
    - `path` (string, required): A folder of the path app, relative to its path and ending in `/`, such as `wp-content/uploads/`. Two links cannot share a folder or lie inside one another, and PHP never runs under a link.
    - `target` (string, required): A folder below the site's shared folder that holds only public files, such as `shared/wp-content/uploads` on WordPress, with no trailing `/`. Refused: `shared` itself, a hidden folder (a name that starts with `.`), and a folder that is, is inside or contains one where the platform keeps code, logs or secrets, such as `shared/logs` or `shared/vendor`. The list differs per platform; on WordPress `shared/wp-content/uploads` and the folders below it are allowed although the rest of `shared/wp-content` is not.
  - `methods` (array of strings): The request methods admitted. `GET`, `HEAD` and `POST` when left out.
  - `php` (object): For a PHP app, which needs it.
    - `dir_index` (array of strings): Up to 8 folders whose `index.php` answers the folder, such as `wp-admin/`.
    - `entries` (array of strings, required): 1 to 32 PHP files that may run, relative to the path, such as `wp-login.php` or `wp-admin/*.php`. Every other PHP file under the path answers 404.
    - `router` (array of strings): Up to 4 folders passed to the app's `index.php`, such as `wp-json/`, or `/` for the whole app.
  - `prefix` (string, required): The path, such as `/wp/`. A PHP app or a gate can also name one file, and a gate `/` with `hosts`.
  - `preset` (string or null): The preset the record started from.
  - `proxy` (object): For another site on the path, which needs it.
    - `connect_timeout` (integer) Defaults to `5`.
    - `host_header` (string): `target` (the other site's own name), `visitor` (the name the visitor used) or another host name. Defaults to `target`.
    - `path` (string): `keep` sends the path as it is; `strip` leaves your path out. One of `keep`, `strip`. Defaults to `keep`.
    - `read_timeout` (integer) Defaults to `60`.
    - `share_cookies` (boolean): True sends your visitors' cookies and logins to the other site and lets it set cookies here. Defaults to `false`.
    - `url` (string, required): The other site: `https://`, a host name and optionally a port and a folder.
  - `rate` (object or null): A rate limit per visitor, for a PHP app, a static folder or another site. Send both fields, or leave `rate` out (or send null) for no limit. Left out of a saved record that has none.
    - `burst` (integer, required)
    - `per_second` (integer, required)
  - `root` (string): For a PHP app or static folder: `htdocs` or `shared`, optionally with sub-folders.
  - `static` (object): For a PHP app or static folder.
    - `types` (array of strings): Lower-case file extensions served from disk, up to 32. The policy's default list when left out. A static folder serves at least one.
  - `type` (string, required): A PHP app, a static folder, another site shown on the path (`proxy`), a closed path (`deny`) or a gate that admits only listed addresses. One of `php-app`, `static`, `proxy`, `deny`, `gate`.
- `test_id` (integer): A passed test run of the same content, from a check, so it is not run again.
- `verify_paths` (array of objects): Replaces the list of paths checked after every change. Sent on its own, only this list is saved.
  - `expect` (string): The answer expected: an exact status such as `403`, a class such as `2xx`, or `<500`. Defaults to `<500`.
  - `path` (string, required): A path on the site, starting with `/`.
- `version` (integer, required): The `version` from the last read.

## Request

### curl

```bash
curl -X PUT https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "WordPress admin under /wp/",
    "path_apps": [
      {
        "label": "Blog admin",
        "php": {
          "dir_index": [
            "wp-admin/"
          ],
          "entries": [
            "wp-admin/*.php",
            "wp-login.php"
          ],
          "router": [
            "wp-json/"
          ]
        },
        "prefix": "/wp/",
        "preset": "wordpress-admin",
        "root": "htdocs",
        "type": "php-app"
      }
    ],
    "version": 0
  }'
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->put('https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules', [
        'note' => 'WordPress admin under /wp/',
        'path_apps' => [
            [
                'label' => 'Blog admin',
                'php' => [
                    'dir_index' => [
                        'wp-admin/',
                    ],
                    'entries' => [
                        'wp-admin/*.php',
                        'wp-login.php',
                    ],
                    'router' => [
                        'wp-json/',
                    ],
                ],
                'prefix' => '/wp/',
                'preset' => 'wordpress-admin',
                'root' => 'htdocs',
                'type' => 'php-app',
            ],
        ],
        'version' => 0,
    ]);

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    note: 'WordPress admin under /wp/',
    path_apps: [
      {
        label: 'Blog admin',
        php: {
          dir_index: [
            'wp-admin/',
          ],
          entries: [
            'wp-admin/*.php',
            'wp-login.php',
          ],
          router: [
            'wp-json/',
          ],
        },
        prefix: '/wp/',
        preset: 'wordpress-admin',
        root: 'htdocs',
        type: 'php-app',
      },
    ],
    version: 0,
  }),
});

// 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/nginx-rules",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "note": "WordPress admin under /wp/",
        "path_apps": [
            {
                "label": "Blog admin",
                "php": {
                    "dir_index": [
                        "wp-admin/",
                    ],
                    "entries": [
                        "wp-admin/*.php",
                        "wp-login.php",
                    ],
                    "router": [
                        "wp-json/",
                    ],
                },
                "prefix": "/wp/",
                "preset": "wordpress-admin",
                "root": "htdocs",
                "type": "php-app",
            },
        ],
        "version": 0,
    },
)

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

## Responses

### 200 Nothing was started: the content is what the site already has (`operation` and `revision` are null), or only the verify paths were saved (`version` and `verify_paths`).

```json
{
  "operation": null,
  "revision": null
}
```

### 201 The change was saved. Follow `operation`; `revision` is the new revision. A change that waits for a window answers `queued: true` with nothing started.

```json
{
  "item_id": 77,
  "operation": null,
  "queued": true,
  "revision": null,
  "window_date": "2026-11-07"
}
```

### 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), or your company requires two-factor authentication and you have not set it up. For routes outside Managed Clusters.

```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 request was refused because of the site's state. `reason` says why: `stale` (the rules changed since your read: read them again and send the new `version`), `busy` or `change_pending` (another change is running or waiting), `restore_running`, `command_running` or `deployment_running` (a restore, a command or a deployment is running on the site), `conflict` (another change to the platform landed first: send the request again), `cluster_paused`, `cluster_not_ready` or `cluster_deleting` (the site's cluster cannot take changes at the moment), or `managed_elsewhere`.

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

### 413 A hook is over its size limit (`too_large`). `hook` names it and `max_bytes` is the limit.

```json
{
  "code": "too_large",
  "hook": "server",
  "max_bytes": 65536,
  "message": "The server hook is larger than 64 KB.",
  "reason": "too_large"
}
```

### 422 A field is missing or wrong (`invalid`, with `field` and `errors`), or the change was refused for a reason of its own: `nginx_invalid` (the rules break the policy; `diagnostics` lists each problem), `nginx_test_failed` (the rules failed the test on the site's own Nginx; `diagnostics`), `hook_unavailable` (the site cannot use that hook yet), `nginx_rules_locked` (Corefinity manages the site's Nginx rules), or `feature_off` when `apply` asks for a window and changes cannot wait for one at the moment.

```json
{
  "code": "feature_off",
  "message": "Queuing changes for the maintenance window is switched off at the moment",
  "reason": "feature_off"
}
```

### 429 Too many requests (`rate_limited`): the API's general limit, or the 20 saves a minute this environment takes from the API, the Control Panel and AI assistants together. Wait for `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many attempts on this environment. Try again shortly.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 500 The platform did not answer while the site's files were being read for the change, or the Control Panel may not write this site's files. Nothing was changed. When the platform is at fault, send the request again in a minute. The answer is a sentence only, with no `reason`.

```json
{
  "message": "Server Error"
}
```

### 502 The platform did not save the change. Nothing was changed. Send the request again in a minute. The answer is a sentence only, with no `reason`.

```json
{
  "message": "The change could not be saved. Contact support."
}
```

### 503 The rules sent are the saved ones, a change made outside the Control Panel is waiting, and the site's configuration cannot be read at the moment to put the saved rules back (`upstream_unavailable`). Try again in a few minutes.

```json
{
  "code": "upstream_unavailable",
  "message": "This environment's configuration repository can't be read right now. Try again in a few minutes.",
  "reason": "upstream_unavailable"
}
```

## 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 | `conflict` | The action conflicts with the object's present state. Read the message. |
| 409 | `managed_elsewhere` | This site is read-only here. Change it in the control panel that manages 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. |
| 413 | `too_large` | The upload is larger than the limit for one file. |
| 422 | `feature_off` | This feature is not on for your organisation yet. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 422 | `nginx_invalid` | These nginx rules cannot be saved: fix the errors shown. |
| 422 | `nginx_rules_locked` | Corefinity has locked this environment's nginx rules. Contact support to change them. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 500 |  | Read the message; it says what happened. |
| 502 |  | Read the message; it says what happened. |
| 503 | `upstream_unavailable` | A service the action depends on did not answer. Try again later. |

## The same task elsewhere

- Guide: [Web server rules](https://docs.corefinity.com/guides/sites/site-settings/web-server-rules.md)
- MCP tool: [`corestack_nginx_rules_update`](https://docs.corefinity.com/mcp/tools/corestack_nginx_rules_update.md)
