Current API status
The public API is currently released as alpha in read-only mode. More features will be rolled out soon.
If you're interested in implementing the Bitrated API in your product, we would love to learn about your use-case, hear which features you'd like to see and assist you with the integration process. Please don't hesitate contacting us with any questions, feedback or suggestions.
Introduction
The Bitrated API follows the REST architecture style and the KISS principle. We use resource-oriented, simple and predictable URLs, semantic HTTP verbs, HTTP status codes to indicate errors, and JSON as our exclusive data interchange format.
The website and API are symmetric and share the same URLs
(once a stable API is released, we'll provide versioned API endpoints as well).
Almost every page on Bitrated can be consumed as JSON by specifying the Accept: application/json header,
or by appending .json to the URL.
API endpoints for public information do not require an API key.
Users API basic identity data
GET /:user
Returns a user object with the following fields:
username, scores, created_at,
pubkey, subkeys, pubkey_sin, pubkey_address, sigs,
full_name, title, about, tags, roles
and arbitration_fees.
Example: https://www.bitrated.com/nadav.json
GET /:user/{pubkey,sin}
Returns the public key associated with the user, in hex or SIN format.
Examples: https://www.bitrated.com/nadav/pubkey, https://www.bitrated.com/nadav/sin
GET /:user[/:format].png
Returns the user image encoded as PNG. Format is either thumb (70x70) or full (290x290), and is set to thumb by default.
Examples: https://www.bitrated.com/nadav.png, https://www.bitrated.com/nadav/full.png
GET /:user/feed
Returns the user's activity feed, along with the X-Pagination-Pages header
to indicate the number of available pages.
Example: https://www.bitrated.com/nadav/feed.json
GET /users
Returns a list of users, along with the X-Pagination-Pages header
to indicate the number of available pages.
Query params: username (search by username), q (search by username, full name and title),
role ("buyer", "seller" or "arbiter"), tag (search by tag) and page.
Examples: https://www.bitrated.com/users.json, https://www.bitrated.com/users.json?q=ab&role=arbiter
Reputation API trust scores, aggregated totals and linked accounts
GET /:user/scores
Returns the user's primary identity trust scores, with the following fields:
bitrating (numeric trust score), bitrank (trust score normalized to a scale of -1 to 5),
position_rank, percentile, totals.reviews, totals.vouches and totals.linked.
Example: https://www.bitrated.com/nadav/scores.json
GET /:user/linked
Returns an list of linked accounts the user has verified, each with the following fields:
provider, username, name, url,
creation_time (original account creation time)
and metrics (JSON object of account metrics extracted by Bitrated).
Example: https://www.bitrated.com/nadav/linked.json
GET /:user/bitrating
Returns just the user's Bitrating score.
Example: https://www.bitrated.com/nadav/bitrating
Ratings API user reviews & web-of-trust vouches
All ratings have the following fields: id, type ("review" or "vouch"), rater,
target, value, comment, created_at, rater_scores,
rater_sin, target_sin and sig.
Reviews which are attached to a Bitrated trade have the following additional fields:
rater_role, target_role and trade.
GET /:user/{ratings,reviews,vouches}[/newest]
Returns a list of ratings received by the user.
Can be filtered for reviews/vouches only, or return both (by specifying ratings).
The newest flag causes the ratings to be sorted by their timestamp instead of by the rater's bitrating.
Examples: https://www.bitrated.com/nadav/ratings.json, https://www.bitrated.com/nadav/reviews/newest.json
GET /:user/{rated,reviewed,vouched}[/newest]
Like above, but returns ratings made by the user rather than ones received by him.
Examples: https://www.bitrated.com/nadav/rated.json, https://www.bitrated.com/nadav/reviewed.json
GET /:user/{reviews,reviewed}/{positive,negative}[/newest]
Returns a list of reviews, filtered to positive or negative ones only.
Examples: https://www.bitrated.com/nadav/reviews/positive.json
GET /:user/rating/:id[.sig]
Returns a single rating by ID. Specifying the .sig extension returns the rating in a signed message format.
Contracts API multi-signature reversible payments
Public beta coming soon.
Miscellaneous
Signed response
You can request Bitrated to digitally sign HTTP responses by specifying the X-Sign-Response: true header
or the sign_resp query string argument,
allowing you to prove the response was originated from Bitrated.
When enabled, the signature is provided in the X-Response-Sig response header.
See ecdsa-signed-response for the exact
message format.
Our ECDSA (secp256k1) signing public key is 03eca14fb11919901f1d477682da1a187fdb4e7a2f3682c2f67db445ac62a6f5e0,
encoded to a Bitcoin address as 1GfnUGm3s6AqMCJtSqr8h8SMurCDvaL2QY.