Developer Docs

BlooTrue API

Read your widgets and reviews as JSON, from your own code or from automation tools like viaSocket, Zapier, Make and n8n. The API is read only: it never changes anything in your account.

Get your API key

API access is included in every paid plan (Starter and up). In the BlooTrue app, open Settings > API and click Create API key. Keys look like bt_live_ followed by 32 characters. Keep yours private: anyone with it can read your widgets and reviews. If it leaks, create a new key on the same screen; the old one stops working at once.

Authentication

Send the key with every request, in the Authorization header (or as X-API-Key). All endpoints are GET and return JSON.

curl https://api.blootrue.com/api/v1/me \
  -H "Authorization: Bearer bt_live_YOUR_KEY"

Base URL: https://api.blootrue.com/api/v1

Endpoints

`GET /me`

The account the key belongs to and its plan. Use it to test a connection.

{
  "account": { "id": "65f0...", "email": "owner@example.com", "business_name": "Example Plumbing" },
  "plan": "widget_starter"
}

`GET /widgets`

Your review widgets, newest first. id is the widget's embed id, the same one in your embed code.

{
  "data": [
    {
      "id": "aBcD3fGh1jKl",
      "name": "Homepage slider",
      "type": "slider",
      "source": "google",
      "sources": ["google"],
      "active": true,
      "rating": 4.8,
      "review_count": 214,
      "created_at": "2026-08-02T14:03:11.000Z",
      "updated_at": "2026-10-12T08:41:52.000Z"
    }
  ]
}

`GET /widgets/{id}/reviews`

The reviews that widget shows on your site, in its order: the same business, star filter and number of reviews you set in the widget editor.

{
  "data": [ {
    "id": "6712f0c4a1b2c3d4e5f60718",
    "source": "google",
    "rating": 5,
    "text": "Fast, friendly and fair. Would hire again.",
    "author_name": "Ann Smith",
    "author_photo_url": "https://...",
    "review_date": "2026-10-14T09:12:00.000Z",
    "created_at": "2026-10-15T03:00:41.000Z",
    "review_url": "https://...",
    "reply_text": "Thanks Ann!",
    "reply_date": "2026-10-15T10:20:00.000Z",
    "photos": []
  } ],
  "widget": {
    "id": "aBcD3fGh1jKl",
    "name": "Homepage slider",
    "type": "slider",
    "source": "google",
    "sources": ["google"],
    "active": true,
    "rating": 4.8,
    "review_count": 214,
    "created_at": "2026-08-02T14:03:11.000Z",
    "updated_at": "2026-10-12T08:41:52.000Z"
  }
}

`GET /reviews`

Your reviews, newest first by when BlooTrue stored them (created_at), every star rating. This is the endpoint for a new review trigger: poll it and treat any id you have not seen as new.

Parameter	What it does
`since`	Only reviews stored after this time. ISO 8601, for example 2026-10-01T00:00:00Z.
`widget_id`	Only the reviews of that widget's business and platforms.
`min_rating`	Only reviews with at least this many stars, 1 to 5.
`limit`	How many to return, 1 to 100. Default 50.

curl "https://api.blootrue.com/api/v1/reviews?since=2026-10-01T00:00:00Z&min_rating=4" \
  -H "Authorization: Bearer bt_live_YOUR_KEY"

Widget fields

Field	What it holds
`id`	The widget's embed id, the same one in your embed code. Use it with /widgets/{id}/reviews and widget_id.
`name`	The name you gave the widget in BlooTrue.
`type`	The layout: slider, grid, list, masonry, wall, marquee, review-spotlight, slider-summary, slider-rated, or one of the badge styles (badge, badge-compact, badge-score, badge-rating, badge-stars and others starting with badge-).
`source`	The review platform: google, yelp, facebook, tripadvisor, bbb, angi, g2, capterra, glassdoor, indeed, trustradius, clutch, ratemds, expedia, agoda, etsy, googleplay, opentable, booking, airbnb or trustpilot. mixed = an all-in-one widget with several platforms.
`sources`	The platforms whose reviews the API returns for this widget. Trustpilot is never listed, so a Trustpilot widget has an empty list.
`active`	true when the widget is switched on.
`rating`	The platform's average rating shown in the widget header, or null.
`review_count`	The platform's total review count shown in the widget header, or null.
`created_at, updated_at`	When the widget was created and last changed, ISO 8601 in UTC.

Review fields

id: stable, unique per review. Use it to spot new reviews.
source: the platform, for example google, yelp, facebook, tripadvisor.
review_date: when the reviewer wrote it. created_at: when BlooTrue stored it.
review_url: the review on the platform, when the platform gives one.
reply_text and reply_date: your reply, or null.

New reviews appear once BlooTrue has synced them from the platform. The API reads what is already stored, so polling it never slows down your widgets.

Limits and errors

Up to 120 requests a minute per key. Over that you get 429 with a Retry-After header. Trustpilot reviews are not available through the API.

Status	Code	Meaning
401	`invalid_api_key`	Missing, wrong or replaced key.
403	`plan_required`	The account is on the free plan.
404	`not_found`	No such widget on your account, or no such endpoint.
400	`invalid_parameter`	A parameter has the wrong format.
429	`rate_limited`	Too many requests. Wait for Retry-After.
500	`server_error`	Something failed on our side. Retry in a minute.

{ "error": { "code": "invalid_api_key", "message": "This API key is not valid. ..." } }

Support

Questions, a bug, or building an integration? Email info@blootrue.com and include the request you sent and the error you got back. Never send your API key.

How widgets are crawled and indexed is in the widget SEO docs →