Environments

Environments partition a Celigo account into separate, isolated spaces. Each environment has its own users, integrations, connections, and flows, functioning like independent accounts under a single license.

Requires the environments feature to be enabled. Every account with the feature starts with a Production environment that cannot be disabled.

Environment schema

List environments

get

/v1/environments

Returns all environments in the account. Requires the environments feature to be enabled -- accounts without it receive feature_not_enabled. Every account with the feature has at least one environment (Production). The full list is returned in a single unpaginated response.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

List of environments.

application/json

Environment object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the environment. Must be unique within the account.

Example: Sandbox

descriptionstring · nullableOptional

Free-text description of the environment's purpose. Null on environments provisioned automatically by the platform; descriptions set through the UI or API are strings. When writing, send a string or omit the field.

Example: Pre-production testing environment

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_envUserIdstring · objectIdRead-onlyRequired

Account user ID that owns this environment.

Example: 624cb0346309dc3a543733a2

enabledbooleanRead-onlyRequired

When true, the environment is currently enabled. Controlled via the toggle endpoint, not create/update.

isMigratedbooleanRead-onlyOptional

When true, the environment has been migrated from legacy sandbox. Present only on enterprise accounts.

204

No environments exist in the account

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/environments

GET /v1/environments HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "68f76c67f7876d161ffb9c52",
    "_envUserId": "624cb0346309dc3a543733a2",
    "name": "Production",
    "enabled": true,
    "lastModified": "2025-10-21T11:20:07.448Z",
    "createdAt": "2025-10-21T11:20:07.448Z"
  },
  {
    "_id": "69150a05578417f9fa40dbe4",
    "_envUserId": "69150a05578417f9fa40dbe6",
    "name": "Sandbox",
    "description": "Pre-production testing environment",
    "enabled": true,
    "lastModified": "2025-11-12T22:28:22.433Z",
    "createdAt": "2025-11-12T22:28:22.433Z"
  }
]

Create an environment

post

/v1/environments

Creates a new environment. The environment starts disabled; use the toggle endpoint to enable it. name is the only required field and must be unique within the account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Fields for creating or updating an environment.

namestring · min: 1 · max: 100Required

Display name for the environment. Must be unique within the account.

Example: Sandbox

descriptionstring · nullableOptional

Free-text description of the environment's purpose. Null on environments provisioned automatically by the platform; descriptions set through the UI or API are strings. When writing, send a string or omit the field.

Example: Pre-production testing environment

Responses

201

Environment created.

application/json

Environment object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the environment. Must be unique within the account.

Example: Sandbox

descriptionstring · nullableOptional

Free-text description of the environment's purpose. Null on environments provisioned automatically by the platform; descriptions set through the UI or API are strings. When writing, send a string or omit the field.

Example: Pre-production testing environment

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_envUserIdstring · objectIdRead-onlyRequired

Account user ID that owns this environment.

Example: 624cb0346309dc3a543733a2

enabledbooleanRead-onlyRequired

When true, the environment is currently enabled. Controlled via the toggle endpoint, not create/update.

isMigratedbooleanRead-onlyOptional

When true, the environment has been migrated from legacy sandbox. Present only on enterprise accounts.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/environments

POST /v1/environments HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "name": "Staging"
}

{
  "_id": "60a2c4e6f321d800129a1a3c",
  "_envUserId": "60a2c4e6f321d800129a1a3e",
  "name": "Staging",
  "description": "Pre-production testing environment",
  "enabled": false,
  "apim": {},
  "lastModified": "2025-08-10T14:22:33.000Z",
  "createdAt": "2025-08-10T14:22:33.000Z"
}

Get an environment

get

/v1/environments/{_id}

Retrieves a single environment by ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Environment ID.

Responses

200

Environment details.

application/json

Environment object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the environment. Must be unique within the account.

Example: Sandbox

descriptionstring · nullableOptional

Free-text description of the environment's purpose. Null on environments provisioned automatically by the platform; descriptions set through the UI or API are strings. When writing, send a string or omit the field.

Example: Pre-production testing environment

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_envUserIdstring · objectIdRead-onlyRequired

Account user ID that owns this environment.

Example: 624cb0346309dc3a543733a2

enabledbooleanRead-onlyRequired

When true, the environment is currently enabled. Controlled via the toggle endpoint, not create/update.

isMigratedbooleanRead-onlyOptional

When true, the environment has been migrated from legacy sandbox. Present only on enterprise accounts.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/environments/{_id}

GET /v1/environments/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "68f76c67f7876d161ffb9c52",
  "_envUserId": "624cb0346309dc3a543733a2",
  "name": "Production",
  "enabled": true,
  "lastModified": "2025-10-21T11:20:07.448Z",
  "createdAt": "2025-10-21T11:20:07.448Z"
}

Update an environment

put

/v1/environments/{_id}

Replaces an environment's mutable fields (name, description, apim). To enable or disable an environment, use the toggle endpoint instead.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Environment ID.

Body

Fields for creating or updating an environment.

namestring · min: 1 · max: 100Required

Display name for the environment. Must be unique within the account.

Example: Sandbox

descriptionstring · nullableOptional

Free-text description of the environment's purpose. Null on environments provisioned automatically by the platform; descriptions set through the UI or API are strings. When writing, send a string or omit the field.

Example: Pre-production testing environment

Responses

200

Updated environment.

application/json

Environment object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the environment. Must be unique within the account.

Example: Sandbox

descriptionstring · nullableOptional

Free-text description of the environment's purpose. Null on environments provisioned automatically by the platform; descriptions set through the UI or API are strings. When writing, send a string or omit the field.

Example: Pre-production testing environment

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_envUserIdstring · objectIdRead-onlyRequired

Account user ID that owns this environment.

Example: 624cb0346309dc3a543733a2

enabledbooleanRead-onlyRequired

When true, the environment is currently enabled. Controlled via the toggle endpoint, not create/update.

isMigratedbooleanRead-onlyOptional

When true, the environment has been migrated from legacy sandbox. Present only on enterprise accounts.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

put/v1/environments/{_id}

PUT /v1/environments/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "name": "Staging"
}

{
  "_id": "69150a05578417f9fa40dbe4",
  "_envUserId": "69150a05578417f9fa40dbe6",
  "name": "Sandbox",
  "description": "Updated environment description",
  "enabled": true,
  "apim": {
    "environmentId": "0b893522-51b3-482f-8935-2251b3b82f28",
    "environmentHRID": "sandbox",
    "groupId": "0b37df28-5543-40dc-b7df-28554310dc1b"
  },
  "createdAt": "2025-11-12T22:28:22.433Z",
  "lastModified": "2026-06-09T17:45:12.882Z"
}

Toggle an environment on or off

put

/v1/environments/{_id}/enable

Toggles the enabled state of an environment -- a disabled environment becomes enabled and vice versa. The Production environment cannot be disabled, and pending user invitations must be resolved before disabling any environment.

Requires a Content-Type: application/json header even though no request body is needed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Environment ID.

Responses

204

Environment state toggled.

No content

400

The Production environment cannot be disabled.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Pending user invitations must be resolved before disabling.

application/json

put/v1/environments/{_id}/enable

PUT /v1/environments/{_id}/enable HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content