Sandbox management endpoint
Sandboxes in Adobe Experience Platform provide isolated development environments that allow you to test features, run experiments, and make custom configurations without impacting your production environment. The /sandboxes
endpoint in the Sandbox API allows you to programmatically manage sandboxes in Platform.
Getting started
The API endpoint used in this guide is part of the Sandbox API. Before continuing, please review the getting started guide for links to related documentation, a guide to reading the sample API calls in this document, and important information regarding required headers that are needed to successfully make calls to any Experience Platform API.
Retrieve a list of sandboxes list
You can list all sandboxes belonging to your organization (active or otherwise), by making a GET request to the /sandboxes
endpoint.
API format
GET /sandboxes?{QUERY_PARAMS}
{QUERY_PARAMS}
Request
curl -X GET \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes?&limit=4&offset=1 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns a list of sandboxes belonging to your organization, including details such as name
, title
, state
, and type
.
{
"sandboxes": [
{
"name": "prod",
"title": "Production",
"state": "active",
"type": "production",
"region": "VA7",
"isDefault": true,
"eTag": 2,
"createdDate": "2019-09-04 04:57:24",
"lastModifiedDate": "2019-09-04 04:57:24",
"createdBy": "{USER_ID}",
"modifiedBy": "{USER_ID}"
},
{
"name": "dev",
"title": "Development",
"state": "active",
"type": "development",
"region": "VA7",
"isDefault": false,
"eTag": 1,
"createdDate": "2019-09-03 22:27:48",
"lastModifiedDate": "2019-09-03 22:27:48",
"createdBy": "{USER_ID}",
"modifiedBy": "{USER_ID}"
},
{
"name": "stage",
"title": "Staging",
"state": "active",
"type": "development",
"region": "VA7",
"isDefault": false,
"eTag": 1,
"createdDate": "2019-09-03 22:27:48",
"lastModifiedDate": "2019-09-03 22:27:48",
"createdBy": "{USER_ID}",
"modifiedBy": "{USER_ID}"
},
{
"name": "dev-2",
"title": "Development 2",
"state": "creating",
"type": "development",
"region": "VA7",
"isDefault": false,
"eTag": 1,
"createdDate": "2019-09-07 10:16:02",
"lastModifiedDate": "2019-09-07 10:16:02",
"createdBy": "{USER_ID}",
"modifiedBy": "{USER_ID}"
}
],
"_page": {
"limit": 4,
"count": 4
},
"_links": {
"next": {
"href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes/?limit={limit}&offset={offset}",
"templated": true
},
"prev": {
"href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes?offset=0&limit=1",
"templated": null
},
"page": {
"href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes?offset=1&limit=1",
"templated": null
}
}
}
name
title
state
The current processing state of the sandbox. A sandbox’s state can be any of the following:
creating
: The sandbox has been created, but is still being provisioned by the system.active
: The sandbox is created and active.failed
: Due to an error, the sandbox was not able to be provisioned by the system and is disabled.deleted
: The sandbox has been manually disabled.
type
development
and production
.isDefault
eTag
Look up a sandbox lookup
You can look up an individual sandbox by making a GET request that includes the sandbox’s name
property in the request path.
API format
GET /sandboxes/{SANDBOX_NAME}
{SANDBOX_NAME}
name
property of the sandbox you want to look up.Request
The following request retrieves a sandbox named “dev-2”.
curl -X GET \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/dev-2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
Response
A successful response returns the details of the sandbox, including its name
, title
, state
, and type
.
{
"name": "dev-2",
"title": "Development 2",
"state": "creating",
"type": "development",
"region": "VA7",
"isDefault": false,
"eTag": 1,
"createdDate": "2019-09-07 10:16:02",
"lastModifiedDate": "2019-09-07 10:16:02",
"createdBy": "{USER_ID}",
"modifiedBy": "{USER_ID}"
}
name
title
state
The current processing state of the sandbox. A sandbox’s state can be any of the following:
- creating: The sandbox has been created, but is still being provisioned by the system.
- active: The sandbox is created and active.
- failed: Due to an error, the sandbox was not able to be provisioned by the system and is disabled.
- deleted: The sandbox has been manually disabled.
type
development
and production
.isDefault
eTag
Create a sandbox create
You can create a new development or production sandbox by making a POST request to the /sandboxes
endpoint.
Create a development sandbox
To create a development sandbox, you must provide a type
attribute with a value of development
in the request payload.
API format
POST /sandboxes
Request
The following request creates a new development sandbox named “acme-dev”.
curl -X POST \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'Content-Type: application/json' \
-d '{
"name": "acme-dev",
"title": "Acme Business Group dev",
"type": "development"
}'
name
title
type
development
.Response
A successful response returns the details of the newly created sandbox, showing that its state
is “creating”.
{
"name": "acme-dev",
"title": "Acme Business Group dev",
"state": "creating",
"type": "development",
"region": "VA7"
}
state
will become “active” or “failed”.Create a production sandbox
To create a production sandbox, you must provide a type
attribute with a value of production
in the request payload.
API format
POST /sandboxes
Request
The following request creates a new production sandbox named “acme”.
curl -X POST \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H `Accept: application/json` \
-H 'Content-Type: application/json' \
-d '{
"name": "acme",
"title": "Acme Business Group",
"type": "production"
}'
name
title
type
production
.Response
A successful response returns the details of the newly created sandbox, showing that its state
is “creating”.
{
"name": "acme",
"title": "Acme Business Group",
"state": "creating",
"type": "production",
"region": "VA7"
}
state
will become “active” or “failed”.Update a sandbox put
You can update one or more fields in a sandbox by making a PATCH request that includes the sandbox’s name
in the request path and the property to update in the request payload.
title
property can be updated.API format
PATCH /sandboxes/{SANDBOX_NAME}
{SANDBOX_NAME}
name
property of the sandbox you want to update.Request
The following request updates the title
property of the sandbox named “acme”.
curl -X PATCH \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'Content-Type: application/json'
-d '{
"title": "Acme Business Group prod"
}'
Response
A successful response returns HTTP status 200 (OK) with the details of the newly updated sandbox.
{
"name": "acme",
"title": "Acme Business Group prod",
"state": "active",
"type": "production",
"region": "VA7"
}
Reset a sandbox reset
Sandboxes have a “factory reset” feature which deletes all non-default resources from a sandbox. You can reset a sandbox by making a PUT request that includes the sandbox’s name
in the request path.
API format
PUT /sandboxes/{SANDBOX_NAME}
{SANDBOX_NAME}
name
property of the sandbox you want to reset.validationOnly
validationOnly=true
to check if the sandbox you are about to reset contains any Adobe Analytics, Adobe Audience Manager, or segment sharing data.Request
The following request resets a sandbox named “acme-dev”.
curl -X PUT \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme-dev?validationOnly=true \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'Content-Type: application/json'
-d '{
"action": "reset"
}'
action
Response
A successful response returns the details of the updated sandbox, showing that its state
is “resetting”.
{
"id": "d8184350-dbf5-11e9-875f-6bf1873fec16",
"name": "acme-dev",
"title": "Acme Business Group dev",
"state": "resetting",
"type": "development",
"region": "VA7"
}
The default production sandbox and any user-created production sandboxes cannot be reset if the identity graph hosted within it is also being used by Adobe Analytics for the Cross Device Analytics (CDA) feature, or if the identity graph hosted within it is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature.
The following is a list of possible exceptions that could prevent a sandbox from being reset:
{
"status": 400,
"title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Analytics for the Cross Device Analytics (CDA) feature.",
"type": "http://ns.adobe.com/aep/errors/SMS-2074-400"
},
{
"status": 400,
"title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature.",
"type": "http://ns.adobe.com/aep/errors/SMS-2075-400"
},
{
"status": 400,
"title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature, as well by Adobe Analytics for the Cross Device Analytics (CDA) feature.",
"type": "http://ns.adobe.com/aep/errors/SMS-2076-400"
},
{
"status": 400,
"title": "Warning: Sandbox `{SANDBOX_NAME}` is used for bi-directional segment sharing with Adobe Audience Manager or Audience Core Service.",
"type": "http://ns.adobe.com/aep/errors/SMS-2077-400"
}
You can proceed to reset a production sandbox that is used for bi-directional segment sharing with Audience Manager or Audience Core Service by adding the ignoreWarnings
parameter to your request.
API format
PUT /sandboxes/{SANDBOX_NAME}?ignoreWarnings=true
{SANDBOX_NAME}
name
property of the sandbox you want to reset.ignoreWarnings
Request
The following request resets a production sandbox named “acme”.
curl -X PUT \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme?ignoreWarnings=true \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'Content-Type: application/json'
-d '{
"action": "reset"
}'
Response
A successful response returns the details of the updated sandbox, showing that its state
is “resetting”.
{
"id": "d8184350-dbf5-11e9-875f-6bf1873fec16",
"name": "acme",
"title": "Acme Business Group prod",
"state": "resetting",
"type": "production",
"region": "VA7"
}
Delete a sandbox delete
You can delete a sandbox by making a DELETE request that includes the sandbox’s name
in the request path.
status
property to “deleted” and deactivates it. GET requests can still retrieve sandbox’s details after it has been deleted.API format
DELETE /sandboxes/{SANDBOX_NAME}
{SANDBOX_NAME}
name
of the sandbox you want to delete.validationOnly
validationOnly=true
to check if the sandbox you are about to reset contains any Adobe Analytics, Adobe Audience Manager, or segment sharing data.ignoreWarnings
Request
The following request deletes a production sandbox named “acme”.
curl -X DELETE \
https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme?ignoreWarnings=true \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}'
Response
A successful response returns the sandbox’s updated details, showing that its state
is “deleted”.
{
"name": "acme",
"title": "Acme Business Group prod",
"state": "deleted",
"type": "development",
"region": "VA7"
}