Documentation
- Last updated Last updated:
-
We recognise that many members of our platform, and more specifically those who author resources, are actively seeking methods in which they can automate their interactions with our platform. Whilst such automation in form of scraping or otherwise is known to be a violation of our Terms of Service, we've developed and deployed this REST API in order for us to satisfy these requests in a controlled manner.
This API is only made available to members with an active Ultimate upgrade. No exceptions. Access is liable to be removed at any time and for any reason, though the most likely cause may be abuse. Restricted and banned members will also be denied access even if they still hold an active Ultimate upgrade.
Would you like your resource to have a licensing system and update/version checking without the need to self-host anything? Would you like to develop an identity verification system? Would you like to synchronise replies to your threads within a Discord channel? Would you like to display your resource's reviews on your website? All of this and much more can be achieved via this API.
We're always wanting to improve the functionality of this API along with the usefulness of this documentation. As a result, we've defined clear versioning for future interoperability in the event that we need to drastically change this API's behaviour in significant ways. If you feel improvements can be made in any area, we encourage the use of our site's suggestions forum to communicate those to us.
The base URL and current version is as follows: https://api.builtbybit.com/v1/
Usage Policies
Violations of the following policies may lead to onsite punishments or an outright ban from utilising our API in serve circumstances:
- Don't distribute your private token or neglect to refresh it if discovered.
- Don't use your private token to provide other members unrestricted access to the API.
- Don't provide a hosted interface to the API for any business or service of which you are not the owner.
- Don't fail to respect and adhere to dynamic rate limiting errors.
Authentication
An API token is required to access all of our endpoints and can be generated via the API Credentials page. To authenticate with our API, the 'Authorization' HTTP header must be present in all requests containing your API token. If you're receiving an error suggesting this header was missing or not in the expected format, please read through this section thoroughly.
We support two types of tokens that grant varied access to our endpoints. The primary token type, 'Private', grants access to all public endpoints and as the name suggests, should be kept private. This token type grants access to view and modify potentially sensitive data specific to your account.
Alternatively, we also support a secondary 'Shared' token type that grants very limited access to our API and can be shared with other members or within your products. This token type grants access to public validation of resource licenses, public version checking and public update checking. However, its scope is limited to your account and the resources you've authored solely.
We expect the 'Authorization' header to be in the following format:
An example of this header might be:
Response Handling
All responses from our API endpoints will include a top-level object detailing information about the response. It will always include a 'result' field with a value of either 'success' or 'error'. Use this field along with the response's status code to handle unexpected errors.
An example of a successful response:
Code:{
"result": "success",
"data": "ok"
}
An example of an errored response:
Code:{
"result": "error",
"error": {
"code": "HeaderMissingError",
"message": "The 'Authorization' header was not present."
}
}
Formatting
By default, all responses from our API endpoints are returned in the non-pretty JSON format. This behaviour can be altered for any request via query parameters. We currently support JSON, XML, and YAML formatting only with JSON being the only one of the three to support pretty printing. More formats may be supported in the future.
The following query parameters are available:
- 'format' - accepts either 'json', 'xml', or 'yaml'.
- 'pretty' - accepts either 'true' or 'false'.
Similarly, request bodies for CREATE/UPDATE operations support the same formats. The request's 'Content-Type' header must be set appropriately:
- JSON - 'application/json'
- XML - 'application/xml'
- YAML - 'text/yaml'
Sorting
For all endpoints which return a list of objects, you also have the ability to sort and order them via query parameters. Results are paginated with 20 objects per page and fields you can sort by are defined on a per endpoint basis.
The following query parameters are available:
- 'sort' - accepts object field names (see endpoint documentation below).
- 'order' - accepts either 'asc' (ascending) or 'desc' (descending).
- 'page' - accepts an integer greater than or equal to 1.
Rate Limiting
We apply rate limiting rules per connection IP address as well as per account. The latter means that when using a shared token, you may hit a rate limit not due to your own actions, but the actions of other individuals also using that same shared token. Note also that rate limits for READ operations (ie. GET) are independent of those applied to WRITE operations (ie. POST, PATCH, DELETE).
Rate limits may be adjusted so to avoid the hard-coding of these rates into products or wrappers, we won't be disclosing them within this documentation. Instead, we include a 'Retry-After' header when you hit a rate limit which we expect members to adhere to. Note that this header provides a millisecond granularity, rather than the second granularity set out by the header's HTTP specification.
Wrappers
We've written an official open-source JavaScript (Node.js) wrapper which a rich feature set including full coverage of our API, as well as in-built request stalling to ensure compliance with rate limits. Its repository and associated documentation can be found here:
https://github.com/BuiltByBit/js-api-wrapper
A list of notable community-built wrappers can also be found below for various different languages which contain similar and desirable feature sets. If you've developed a wrapper and feel it meets these same criteria, feel free to open a support ticket and suggest it be added to this list as well.
Java:
Rust:
PHP:
C#:
Kotlin: