V2 Documentation

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/v2/

Usage Policies​

Violations of the following policies may lead to onsite punishments or an outright ban from utilising our API in severe circumstances:

• Don't distribute your token outside of individuals required for your project, or neglect to refresh it if discovered.
• Don't use your token to provide other members unrestricted access to the API.
• Don't provide a hosted interface to the API for any business or service for 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. If you're receiving an error suggesting this header was missing or not in the expected format, please read through this section thoroughly. We suggest only granting scopes for your token which you intend to use.

We expect the 'Authorization' header to be in the following format:

Authorization: Type Value

Click to expand...

An example of this header might be:

Authorization: Token xXoIjvQ6G8UmUPufZWxN-Kkyd54Js_bY

Click to expand...

There are three ways to authenticate:
- the 'Token' type, which is the common way to authenticate using the token found on the 'Details' page as the value
- the 'Basic' type, which is used for OAuth2 token endpoints only (see our OAuth2 documentation)
- the 'Bearer' type, which is used for calling endpoints on behalf of users via OAuth2 (see our OAuth2 documentation)

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:

An example of an errored response:

Formatting​

By default, all responses from our API endpoints are returned in the non-pretty JSON format.

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.

Endpoints, OpenAPI Specification & Wrappers​

We utilise an OpenAPI specification for generating endpoint documentation and basic wrappers.

Documentation: https://builtbybit.gitbook.io/api
OpenAPI Specification and a list of pre-generated wrappers: https://github.com/BuiltByBit/api-openapi-spec

If we haven't yet pre-generated a wrapper for a language you'd like to use, and you think that wrapper would be helpful for other users, please open an issue in this repository.

JWT signing​

You can set the &jwt=1 query parameter to indicate that the response should be a signed JSON web token. When set, you will always receive a successful response where the data field is the JWT string (unless a pre-endpoint error is encountered, like auth or rate limiting). The JWT will then contain the API response as if the request was not called with JWT signing. For instance, if you made a request to an unknown endpoint, the outer response containing the JWT will be successful. However, when you decode the JWT, the inner response will be an error (with result="error" and its relevant message).

The JWT will be valid for 24 hours and contains two fields:

• 'request' - the request URI that was used to generate the JWT (path + query parameters)
• 'response' - the original response encoded with the requested format. Eg, if JSON, this will be a stringified JSON object.

It must be decoded using ES256 and the following public key:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAECRQAAg0y44Vp+QvbxHRQlD+Poam7
eD/SteU/tf9MAlz94CnGz6nKExB0WaQI8ixKmCsIq0+yOCWJTk9ei5pX1g==
-----END PUBLIC KEY-----

Click to expand...

API Events​

Previously, if you wanted to listen for new data (such as updates or purchases), you'd need to poll individual endpoints to watch for changes. This was wasteful and added complexity for implementers as they'd need to track the last time they polled the endpoint (or the most recent ID returned) and compare the results to extract only the delta. We've introduced API Events as a way to listen for events, no differently than if you were creating a webhook or a Discord action. In fact, our implementation is shared across API events, webhooks, and Discord actions, meaning API Events support the same existing triggers & filtering options as they do.

Create a new event listener by heading to the 'Events' page. Once created, new events will populate your pending events. These pending events can be polled via the '/v2/events' endpoint. Once you've completed the handling of the event, you may mark it as complete, meaning it will no longer be returned in calls to '/v2/events'. The data of each event will simply be a combined object where each of the placeholder names maps to their values.

With hints​

Many endpoints will support ‘with hints’, which tell us what additional data you’d like us to return in the request. This could be additional fields on models, or could be additional fields in the top-level response data field itself. These hints aid in reducing bandwidth for both us and the implementers of our API by only returning necessary data. For instance, if fetching a list of resources, including the HTML-rendered & raw BBCode of user-generated descriptions could increase response sizes by orders of magnitude.

These hints are provided in a comma-separated format via the ‘with’ query parameter. The supported hints will be documented on a per-model (Camel case) and per-endpoint basis (lower case). They will always be string names, and can be nested via the ‘.’ separator (for instance, Resource.Creator).