---
title: "Create or update a data plane"
method: PUT
path: "/organizations/{orgId}/environments/{envId}/dataplanes"
tags: ["Data Planes"]
---

# Create or update a data plane

`PUT /organizations/{orgId}/environments/{envId}/dataplanes`

## Request

- Base URL: `http://localhost:8093/automation`
- URL: `http://localhost:8093/automation/organizations/{orgId}/environments/{envId}/dataplanes`
- Auth: HTTP bearer

Idempotent create-or-update. Uses the id field in the body to identify the data plane within the environment. The type is immutable, and the organization and environment come from the path. An id: reference updates a data plane the Automation API does not manage, and cannot create one.

## Path parameters

- `orgId` string, required
- `envId` string, required

## Request body

- AutomationDataPlane: A data plane managed by the Automation API. Data planes store the runtime data of the domains bound to them. The id field is the stable, immutable identity used for idempotent create-or-update.
  - `configuration` object: Connection settings. Write-only: it can hold credentials.
  - `createdAt` string, date-time: Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.
  - `database` string: Name of the database the configuration points at. Read-only.
  - `environmentId` string: Identifier of the environment the data plane belongs to. Read-only.
  - `gatewayUrl` string: Base URL of the gateway serving the domains bound to this data plane. Must be an absolute http(s) URL with a lowercase scheme; omitted or empty leaves it unset.
  - `hosts` string[]: Hosts the configuration points at, as host:port. Read-only.
  - `id` string, required: Stable, immutable identifier for the data plane within its environment. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. This is the value a domain's dataPlaneId refers to.
  - `name` string: Human-readable name of the data plane.
  - `organizationId` string: Identifier of the organization the data plane belongs to. Read-only.
  - `type` string: Data plane plugin type identifier, matching the dataplane-am-<type> plugin. Immutable after creation.
  - `updatedAt` string, date-time: Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

## Response `200`

The created or updated data plane

- AutomationDataPlane: A data plane managed by the Automation API. Data planes store the runtime data of the domains bound to them. The id field is the stable, immutable identity used for idempotent create-or-update.
  - `configuration` object: Connection settings. Write-only: it can hold credentials.
  - `createdAt` string, date-time: Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.
  - `database` string: Name of the database the configuration points at. Read-only.
  - `environmentId` string: Identifier of the environment the data plane belongs to. Read-only.
  - `gatewayUrl` string: Base URL of the gateway serving the domains bound to this data plane. Must be an absolute http(s) URL with a lowercase scheme; omitted or empty leaves it unset.
  - `hosts` string[]: Hosts the configuration points at, as host:port. Read-only.
  - `id` string, required: Stable, immutable identifier for the data plane within its environment. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. This is the value a domain's dataPlaneId refers to.
  - `name` string: Human-readable name of the data plane.
  - `organizationId` string: Identifier of the organization the data plane belongs to. Read-only.
  - `type` string: Data plane plugin type identifier, matching the dataplane-am-<type> plugin. Immutable after creation.
  - `updatedAt` string, date-time: Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

## Other responses

- `400`: Invalid request: a missing required field, an unknown data plane type, a configuration the type's plugin rejects, an id reserved by the node's gravitee.yml, or an attempt to change an immutable field
- `403`: Permission denied
- `404`: An id: reference naming a data plane that does not exist in this environment
- `409`: The id is already taken by a data plane the Automation API does not manage

## Changes

- **2026-09-29** `821321fb3bcf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api/changes/organizations/:orgId/environments/:envId/dataplanes/put.md)

---

[API](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api.md) - [All operations](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api/revisions/b0b6bdfd65cb?raw)