---
title: "Copy Nginx rules between environments"
url: https://docs.corefinity.com/api/reference/site-settings/copy-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_copy.md
---
# Copy Nginx rules between environments

Copies the live rules of another environment of the same website onto this one, for example staging onto production, with the web root rewritten for this environment. `dry_run: true` previews the result and saves nothing. Otherwise the copy is saved like any change; copying onto a production environment needs `confirm_production: true`. Unless `hooks` says otherwise, every part is copied.

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

- 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`.
- `confirm_production` (boolean): Must be true to copy onto a production environment.
- `dry_run` (boolean): True previews the copy and saves nothing. Defaults to `false`.
- `from_site_id` (integer, required): The id of the environment to copy from: another environment of the same website.
- `hooks` (array of strings): The parts to copy. Left out, every part is copied. While path apps are on for your company, `hooks` left out copies the four hooks and the path apps too. Copying `path_apps` replaces this environment's whole list of path apps and gates with the other environment's, so an empty list there removes every one here. Send `[server, headers, php, http]` to copy the hooks and keep this environment's own path apps.
- `note` (string or null): Why, shown in the history.
- `test_id` (integer): A passed test run of the same content, from a check, so it is not run again.
- `version` (integer): The `version` from the last read of this environment. Required unless `dry_run` is true.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules/copy \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm_production": true,
    "from_site_id": 1043,
    "hooks": [
      "server",
      "headers",
      "php",
      "http"
    ],
    "note": "Promote staging",
    "version": 2
  }'
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules/copy', [
        'confirm_production' => true,
        'from_site_id' => 1043,
        'hooks' => [
            'server',
            'headers',
            'php',
            'http',
        ],
        'note' => 'Promote staging',
        'version' => 2,
    ]);

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules/copy', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    confirm_production: true,
    from_site_id: 1043,
    hooks: [
      'server',
      'headers',
      'php',
      'http',
    ],
    note: 'Promote staging',
    version: 2,
  }),
});

// 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.post(
    "https://manage.corefinity.com/api/corestack/sites/1042/nginx-rules/copy",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "confirm_production": True,
        "from_site_id": 1043,
        "hooks": [
            "server",
            "headers",
            "php",
            "http",
        ],
        "note": "Promote staging",
        "version": 2,
    },
)

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

## Responses

### 200 A preview (`state: dry_run`), or a copy of content this environment already has (`operation` and `revision` null).

```json
{
  "content": {
    "headers": null,
    "http": null,
    "php": null,
    "server": "location = /staging-only {\n    return 410;\n}\n"
  },
  "diagnostics": [],
  "diff": {
    "headers": null,
    "http": null,
    "php": null,
    "server": "--- this environment\n+++ copied\n@@ -1,3 +1,3 @@\n-location = /older {\n+location = /staging-only {\n     return 410;\n }\n"
  },
  "rewrites": [],
  "source_revision": {
    "id": 57,
    "number": 1,
    "site_id": 1043
  },
  "state": "dry_run"
}
```

### 201 The copy was saved as a new revision. Follow `operation`.

```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"
}
```

### 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. A copy onto production without `confirm_production: true` answers `confirm`.

```json
{
  "code": "confirm",
  "errors": {
    "confirm_production": [
      "Confirm that this changes production's nginx rules to copy onto production."
    ]
  },
  "field": "confirm_production",
  "message": "Confirm that this changes production's nginx rules to copy onto production.",
  "reason": "confirm"
}
```

### 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. |
| 422 | `confirm` | The action needs an explicit confirmation field. Ask the person, then send it. |
| 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_copy`](https://docs.corefinity.com/mcp/tools/corestack_nginx_rules_copy.md)
