Adobe Suite Admin operations API

openapi: 3.2.0
info:
  title: Sandbox Admin operations API
  description: "Adobe Experience Platform provides virtual sandbox environments which provide isolation and access control for Platform integrations. Use sandboxes for application lifecycle management, project management, and to build customized development ecosystems. Use sandbox tooling to seamlessly export and import sandbox configurations between sandboxes through the use of packages.\n- **Related documentation**:\n    - [Sandbox documentation](https://adobe.com/go/sandbox-overview-en)\n    - [Sandbox tooling documentation](http://adobe.com/go/sandbox-tooling-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n    - [Sandbox API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Sandbox%20API.postman_collection.json)\n    - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n    - [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n- **API paths**:\n    - PLATFORM Gateway URL: https://<span>platform.adobe.io/\n    - Base path for the sandbox API: /data/foundation/sandbox-management\n    - Example of a complete path: https://<span>platform.adobe.io/data/foundation/sandbox-management/sandboxes\n    - Base path for the sandbox tooling API: /data/foundation/exim\n    - Example of a complete path: https://<span>platform.adobe.io/data/foundation/exim/packages\n\n- **Required headers**:\n    - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n    - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n    - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n- **API error handling**:\n    - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors).        \n\n- **Filtering responses**:\n    - When performing listing (GET) requests in the Sandbox API, you can use query parameters to filter responses. Refer to the [Sandbox API queries](https://experienceleague.adobe.com/docs/experience-platform/sandbox/api/appendix.html#query) or the [Sandbox tooling API queries](http://experienceleague.adobe.com/en/docs/experience-platform/sandbox/sandbox-tooling-api/appendix) for a list of available queries."
  version: '1.0'
servers:
- url: https://{environment}.adobe.io/data/foundation
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Admin operations
  description: Sandbox operations available only to admins. Sandbox admin privileges are managed through the [Adobe Admin Console](https://adminconsole.adobe.com).
paths:
  /sandbox-management/sandboxTypes:
    get:
      tags:
      - Admin operations
      summary: List all supported sandbox types
      description: Use this endpoint to list your organization's supported sandbox types.
      operationId: listSandboxTypes
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      responses:
        '200':
          x-summary: Request successful.
          description: List of supported sandbox types was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSandboxTypes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandbox-management/sandboxes:
    get:
      tags:
      - Admin operations
      summary: List sandboxes
      description: Use this endpoint to list all the sandboxes that belong to your organization.
      operationId: listSandboxes
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-user-token'
      - $ref: '#/components/parameters/property'
      - $ref: '#/components/parameters/orderBy'
      responses:
        '200':
          x-summary: Request successful.
          description: All sandboxes were successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSandboxes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Admin operations
      summary: Create a sandbox
      description: Use this endpoint to create a new development or production sandbox.
      operationId: createSandbox
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-user-token'
      requestBody:
        description: JSON payload that outlines the details of the sandbox to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxPayload'
        required: true
      responses:
        '202':
          x-summary: Request accepted.
          description: The sandbox creation request was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSandboxResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandbox-management/sandboxes/{sandboxName}:
    get:
      tags:
      - Admin operations
      summary: Retrieve a sandbox
      description: Use this endpoint to retrieve a sandbox by name.
      operationId: retrieveSandbox
      parameters:
      - $ref: '#/components/parameters/sandboxName'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/x-user-token'
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          x-summary: Request successful.
          description: The sandbox was retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Admin operations
      summary: Reset a sandbox
      description: Use this endpoint to reset a sandbox by name.
      operationId: resetSandbox
      parameters:
      - $ref: '#/components/parameters/sandboxName'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-user-token'
      requestBody:
        description: Reset Sandbox
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetSandboxPayload'
        required: true
      responses:
        '202':
          x-summary: Request accepted.
          description: The sandbox creation request was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResetSandboxResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Admin operations
      summary: Delete a sandbox
      description: Use this endpoint to delete a sandbox by name.
      operationId: deleteSandbox
      parameters:
      - $ref: '#/components/parameters/sandboxName'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/x-user-token'
      responses:
        '202':
          x-summary: Request accepted.
          description: The sandbox deletion request was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
      - Admin operations
      summary: Update a sandbox
      description: Use this endpoint to update a sandbox by name.
      operationId: patchSandbox
      parameters:
      - $ref: '#/components/parameters/sandboxName'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-user-token'
      requestBody:
        description: JSON payload outlining the sandbox properties to be updated, along with their new values.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSandboxPayload'
        required: true
      responses:
        '200':
          x-summary: Request successful.
          description: The sandbox was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-codegen-request-body-name: action
components:
  schemas:
    ResetSandboxPayload:
      required:
      - action
      type: object
      properties:
        action:
          type: string
          example: reset
    Page.Links:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/Link'
        page:
          $ref: '#/components/schemas/Link'
    Page:
      type: object
      properties:
        limit:
          type: integer
          description: The maximum number of records to be returned in the response.
        count:
          type: integer
          description: The number of records returned in the response.
    PatchSandboxPayload:
      required:
      - title
      type: object
      properties:
        title:
          type: string
          example: My Sandbox
    CreateSandboxResponse:
      type: object
      description: A successful response returns the details of the newly created sandbox.
      properties:
        id:
          type: string
          description: Only visible to services. User responses will omit this attribute.
          example: 180e1210-d33a-11e9-8b17-d9e538719ued
        name:
          type: string
          description: The user-generated human-friendly name for the sandbox that will be used to access the sandbox in future requests. This value must be unique, and best practice is to make it as descriptive as possible. This value cannot contain any spaces or special characters.
          example: acme-sandbox
        title:
          type: string
          description: A human-readable name used for display purposes in the Platform user interface.
          example: ACME Sandbox
        state:
          type: string
          description: The state of the sandbox and has two values, `active` or `failed`. A sandbox becomes `active` once it has been successfully provisioned.
          example: creating
          enum:
          - creating
          - provisioning
          - active
          - cleaning
          - de-provisioning
          - deleted
          - failed
        type:
          type: string
          description: The type of sandbox to be created. For a non-production sandbox, this value must be `development`. For a production sandbox, this value must be `production`.
          example: development
          enum:
          - production
          - development
        region:
          type: string
          example: VA7
    ListSandboxTypes:
      type: object
      description: A successful response returns a list of sandbox types that are supported for your organization.
      properties:
        sandboxTypes:
          type: array
          items:
            $ref: '#/components/schemas/GetSandboxTypeResponse'
    CreateSandboxPayload:
      required:
      - name
      - title
      - type
      type: object
      properties:
        name:
          type: string
          example: my-dev-sandbox
        title:
          type: string
          example: My Dev Sandbox
        type:
          type: string
          example: development
          enum:
          - production
          - development
    RetrieveSandbox:
      type: object
      description: A successful response returns the details of the sandbox.
      properties:
        id:
          type: string
          description: Only visible to services. User responses will omit this attribute
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        name:
          type: string
          description: The name of the sandbox in which the operation will take place.
          example: acme-sandbox
        title:
          type: string
          description: The display name for the sandbox.
          example: ACME Sandbox
        state:
          type: string
          description: "The current processing state of the sandbox. The state of a sandbox can be any of the following:\n\n - **`creating`:** The sandbox has been created, but is still being provisioned by the system.\n - **`active`:** The sandbox is created and active.\n - **`deleted`:** The sandbox has been manually disabled.\n - **`failed`:** Due to an error, the sandbox was not able to be provisioned by the system and is disabled.\n"
          example: active
          enum:
          - creating
          - active
          - deleting
          - resetting
          - deleted
          - failed
        type:
          type: string
          description: The type of sandbox. The current supported sandbox types include `development` and `production`.
          example: development
          enum:
          - production
          - development
        region:
          type: string
          example: VA7
        isDefault:
          type: boolean
          description: A boolean property indicating whether this sandbox is the default production sandbox for the organization.
          example: true
        etag:
          type: integer
          description: An identifier for a specific version of the sandbox. `etag` is used for version control and caching efficiency.
          example: 1
        createdDate:
          type: string
          description: The date and time the sandbox was created.
          format: date-time
        lastModifiedDate:
          type: string
          description: The date and time the sandbox was last modified.
          format: date-time
        createdBy:
          type: string
          description: Details of the user who created the sandbox.
          example: ''
        modifiedBy:
          type: string
          description: Details of the user who last modified the sandbox.
          example: ''
        _system:
          $ref: '#/components/schemas/SandboxSystemObject'
    GetSandboxSystemResponse:
      type: object
      properties:
        id:
          type: string
          description: Only visible to services. User responses will omit this attribute
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        name:
          type: string
          description: The name of the sandbox in which the operation will take place.
          example: acme-sandbox
        title:
          type: string
          description: The display name for the sandbox.
          example: ACME Sandbox
        state:
          type: string
          description: "The current processing state of the sandbox. The state of a sandbox can be any of the following:\n\n - **`creating`:** The sandbox has been created, but is still being provisioned by the system.\n - **`active`:** The sandbox is created and active.\n - **`deleted`:** The sandbox has been manually disabled.\n - **`failed`:** Due to an error, the sandbox was not able to be provisioned by the system and is disabled.\n"
          example: active
          enum:
          - creating
          - active
          - deleting
          - resetting
          - deleted
          - failed
        type:
          type: string
          description: The type of sandbox. The supported sandbox types include `development` and `production`.
          example: development
          enum:
          - production
          - development
        region:
          type: string
          example: VA7
        isDefault:
          type: boolean
          description: A boolean property indicating whether this sandbox is the default production sandbox for the organization.
          example: true
        etag:
          type: integer
          description: An identifier for a specific version of the sandbox. `etag` is used for version control and caching efficiency.
          example: 1
        createdDate:
          type: string
          description: The date and time the sandbox was created.
          format: date-time
        lastModifiedDate:
          type: string
          description: The date and time the sandbox was last modified.
          format: date-time
        createdBy:
          type: string
          description: Details of the user who created the sandbox.
          example: ''
        modifiedBy:
          type: string
          description: Details of the user who last modified the sandbox.
          example: ''
        _system:
          $ref: '#/components/schemas/SandboxSystemObject'
    SandboxSystemObject:
      type: object
      description: Only visible to services. User responses will omit this attribute
      properties:
        state:
          type: string
          example: active
          enum:
          - creating
          - provisioning
          - active
          - cleaning
          - de-provisioning
          - deleted
          - failed
        createdDate:
          type: string
          description: The date and time the sandbox was created.
          format: date-time
        createdBy:
          type: string
          description: Details of the user who created the sandbox.
          example: ''
        lastModifiedDate:
          type: string
          description: The date and time the sandbox was last modified.
          format: date-time
        lastModifiedBy:
          type: string
          description: Details of the user who last modified the sandbox.
          example: ''
    DeleteSandbox:
      type: object
      description: A successful response returns the sandbox’s updated details, showing that its state is `deleted`.
      properties:
        id:
          type: string
          description: Only visible to services.
          example: 180e1210-d33a-11e9-8b17-d9e538719ued
        name:
          type: string
          description: The name of the sandbox you want to delete.
          example: acme-sandbox
        title:
          type: string
          description: The display name for the sandbox.
          example: ACME Sandbox
        state:
          type: string
          description: A successful deletion request for a sandbox updates the sandbox `state` to `deleted` and deactivates it. The default production sandbox cannot be deleted.
          example: cleaning
          enum:
          - creating
          - provisioning
          - active
          - cleaning
          - de-provisioning
          - deleted
          - failed
        type:
          type: string
          description: The type of sandbox being deleted. The current supported sandbox types include `development` and `production`.
          example: development
          enum:
          - production
          - development
        region:
          type: string
          example: VA7
    Link:
      type: object
      properties:
        href:
          type: string
        templated:
          type: boolean
    ListSandboxes:
      type: object
      description: A successful response returns a list of sandboxes belonging to your organization.
      properties:
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/GetSandboxSystemResponse'
        _page:
          $ref: '#/components/schemas/Page'
        _links:
          $ref: '#/components/schemas/Page.Links'
    ResetSandboxResponse:
      type: object
      description: A successful response returns the details of the updated sandbox.
      properties:
        id:
          type: string
          description: Unique identifier of the sandbox.
          example: d8184350-dbf5-11e9-875f-6bf1873fec16
        name:
          type: string
          description: Name of the sandbox.
          example: acme-dev
        title:
          type: string
          description: Display name or title of the sandbox.
          example: Acme Business Group dev
        state:
          type: string
          description: Current state of the sandbox.
          example: resetting
        type:
          type: string
          description: The sandbox type.
          example: development
        region:
          type: string
          description: Region code where the sandbox is hosted.
          example: VA7
    GetSandboxTypeResponse:
      type: object
      description: A successful response returns a list of sandbox types that are supported for your organization.
      properties:
        id:
          type: string
        title:
          type: string
  responses:
    InternalServerError:
      x-summary: Internal Server Error.
      description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
      content: {}
    Forbidden:
      x-summary: Forbidden
      description: You do not have the correct access permissions for this endpoint.
      content: {}
    BadRequest:
      x-summary: Bad Request
      description: Bad request. Check the syntax and payload information.
      content: {}
    Conflict:
      x-summary: Conflict.
      description: There was a conflict with the request. Double check for unique parameters.
      content: {}
  parameters:
    accept:
      name: Accept
      in: header
      description: The type of content that should be accepted. This value should be `application/json`.
      required: true
      schema:
        type: string
    property:
      name: property
      in: query
      description: 'Regex used to filter objects in the response. For example: "property=name==test."'
      schema:
        type: string
    authorization:
      name: Authorization
      in: header
      description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-user-token:
      name: x-user-token
      in: header
      description: The access token for the current user. If present, this token is used instead of the token in the Authorization header to lookup sandboxes.
      schema:
        type: string
    x-api-key:
      name: x-api-key
      in: header
      description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    sandboxName:
      name: sandboxName
      in: path
      description: The name of a sandbox, used as an identifier.
      required: true
      schema:
        type: string
    content-type:
      name: Content-Type
      in: header
      description: The type of content being sent in the body of the request. This value should be `application/json`.
      required: true
      schema:
        type: string
    orderBy:
      name: orderBy
      in: query
      description: Parameter used to identify a property to order listed responses by, including sort direction ("asc:" for ascending, "desc:" for descending). For example, "orderBy=asc:created,updated".
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
      required: true
      schema:
        type: string