/ api reference

Deployments

A deployment is one build of a project's source in an environment. It's queued while it waits for a build slot, pending while it builds, then success or failed. A successful one becomes the environment's current deployment; a rollback restores an earlier one.

get/deploymentsList deployments
get/deployments/{deploymentId}Get a deployment
get/deployments/{deploymentId}/stepsGet a deployment's build steps
get/deployments/{deploymentId}/streamStream a deployment's build
get/environments/{environmentId}/deploymentsList an environment's deployments
post/deployments/{deploymentId}/cancelCancel a queued deployment
post/deployments/{deploymentId}/redeployRedeploy
patch/environments/{environmentId}/active-deploymentRoll back
post/environments/{environmentId}/deploymentsCreate a deployment

List deployments

get/api/v1/deployments

Every deployment in the workspace, most recent first, each with its project's and environment's names.

Requires Viewer key or above (workspace.read)

Responses

200The deployments.
Response fields
- idstringrequired
- environmentIdstringrequired
- workerScriptRefstring | nullrequired
- assetsManifestRefstring | nullrequired
- status"queued" | "pending" | "success" | "failed"required
- triggerSource"cli" | "upload"required
- triggeredByUserIdstringrequired
- gitShastring | nullrequired
- gitRefstring | nullrequired
- framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
- commitMessagestring | nullrequired
- commitAuthorstring | nullrequired
- repoUrlstring | nullrequired
- deployedUrlstring | nullrequired
- errorstring | nullrequired
- createdAtstringrequired
- finishedAtstring | nullrequired
- dispatchStatus"not_applicable" | "pending" | "live" | "error"required
- dispatchErrorstring | nullrequired
- publishStartedAtstring | nullrequired
- publishPlannedboolean
- buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
- startedAtstring | nullrequired
- queuePositioninteger | null
- queueReason"plan_limit" | "capacity" | nullrequired
- projectIdstringrequired
- projectNamestringrequired
- projectSlugstringrequired
- environmentNamestringrequired
401No valid API key.

Request

curl "https://api.hiraiship.com/api/v1/deployments" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Get a deployment

get/api/v1/deployments/{deploymentId}

status is the build's (queued, pending, success, failed, with error set on failure); dispatchStatus is the publish's: live once the deployment serves traffic at deployedUrl.

Requires Viewer key or above (workspace.read)

Parameters

deploymentIdstringin pathrequired

Responses

200The deployment.
Response fields
- idstringrequired
- environmentIdstringrequired
- workerScriptRefstring | nullrequired
- assetsManifestRefstring | nullrequired
- status"queued" | "pending" | "success" | "failed"required
- triggerSource"cli" | "upload"required
- triggeredByUserIdstringrequired
- gitShastring | nullrequired
- gitRefstring | nullrequired
- framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
- commitMessagestring | nullrequired
- commitAuthorstring | nullrequired
- repoUrlstring | nullrequired
- deployedUrlstring | nullrequired
- errorstring | nullrequired
- createdAtstringrequired
- finishedAtstring | nullrequired
- dispatchStatus"not_applicable" | "pending" | "live" | "error"required
- dispatchErrorstring | nullrequired
- publishStartedAtstring | nullrequired
- publishPlannedboolean
- buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
- startedAtstring | nullrequired
- queuePositioninteger | null
- queueReason"plan_limit" | "capacity" | nullrequired
404No such deployment in this workspace.

Request

curl "https://api.hiraiship.com/api/v1/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Get a deployment's build steps

get/api/v1/deployments/{deploymentId}/steps

The four build steps (preparing, installing, building, packaging) with their status and timing: the same data the stream sends, for a client that polls instead.

Requires Viewer key or above (workspace.read)

Parameters

deploymentIdstringin pathrequired

Responses

200The steps, in order.
Response fields
- idstringrequired
- deploymentIdstringrequired
- step"preparing" | "installing" | "building" | "packaging"required
- status"pending" | "running" | "success" | "failed"required
- startedAtstring | nullrequired
- finishedAtstring | nullrequired
404No such deployment in this workspace.

Request

curl "https://api.hiraiship.com/api/v1/deployments/$DEPLOYMENT_ID/steps" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Stream a deployment's build

get/api/v1/deployments/{deploymentId}/stream

