Back to top

Bloomreach Cloud API

API that drives the Bloomreach Cloud platform

Resource Group

Authentication

All authentication related endpoints

Login
POST/v3/authn/access_token

Create a JWT access token from the submitted credentials.

Token lifetimes:

  • The access token is valid for 10 minutes.

  • The refresh token is valid for 24 hours.

Example URI

POST /v3/authn/access_token
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "username": [your-username],
    "password": [your-password]
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "token_type": "bearer",
    "access_token": [jwt-token]
    "refresh_token": [refresh-token]
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "error_code": "AuthenticationFailed",
    "error_detail": [detail message]
}

Validate access token
GET/v3/authn/verify_token

Example URI

GET /v3/authn/verify_token
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: bearer 5262d64b892e8d4341000001
Response  200
HideShow
Headers
X-User-Id: [ user-id ]
X-User-Role: [ user-role ]
Response  401

Generate new access token from refresh token
POST/v3/authn/refresh_token

Example URI

POST /v3/authn/refresh_token
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "grant_type": "refresh_token",
    "refresh_token": [your-refresh-token]
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "token_type": "bearer",
    "access_token": [jwt-token]
}
Response  401

Delete refresh token
DELETE/v3/authn/refresh_token

Example URI

DELETE /v3/authn/refresh_token
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "grant_type": "refresh_token",
    "refresh_token": [your-refresh-token]
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

Logout
POST/v3/authn/logout

Logout user by invalidating all user’s access tokens

Example URI

POST /v3/authn/logout
Request
HideShow
Headers
Authorization: [ access token ]
Response  200
Response  401

Distributions

Handles the distribution file operations

List distributions
GET/v3/distributions

List distribution files

Example URI

GET /v3/distributions
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "offset": 0,
  "max": 100,
  "count": 6,
  "more": false,
  "total": 6,
  "items": [
    {
      "id": "4B36A01A8EBA74B7",
      "name": "cms-4.1.0-distribution.tar.gz",
      "createdAt": "2017-12-07T15:12:35+00:00",
      "createdBy": "john.doe@bloomreach.com",
      "modifiedAt": "2017-12-07T15:12:35+00:00",
      "modifiedBy": "john.doe@bloomreach.com",
    }
  ]
}

Upload distribution
POST/v3/distributions

Upload a distribution file. Add query parameter replace=true to replace an already uploaded distribution with the same name. This avoids appending a unique serial number to the file name.

Example URI

POST /v3/distributions
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Content-type: [ multipart/form-data ]
Body
dist_file: [ file path location of the distribution file ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "4B36A01A8EBA74B7",
  "distributionName": "dist_file",
  "createdBy": "john.doe@bloomreach.com",
  "createdAt": "2018-12-07T15:12:35+00:00",
  "modifiedAt": "",
  "modifiedBy": "",
  "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
Response  400

Distribution Info
GET/v3/distributions/{id}

Retrieve distribution file information. The modifiedXx fields are updated when the file is renamed.

Example URI

GET /v3/distributions/id
URI Parameters
HideShow
id
string (required) 

Distribution file id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "E2E3927146F011A3",
  "name": "cms-5.2-tar.gz",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "john.doe@bloomreach.com",
  "modifiedAt": "2017-15-07T15:13:45+00:00",
  "modifiedBy": "marry.doe@bloomreach.com",
  "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}

Rename distribution
PATCH/v3/distributions/{id}

Rename a distribution file. The modifiedXx fields are updated when the file is renamed.

Example URI

PATCH /v3/distributions/id
URI Parameters
HideShow
id
string (required) 

Distribution file id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "name": "new_distribution_file_name.tgz"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "E2E3927146F011A3",
  "name": "new_distribution_file_name.tgz",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "john@bloomreach.com",
  "modifiedAt": "2017-12-07T15:12:35+00:00",
  "modifiedBy": "marry@bloomreach.com",
  "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}

Delete a distribution
DELETE/v3/distributions/{id}

Delete a distribution file

Example URI

DELETE /v3/distributions/id
URI Parameters
HideShow
id
string (required) 

Distribution file id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
true

AppConfigFiles

An appConfigFile can be used as a configuration file for a distribution per environment. Note that it is not possible to view or download an appConfigFile for security reasons. So it is recommended to store configuration files in a secrets manager and/or put them under version control depending on the sensitivity of the content. Use the md5 hash to check the uploaded file against the local file. Since a cms deploy is tight to a distribution and its appConfigFiles, their file names need to be unique. We recommend semantic versioning for the appConfigFile names to ensure uniqueness. See the deploy end point for more information.

App config files are not allowed to contain a key javax.net.truststore.

List appConfigFiles
GET/v3/appconfigfiles

List appConfigFiles

Example URI

GET /v3/appconfigfiles
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  [
    {
      "id": "4B36A01A8EBA74B7",
      "name": "cms-4.1.0-appConfigFile.tar.gz",
      "createdAt": "2017-12-07T15:12:35+00:00",
      "createdBy": "john.doe@bloomreach.com",
      "modifiedAt": "2017-12-07T15:12:35+00:00",
      "modifiedBy": "john.doe@bloomreach.com",
      "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
    }
  ]
}
Response  400

