API

Selected functionality of BriefBuilder is exposed in the form of an API (application programming interface), which selected partners can use to exchange BriefBuilder model data. An API can be useful for linking BriefBuilder to CDE’s (common data environments), parametric design applications, and for dedicated add-ins (such as the BriefBuilder Revit add-in).

See below for some info about the existing BriefBuilder API.

Documentation

The RESTful API is documented using Swagger and can be accessed here. Please note that you need a valid BriefBuilder user account to access the API documentation. If you do not have a user account, but would like to access the API documentation anyway, please contact us.

The API is designed to follow general REST principals. The following general error codes can be expected:
401 You are not authenticated.
403 You are not authorised for this resource.
404 Incorrect API url.
400 Incorrect API usage. Response contains a message regarding the nature of the error.
5XX BriefBuilder server error. Should generally not happen and indicates fault in the API implementation. Technical staff will be alerted automatically when this happens.

We expect API consumers to act as a TolerantReader. These API operations will be expanded over time and you should be able to handle additional fields that are not yet documented as well as missing fields that are documented as much as possible.

Access control

Access to our API is granted to authenticated end users, using the Swagger API documentation. Actual API access for third-parties is granted through our OAuth2 authentication protocol. Using this protocol, third-parties can request access the BriefBuilder data for a specific end-user, who has explicitly granted access for this by authenticating themselves on the BriefBuilder website. We are restricting the available OAuth2 grant types to Authorization code using Bearer tokens only at this point in time for use cases where a third-party application provides additional functionality to all BriefBuilder customers. This will require third-parties to exchange the access code for an access token using their client secret credentials in a back-end application.

For direct one-to-one API access from a customer to their own data in BriefBuilder, we provide to option to use the Oauth2 Password grant type.

If you would like to receive a set of client-credentials for creating a third-party application integration, or programmatic access to your own BriefBuilder data, please contact us so we can discuss the possibilities.

Password Grant example

Once you have received a set of client credentials from us you can use them in the following manner. This example uses cURL to show the HTTP interactions and may be implemented in any language.

Retrieve an OAuth2 access token using both your client credentials (CLIENT_ID, CLIENT_SECRET) and the you regular credentials, used to login to BriefBuilder (USERNAME, PASSWORD):

curl -v -X POST --user CLIENT_ID:CLIENT_SECRET \
https://api-app.briefbuilder.com/oauth/token \
-d 'grant_type=password&username=USERNAME&password=PASSWORD' \
-H "Accept: application/json"

If the credentials are all correct, the server will respond with a JSON response like this:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600, 
  "scope": "read"
}

Grab the value from the “access_token” field, in this case YOUR_ACCESS_TOKEN and use it in subsequent calls to our API in the Authorization header. For example, to retrieve a full requirements set for a specific project model, where PROJECT_ID is the id of the specific project:

curl -v -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H "Accept: application/json" \
https://api-app.briefbuilder.com/ext/api/project/PROJECT_ID/export

Was this article helpful?

Need Support?
Can't find the answer you're looking for? Don't worry we're here to help!
CONTACT SUPPORT

Leave a Comment