Choose an integration
REST API, signed embed, public link or MCP server. A decision table for what each is for and who it reads as, with one example of each.
Halo offers four ways in. Start from what should happen to the data: your code uses it, your readers look at it, anyone may see it, or an AI tool reads it.
| REST API | Signed embed | Public link | MCP server | |
|---|---|---|---|---|
| Use it when | Your code needs the numbers | A report sits inside your product, with each reader seeing their own rows | Anyone with the address may see a report | An AI tool reads data for someone |
| You get | JSON: rows and columns, chart specs, report documents | A live report in an iframe | A report page | Text a model can read |
| Reads as | The person who made the key | The reader your token describes | Nobody, so a dataset with row policies shows no rows | The person who connected the tool |
| Your readers need a Halo account | No | No | No | Yes |
| Credential | hak_… | A JWT signed with hes_… | hlp_… | hpat_… or hmat_… |
| Reads | Any dataset, chart or report the person can | One published report | One published report | Any dataset, chart or report the person can |
| Rows | 1,000 a request, with paging, and a daily budget by plan | The fields the report uses, within your locked filters and row policies | Any values of the fields the report uses | 200 a query, or 1,000 where allowed, and 20,000 a day |
| Before it works | An Admin turns it on. It's off by default | An Admin makes a secret and lists your site | Someone with share rights makes a link | An Admin turns it on. It's off by default |
REST API: your code reads the numbers
Use it for syncing rows out, powering your own charts, or sending a number somewhere.
curl -sS -X POST "https://api.usehalo.net/v1/developer/datasets/$DATASET_ID/query" \
-H "Authorization: Bearer $HALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "dimensions": [{ "field": "region" }], "measures": [{ "field": "revenue" }] }'Start with the Quickstart.
Signed embed: a report in your product
Your server signs a short-lived token that names the report, its locked filters and the reader's attributes. Your readers don't need a Halo account.
<script type="module" src="https://cdn.usehalo.net/halo-report.js"></script>
<halo-report token="SIGNED_EMBED_TOKEN" origin="https://{org}.usehalo.net"></halo-report>Start with Signed embeds, or follow Embed a report in Next.js.
Public link: a report for anyone
The link is the only key. Anyone who has it can open the report and pass it on, so use one only for numbers you'd be happy to see forwarded. It can reach only the datasets and fields the report uses, but within those it can ask for any values.
https://{org}.usehalo.net/r/hlp_…Public links can't be framed on other sites. To put a report on your site with no signing, use an embed link (hle_…) instead. See Public links and snapshots.
MCP server: an AI tool reads data
The tool reads as the person who connected it, can't change anything, and picks the tools it calls.
claude mcp add --transport http halo https://mcp.usehalo.net/mcpStart with The MCP server, and compare it with REST.
Websites and the directory
The REST API and the MCP server also read Halo CMS and Halo CRM: see Read websites and the directory. Two more ways work with the directory. Webhooks tell your systems when it changes, and a webhook source lets your systems add to it.
If you need two
They work side by side, and each has its own credential. A common pair is a signed embed for what your readers see, and a nightly REST sync for what your own systems need.