API Overview (beta)
The Brainstorm API is a RESTful service that provides data endpoints to retrieve and add data to Brainstorm. A two factor authentication system is used to authenticate API request that act on behalf of user. The API supports Brainstorm customers who have integrated SSO (SAML 2.0) through the provisioning of access keys.
All responses are XML responses by default. To retrieve JSON responses, specify the fmt=json GET attribute with your API URL requests or include the application/json MIME type in the Content-Type header of your request.
See also: http://en.wikipedia.org/wiki/REST
All timestamps are formatted according to RFC3339.
Developers should anticipate the ordering of items within the data structures changing and code appropriately. Expect, for example, the order of certain data elements can be changed in both XML and JSON responses.
API usage is monitored closely. All API calls are subject to rate limiting, and if necessary, the API will temporarily suspend API calls if usage exceeds a certain threshold. The specific rate limits are constantly changing based on activity, but following the guidelines in this API documentation will ensure your application will not exceed the limits.
Admin API Functionality
The API also exposes certain endpoints functionality meant to manage your Brainstorm instance. Stay tuned for more information.
All non-error responses will have 200 Response code. For API endpoints where data is posted to Brainstorm, an HTTP 200 is returned.
- 200 OK
- 201 Created/Updated
The HTTP Response error code can often help you debug why your API request is failing. Here are the error codes you should be aware of while developing against the API.
- 401 - Forbidden. Check your apikey and apisecret value. Also make sure you have base 64 encoded the value of your Authorization header
- 403 - Unauthorized. Only returned when you have tried to access an API endpoint that requires the On-Behalf-Of header. If returned, check the value of your header and make sure that it contains a valid user AccessKey or email & password combo.
- 406 - Arguments missing. You are missing required parameters in your request.
- 50x - Something went terribly wrong! Please contact support with information about your request and the error it generated.
There are several query strings that can be used to manipulate the response of API calls. They can all be added as GET query string parameters to your API requests like so:
- fmt=json - Returns the response in JSON format. The default response is in XML.
- results - Specifies how many results to return. (If the API call returns a list of items). If left unspecified, 10 results will be returned by default.
- page - Specifies which page of results to return. (If the API call returns a list of items). For example, if there are 50 total results, and results is set to 10, then calling page=2 will return the 3rd through 13th results.
- callback - Only applicable to JSON responses. Wraps the JSON response with 'padding'. See JSONP wiki for more details. The value of the callback parameter will be used to wrap the JSON response.
Error responses will be returned in XML or JSON format. Here is a sample error response in XML.
<ApiError xmlns="http://brainstorm.intuit.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Message xmlns="http://schemas.datacontract.org/2004/07/Brainstorm.Model.DTO">Invalid API credentials. Please check your appKey and appSecret values and try again.</Message> <StatusCode xmlns="http://schemas.datacontract.org/2004/07/Brainstorm.Model.DTO">401</StatusCode> <StackTrace/> </ApiError>