{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d91bcddd-c53f-48ec-ad8e-f89af4bb456a","name":"brainCloud Builder API v5.9","description":"The brainCloud portal provides mechanisms for managing teams and apps within those teams. It also provides facilities for managing CloudCode scripts belonging to or shared between those apps. This works quite well for the majority of our clients and for small to medium-sized development teams.\n\nWhere this begins to break down is for larger development teams or more complex application structures.\n\nOften, larger teams will have many, many applications and/or complex applications that may have hundreds or thousands of CloudCode scripts. For their needs, a more structured management of teams, apps, and scripts is desirable.\n\nThis is where the Builder API and CLI come in.\n\nThe Builder API is a REST API for performing many tasks previously only supported by the portal. The Builder API uses API Keys for security and traceability when invoking Builder API endpoints.\n\nSimilarly, the Builder CLI is a new command-line tool built to interact with the Builder API in an easy-to-use and consistent way. Also note that any new features that are released in the future for the Builder API will be supported by a concurrent release of the Builder CLI. The two should always be in sync.\n\n# Basic mechanics\n\nPrior to enumerating all the calls that are supported by the current release of the Builder API/CLI, it is worth mentioning the basic mechanics for using the CLI or for making API calls directly. The mechanics are described here:\n\nThe basic mechanics for using the Builder API and CLI are described below. It is up to the developer to determine which is the more desirable way to integrate with brainCloud for their project(s).\n\n> Note that much of this is abstracted away by the Builder CLI; however, if you choose to invoke the REST endpoints directly, this is how you do it. \n  \n\n## Request basics\n\n### Authentication\n\nIt is assumed that each call to a Builder API endpoint uses BASIC authentication whereby the authentication string is a Base64-encoded UTF-8 string of the following format:\n\n> email - The email address of the api key owner \n  \n> api-key - The api key being used to validate the action. \n  \n\n### HTTP headers\n\nUnless otherwise specified, the following HTTP headers should be included with each request:\n\nAccept: application/json, text/plain, \\*/\\*\n\nAccept-Encoding: gzip\n\nContent-Type: application/json (OR multipart/form-data for some of the file upload calls)\n\n## Response basics\n\nIn addition to the standard HTTP status codes indicating success or failure, all endpoints will return a JSON response body of the following format:\n\n``` json\n{\n    \"response\": {},\n    \"errors\": {  <- may or may not be present\n        \"reason\": 12345,\n        \"msgs\": [ \"aaa\", \"bbb\", \"ccc\" ]\n    } \n}\n\n ```\n\nNote that the return value described for each endpoint in the specific API sections is the value that will be returned in the response field described above.\n\n# Builder CLI mechanics\n\nThe Builder API provides a convenient mechanism for interacting with the Builder API - abstracting the low-level details of formatting and sending the HTTPS requests, allowing the integrator to focus on the JSON payloads of the API requests and the corresponding API responses.\n\n## Configuration files\n\nTo begin - the Builder CLI requires access to a configuration file. This file contains the details of the server to connect to - and the API Key and associated email to use when making requests.\n\nBy default, the file is named bc-builder.json, and is located in the local (.) or \\~/.bc-builder directory; the local directory takes precedence.\n\n``` json\n{\n    \"server\":\"https://api.bc.company.com\",\n    \"apikey\":\"t-aaa-bbb-ccc-ddd\",\n    \"email\":\"bruce@company.com\",\n    \"version\" : \"v1\"\n}\n\n ```\n\nNote that developers may also specifically specify a config file using the --config command-line parameter.\n\n## Running commands\n\nOnce the configuration file is in place, you can access the tool using the following command format:\n\n``` shell\nbc-builder <app|deploy|team> {<command> [sub-command]} [parameters] [flags]\n\n ```\n\nFor example, the bc-builder team list command retrieves a list of teams that you have access to:\n\n``` shell\n> bc-builder team list\nBuilder API Returned Success (status = 200)\n{\n  \"response\": {\n    \"teams\": [\n      {\n        \"teamName\": \"brainCloud - SCRATCH\",\n        \"contactEmail\": \"bruce@bitheads.com\",\n        \"contactName\": \"Bruce Wayne\",\n        \"teamId\": \"fc072b84-xxx-xxxx-xxxx-9f4626f385f1\",\n        \"numApps\": 375,\n        \"numMembers\": 36\n      },\n      {\n        \"teamName\": \"XXXPaulTest\",\n        \"contactEmail\": \"paulw@bitheads.com\",\n        \"contactName\": \"Paul Winterhalder\",\n        \"teamId\": \"f899c849-xxx-xxx-xxx-2fef79a1f3c9\",\n        \"numApps\": 4,\n        \"numMembers\": 2\n      }\n    ],\n    \"count\": 2\n  }\n}\n\n ```\n\nLikewise, we would retrieve the list of apps for the XXXPaulTest team like so:\n\n``` shell\nbc-builder app list f899c849-xxx-xxx-xxx-2fef79a1f3c9\n\n ```\n\n### Providing JSON inputs via files\n\nSome commands require JSON as parameters - you specify the file to use with the --f command-line parameter. For example:\n\n``` shell\nbc-builder app enable f899c849-xxx-xxx-xxx-2fef79a1f3c9 24010 --f app-enable.json\n\n ```\n\n### Using STDIN for JSON inputs\n\nYou can also provide the JSON via stdin - which can be useful for tools integration. You do so via the --s command-line parameter.\n\n``` shell\n> echo '{ \"isUserEnabled\": true, \"updatedAt\": 1616980697278 }' | bc-builder app enable f899c849-xxx-xxx-xxx-2fef79a1f3c9 24010 --s\nBuilder API Returned Success (status = 200)\n{\n  \"response\": {\n    \"app\": {\n      \"isDeleted\": false,\n      \"appName\": \"ChildApp\",\n      \"appId\": \"24010\",\n      \"isEnabled\": true,\n      \"isUserEnabled\": true,\n      \"userDisabledReason\": {\n        \"message\": \"App disabled for maintenance.\"\n      },\n      \"updatedAt\": 1617055798171\n    }\n  }\n}\n\n ```\n\n### Debugging and viewing request data\n\nYou can also add the --debug flag to view the request sent to the server (and additional debugging info).\n\n``` shell\n> echo '{ \"isUserEnabled\": true, \"updatedAt\": 1616980697278 }' | bc-builder app enable f899c849-xxx-xxx-xxx-2fef79a1f3c9 24010 --s --debug\nUsing config file: /Users/winterhalder/bitHeads/Projects/go-workspace/src/bitbucket.org/braincloud/braincloud-builder/bc-builder.json\n- Email:           bruce@company.com\n- API Key:         t-eb0c58af-xxxx-xxxx-xxxx-f8b6ee4766ad\nRequest:  PATCH https://internal.braincloudservers.com/team/f899c849-xxx-xxx-xxxx-2fef79a1f3c9/app/24010/enable\n{\n  \"isUserEnabled\": true,\n  \"updatedAt\": 1616980697278\n}\nBuilder API Returned Error (status = 400)\n{\n  \"response\": {},\n  \"errors\": {\n    \"msgs\": [\"'updatedAt' value does not match current value\"],\n    \"reason\": 60102\n  }\n}\n\n ```\n\n### JSON-only output\n\nFinally, you can use the --quiet option to restrict the tool to returning JSON results only. The exit value of the tool will indicate whether the API calls was successful \\[0\\] or a failure \\[1\\]. Note the absence of the line the indicates the HTTP return status.\n\n``` shell\n> bc-builder app get f899c849-xxx-xxx-xxx-2fef79a1f3c9 24010 --quiet\n{\n  \"response\": {\n    \"app\": {\n      \"appId\": \"24010\",\n      \"appName\": \"ChildApp\",\n      \"imageUrl\": null,\n      \"imageUrlFullPath\": null,\n      \"teamId\": \"f899c849-xxx-xxx-xxx-2fef79a1f3c9\",\n      \"parentAppId\": \"24009\",\n      \"allowParentAssignment\": false,\n      \"levelName\": null,\n      \"inheritFriendsFromParents\": false,\n      \"isEnabled\": true,\n      \"isUserEnabled\": true,\n      \"isDeleted\": false,\n      \"runState\": \"Limited\",\n      \"publishState\": \"Development\",\n      \"planName\": \"Dev\",\n      \"subscriptionType\": \"\",\n      \"subscriptionId\": \"_local\",\n      \"updatedAt\": 1617055798171,\n      \"supportedVersions\": {\n        \"WINDOWS\": {\n          \"releasePlatform\": \"WINDOWS\",\n          \"gameVersion\": {\n            \"version\": null,\n            \"upgradeAppId\": null\n          }\n        },\n        \"ANG\": {\n          \"releasePlatform\": \"ANG\",\n          \"gameVersion\": {\n            \"version\": null,\n            \"upgradeAppId\": null\n          }\n        },\n        \"FB\": {\n          \"releasePlatform\": \"FB\",\n          \"gameVersion\": {\n            \"version\": null,\n            \"upgradeAppId\": null\n          }\n        },\n        \"IOS\": {\n          \"releasePlatform\": \"IOS\",\n          \"gameVersion\": {\n            \"version\": null,\n            \"upgradeAppId\": null\n          }\n        }\n      },\n      \"userDisabledReason\": {\n        \"message\": \"App disabled for maintenance.\"\n      }\n    }\n  }\n}\n\n ```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"9443971","team":5902458,"collectionId":"d91bcddd-c53f-48ec-ad8e-f89af4bb456a","publishedId":"2sBXcEizaV","public":true,"publicUrl":"https://builder.docs.braincloudservers.com","privateUrl":"https://go.postman.co/documentation/9443971-d91bcddd-c53f-48ec-ad8e-f89af4bb456a","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.0","publishDate":"2026-03-11T19:45:25.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Public BaaS","id":"534c1f6d-cb24-499d-a407-70cf773614f4","owner":"33294635","values":[{"key":"host-url","value":"https://api.braincloudservers.com","enabled":true,"type":"default"},{"key":"builder-url","value":"builder/v1","enabled":true,"type":"default"},{"key":"super-api-key","value":"s-xxxxx-xxxxx","enabled":true,"type":"secret"},{"key":"team-api-key","value":"t-xxxxx-xxxxx","enabled":true,"type":"secret"},{"key":"user-email","value":"user@company.com","enabled":true,"type":"default"},{"key":"team-id","value":"aaa-bbb-ccc-ddd-eee","enabled":true,"type":"default"},{"key":"app-id","value":"1xxxx","enabled":true,"type":"default"},{"key":"admin-profile-id","value":"222","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/48d07f97f6ca82432ede008d2b91bd5a8fd00c942101a15c38d11d6009ca8684","favicon":"https://braincloudservers.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Public BaaS","value":"33294635-534c1f6d-cb24-499d-a407-70cf773614f4"}],"canonicalUrl":"https://builder.docs.braincloudservers.com/view/metadata/2sBXcEizaV"}