Skip to main content
All CollectionsLicensee Docs
How to invoke builder API with builder CLI tool
How to invoke builder API with builder CLI tool

builder API, builder CLI tool, API keys

Jason Liang avatar
Written by Jason Liang
Updated over a year ago

By using brainCloud builder CLI tool to invoke REST builder APIs, you can programmatically and efficiently manage your teams, apps and app tasks without interacting with the portal.

The Builder API currently supports the following features:

Access Team Info

  • Get teams list info

  • Get specific team info

App management

  • Create, update and delete apps within a team

  • Manage app lifecycle - enable/disable, etc.

Deployment management

  • Scriptable deployment of configuration meta-data (including files + scripts + unowned migrate-able custom entities) from app to app

  • Deployment of scripts (independent of app metadata); support full script tree or individual folders

Script management

  • Create, update and delete scripts within an app

API Keys and Security

To utilize the Team API for a team, the following conditions must be met:

  • Builder API access must be enabled on the TEAM - a Team Administrator must have enabled Builder API access for the team via the Team | Manage | Team Info screen.

  • Builder API access must be enabled for the MEMBER - a Team Administrator must have enabled Builder API access for the team member via the Team | Manage | Members page. Select the user, Choose View/Edit from the Action menu, and enable Builder API Access.

  • The MEMBER must have a valid, non-expired API KEY - the Team Member can generate an API key via the Personal Settings portion of the Design Portal.

  • API KEY + EMAIL required for all calls - The email address of the TEAM MEMBER must be provided with the API KEY for all API calls. API Keys cannot be used on their own in brainCloud.

---

Installation:

  • Request the builder CLI tool from brainCloud support.

  • Install it in your local folder. After installation, you should get an executable file bc-builder under the folder you installed.

Generate API access key:

  • Login brainCloud portal and edit the user. Click Add new key to create a new API key if you don't have any keys listed here.

  • Click the get key to copy the key value after adding.

Configure build CLI file (mac OS):

  • Create a JSON file .bc-builder.json under your home folder, paste the API Key you got from the above step to "apikey" field, and replace the email files with your brainCloud login email. 

 {
    "server":"https://api.braincloudservers.com",
    "apikey":"your-api-key",
    "email":"your-braincloud-login-email",
    "version" : "v1"
}

Test and run:

  • Get the user team list by running bc-builder team list:

  • Run bc-builder app list teamid --debug to get your app list under a team

  • Run bc-builder help to get all available commands:

---

