Endpoint reference

CritiqueBrainz provides various endpoints that can be used to interact with the data. Web API uses JSON format.

Root URL: https://critiquebrainz.org/ws/1

Below you will find description of all available endpoints.

Reviews

GET /review/languages

Get list of supported review languages (language codes from ISO 639-1).

Example Request:

$ curl https://critiquebrainz.org/ws/1/review/languages \
       -X GET

Example Response:

{
  "languages": [
    "aa",
    "ab",
    "af",
    "ak",
    "yo",
    "za",
    "zh",
    "zu"
  ]
}
Response Headers:
 
GET /review/

Get list of reviews.

Request Example:

$ curl "https://critiquebrainz.org/ws/1/review/?limit=1&offset=50" \
        -X GET

Response Example:

{
  "count": 9197,
  "limit": 1,
  "offset": 50,
  "reviews": [
    {
      "created": "Fri, 16 May 2008 00:00:00 GMT",
      "edits": 0,
      "entity_id": "09259937-6477-3959-8b10-af1cbaea8e6e",
      "entity_type": "release_group",
      "id": "c807d0b4-0dd0-43fe-a7c4-d29bb61f389e",
      "language": "en",
      "last_updated": "Fri, 16 May 2008 00:00:00 GMT",
      "license": {
        "full_name": "Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported",
        "id": "CC BY-NC-SA 3.0",
        "info_url": "https:\/\/creativecommons.org\/licenses\/by-nc-sa\/3.0\/"
      },
      "popularity": 0,
      "source": "BBC",
      "source_url": "http:\/\/www.bbc.co.uk\/music\/reviews\/vh54",
      "text": "TEXT CONTENT OF REVIEW",
      "rating": 5,
      "user": {
        "created": "Wed, 07 May 2014 16:20:47 GMT",
        "display_name": "Jenny Nelson",
        "id": "3bf3fe0c-6db2-4746-bcf1-f39912113852",
        "karma": 0,
        "user_type": "Noob"
      },
      "votes": {
        "positive": 0,
        "negative": 0
      }
    }
  ]
}
JSON Parameters:
 
  • entity_id (uuid) – UUID of the release group that is being reviewed
  • entity_type (string) – One of the supported reviewable entities. ‘release_group’ or ‘event’ etc. (optional)
Query Parameters:
 
  • user_id – user’s UUID (optional)
  • sortpopularity or created (optional)
  • limit – results limit, min is 0, max is 50, default is 50 (optional)
  • offset – result offset, default is 0 (optional)
  • language – language code (ISO 639-1) (optional)
Response Headers:
 
POST /review/

Publish a review.

OAuth scope: review

Request Headers:
 
JSON Parameters:
 
  • entity_id (uuid) – UUID of the entity that is being reviewed
  • entity_type (string) – One of the supported reviewable entities. ‘release_group’ or ‘event’ etc.
  • text (string) – Text part of review, min length is 25, max is 5000 (optional)
  • rating (integer) – Rating part of review, min is 1, max is 5 (optional)
  • license_choice (string) – license ID
  • lang (string) – language code (ISO 639-1), default is en (optional)
  • is_draft (boolean) – whether the review should be saved as a draft or not, default is False (optional)

NOTE: You must provide some text or rating for the review.

Response Headers:
 
GET /review/(uuid: review_id)/revisions/(int: rev)

Get a particular revisions of review with a specified UUID.

Request Example:

$ curl https://critiquebrainz.org/ws/1/review/b7575c23-13d5-4adc-ac09-2f55a647d3de/revisions/1 \
       -X GET

Response Example:

{
  "revision": {
    "id": 1,
    "review_id": "b7575c23-13d5-4adc-ac09-2f55a647d3de",
    "text": "TEXT CONTENT OF REVIEW",
    "rating": 5,
    "timestamp": "Tue, 10 Aug 2010 00:00:00 GMT",
    "votes_negative": 0,
    "votes_positive": 0
  }
}
Status Codes:
Response Headers:
 
GET /review/(uuid: review_id)/revisions

Get revisions of review with a specified UUID.

Request Example:

$ curl https://critiquebrainz.org/ws/1/review/b7575c23-13d5-4adc-ac09-2f55a647d3de/revisions \
       -X GET

Response Example:

{
  "revisions": [
    {
      "id": 1,
      "review_id": "b7575c23-13d5-4adc-ac09-2f55a647d3de",
      "text": "TEXT CONTENT OF REVIEW",
      "rating": 5,
      "timestamp": "Tue, 10 Aug 2010 00:00:00 GMT",
      "votes_negative": 0,
      "votes_positive": 0
    }
  ]
}
Status Codes:
Response Headers:
 
