Skip to main content
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

​
site_id
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.
​
source_url
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.
​
environment
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

​
id
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

StatusDescription
pendingThe deployment has been queued and is waiting to start.
buildingStarhost is currently building and processing the site files.
publishedThe deployment completed successfully and the site is live.
failedThe 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

​
id
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

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