As you expected, you can always call brainCloud builder API with other tools, such as Postman. See the following steps for detail.

  • Fill your login email and API key with Basic auth of Authorization tab

  • Add these following headers to the headers section

  • Put the correlated endpoint (the following example will list team info, so the endpoint is https://api.braincloudservers.com/builder/v1/team) and method (the following example is GET) of the request and hit Send.

---

Available actions and endpoints are listed below.

( Note: All the endpoints described below are accessible via the brainCloud API servers with the following root path: https://<braincloud-host>/builder/v1/team

In the docs, we will omit the host part and just use the shortened path /builder/v1/team to signify the same thing.)

  • Team scope actions:

Action

Endpoint

Get a list of teams

Returns those teams that the user:

  • Is a member of

  • Are contained with the API Keys scope

  • That the user still has API Key access to (which can dynamically change).

GET /builder/v1/team

Builder CLI:

> ./bc-builder team list

Get a specific team

Works for teams that the user (and their API key) have access to.

GET /builder/v1/team/<team-id>

Builder CLI:

> ./bc-builder team get <team-id>

  • App actions:

Action

Endpoint

Get list of apps

If the user is a Team Administrator for the specified team, returns all apps for that team.

If the user is not a Team Administrator, returns only the apps that that user has permissions on (any role).

GET /builder/v1/team/<team-id>/app

Builder tool:

> ./bc-builder app list <team-id>

Get a single app

Returns the general info of the specified app.

User must be a Team Administrator, or have at least DESIGN_APPIDS READ access (i.e. can view Design | Core App Info | Application IDs screen) to make this call.

GET /builder/v1/team/<team-id>/app/<app-id>

Builder tool

> ./bc-builder app get <team-id> <app-id>

Get the secret info of an app

Returns the appSecret for the specified app. Especially useful for admin apps that will be performing some app operations via the Client API.

User must be a Team Administrator, or have at least DESIGN_APPIDS READ access (i.e. can view Design | Core App Info | Application IDs screen) to make this call.

GET /builder/v1/team/<team-id>/app/<app-id>/appsecret

Builder tool

> ./bc-builder app get-app-secret <team-id> <app-id>

Create an app

Creates a new app belonging to the given team.

User must be a Team Administrator.

POST /builder/v1/team/<team-id>/app

{     "appName": "My New App",     "appOptions": {          "supportedPlatforms": [             "IOS",              "PS4"],                  "gamificationEnabled": true             }             }

Builder tool:

> ./bc-builder app create <team-id> --f app-create.json

Update basic info about an app

User must be a Team Administrator, or have DESIGN_APPIDS WRITE access (i.e. can edit Design | Core App Info | Application IDs screen) to make this call.

PATCH /builder/v1/team/<team-id>/app/<app-id>

Only the following fields may be directly edited (via this call). Fields are only updated if they are present in the parameters. Note that “updatedAt” must be included.

{   "updatedAt": 123456789,   "appName": "New name",   "imageUrl": "New image URL",      "parentAppId": "11110",   "allowParentAssignment": false,   "levelName": null,   "inheritFriendsFromParents": false,      "supportedVersions": {     "BB" : {       "releasePlatform" : "BB",       "gameVersion" : {         "version" : null,         "upgradeAppId" : null       }     },     "AMAZON" : {       "releasePlatform" : "AMAZON",       "gameVersion" : {         "version" : null,         "upgradeAppId" : null       }     }   } }

Builder tool

> ./bc-builder app update <team-id> <app-id> --f app-info.json

Enable/Disable an app

Used to temporarily enable/disable end-user access to an app.

Note that apps have two enabled flats - isUserEnabled which is the flag settable by Team’s, and isEnabled - which is a master flag controlled by brainCloud Super Users. An app is considered disabled if either of these flags is false.

User must be a Team Administrator, or have DESIGN_ADVANCED WRITE access (i.e. can edit Design | Core App Info | Advanced Settings screen) to make this call.

PATCH /builder/v1/team/<team-id>/app/<app-id>/enable

{    "updatedAt": 123456789,   "isUserEnabled": false,   "userDisabledReason": {     "message": "App disabled for maintenance."   } }

Builder tool:

> ./bc-builder app enable <team-id> <app-id> --f app-enable.json

[Soft-]Delete an app

Deletes the app.

User must be a Team Administrator.

DELETE /builder/v1/team/<team-id>/app/<app-id>

{    "updatedAt": 123456789,   "isDeleted": true }

Builder tool:

> ./bc-builder app delete <team-id> <app-id> --f app-delete.json

  • Cloud code actions:

Action

Endpoint

Get list of apps

If the user is a Team Administrator for the specified team, returns all apps for that team.

If the user is not a Team Administrator, returns only the apps that that user has permissions on (any role).

GET /builder/v1/team/<team-id>/app

Builder tool:

> ./bc-builder app list <team-id>

Get a single app

Returns the general info of the specified app.

User must be a Team Administrator, or have at least DESIGN_APPIDS READ access (i.e. can view Design | Core App Info | Application IDs screen) to make this call.

GET /builder/v1/team/<team-id>/app/<app-id>

Builder tool

> ./bc-builder app get <team-id> <app-id>

Get the secret info of an app

Returns the appSecret for the specified app. Especially useful for admin apps that will be performing some app operations via the Client API.

User must be a Team Administrator, or have at least DESIGN_APPIDS READ access (i.e. can view Design | Core App Info | Application IDs screen) to make this call.

GET /builder/v1/team/<team-id>/app/<app-id>/appsecret

Builder tool

> ./bc-builder app get-app-secret <team-id> <app-id>

Create an app

Creates a new app belonging to the given team.

User must be a Team Administrator.

POST /builder/v1/team/<team-id>/app

{     "appName": "My New App",     "appOptions": {          "supportedPlatforms": [             "IOS",              "PS4"],                  "gamificationEnabled": true             }             }

Builder tool:

> ./bc-builder app create <team-id> --f app-create.json

Update basic info about an app

User must be a Team Administrator, or have DESIGN_APPIDS WRITE access (i.e. can edit Design | Core App Info | Application IDs screen) to make this call.

PATCH /builder/v1/team/<team-id>/app/<app-id>

Only the following fields may be directly edited (via this call). Fields are only updated if they are present in the parameters. Note that “updatedAt” must be included.

{   "updatedAt": 123456789,   "appName": "New name",   "imageUrl": "New image URL",      "parentAppId": "11110",   "allowParentAssignment": false,   "levelName": null,   "inheritFriendsFromParents": false,      "supportedVersions": {     "BB" : {       "releasePlatform" : "BB",       "gameVersion" : {         "version" : null,         "upgradeAppId" : null       }     },     "AMAZON" : {       "releasePlatform" : "AMAZON",       "gameVersion" : {         "version" : null,         "upgradeAppId" : null       }     }   } }

Builder tool

> ./bc-builder app update <team-id> <app-id> --f app-info.json

Enable/Disable an app

Used to temporarily enable/disable end-user access to an app.

Note that apps have two enabled flats - isUserEnabled which is the flag settable by Team’s, and isEnabled - which is a master flag controlled by brainCloud Super Users. An app is considered disabled if either of these flags is false.

User must be a Team Administrator, or have DESIGN_ADVANCED WRITE access (i.e. can edit Design | Core App Info | Advanced Settings screen) to make this call.

PATCH /builder/v1/team/<team-id>/app/<app-id>/enable

{    "updatedAt": 123456789,   "isUserEnabled": false,   "userDisabledReason": {     "message": "App disabled for maintenance."   } }

Builder tool:

> ./bc-builder app enable <team-id> <app-id> --f app-enable.json

[Soft-]Delete an app

Deletes the app.

User must be a Team Administrator.

DELETE /builder/v1/team/<team-id>/app/<app-id>

{    "updatedAt": 123456789,   "isDeleted": true }

Builder tool:

> ./bc-builder app delete <team-id> <app-id> --f app-delete.json

  • Deploy actions:

Action

Endpoint

Create / initiate a deployment

User must be a Team Administrator on all associated teams, or have DESIGN_ADMIN WRITE access (i.e. can edit Design | Core App Info | Admin Tools screen) to both apps to make this call.

POST /builder/v1/deploy/

{   "source": {     "teamId": "aaa-bbb-ccc-ddd",     "appId": "11111",     "appName": "Source App",     "updatedAt": 123456789   },   "target": {     "teamId": "aaa-bbb-ccc-ddd",     "appId": "22222",     "appName": "Target App",     "updatedAt": 123456789     },   "components": {     "meta": true,     "files": true,     "scripts": true,     "customEntities": true  // FUTURE   },   "options": {     "meta": {       "excludes": {         "productPricing": true,         "pushCertificates": true,         "integrations": true,         "myServers": true,         "lobbies": true,         "itemCatalog": false,         "leaderboardsTournaments": false,         "independentLeaderboards": true       }     },     "files": {       // FUTURE     },     "scripts": {       "includes": {         "sourceAppFolder": "/",         "targetAppFolder": "/test",         "targetAppFolderCreateIfAbsent": true,         "importStrategy": "addOnly"       }     },     "customEntities": {       // FUTURE     }   }   "allowLiveUpdate": true }

Builder tool:

> ./bc-builder deploy create --f ./filepath/deployInfo.json

Retrieve the details of a specific deployment task

User must be a Team Administrator, or have DESIGN_ADMIN WRITE access (i.e. can edit Design | Core App Info | Admin Tools screen) to make this call.

GET /builder/v1/deploy/<task-id>

Builder tool:

> ./bc-builder deploy get <task-id>

Did this answer your question?