POST /review/(uuid: review_id)/report

Create spam report for a specified review.

OAuth scope: vote

Response Headers:
 
GET /review/(uuid: review_id)/vote

Get your vote for a specified review.

Request Example:

$ curl "https://critiquebrainz.org/ws/1/review/9cb11424-d070-4ac1-8771-a8703ae5cccd/vote" \
       -X GET \
       -H "Authorization: Bearer <access token>"

Response Example:

{
  "vote": {
    "vote": true,
    "voted_at": "Thu, 22 Dec 2016 11:49:56 GMT"
  }
}

OAuth scope: vote

Response Headers:
 
PUT /review/(uuid: review_id)/vote

Set your vote for a specified review.

OAuth scope: vote

Request Example:

$ curl "https://critiquebrainz.org/ws/1/review/9cb11424-d070-4ac1-8771-a8703ae5cccd/vote" \
       -X PUT \
       -H "Content-type: application/json" \
       -H "Authorization: Bearer <access token>" \
       -d '{"vote":true}'

Response Example:

{
  "message": "Request processed successfully"
}
JSON Parameters:
 
  • vote (boolean) – true if upvote, false if downvote

NOTE: Voting on reviews without text is not allowed.

Status Codes:
Response Headers:
 
DELETE /review/(uuid: review_id)/vote

Delete your vote for a specified review.

OAuth scope: vote

Request Example:

$ curl "https://critiquebrainz.org/ws/1/review/9cb11424-d070-4ac1-8771-a8703ae5cccd/vote" \
       -X DELETE \
       -H "Authorization: Bearer <access token>"

Response Example:

{
  "message": "Request processed successfully"
}
Response Headers:
 
GET /review/(uuid: review_id)

Get review with a specified UUID.

Request Example:

$ curl https://critiquebrainz.org/ws/1/review/b7575c23-13d5-4adc-ac09-2f55a647d3de \
       -X GET

Response Example:

{
  "review": {
    "created": "Tue, 10 Aug 2010 00:00:00 GMT",
    "edits": 0,
    "entity_id": "03e0a99c-3530-4e64-8f50-6592325c2082",
    "entity_type": "release_group",
    "id": "b7575c23-13d5-4adc-ac09-2f55a647d3de",
    "language": "en",
    "last_updated": "Tue, 10 Aug 2010 00:00:00 GMT",
    "license": {
      "full_name": "Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported",
      "id": "CC BY-NC-SA 3.0",
      "info_url": "https:\/\/creativecommons.org\/licenses\/by-nc-sa\/3.0\/"
    },
    "popularity": 0,
    "source": "BBC",
    "source_url": "http:\/\/www.bbc.co.uk\/music\/reviews\/3vfd",
    "text": "TEXT CONTENT OF REVIEW",
    "rating": 5,
    "user": {
      "created": "Wed, 07 May 2014 14:55:23 GMT",
      "display_name": "Paul Clarke",
      "id": "f5857a65-1eb1-4574-8843-ae6195de16fa",
      "karma": 0,
      "user_type": "Noob"
    },
    "votes": {
      "positive": 0,
      "negative": 0
    }
  }
}
Status Codes:
Response Headers:
 
DELETE /review/(uuid: review_id)

Delete review with a specified UUID.

OAuth scope: review

Request Example:

$ curl "https://critiquebrainz.org/ws/1/review/9cb11424-d070-4ac1-8771-a8703ae5cccd" \
       -X DELETE \
       -H "Authorization: Bearer <access token>"

Response Example:

{
  "message": "Request processed successfully"
}
Status Codes:
Response Headers:
 
POST /review/(uuid: review_id)

Update review with a specified UUID.

OAuth scope: review

JSON Parameters:
 
  • text (string) – Text part of review, min length is 25, max is 5000 (optional)
  • rating (integer) – Rating part of review, min is 1, max is 5 (optional)

NOTE: Please provide only those parameters which need to be updated

Status Codes:
Response Headers:
 

Users

GET /user/me/applications

Get your applications.

Request Example:

$ curl "https://critiquebrainz.org/ws/1/user/me/applications" \
        -X GET \
        -H "Authorization: Bearer <access token>"

Response Example:

{
  "applications": [
    {
      "website": "https:\/\/your-website.com",
      "user_id": "your-unique-user-id",
      "name": "Name of your Application",
      "redirect_uri": "https:\/\/your-call-back.com/uri",
      "client_id": "your Oauth client ID",
      "client_secret": "your super-secret Oauth client secret",
      "desc": "Application description set by you."
    }
  ]
}
Response Headers:
 
GET /user/me/reviews

Get your reviews.

Response Headers:
 
GET /user/me/tokens

Get your OAuth tokens.

Request Example:

$ curl "https://critiquebrainz.org/ws/1/user/me/tokens" \
        -X GET \
        -H "Authorization: Bearer <access token>"

Response Example:

{
  "tokens": [
    {
      "scopes": "user",
      "client": {
        "website": "https:\/\/your-website.com",
        "user_id": "your-unique-user-id",
        "name": "Name of your Application",
        "redirect_uri": "https:\/\/your-call-back.com/uri",
        "client_id": "your Oauth client ID",
        "client_secret": "your super-secret Oauth client secret",
        "desc": "Application description set by you."
      },
      "refresh_token": "refresh token generated for your Oauth authorization code"
    }
  ]
}
Response Headers:
 
GET /user/me

Get your profile information.

Request Example:

$ curl "https://critiquebrainz.org/ws/1/user/me" \
       -X GET \
       -H "Authorization: Bearer <access token>"

Response Example:

{
  "user": {
    "display_name": "your_display_name",
    "created": "Fri, 02 Dec 2016 19:02:47 GMT",
    "show_gravatar": true,
    "user_type": "Noob",
    "email": "your_email_id",
    "karma": 0,
    "musicbrainz_username": "username/id associated with musicbrainz",
    "id": "your-unique-user-id",
    "avatar": "https:\/\/gravatar.com\/your-gravatar-link"
  }
}
Query Parameters:
 
  • inc – includes
Response Headers:
 
POST /user/me

Modify your profile.

OAuth scope: user

Request Headers:
 
JSON Parameters:
 
  • display_name (string) – Display name (optional)
  • email (string) – Email address (optional)
  • show_gravatar (boolean) – Show gravatar (optional)
Response Headers:
 
DELETE /user/me

Delete your profile.

OAuth scope: user

Request Example:

$ curl "https://critiquebrainz.org/ws/1/user/me" \
       -X DELETE \
       -H "Authorization: Bearer <access token>"

Response Example:

{
  "message": "Request processed successfully"
}
Response Headers:
 
GET /user/

Get list of users.

Request Example:

$ curl "https://critiquebrainz.org/ws/1/user/?offset=10&limit=3" \
       -X GET

Response Example:

{
  "count": 925,
  "limit": 3,
  "offset": 10,
  "users": [
    {
      "created": "Wed, 07 May 2014 14:46:58 GMT",
      "display_name": "Display Name",
      "id": "b291a99b-7bb0-4531-ba45-f6cfb4d944de",
      "karma": 0,
      "user_type": "Noob"
    },
    {
      "created": "Wed, 07 May 2014 14:46:59 GMT",
      "display_name": "Name comes here",
      "id": "a52e1629-a516-43c2-855f-bb195aeb2a33",
      "karma": 3,
      "user_type": "Noob"
    },
    {
      "created": "Wed, 07 May 2014 14:47:00 GMT",
      "display_name": "Display Name",
      "id": "1fb36917-d4d3-411b-82c4-901d949e17b8",
      "karma": 0,
      "user_type": "Noob"
    }
  ]
}
Query Parameters:
 
  • limit – results limit, min is 0, max is 50, default is 50 (optional)
  • offset – result offset, default is 0 (optional)
Response Headers:
 
GET /user/(uuid: user_id)

Get profile of a user with a specified UUID.

Request Example:

$ curl https://critiquebrainz.org/ws/1/user/ae5a003f-292c-497e-afbd-8076e9626f2e \
       -X GET

Response Example:

{
  "user": {
    "created": "Wed, 07 May 2014 14:47:03 GMT",
    "display_name": "User's Name comes here",
    "id": "ae5a003f-292c-497e-afbd-8076e9626f2e",
    "karma": 0,
    "user_type": "Noob"
  }
}
Response Headers:
 

OAuth

See OAuth documentation for more info.

POST /oauth/token

OAuth 2.0 token endpoint.

Form Parameters:
 
  • string client_id
  • string client_secret
  • string redirect_uri
  • string grant_typeauthorization_code or refresh_token
  • string code – (not required if grant_type is refresh_token)
  • string refresh_token – (not required if grant_type is authorization_code)
Response Headers: