---
title: "Cancel a site's deployment"
url: https://docs.corefinity.com/api/reference/deployments/cancel-site-deployment
type: endpoint
last_updated: 2026-11-13
feature: deployments
related:
  - https://docs.corefinity.com/guides/sites/code-and-deployments/connect-a-repository.md
  - https://docs.corefinity.com/mcp/tools/corestack_deployment_stop.md
---
# Cancel a site's deployment

Stops a deployment the settings mark `can_stop`. That is a running deployment, which is answered with
`status` `cancelled`: the site keeps, or goes back to, the release that was live. It is also a failed
deployment whose `crons_paused.state` is `database_failed`: its database stage failed after maintenance mode
went on and scheduled tasks and queues were paused, and no other deployment of the site is in progress.
Stopping that one builds nothing: it puts the earlier release back, switches maintenance mode off and resumes
the scheduled tasks and queues, and the deployment is answered still `failed`. Your role needs the Stop
Deployments permission. The request has no body.

```http
POST /api/corestack/sites/{site}/deployments/{deployment}/stop
```

- Scope: `write`
- Also needs `deploy` when Always
- Two-factor: required on your account (all)
- Rate limit: 10 a minute
- Try it in the console: off. It can need a stronger scope, depending on what you send. 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.
- `deployment` (integer, required): The id of a deployment of this site, as the settings list it. Digits only.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/deployments/5127/stop \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json"
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/sites/1042/deployments/5127/stop');

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/deployments/5127/stop', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
  },
});

// 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/deployments/5127/stop",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
)

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

## Responses

### 200 The deployment: `cancelled` when it was running, still `failed` when it was a failed deployment whose paused scheduled tasks and queues the stop resumes.

```json
{
  "deployment": {
    "attempt_id": 8035,
    "binding": {
      "id": 2211,
      "label": "Default pipeline"
    },
    "can_retry": false,
    "can_rollback": false,
    "can_stop": false,
    "crons_paused": null,
    "duration_seconds": null,
    "error": null,
    "finished_at": "2026-11-09T09:17:02Z",
    "git_author": null,
    "git_commit_url": null,
    "git_merge_request": null,
    "href": "/resources/deployments/5127",
    "id": 5127,
    "is_current": false,
    "maintenance_lift": null,
    "queued_at": "2026-11-09T09:16:40Z",
    "ref": {
      "branch": "main",
      "message": "Fix the basket count in the mobile header",
      "sha": "9730595c6ec7aa59b77674ada74e30d961b1817c",
      "short_sha": "9730595"
    },
    "release_id": null,
    "requested_by": {
      "id": 3301,
      "name": "Daniel Reyes"
    },
    "retry_warning": null,
    "stage": null,
    "stage_label": null,
    "started_at": null,
    "status": "cancelled",
    "status_label": "Cancelled",
    "stop_termination": null,
    "task": null,
    "trigger": "manual"
  }
}
```

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

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

### 403 The token lacks the `write` scope (`scope_required`; to deploy, stop, retry or roll back it also needs the `deploy` ability, and `scope` names which is missing), your company requires two-factor authentication and you have not set it up, or your role lacks the permission the action needs (`forbidden`, with the `permission`): Create Deployments to deploy, and Deploy Deployments as well to start a deployment that waits. A waiting deployment you may not start answers a message only.

```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 deployment is neither running nor a failed one the settings mark `can_stop` (`not_running`), or the site is managed by another control panel (`managed_elsewhere`).

```json
{
  "code": "not_running",
  "message": "This deployment is not running",
  "reason": "not_running"
}
```

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

## 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 | `forbidden` | The person is not allowed to do this. |
| 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 | `not_running` | The site, environment or deployment is not running. Read the message: where it can be started or will recover, start it or wait, then try again. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

- Guide: [Connect a repository](https://docs.corefinity.com/guides/sites/code-and-deployments/connect-a-repository.md)
- MCP tool: [`corestack_deployment_stop`](https://docs.corefinity.com/mcp/tools/corestack_deployment_stop.md)
