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

• Content-Type – application/json

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
      }
    }
  ]
}

Query Parameters

• entity_id – UUID of an entity to retrieve reviews for (optional)

• entity_type – musicbrainz (for reviews about MusicBrainz entities) or bookbrainz (for reviews about bookbrainz entities) or one of the following entity types critiquebrainz.db.review.ENTITY_TYPES (optional)

• user_id – user’s UUID (optional)

• sort – popularity or published_on (optional). Defaults to published_on

• sort_order – asc or desc (optional). Defaults to desc

• 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)

• review_type – review or rating. If set, only return reviews which have a text review, or a rating (optional)

• include_metadata – true or false. Include metadata of the entity (optional)

NOTE: If entity_id is provided, then additional top-level item “average_rating” which includes the average of all ratings for this entity and the total count of these ratings is also included.

Response Headers

• Content-Type – application/json

POST /review/

Publish a review.

OAuth scope: review

Request Headers

• Content-Type – application/json

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

• language (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

• Content-Type – application/json

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

• 200 OK – no error

• 404 Not Found – review not found

Response Headers

• Content-Type – application/json

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

• 200 OK – no error

• 404 Not Found – review not found

Response Headers

• Content-Type – application/json

POST /review/(uuid: review_id)/report

Create spam report for a specified review.

OAuth scope: vote

Response Headers

• Content-Type – application/json

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

• Content-Type – application/json

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

• 200 OK – success

• 400 Bad Request – invalid request (see source)

• 403 Forbidden – daily vote limit exceeded

• 404 Not Found – review not found

Response Headers

• Content-Type – application/json

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

• Content-Type – application/json

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

• 200 OK – no error

• 404 Not Found – review not found

Response Headers

• Content-Type – application/json

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

• 200 OK – success

• 403 Forbidden – access denied

• 404 Not Found – review not found

Response Headers

• Content-Type – application/json

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

• 200 OK – success

• 400 Bad Request – invalid request

• 403 Forbidden – access denied

• 404 Not Found – review not found

Response Headers

• Content-Type – application/json

GET /reviews/

Get a list of reviews with specified UUIDs.

Hidden reviews are omitted from the response. UUIDs which are not valid result in an error. UUIDs which are not review ids are omitted from the response.

The returned data is a dictionary where each key is the review id. This UUID is formatted in the canonical UUID representation and may be different from the UUID that was passed in as the query parameter. A mapping of user-provided UUIDs to canonical representation is provided in the review_id_mapping element of the response.

Request Example:

$ curl https://critiquebrainz.org/ws/1/reviews?review_ids=B7575C23-13D5-4ADC-AC09-2F55A647D3DE,e4364ed2-a5db-4427-8456-ea7604b499ef \
       -X GET

Response Example:

{
  "reviews": {
    "b7575c23-13d5-4adc-ac09-2f55a647d3de": {
      "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
      }
    },
    -- more reviews here --
  },
  "review_id_mapping": {
    "B7575C23-13D5-4ADC-AC09-2F55A647D3DE": "b7575c23-13d5-4adc-ac09-2f55a647d3de"
  }
}

Status Codes

• 200 OK – no error

• 400 Bad Request – Too many review ids were requested, or a provided review id isn’t a valid UUID

• 503 Service Unavailable – Query string is too long

Query Parameters

• review_ids – a comma-separated list of review IDs to retrieve.

Response Headers

• Content-Type – application/json

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

• Content-Type – application/json

GET /user/me/reviews

Get your reviews.

Response Headers

• Content-Type – application/json

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

• Content-Type – application/json

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",
    "user_type": "Noob",
    "email": "your_email_id",
    "karma": 0,
    "musicbrainz_username": "username/id associated with musicbrainz",
    "id": "your-unique-user-id"
  }
}

Query Parameters

• inc – includes

Response Headers

• Content-Type – application/json

POST /user/me

Modify your profile.

OAuth scope: user

Request Headers

• Content-Type – application/json

JSON Parameters

• display_name (string) – Display name (optional)

• email (string) – Email address (optional)

Response Headers

• Content-Type – application/json

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

• Content-Type – application/json

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

• Content-Type – application/json

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

• Content-Type – application/json

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_type – authorization_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

• Content-Type – application/json

Constants

Constants that are relevant to using the API:

critiquebrainz.db.review.ENTITY_TYPES = ['event', 'place', 'release_group', 'work', 'artist', 'label', 'recording', 'bb_edition_group', 'bb_literary_work', 'bb_author', 'bb_series']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.