Upload appConfigFile
POST/v3/appconfigfiles

Upload an appConfigFile file.

Example URI

POST /v3/appconfigfiles
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Content-type: [ multipart/form-data ]
Body
appconfigfile: [ file path location of the appConfigFile ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "4B36A01A8EBA74B7",
  "name": "license.properties",
  "createdBy": "john.doe@bloomreach.com",
  "createdAt": "2018-12-07T15:12:35+00:00",
  "modifiedAt": "",
  "modifiedBy": "",
  "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
Response  400

AppConfigFile Info
GET/v3/appconfigfiles/{id}

Retrieve appConfigFile file information. The modifiedXx fields are updated when the file is renamed.

Example URI

GET /v3/appconfigfiles/id
URI Parameters
HideShow
id
string (required) 

appConfigFile id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "4B36A01A8EBA74B7",
  "name": "license.properties",
  "createdBy": "john.doe@bloomreach.com",
  "createdAt": "2018-12-07T15:12:35+00:00",
  "modifiedAt": "",
  "modifiedBy": "",
  "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}

Rename appConfigFile
PATCH/v3/appconfigfiles/{id}

Rename an appConfigFile file. The modifiedXx fields are updated when the file is renamed.

Example URI

PATCH /v3/appconfigfiles/id
URI Parameters
HideShow
id
string (required) 

file id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "name": "newlicense.properties"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "E2E3927146F011A3",
  "name": "license.properties",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "john@bloomreach.com",
  "modifiedAt": "2017-12-07T15:12:35+00:00",
  "modifiedBy": "marry@bloomreach.com",
  "md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}

Delete appConfigFile
DELETE/v3/appconfigfiles/{id}

Delete appConfigFile file

Example URI

DELETE /v3/appconfigfiles/id
URI Parameters
HideShow
id
string (required) 

Distribution file id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
true

Domains

Domains are used to direct incoming traffic with a host that matches the domain name to a specified environment.

List domains
GET/v3/domains

Example URI

GET /v3/domains
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: [ access token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
    "name": "example.onehippo.io",
    "environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
    "createdAt": "2018-02-21T16:27:04+00:00",
    "createdBy": "hippo-ondemand@bloomreach.com",
    "updatedAt": "",
    "updatedBy": ""
  }
]

Get domain
GET/v3/domains/{id}

Example URI

GET /v3/domains/id
URI Parameters
HideShow
id
string (required) 

Domain id

Request
HideShow
Headers
Authorization: [ access token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
  "name": "example.onehippo.io",
  "environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
  "createdAt": "2018-02-21T16:27:04+00:00",
  "createdBy": "hippo-ondemand@bloomreach.com",
  "updatedAt": "",
  "updatedBy": ""
}

Get domain by name
GET/v3/domains/?name=domain_name

