Skip to content
docs

/ api reference

Environments

An environment is where a project's deployments run: production exists from the start, others such as staging are added as needed. Each has its own current deployment, domains and variables.

Get an environment

get/api/v1/environments/{environmentId}

The environment, its current deployment (activeDeploymentId) and its variables. A secret variable never carries its value. suspendedReason is inactive or hibernated when the environment was paused for inactivity.

Requires Viewer key or above (workspace.read)

Parameters

  • environmentIdstringin pathrequired

Responses

  • 200The environment.
    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
  • 404No such environment in this workspace.
Request
curl "https://api.hiraiship.com/api/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

List a project's environments

get/api/v1/projects/{projectId}/environments

Oldest first, so the production environment (the project's productionEnvironmentId) comes first. Variables aren't included: get an environment for them.

Requires Viewer key or above (workspace.read)

Parameters

  • projectIdstringin pathrequired

Responses

  • 200The environments.
    Response fields
    • idstringrequired
    • projectIdstringrequired
    • namestringrequired
    • workerNamestringrequired
    • activeDeploymentIdstring | nullrequired
    • suspendedReason"inactive" | "hibernated" | nullrequired
    • suspendedAtstring | nullrequired
    • neverHibernatebooleanrequired
    • createdAtstringrequired
  • 404No such project in this workspace.
Request
curl "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Rename an environment

patch/api/v1/environments/{environmentId}

Changes the name only: the environment keeps its id, deployments, domains and variables.

Requires Developer key or above (project.update)

Parameters

  • environmentIdstringin pathrequired

Body

  • namestringrequired

    at most 19 characters · matches ^[a-z0-9-]+$

Responses

  • 200The updated environment.
    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
  • 404No such environment in this workspace.
  • 409The project already has an environment with that name.
Request
curl -X PATCH "https://api.hiraiship.com/api/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "preview"
  }'

Delete an environment

delete/api/v1/environments/{environmentId}

Takes the environment offline and deletes its domains, environment variables and queued builds. A project's production environment can't be deleted: delete the project instead.

Requires Developer key or above (project.update)

Parameters

  • environmentIdstringin pathrequired

Responses

  • 204Deleted.
  • 404No such environment in this workspace.
  • 409It's the project's production environment (code: production_environment).
Request
curl -X DELETE "https://api.hiraiship.com/api/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Create an environment

post/api/v1/projects/{projectId}/environments

Adds an environment, such as staging, next to the project's production one. It has no deployment and no domain until you deploy to it.

Requires Developer key or above (project.update)

Parameters

  • projectIdstringin pathrequired

Body

  • namestringrequired

    at most 19 characters · matches ^[a-z0-9-]+$

Responses

  • 201The created environment.
    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 project already has as many environments as your plan allows (quota: environments).

    Body: see Errors

  • 404No such project in this workspace.
  • 409The project already has an environment with that name.
Request
curl -X POST "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging"
  }'