Reviews

Reviewable items are upserted on first submission. Average + count aggregates on reviewable_items are recomputed on every write.

Endpoints

POST /client/reviews

Request (SubmitReviewInput)

item_type is content_item or custom. item_id is a non-empty string of at most 256 characters (a whole JSON number is read as its digits). rating is a whole number from 1 to 5, as a JSON number or a digit string. The SDKs send the same pair as target_type and target_id, and the route reads either spelling.

Response 201

{
  "data": {
    "id": "…",
    "reviewable_item_id": "…",
    "app_user_id": "…",
    "rating": 5,
    "title": "…",
    "body": "…",
    "is_approved": true,
    "created_at": "…",
    "updated_at": "…",
    "author_id": "…",
    "target_type": "custom",
    "target_id": "…"
  }
}

author_id, target_type and target_id are the SDKs' Review fields: the author's user id and the reviewed item.

Errors

• 400 INVALID_ITEM_TYPE — item_type is not content_item or custom.
• 400 INVALID_ITEM_ID — item_id is missing, empty or longer than 256 characters.
• 400 INVALID_RATING — rating is not a whole number from 1 to 5.
• 400 INVALID_INPUT — the body is not a JSON object, or title / body is not a string.
• 409 ALREADY_REVIEWED — one review per (user, item).
• 500 CREATE_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/client/reviews' \
  -H 'Content-Type: application/json' \
  -d '{
  "item_id": "<item_id>",
  "rating": 5
}'

Curl:

curl -X POST "${BASE_URL}/client/reviews" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"item_id":"<item_id>","rating":5}'

GET /client/reviews/item/:itemType/:itemId

Approved reviews only, plus item aggregates.

Query

Response 200

{
  "data": [
    { "id": "…", "rating": 5, "app_users": { "id": "…", "display_name": "…", "avatar_url": "…" } }
  ],
  "total": 42,
  "offset": 0,
  "limit": 20,
  "avg_rating": 4.3,
  "review_count": 42
}

Try it:

curl -X GET 'https://api.amba.dev/v1/client/reviews/item/%7B%7BitemType%7D%7D/%7B%7BitemId%7D%7D'

Curl:

curl -X GET "${BASE_URL}/client/reviews/item/{itemType}/{itemId}" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}"

GET /client/reviews/mine

Response 200

{
  "data": [
    { "id": "…", "rating": 5, "reviewable_items": { "item_type": "product", "item_id": "…" } }
  ]
}

Try it:

curl -X GET 'https://api.amba.dev/v1/client/reviews/mine'

Curl:

curl -X GET "${BASE_URL}/client/reviews/mine" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}"

PATCH /client/reviews/:reviewId

Update rating, title, and/or body. Only the review's author can edit — others get 404 UPDATE_FAILED. The response is the updated review in the POST response's shape, author_id, target_type and target_id included.

Errors

• 400 INVALID_INPUT — no updatable fields, or title / body is not a string.
• 400 INVALID_RATING — rating is not a whole number from 1 to 5.
• 404 UPDATE_FAILED.
• 500 UPDATE_FAILED.

Try it:

curl -X PATCH 'https://api.amba.dev/v1/client/reviews/%7B%7BreviewId%7D%7D' \
  -H 'Content-Type: application/json' \
  -d '{
  "rating": 4
}'

Curl:

curl -X PATCH "${BASE_URL}/client/reviews/{reviewId}" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"rating":4}'

DELETE /client/reviews/:reviewId

Only the author can delete. Aggregates on reviewable_items are recomputed.

Response 200

{ "data": { "deleted": true } }

Try it:

curl -X DELETE 'https://api.amba.dev/v1/client/reviews/%7B%7BreviewId%7D%7D'

Curl:

curl -X DELETE "${BASE_URL}/client/reviews/{reviewId}" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}"