Example URI

GET /v3/domains/?name=domain_name
Request
HideShow
Headers
Authorization: [ access token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
  "name": "example.onehippo.io",
  "environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
  "createdAt": "2018-02-21T16:27:04+00:00",
  "createdBy": "hippo-ondemand@bloomreach.com",
  "updatedAt": "",
  "updatedBy": ""
}

Add a new domain
POST/v3/domains

Add a new domain. This will direct incoming traffic with a host that matches the domain name to the specified environment. The name field is required and must be unique to add a domain. The name must resememble a domain like for example customer.com or www.customer.com and the name must match with one of the subject alternative names (SAN) in the customers SSL certificate.
This SSL certificate must be configured in the stack by the BRC team. The environmentId is optional. This allows the domains to be specified upfront and used later on. Source path and Target path is optional. You can specify route path ( source path ) and target path ( context path)

Example URI

POST /v3/domains
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
    "name": "customer.com",
    "environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
    "sourcePath": "/",
    "targetPath": "/marketing",
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
    "name": "example.onehippo.io",
    "environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
    "createdAt": "2018-02-21T16:27:04+00:00",
    "createdBy": "hippo-ondemand@bloomreach.com",
    "updatedAt": "",
    "updatedBy": "",
    "sourcePath": "/",
    "targetPath": "/marketing",
}

Update an existing domain
PUT/v3/domains/{id}

Update the fields ‘name’ and ‘environmentId’ of an existing domain by passing in the domain id on the path. See the section Add a new domain on the requirements of the field name.

Example URI

PUT /v3/domains/id
URI Parameters
HideShow
id
string (required) 

