Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

create_environment

Adds one place a project runs, so Heimdall can lay down the development, staging, UAT and production rows of a new project.

Add an environment to a project: project_id and name are required; kind is development by default or one of local, qa, staging, uat, preproduction, production, custom; component_id names the component it runs (omit it when it serves the whole project); url, api_url, admin_url, branch, hosting, region, auto_deploy, protected (a deployment then needs a promotion approval), health_check_url, current_version and notes (HTML) fill in the rest. The environment is written through the same action the Environments page and the intake wizard run, and environment.created goes out.

The health is recorded by monitoring and a freeze is a release manager's call in the application; neither is written here. A staff token with environment:create on the project is needed.

Requires ability

environment:create

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same action as

POST/v1/projects/{project}/environments

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires one event

environment.created

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

project_id*string

UUID of the project.

name*string

What the environment is called, such as Staging, 2 to 60 characters.

kindstringoptional

What the environment is for; development by default.

localdevelopmentqastaginguatpreproductionproductioncustom
component_idstringoptional

UUID of the component it runs; omit when it serves the whole project.

urlstringoptional

The address people open.

api_urlstringoptional

The address the API answers on.

admin_urlstringoptional

The address of the back office.

branchstringoptional

The branch deployed there.

hostingstringoptional

Where it runs, in words.

regionstringoptional

The region it runs in.

auto_deploybooleanoptional

Whether the pipeline deploys to it without a hand.

protectedbooleanoptional

Whether a deployment needs a promotion approval.

health_check_urlstringoptional

The address the scheduled health check calls.

current_versionstringoptional

The version running there, as last recorded.

notesstringoptional

Anything the team should know, as HTML.

What it returns

{  "data": {    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "component_id": "c0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",    "name": "Staging",    "kind": "staging",    "url": "https://staging.example.test",    "api_url": null,    "admin_url": null,    "branch": "develop",    "hosting": null,    "region": null,    "auto_deploy": true,    "protected": false,    "health": "unknown",    "health_check_url": null,    "last_checked_at": null,    "consecutive_failures": 0,    "current_version": null,    "frozen_until": null,    "frozen": false,    "notes": null,    "position": 2,    "created_at": "2026-10-28T09:20:00+00:00",    "updated_at": "2026-10-28T09:20:00+00:00"  }}

How it fails

VALIDATION_FAILED

name missing or outside 2 to 60 characters, a kind outside the list, an address that is not a URL, a component_id that is not the project's, or a name already used for the same component.

RESOURCE_NOT_FOUND

unknown project_id, or a project outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry environment:create.

TOKEN_MISSING_ABILITY

token lacks environment:create.

Related

list_environmentswhere the project runs today.update_environmentchange it later.create_componentthe component an environment runs.Environments APIthe same door over REST.

How is this guide?

Last updated on