Starhost Deployments API: Create and Manage Deploys

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

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.

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.

string

The target environment for this deployment. Accepted values are "production" and "preview". Defaults to "production". Use "preview" to test changes before going live.

Example request

create-deployment.sh

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

create-deployment-response.json

{
  "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

string

required

The unique identifier of the deployment, returned when you created it.

Example request

get-deployment.sh

curl -X GET https://api.verbosec.com/v1/starhost/deployments/dep_mno303 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

get-deployment-response.json

{
  "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

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.

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

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.

Example request

rollback-deployment.sh

curl -X POST https://api.verbosec.com/v1/starhost/deployments/dep_mno303/rollback \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

rollback-response.json

{
  "id": "dep_mno303",
  "status": "rolled_back",
  "environment": "production",
  "site_id": "site_abc001",
  "rolled_back_at": "2025-01-15T11:15:00Z"
}

Error responses

400 Bad Request — Missing required field

Returned when a required body parameter such as site_id is missing from a create deployment request.

400-response.json

{
  "error": {
    "code": "missing_required_field",
    "message": "The 'site_id' field is required."
  }
}

404 Not Found — Deployment not found

Returned when the deployment id in the path does not match a deployment on your account.

404-response.json

{
  "error": {
    "code": "not_found",
    "message": "No deployment with the given ID was found on your account."
  }
}

401 Unauthorized

Returned when your API key is missing or invalid. See the Authentication guide for help.

401-response.json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

Overview

Nexus AI API

Starhost API

Starhost Deployments API: Create and Manage Deploys

Create a deployment

Request parameters

Example request

Example response

Get deployment status

Path parameters

Example request

Example response

Deployment status values

Roll back a deployment

Path parameters

Example request

Example response

Error responses

​Create a deployment

​Request parameters

​Example request

​Example response

​Get deployment status

​Path parameters

​Example request

​Example response

​Deployment status values

​Roll back a deployment

​Path parameters

​Example request

​Example response

​Error responses

Create a deployment

Request parameters

Example request

Example response

Get deployment status

Path parameters

Example request

Example response

Deployment status values

Roll back a deployment

Path parameters

Example request

Example response

Error responses