Domain id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
    "name": "customer.com",
    "environmentId": """,
    "sourcePath": "/",
    "targetPath": "/marketing",
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
    "name": "example.onehippo.io",
    "environmentId": "",
    "createdAt": "2018-02-21T16:27:04+00:00",
    "createdBy": "hippo-ondemand@bloomreach.com",
    "updatedAt": "2018-03-11T13:22:04+00:00",
    "updatedBy": "hippo-ondemand@bloomreach.com"
    "sourcePath": "/",
    "targetPath": "/marketing",
}

Delete a domain
DELETE/v3/domains/

Example URI

DELETE /v3/domains/
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Body
{}

Environments

An environment is the place where a cms deployment lives. An environment requires a distribution to be deployed, optionally together with configuration files (called AppConfigFiles). The required resources like a database and Elasticsearch are provided by the environment.

List environments
GET/v3/environments

List all the environments

Example URI

GET /v3/environments
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "count": 4,
  "items": [
    {
      "id": "F84A857BEBD63BEF",
      "name": "samefile",
      "url": "samefile-testing.onehippo.io",
      "createdAt": "2017-12-07T15:12:35+00:00",
      "createdBy": "john@bloomreach.com",
      "deployedAt": "2017-12-07T15:14:42+00:00",
      "deployedBy": "marry@bloomreach.com",
      "distributionId": "81DF6E9CDCDA1813",
      "state": "active",
      "configuration": {
      "bootstrap": false,
      "virtualHosts": ["samefile-testing.onehippo.io"]
    }
  ],
  "max": -1,
  "more": false,
  "offset": 0,
  "total": 4
}

Create Environment
POST/v3/environments

Create a new environment

Example URI

POST /v3/environments
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "name": "new-environment-name"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "91f28c69-cfb2-486d-9308-14d80",
  "name": "mar06-qa01",
  "url": "new-env-name-testing.onehippo.io",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "hippo-ondemand@bloomreach.com",
  "deployedAt": "",
  "deployedBy": "",
  "distributionId": "",
  "state": "",
  "configuration": {
    "bootstrap": false,
    "virtualHosts": [
      "mar06-qa01-test.onehippo.io"
    ]
  }
}

Deploy distribution
PUT/v3/environments/{environmentId}/deploy

Deploy a distribution to an environment. This will start the CMS application within the distribution. During the deploy the state field has the value ‘deploying’. When the deploy is finished, the state is ‘active’.

The deploy payload has an optional field called ‘strategy’. The default strategy is “stopstart”
If its value is “stopstart” then this means that BRC will first stop the environment and then deploy the distribution. Especially when developing the project this is useful as the initialization is triggered by one container and the other containers need to wait.
If its value is “rollingupdate” then the BRC will instead upgrade each pod individually without stopping the environment. This means that there will not be any expected downtime, however this method can trigger backwards-compatibility issues.

The deploy payload supports cms application configuration files (optional). The role of the file can be either ‘file’ which means it will be copied to the cms container as is or the role can be ‘systemproperty’. In the latter case the file is treated as a Java system property file and its key value pairs will be passed on as Java system properties to the Java runtime. If the role is ‘file’ then it is also possible to specify a new filename for the file to be copied (optional). Since configuration file names need to be unique, this comes in very handy as the distribution can use the same filename to read a configuration file.

Example URI

PUT /v3/environments/environmentId/deploy
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
    "distributionId": "F8A4CFAF8740B2C8",
    "strategy" : "stopstart",

}
Response  202
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "91f28c69-cfb2-486d-9308-14d803",
  "name": "mar06-qa01",
  "url": "new-env-name-testing.onehippo.io",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "hippo-ondemand@bloomreach.com",
  "deployedAt": "2019-07-29T12:09:50+00:00",
  "deployedBy": "hippo-ondemand@bloomreach.com",
  "distributionId": "cd04e191-95d8-a7d5-07c0370e9d6c",
  "state": "deploying",
  "configuration": {
    "bootstrap": false,
    "virtualHosts": [
      "mar06-qa01-test.onehippo.io"
    ]
  }
}
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "distributionId": "F8A4CFAF8740B2C8",
  "appConfigFileRoles": [
    {
      "appConfigFileId": "4bbb1f9c-733f-4709-9ec3-3b7d3a40507c",
      "role": "file",
      "newFilename": "db.properties"
    },
    {
      "appConfigFileId": "533b4426-acb1-42dc-b062-d0e2f09d3f6e",
      "role": "systemproperty"
    }
  ]
}
Response  202
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
""

Get environment
GET/v3/environments/{environmentId}

Get environment information

Example URI

GET /v3/environments/environmentId
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "8CA48B97CD9369F3",
  "name": "mar06-qa02",
  "url": "mar06-qa02-testing.onehippo.io",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "joe@bloomreach.com",
  "deployedAt": "2017-12-07T15:14:42+00:00",
  "deployedBy": "wendy@bloomreach.com",
  "distributionId": "F8A4CFAF8740B2C8",
  "state": "active",
  "configuration": {
    "bootstrap": false,
    "virtualHosts": [
      "mar06-qa02-testing.onehippo.io"
    ]
  }
}

Get environment by name
GET/v3/environments?name={name}

Get environment information by passing in environment name as query parameter. Note that using the environment’s id in scripts is safer since environment names are not guaranteed to be unique in time.

Example URI

GET /v3/environments?name=name
URI Parameters
HideShow
name
string (required) 

name of the environment

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "8CA48B97CD9369F3",
  "name": "mar06-qa02",
  "url": "mar06-qa02-testing.onehippo.io",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "createdBy": "joe@bloomreach.com",
  "deployedAt": "2017-12-07T15:14:42+00:00",
  "deployedBy": "wendy@bloomreach.com",
  "distributionId": "F8A4CFAF8740B2C8",
  "state": "active",
  "configuration": {
    "bootstrap": false,
    "virtualHosts": [
      "mar06-qa02-testing.onehippo.io"
    ]
  }
}

Generate "Download token"
POST/v3/environments/:environmentId/logs/download-token

Generate download token for environment’s CMS logs (cms, site, catalina, etc).

Example URI

POST /v3/environments/:environmentId/logs/download-token
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "0cef47e192e0786eeb3e4d082dc2653247fd0f97adebd0b985ed0a4b0c44350f"
}
Response  401

Download Environment CMS logs
GET/v3/environments/logs/download/:download_log_token

Download CMS logs of an environment (cms, site, catalina, etc) using the download token.

Example URI

GET /v3/environments/logs/download/:download_log_token
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
accept-ranges: →bytes
content-disposition: →attachment; filename="cmslogs feb01qa01 2018-02-09 0910.tar.gz"
content-length: →13442
Response  404
HideShow
Body
{
  "error_code": "InvalidDownloadToken",
  "error_detail": "Download token '3b42c66d8b07a389dsafa1968ad8d7f25c1659b0a' not valid."
}

Delete an environment
DELETE/v3/environments/{environmentId}

Delete an existing environment

Example URI

DELETE /v3/environments/environmentId
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
null

Mark an environment as production environment (DEPRECATED)
PUT/v3/production/

This endpoint is deprecated. Please use /v3/production2.
An environment marked as production gets more resources from Bloomreach Cloud to handle more load. You can mark an environment as a production environment by calling this api endpoint and passing in the old production environment id (optional) and the new environment id. It is also possible to make all domain rules point from the old to the new environment by setting the body field ‘changeDomainRules’ to true.

The max number of production environments is by default 1. In case you want to change this contact Bloomreach. In case you exceed the max number of production environments a 404 with error MaxProdEnvsReached is returned. In case an environment is not a production environment (anymore), you can set ‘newProductionEnvironmentId’ to empty.

Example URI

PUT /v3/production/
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "currentProductionEnvironmentId": "8414f067-ba9e-9306-7c5c5cb3992f",
  "newProductionEnvironmentId": "45414f067-bc9e-1402-3c5cfab3432f",
  "changeDomainRules": "true"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
null

Mark an environment as a production environment
PUT/v3/production2/

An environment marked as production gets more resources from Bloomreach Cloud to handle more load.
You can mark an environment as a production environment by passing in the environment id.
If there is an existing production environment, it is possible to point domain rules from the existing production environment to the new production environment by setting the body field ‘changeDomainRules’ to true.

Only one environment can be marked as production. By setting a new environment as a production, the environment that used to be production will get scaled down and unmarked as production.
Passing the emtpy ‘newProductionEnvironmentId’ will unmark current production environment as such.
This API call is asynchronous, it scedules all the needed operations and returns a job token that has to be polled via the /v3/jobs endpoint.

Example URI

PUT /v3/production2/
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "newProductionEnvironmentId": "45414f067-bc9e-1402-3c5cfab3432f",
  "changeDomainRules": "true"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "JobID": "94029e739-ea88-1402-3c5cfab3444"
}

Poll job status
GET/v3/jobs/{jobID}

This endpoint is BETA, it’s semantics and/or path might change without notice.
Returns the status of an asynchronous job.
Status of a job can be either “started” or “done”. If job is “done”, the success is determined by the “Err” field.
If “Err” is empty, the job completed successfully, otherwise it will contain a description of a problem.

Example URI

GET /v3/jobs/jobID
URI Parameters
HideShow
jobID
string (required) 

ID of a job

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
null
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "Err": "",
  "Status": "started"
}

Protect the site and/or cms of an environment
PUT/v3/environments/{environmentId}/protect/

By enabling protection of the site and/or cms, the visitor needs to enter the environment name as username and the password as specified in the rest call. Protecting the site can be handy in case you do not want to expose the site to the public (yet). Protecting the CMS can be handy in case of maintenance. Only users with the password can access the CMS or the console. These users still need to login into the CMS or console as in normal conditions.

Example URI

PUT /v3/environments/environmentId/protect/
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "site": true,
  "sitepassword": "I love you",
  "cms": false,
  "cmspassword": "I love you more"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
null

Mark deployment as failed
PUT/v3/environments/{environmentId}/markasfailed/

When the CMS and/or site do not start up properly, you can mark the environment as failed. Make sure the CMS is not still indexing or busy with other intensive operations. To do so, consult the logs. After marking an environment as failed, you can (re)deploy or restore backup. It is adviced to restore a backup since the repository can be in an undetermined state.

Example URI

PUT /v3/environments/environmentId/markasfailed/
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
null

Heap dump

API that allows you to create and download a heap dump, also the heap dump automatically created by the JVM in case of OOME. Note that there can be at most one manual and one automated created heap dump. So to get a newly automated created heap dump, you need to delete the existing one. Only admin role can make dumps for production environment.

Create heap dump
POST/v3/environments/{environmentId}/heapdump

Use the Location header to download the dump file.

Example URI

POST /v3/environments/environmentId/heapdump
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  202
HideShow
Headers
Content-Type: application/json; charset=utf-8

Download heap dump created by API
GET/v3/environments/{environmentId}/heapdump/apicreated

By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.

Example URI

GET /v3/environments/environmentId/heapdump/apicreated
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

List heap dumps created through API and/or by JVM in case of out of memory exception
GET/v3/environments/{environmentId}/heapdump

By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.

Example URI

GET /v3/environments/environmentId/heapdump
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

Download created heap dump by JVM when out of memory exception occurs
GET/v3/environments/{environmentId}/heapdump/oomcreated

You need to delete the heap dump after download so a new heap dump can be created by the jvm when an oom occurs.

Example URI

GET /v3/environments/environmentId/heapdump/oomcreated
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

Delete an automatically created heap dump
DELETE/v3/environments/{environmentId}/heapdump/oomcreated

You can do the same for the manually created heap dumps by replacing /oomcreated with /apicreated in the path.

Example URI

DELETE /v3/environments/environmentId/heapdump/oomcreated
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Response  200

Thread dump

API that allows you to create and download thread dumps

Create thread dump
POST/v3/environments/{environmentId}/threaddump

Example URI

POST /v3/environments/environmentId/threaddump
URI Parameters
HideShow
environmentId
string (required) 

Environment id

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  202
HideShow
Headers
Content-Type: application/json; charset=utf-8

Download thread dump created through API
GET/v3/environments/threaddump/apicreated

By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.

Example URI

GET /v3/environments/threaddump/apicreated
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

List thread dump created by API
GET/v3/environments/threaddump

By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.

Example URI

GET /v3/environments/threaddump
Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

Custom Error Pages

API that sets custom error pages for specfic eror codes.

Set customErrorPage
POST/v3/customerrorpages/{errorcode}

Currently only http status / error code 503 is supported. In case you want to remove an existing custom error page, you can set ‘fileId’ to empty.

Example URI

POST /v3/customerrorpages/errorcode
URI Parameters
HideShow
errorcode
string (required) 

http status code, currently only 503 supported

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Body
{
    "fileId": [app config file id]
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8

Backup and Restore

API that drives backup and restore process across the BRC platform

List all backups
GET/v3/backups

Example URI

GET /v3/backups
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "id": "01b23258-eb79-41f0-8c3b-ad2a7d29b566",
    "environmentId": "cafebabe-1234",
    "createdBy": "user@bloomreach.com",
    "createdAt": "2017-12-07T15:12:35+00:00",
    "distributionId": "3791ED1FD651C039",
    "databases": [
      {
        "id": "011280fc-55da-4b52-8483-df7ef0164acd",
        "database": "green",
        "filePath": "/backups/environments/green/databases/green/abc123_green.gz"
      },
      {
        "id": "9807340d-d8b7-4477-96da-9ccf76c93d33",
        "database": "green_targeting",
        "filePath": "/backups/environments/green_/databases/green__targeting/92f4p5b9mr_green_targeting.gz"
      }
    ],
    "backupType": "Manual"
  },
  {
    "id": "f3412a37-2d65-4499-bdf9-5ec979ced6a9",
    "environmentId": "cafebabe-5678",
    "createdBy": "user@bloomreach.com",
    "createdAt": "2017-12-07T15:12:35+00:00",
    "distributionId": "",
    "databases": [
      {
        "id": "cdc004c2-8d06-4761-b67d-cbc9042ea04f",
        "database": "blue",
        "filePath": "/backups/environments/jan17qa01/databases/jan17qa01/j37o43hmi3_blue.gz"
      },
      {
        "id": "703123af-a265-4c96-b1e6-67393eb84e6e",
        "database": "blue_targeting",
        "filePath": "/backups/environments/blue/databases/blue_targeting/mookjrcnl1_blue_targeting.gz"
      }
    ],
    "backupType": "Manual"
  },
  {
    "id": "7dbabb2c-d4b6-4ca6-b5db-fe07bd6b4a36",
    "createdBy": "user@bloomreach.com",
    "createdAt": "2017-12-07T15:12:35+00:00",
    "backupType": "SharedDatastoreBackup"
  }
]

Get download link for repostitory database of backup
GET/v3/backups/{backupId}/repositorydownloadlink

Get a link to AWS S3 to download the repository database of the backup. The downloaded archive contains a MySQL dump of the repository. The link to s3 is valid for 15 minutes.

Example URI

GET /v3/backups/backupId/repositorydownloadlink
URI Parameters
HideShow
backupId
string (required) 

The id of backup that contains the repository to download

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Body
{
    "url":"https://backups-cust-onehippo-io.s3.eu-west-1.amazonaws.com/backups/environments/421f-....-1d6808/databases/421fd41f-4417-41d6-8be8-1719668d6808/ce9f76....6808.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIAZ..._request\u0026X-Amz-Date=20200527T110427Z\u0026X-Amz-Expires=604800\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=9ccc....c"}
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error_code": "ObjectNotFound",
  "error_uid": "54877c97-3fa1-4ea1-ae58-8bca1fe6c3e9",
  "error_detail": "Backup with id 'eb3b02f7-48b3-4298-82d23232543d51' is not found"
}

Create backup of environment's databases
POST/v3/backups

Example URI

POST /v3/backups
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
    "environmentId": [environment id],
    "backupType": Manual
}
Response  202
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "id": "f3e3b02a-f5b4-4357-8255-da1e4685e6c3",
    "environmentId": [environment id],
    "createdBy": "user@bloomreach.com",
    "createdAt": "2017-12-07T15:12:35+00:00",
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error_code": "InvalidParameters",
  "error_detail": "Empty environmentId"
}

Create backup of shared datastore table
POST/v3/backups/shareddatastore

Shared-datastore means that all blobs across environments are stored in the same database table. Reach out to Bloomreach Support to enable this feature. Backup records of this type cannot be restored, they are exclusively for download purposes (see repositorydownloadlink). Backups of shared datastore might take considerable amount of time to be created (hours). In order to check the status of the backup record created by this API endpoint, please supply the returned id to the /v3/backups/jobs/ API endpoint.

Example URI

POST /v3/backups/shareddatastore
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Response  202
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "f3e3b02a-f5b4-4357-8255-da1e4685e6c3",
  "environmentId": "",
  "createdBy": "user@bloomreach.com",
  "createdAt": "2017-12-07T15:12:35+00:00",
  "type": "SharedDatastoreBackup"
}

Restore a backup
PUT/v3/backups/{backupId}/restore

Only backup records of type ‘Manual’ or ‘StackSnapshot’ can be restored. Backup records of type ‘SharedDatastoreBackup’ cannot be restored, they are exclusivery for download purposes (see repositorydownloadlink).

Example URI

PUT /v3/backups/backupId/restore
URI Parameters
HideShow
backupId
string (required) 

The id of backup to restore

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Body
{
    "environmentId": [target environment id]
}
Response  202
HideShow
Body
Response contains the restoring job id.

    {
        "jobId": "f3e3b02a-f5b4-4357-1234-da1e46855678"
    }
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
        "error_code": "InvalidParameters",
        "error_detail": [detail message]
    }

Monitor a running job
GET/v3/backups/jobs/{jobId}

Example URI

GET /v3/backups/jobs/jobId
URI Parameters
HideShow
jobId
string (required) 

The id in the responses of the creating backup call or the restoring backup call

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "jobId": [monitored jobId],
  "status": "completed"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "jobId": [monitored jobId],
  "status": "running"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "jobId": [monitored jobId],
  "status": "error"
}

Delete backup
DELETE/v3/backups/{backupId}

Delete forever the manually created backup from the repository. System created backups cannot be deleted.

Example URI

DELETE /v3/backups/backupId
URI Parameters
HideShow
backupId
string (required) 

The id of backup to delete

Request
HideShow
Headers
Authorization: Bearer [ authentication token ]
Response  200
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "error_code": "InvalidParameters",
    "error_detail": [detail message]
}

Users

Listing users
GET/v3/users

Example URI

GET /v3/users
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: [ access token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "id": "bca4bc54-61c7-42ca-b6a5-0b04bd1823ec",
    "username": "user1@bloomreach.com",
    "role": "root",
    "active": true
  },
  {
    "id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
    "username": "user2@bloomreach.com",
    "role": "admin",
    "active": true
  }
]
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "error_code": "RetrieveUsersFailed",
    "error_detail": [detail message]
}

Get user detail
GET/v3/users/{username}

Example URI

GET /v3/users/username
URI Parameters
HideShow
username
string (required) 

Username to query

Request
HideShow
Headers
Authorization: [ access token ]
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
    "username": "exampleuser@bloomreach.com",
    "role": "user",
    "active": true,
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "error_code": "RetrieveUsersFailed",
    "error_detail": [detail message]
}

Add a new user
POST/v3/users

Add a new user. Username, password, role (user, admin or root) and active fields are required to add an user. The username must be a valid email address. The password must be at least 8 characters long and contain digit, lower and upper case characters.

Example URI

POST /v3/users
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
    "username": "exampleuser@bloomreach.com",
    "password": [super secret password],
    "role": "user",
    "active": "true",
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
  "username": "exampleuser@bloomreach.com",
  "role": "user",
  "active": true
}
Response  400

Update an existing user
PUT/v3/users/{username}

Update the fields ‘active’ and ‘role’ of an existing user by passing in the username on the path. Username cannot be changed. Admin or root role required to update an user

Example URI

PUT /v3/users/username
URI Parameters
HideShow
username
string (required) 

Name of the user to update

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
    "active" : false
    "role": "user"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
  "username": "exampleuser@bloomreach.com",
  "role": "user",
  "active": true
}
Response  400

Change user password
PUT/v3/users/{username}/password

Change or update passwords

Example URI

PUT /v3/users/username/password
URI Parameters
HideShow
username
string (required) 

The username to change password

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
  "currentPassword": "P4ssw0rd123",
  "newPassword": "N3wExamplePassword123"
}
Response  200
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
        "error_code": "ChangePasswordFailed",
        "error_detail": [detail message]
    }

Send reset-password email
POST/v3/password-reset/{username}

Request reset-password token

Example URI

POST /v3/password-reset/username
URI Parameters
HideShow
username
string (required) 

The username to send reset-password email

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Response  200
Response  400

Verify reset-password token
GET/v3/password-reset/{token}

Verify the reset-password token and redirect to the change password page

Example URI

GET /v3/password-reset/token
URI Parameters
HideShow
token
string (required) 

The reset-password token sent by email.

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Response  302
HideShow
Headers
Location: [URL of the change password webpage]
Response  400

Set new password
PUT/v3/password-reset/password

Set the new password to the user referred by the reset token

Example URI

PUT /v3/password-reset/password
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
        "reset_token": [ generated reset-token ],
        "new_password": [new password]
    }
Response  200
Response  400

Delete a user
DELETE/v3/users/{username}

Example URI

DELETE /v3/users/username
URI Parameters
HideShow
username
string (required) 

Name of the user to be deleted

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Response  200
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
        "error_code": "RemoveUserFailed",
        "error_detail": [detail message]
    }

Generated by aglio on 06 Oct 2020