A Server-Sent Events stream (text/event-stream). While the deployment is queued it sends status events with its queuePosition and queueReason (plan_limit: your plan's concurrent builds are all running; capacity: no build machine is free yet). It replays every build step (step) and log line (log) recorded so far, then sends new ones as they happen, and closes after done once the deployment succeeds or fails. Each log event has an id: a connection that sends Last-Event-ID (as EventSource does when it reconnects) gets the steps again but only the log lines after that id. While nothing happens, the stream sends a : keepalive comment every 15 seconds.

Requires Viewer key or above (workspace.read)

Parameters

deploymentIdstringin pathrequired

Responses

200The event stream.
404No such deployment in this workspace.

Request

curl -N "https://api.hiraiship.com/api/v1/deployments/$DEPLOYMENT_ID/stream" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

List an environment's deployments

get/api/v1/environments/{environmentId}/deployments

Most recent first.

Requires Viewer key or above (workspace.read)

Parameters

environmentIdstringin pathrequired

Responses

200The environment's deployments.
Response fields
- idstringrequired
- environmentIdstringrequired
- workerScriptRefstring | nullrequired
- assetsManifestRefstring | nullrequired
- status"queued" | "pending" | "success" | "failed"required
- triggerSource"cli" | "upload"required
- triggeredByUserIdstringrequired
- gitShastring | nullrequired
- gitRefstring | nullrequired
- framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
- commitMessagestring | nullrequired
- commitAuthorstring | nullrequired
- repoUrlstring | nullrequired
- deployedUrlstring | nullrequired
- errorstring | nullrequired
- createdAtstringrequired
- finishedAtstring | nullrequired
- dispatchStatus"not_applicable" | "pending" | "live" | "error"required
- dispatchErrorstring | nullrequired
- publishStartedAtstring | nullrequired
- publishPlannedboolean
- buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
- startedAtstring | nullrequired
- queuePositioninteger | null
- queueReason"plan_limit" | "capacity" | nullrequired
404No such environment in this workspace.

Request

curl "https://api.hiraiship.com/api/v1/environments/$ENVIRONMENT_ID/deployments" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Cancel a queued deployment

post/api/v1/deployments/{deploymentId}/cancel

Only a deployment still queued can be cancelled: it becomes failed with error: "canceled". A build that has started runs to its end.

Requires Developer key or above (deployment.create)

Parameters

deploymentIdstringin pathrequired

Responses

200The cancelled deployment.
Response fields
- idstringrequired
- environmentIdstringrequired
- workerScriptRefstring | nullrequired
- assetsManifestRefstring | nullrequired
- status"queued" | "pending" | "success" | "failed"required
- triggerSource"cli" | "upload"required
- triggeredByUserIdstringrequired
- gitShastring | nullrequired
- gitRefstring | nullrequired
- framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
- commitMessagestring | nullrequired
- commitAuthorstring | nullrequired
- repoUrlstring | nullrequired
- deployedUrlstring | nullrequired
- errorstring | nullrequired
- createdAtstringrequired
- finishedAtstring | nullrequired
- dispatchStatus"not_applicable" | "pending" | "live" | "error"required
- dispatchErrorstring | nullrequired
- publishStartedAtstring | nullrequired
- publishPlannedboolean
- buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
- startedAtstring | nullrequired
- queuePositioninteger | null
- queueReason"plan_limit" | "capacity" | nullrequired
404No such deployment in this workspace.
409The deployment is no longer queued: its build started or finished.

Request

curl -X POST "https://api.hiraiship.com/api/v1/deployments/$DEPLOYMENT_ID/cancel" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Redeploy

post/api/v1/deployments/{deploymentId}/redeploy

Builds a GitHub-sourced deployment again, as a new deployment in the same environment, from the same commit (gitSha), whatever its branch points to now. To build the branch's latest commit, create a deployment with that ref instead. A deployment from a tarball has no stored source: deploy it again instead.

Requires Developer key or above (deployment.create)

Parameters

deploymentIdstringin pathrequired

Responses

202The new deployment, pending or queued.
Response fields
- idstringrequired
- environmentIdstringrequired
- workerScriptRefstring | nullrequired
- assetsManifestRefstring | nullrequired
- status"queued" | "pending" | "success" | "failed"required
- triggerSource"cli" | "upload"required
- triggeredByUserIdstringrequired
- gitShastring | nullrequired
- gitRefstring | nullrequired
- framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
- commitMessagestring | nullrequired
- commitAuthorstring | nullrequired
- repoUrlstring | nullrequired
- deployedUrlstring | nullrequired
- errorstring | nullrequired
- createdAtstringrequired
- finishedAtstring | nullrequired
- dispatchStatus"not_applicable" | "pending" | "live" | "error"required
- dispatchErrorstring | nullrequired
- publishStartedAtstring | nullrequired
- publishPlannedboolean
- buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
- startedAtstring | nullrequired
- queuePositioninteger | null
- queueReason"plan_limit" | "capacity" | nullrequired
400The deployment predates pinned commits and its ref no longer exists (code: unknown_ref).
402A plan limit refused the build (see Create a deployment).
Body: see Errors
404No such deployment in this workspace.
409The deployment has no GitHub source to build from.
501GitHub builds are not configured on this Hiraiship instance.

Request

curl -X POST "https://api.hiraiship.com/api/v1/deployments/$DEPLOYMENT_ID/redeploy" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Roll back

patch/api/v1/environments/{environmentId}/active-deployment

Makes an earlier successful deployment of the environment its current one again, without a build. The next deployment that succeeds becomes current as usual. Your plan keeps a limited number of recent successful deployments available for rollback.

Requires Developer key or above (deployment.create)

Parameters

environmentIdstringin pathrequired

Body

deploymentIdstringrequired
uuid

Responses

200The environment, with its new activeDeploymentId.
Response fields
- idstringrequired
- projectIdstringrequired
- namestringrequired
- workerNamestringrequired
- activeDeploymentIdstring | nullrequired
- suspendedReason"inactive" | "hibernated" | nullrequired
- suspendedAtstring | nullrequired
- neverHibernatebooleanrequired
- variablesobject[]required
  2 shapes
  One of:
  secret: false
  keystringrequired
  secretfalserequired
  valuestringrequired
  notestring | nullrequired
  updatedAtstringrequired
  secret: true
  keystringrequired
  secrettruerequired
  notestring | nullrequired
  updatedAtstringrequired
- createdAtstringrequired
402The environment is paused and every live environment your plan includes is in use (quota: active_environments).
Body: see Errors
404No such environment in this workspace, or the deployment is not one of its own.
409The deployment did not succeed, or is older than what your plan keeps for rollback.

Request

curl -X PATCH "https://api.hiraiship.com/api/v1/environments/$ENVIRONMENT_ID/active-deployment" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "b1c3e5a7-9d2f-4b6a-8c4e-1f3a5b7d9c64"
  }'

