transientBug API Documentation
The v1 API tries to conform to JSON-API v1.0 format.
- Sparse fieldsets are not supported
Additionally, this document is generated from acceptance tests using JSON Schemas so it should always be up to date with the current API.
Issues with the API should be reported on Github. Please check to make sure that the issue you are reporting does not already have an issue created, as to help my sanity when managing them.
The transientBug v1 API uses HTTPS and provides several methods of authentication, depending on the use case: Third Party Clients and Personal Tools.
Third Party Client OAuth2
Third Party Clients are defined as mass distributed clients, such as native applications, browser extensions and web apps. For these clients, OAuth2 Authorization Code Grant flow is provided.
Developers can register new OAuth2 applications here,
for now you’ll need a minumum of a
redirect url and will be
CLIENT_SECRET which you will use below.
To obtain an access token, first make a
GET request to
/oauth/authorize?client_id=CLIENT_ID &redirect_uri=REDIRECT_URL &response_type=code
CLIENT_ID is the client ID provided when registering
the application, and
REDIRECT_URL is the same redirect url you used when
registering the application.
On a successful call, this will redirect to the
REDIRECT_URL with a
the query string. With that
code, issue a
/oauth/token?client_id=CLIENT_ID &client_secret=CLIENT_SECRET &code=RETURNED_CODE &grant_type=authorization_code &redirect_uri=REDIRECT_URL
CLIENT_SECRET is the value provided after registering your app, and
RETURNED_CODE is the
code from the first requests redirect. A successful
request will return a JSON payload with an
After this, you can begin using the API, with all requests containing the
access_token in an Authorization
Authorization: Bearer <access_token>
For Personal Tools, small scale applications and other utilities developed for personal use, two simple methods are provided, modeled off of the Pinboard v1 API with the intention of trying to be easy to use and develop against:
- HTTP Basic
- Query String API Tokens:
The query string API token can also be sent along in the JSON body for
You are encouraged to only use Basic Auth to grab the API token through the profile endpoint, and should prefer to use the API token method everywhere to avoid storing your password.
You can find your API token on your profile page. Through this page you can also regenerate your token, however this will invalidate your previous API token.
As of late July, 2019 the Bookmarks create endpoint no longer overwrites existing bookmark data and will now respond with a 302 to the found bookmark.