1. Docs
  2. API Reference
  3. Replace an Environment's configuration from a JSON payload (destructive)

Replace an Environment's configuration from a JSON payload (destructive)

POST/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/import

Authentication

  • Bearer Token Authorization

    JWT access token

Path Parameters

Name Required Type Description
envSlugRequiredstring

Request body

  • format_versionnumber*
  • source_envany object*
  • access_modelenum: "flat" | "hierarchy"*
  • hierarchy_schemaany object*
  • permissionsany[]*
  • rolesany[]*
  • nodesany[]*
  • oauth_clientsany[]*
  • webhooksany[]*
  • metadataany object

Code samples

cURLJavaScriptPythonGo
curl -X POST "https://api.canopy.dev/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/value/import" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format_version": 1,
    "source_env": {},
    "access_model": "flat",
    "hierarchy_schema": {},
    "permissions": [
      null
    ],
    "roles": [
      null
    ],
    "nodes": [
      null
    ],
    "oauth_clients": [
      null
    ],
    "webhooks": [
      null
    ],
    "metadata": {}
  }'

Responses

200 Existing roles/permissions/nodes/OAuth clients/webhook subscriptions in the target env are deleted before the payload is applied. Operational state (identities, AppMemberships, assignments) survives or cascade-deletes via FK rules.
{
  "environment": {
    "id": "string",
    "application_id": "string",
    "name": "string",
    "slug": "string",
    "settings": {},
    "version": 0,
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z"
  },
  "oauth_client_rotations": [
    {
      "source_client_id": "string",
      "client_id": "string",
      "client_secret": "string"
    }
  ],
  "webhook_subscription_rotations": [
    {
      "id": "string",
      "url": "string",
      "secret": "string"
    }
  ]
}

application/json

  • environmentEnvironmentResponseDto*
  • oauth_client_rotationsOAuthClientRotationResponseDto[]*
  • webhook_subscription_rotationsWebhookSubscriptionRotationResponseDto[]*
400 Payload `format_version` is not supported by this server
401 Invalid or expired token
403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)
404 Environment not found in this Application

Returned object

On this page

Related endpoints

GETList Environments in an Application
POSTCreate a new Environment in an Application
GETGet a single Environment by slug
PATCHRename or re-slug an Environment
DELETEDelete an Environment
GETExport an Environment's configuration as JSON
GETGet the Environment's access model
PUTSwitch the Environment's access model
GETGet hierarchy schema for the active Environment
PATCHUpdate hierarchy schema for the active Environment
POSTRevert this Environment from hierarchy to flat