Create a deployment

post/api/v1/environments/{environmentId}/deployments

Builds and deploys your source to the environment. Send the source as sourceTarballBase64, a gzipped tar of the project directory, base64-encoded (a single top-level directory is unwrapped); this is what hiraiship deploy does. Or send installationId/owner/repo/ref to build a GitHub repository the workspace's GitHub App can read: ref (a branch, tag or commit) is resolved to its commit when you call, and that commit is what gets built, recorded as gitSha with its message and author. installCommand, buildCommand, outputDir and machine override the project's build settings for this deployment only. The build runs asynchronously: follow it with the stream or the steps route. status is pending while it builds, queued while it waits for a free build slot or a free build machine (queueReason says which), then success or failed; on success it becomes the environment's current deployment. The body is at most 40 MB.

Requires Developer key or above (deployment.create)

Parameters

environmentIdstringin pathrequired

Body

One of:

with sourceTarballBase64

sourceTarballBase64stringrequired
triggerSource"cli" | "upload"required
gitShastring
commitMessagestring
repoUrlstring
installCommandstring
buildCommandstring
outputDirstring
at most 500 characters
machine"standard-1" | "standard-2" | "standard-3" | "standard-4"

triggerSource: "cli"

installationIdstringrequired
ownerstringrequired
repostringrequired
refstringrequired
triggerSource"cli"required
installCommandstring
buildCommandstring
outputDirstring
at most 500 characters
machine"standard-1" | "standard-2" | "standard-3" | "standard-4"

Responses

202The build was accepted. The deployment is pending, or queued with its queuePosition and queueReason.
Response fields
- idstringrequired
- environmentIdstringrequired
- workerScriptRefstring | nullrequired
- assetsManifestRefstring | nullrequired
- status"queued" | "pending" | "success" | "failed"required
- triggerSource"cli" | "upload"required
- triggeredByUserIdstringrequired
- gitShastring | nullrequired
- gitRefstring | nullrequired
- framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
- commitMessagestring | nullrequired
- commitAuthorstring | nullrequired
- repoUrlstring | nullrequired
- deployedUrlstring | nullrequired
- errorstring | nullrequired
- createdAtstringrequired
- finishedAtstring | nullrequired
- dispatchStatus"not_applicable" | "pending" | "live" | "error"required
- dispatchErrorstring | nullrequired
- publishStartedAtstring | nullrequired
- publishPlannedboolean
- buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
- startedAtstring | nullrequired
- queuePositioninteger | null
- queueReason"plan_limit" | "capacity" | nullrequired
400The body matches none of the shapes, or mixes fields from several; or (GitHub source) the repository has no such ref (code: unknown_ref).
402A plan limit refused the build: build minutes, live environments, a full build queue (queued_builds), a build machine your plan doesn't allow (build_machine), or the spend limit.
Body: see Errors
403The project was disabled by Hiraiship (code: project_disabled).
404No such environment in this workspace, or (GitHub source) no such installation.
413The body is larger than 40 MB (code: payload_too_large).
501(GitHub source) GitHub builds are not configured on this Hiraiship instance.

Request

curl -X POST "https://api.hiraiship.com/api/v1/environments/$ENVIRONMENT_ID/deployments" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceTarballBase64": "H4sIAAAAAAAAA+3OMQ6CQBCF4a…",
    "triggerSource": "cli",
    "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
    "commitMessage": "Fix the pricing table"
  }'