---
title: "Create a site deployment"
url: https://docs.corefinity.com/api/reference/deployments/create-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_trigger.md
---
# Create a site deployment

Deploys the connected branch, or the branch or commit named in `ref`, and answers the new deployment with
`status` `queued`. Follow it with `GET /corestack/sites/{site}/deployments`. Your role needs the Create
Deployments permission.

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

- 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 runs commands on a live site. 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

- `binding_id` (integer or null): Another pipeline of the same site, by its id in the settings' `pipeline.bindings`. Refused `422` `feature_off` while choosing a pipeline is not on for your company.
- `ref` (string or null): A branch name or a 40-character commit SHA. Left out, the connected branch is deployed.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/deployments \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### PHP

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

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

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

### Node

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

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

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

## Responses

### 201 The new deployment, queued.

```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": null,
    "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": "queued",
    "status_label": "Queued",
    "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 site does not exist or is one you cannot deploy, `binding_id` is not a pipeline of this site, or deployments are not on for your company (`feature_off`).

```json
{
  "message": "Not found."
}
```

### 409 The site cannot deploy now. `reason` says why: `mode` (the site deploys by upload, or its files are not in the releases layout yet), `deployment_running`, `busy` (another change to the site is in progress), `restore_running`, `command_running`, `needs_reauth` (the repository's connection is gone or needs re-authorising), `site_content_off` (deploying site content is paused by Corefinity), `pipeline_untranslated`, `pipeline_review_pending` or `pipeline_switched_off` (the pipeline cannot run yet), `tunnels_switched_off` or `runtime_not_adopted` (the build cannot reach the site's services), `exec_unresolved` or `install_running` (contact support), `managed_elsewhere`, `deleted` or `removed`; `stale` means a deployment that was waiting could no longer be started: read the deployments again.

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

### 422 `ref` is not a branch name or a commit SHA, or a field is wrong (`invalid`); `binding_id` was sent while choosing a pipeline is not on for your company (`feature_off`, naming the field); no repository is connected (`no_repository`); or the git provider's address cannot be reached (a message only).

```json
{
  "code": "feature_off",
  "field": "binding_id",
  "message": "Choosing a pipeline binding is not available yet. Deploy without binding_id to use the repository's.",
  "reason": "feature_off"
}
```

### 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 A provider the request depends on did not answer. Nothing was changed; try again.

```json
{
  "message": "GitLab did not answer. Try again."
}
```

### 503 A deployment that was waiting could not be started. Try again in a moment.

```json
{
  "message": "The deployment could not be started. Try again in a moment."
}
```

## 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 |  | Check the id. You see only what your account can reach. |
| 409 | `busy` | Another operation is running on the site. Wait for it to finish. |
| 409 | `deployment_running` | A deployment of the environment is running, or a stopped one is still being cleaned up. Wait for it to finish, then try again. |
| 409 | `mode` | The site deploys another way than this needs, by upload where Git is needed or the reverse, or its files are not in the releases layout yet. Switch its deployment mode first. |
| 409 | `needs_reauth` | The repository's connection is gone or needs authorising again. Reconnect the repository. |
| 409 | `pipeline_untranslated` | This pipeline came from CoreStack Enterprise and has not been translated yet. Open the deployment settings to review it. |
| 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 | `feature_off` | This feature is not on for your organisation yet. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 422 | `no_repository` | The site has no repository connected. Connect one first. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |
| 503 |  | Try again shortly. |

## 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_trigger`](https://docs.corefinity.com/mcp/tools/corestack_deployment_trigger.md)
