> ## Documentation Index
> Fetch the complete documentation index at: https://help.verbosec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Starhost Deployments API: Create and Manage Deploys

> Use the Starhost API to create deployments, check their status, and trigger rollbacks. Automate your site publishing workflow programmatically.

The Starhost Deployments API lets you automate your entire site publishing workflow without touching the dashboard. You can trigger new deployments for a site, poll their status until they are live, and roll back to a previously published deployment if something goes wrong. All three operations are available as simple REST endpoints.

This page covers the following endpoints:

* `POST /starhost/deployments` — Create a new deployment
* `GET /starhost/deployments/{id}` — Get deployment status
* `POST /starhost/deployments/{id}/rollback` — Roll back to a previous deployment

***

## Create a deployment

Trigger a new deployment for one of your Starhost sites. You can optionally provide a `source_url` pointing to an archive of files that Starhost should fetch and deploy, or omit it to redeploy the site's most recently uploaded content.

**Endpoint**

```
POST https://api.verbosec.com/v1/starhost/deployments
```

### Request parameters

<ParamField body="site_id" type="string" required>
  The unique identifier of the Starhost site you want to deploy. You can find this in the Verbosec Cloud dashboard under your site's settings.
</ParamField>

<ParamField body="source_url" type="string">
  A publicly accessible URL pointing to a `.zip` or `.tar.gz` archive of the site files to deploy. If omitted, Starhost redeploys the site's most recent content.
</ParamField>

<ParamField body="environment" type="string">
  The target environment for this deployment. Accepted values are `"production"` and `"preview"`. Defaults to `"production"`. Use `"preview"` to test changes before going live.
</ParamField>

### Example request

```bash create-deployment.sh theme={null}
curl -X POST https://api.verbosec.com/v1/starhost/deployments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_abc001",
    "source_url": "https://example.com/builds/release-v2.zip",
    "environment": "production"
  }'
```

### Example response

```json create-deployment-response.json theme={null}
{
  "id": "dep_mno303",
  "status": "pending",
  "environment": "production",
  "site_id": "site_abc001",
  "created_at": "2025-01-15T11:00:00Z"
}
```

***

## Get deployment status

Retrieve the current status of a specific deployment. Poll this endpoint to track a deployment's progress from `pending` through to `published` or `failed`.

**Endpoint**

```
GET https://api.verbosec.com/v1/starhost/deployments/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the deployment, returned when you created it.
</ParamField>

### Example request

```bash get-deployment.sh theme={null}
curl -X GET https://api.verbosec.com/v1/starhost/deployments/dep_mno303 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json get-deployment-response.json theme={null}
{
  "id": "dep_mno303",
  "status": "published",
  "environment": "production",
  "url": "https://yoursite.mystarhost.com",
  "site_id": "site_abc001",
  "created_at": "2025-01-15T11:00:00Z"
}
```

### Deployment status values

<Accordion title="Status reference">
  | Status      | Description                                                                |
  | ----------- | -------------------------------------------------------------------------- |
  | `pending`   | The deployment has been queued and is waiting to start.                    |
  | `building`  | Starhost is currently building and processing the site files.              |
  | `published` | The deployment completed successfully and the site is live.                |
  | `failed`    | The deployment encountered an error. Check the dashboard logs for details. |
</Accordion>

***

## Roll back a deployment

Revert a site to the state of a previous successful deployment. This is useful when a newly published deployment introduces unexpected issues and you need to restore the last known good version quickly.

**Endpoint**

```
POST https://api.verbosec.com/v1/starhost/deployments/{id}/rollback
```

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the deployment you want to roll back to. This should be the ID of the previously published deployment you want to restore.
</ParamField>

### Example request

```bash rollback-deployment.sh theme={null}
curl -X POST https://api.verbosec.com/v1/starhost/deployments/dep_mno303/rollback \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json rollback-response.json theme={null}
{
  "id": "dep_mno303",
  "status": "rolled_back",
  "environment": "production",
  "site_id": "site_abc001",
  "rolled_back_at": "2025-01-15T11:15:00Z"
}
```

## Error responses

<Accordion title="400 Bad Request — Missing required field">
  Returned when a required body parameter such as `site_id` is missing from a create deployment request.

  ```json 400-response.json theme={null}
  {
    "error": {
      "code": "missing_required_field",
      "message": "The 'site_id' field is required."
    }
  }
  ```
</Accordion>

<Accordion title="404 Not Found — Deployment not found">
  Returned when the deployment `id` in the path does not match a deployment on your account.

  ```json 404-response.json theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "No deployment with the given ID was found on your account."
    }
  }
  ```
</Accordion>

<Accordion title="401 Unauthorized">
  Returned when your API key is missing or invalid. See the [Authentication guide](/api-reference/authentication) for help.

  ```json 401-response.json theme={null}
  {
    "error": {
      "code": "unauthorized",
      "message": "Invalid or missing API key."
    }
  }
  ```
</Accordion>