REST API basics
The same operations as the MCP tools, as JSON over HTTP. The shapes worth knowing and where the full reference lives.
The REST API is for CI scripts and clients without MCP. Same operations, same validation, same error shape as the tools.
Basics
- Base URL:
https://app.tileset.com. - Auth:
Authorization: Bearer <API key>on every call. See API keys. - Bodies are JSON. A bad value returns an error with
field,receivedandallowed, so a script can correct itself. Creating a widget and changing one refuse a bad value the same way.
The calls you will use
| Call | Does |
|---|---|
POST /v1/sources | Connect a source: type, "mode": "live", plus one of: query (Google), channelHandle (YouTube), pinterestUrl (a Pinterest profile or board link), xHandle (an X @handle or profile link), twitchChannel (a Twitch channel name or twitch.tv link), kickChannel (a Kick channel name or kick.com link). label is optional: leave it out and the source is named after its account or business (a testimonials source takes only type and label). Without "mode": "live" you get a demo source with sample content; with it, a request missing its type's field answers 400 naming the field. |
GET /v1/sources, GET/PATCH/DELETE /v1/sources/:id | List, read, change or remove sources. PATCH takes label (rename), updateEvery, manualOnly and schedule. A PATCH with several parts saves all of them or none |
POST /v1/sources/:id/testimonials, GET /v1/sources/:id/testimonials | Add up to 20 testimonials (they wait for approval in the dashboard), or count the waiting, approved and filtered ones (only testimonials sent through the link are checked, never what a key adds). A key never reads the entries back. Approving, declining (one at a time or several at once), editing, deleting, the order and pausing or resuming the link answer an API key with 403: a person does those in the dashboard |
GET /v1/sources/:id/content | Counts for choosing a design: how many items, their dates and pace, star ratings, photos and videos, picture shapes, text lengths, writing systems and owner replies. Never the items. |
GET/POST /v1/bio, GET/PATCH/DELETE /v1/bio/:id | List or create Link in bio pages (name, the page's fields, and slug on Starter and up; without one the page is assigned an address), and read, change (blocks replaces the list, style changes only the keys you send) or delete one. POST /v1/bio/:id/blocks appends blocks, GET /v1/bio/slug?slug=<slug> checks whether an address is free, and GET /v1/bio/:id/analytics?days=7|30|90 returns views and link clicks (past 7 days needs a higher plan). A taken address answers 409; a page past the plan's count or a gated field answers 403 |
POST /v1/widgets | Create a widget from a source (sourceId, type, plus options), or from up to four with sourceIds for a mixed feed |
GET /v1/widgets, GET/PATCH/DELETE /v1/widgets/:id | List, read, change or delete widgets |
POST /v1/widgets/:id/check-page | Check a page for this widget (url): the same check as the verify_install tool. Answers verified, what it found in lines, and hints with a fix for each common mistake. A local or private address is refused with 400; 30 checks an hour |
GET /v1/credits, PATCH /v1/credits | Balance and projection; set the monthly cap |
GET /v1/prices | Public, no key: what an update costs per source type |
GET /v1/widgets/:id/content | Public, with CORS: the embed's own read, for display through the widget only (not a data API) |
POST /v1/hooks/:secret | A source's webhook (no key; the secret is the credential) |
An account holds at most 200 widgets.
Counts, never content
A key never reads your content: no call answers it with a post or a review. To see the result, open https://app.tileset.com/preview/<widgetId>, the widget as visitors see it. A failed source’s error reads as a fixed sentence.
Fair use
The fair use limits answer 429 with reason, why, limit and retryAt, plus a Retry-After header: wait until then, do not retry sooner. A business name search past the day’s limit answers 429 too. A new Google source past the day’s shared number connects with queued, and lists with firstFetchQueued true until its reviews arrive after 00:00 UTC.
Full reference
The complete, current reference is llms.txt. It is built from the same source as the MCP tools, so the two always agree. Your page itself never calls the API: it only loads the widget script.