APIs
Software outside the cluster talks to HEAT through the HEAT v2 API. It authenticates with a token from HEAT Auth, creates a Session in a Project from a session template, and uploads bytes to a node instance of that session. Everything after that is the template’s job.
Results leave HEAT the same way. The Reports API exports assessment results across sessions as CSV or XLSX files, and the outputs routes return the stored results of a single node instance.
The v2 API is the only API surface available to integrators. It is plain HTTP, so any language with an HTTP client can use it. HEAT does not ship a client library for integrations. The one SDK it ships, the HEAT Runner SDK, is for building runners (see below). Offline tokens make unattended use easier. They are long-lived tokens for devices that cannot sign in interactively.
Neither of these is how a Runner talks to HEAT. Runners claim tasks through their own runner routes with runner tokens. See the note at the end of this page.
An integration from start to finish
Every step of an integration is a v2 route. The table follows one session from creation to its results.
| Step | Route | Notes |
|---|---|---|
| Find a project and a session template | GET /api/v2/project, GET /api/v2/session/session_templates | Fetch one template with GET /api/v2/session/session_templates/{id} to see its nodes and find the input nodes. |
| Create a session | POST /api/v2/session | The response lists the node instances of the new session with their ids. |
| Upload data | POST /api/v2/node-instance/{nodeInstanceId}/outputs/data | Send the raw bytes to an input node. Processing starts from there. |
| Check progress | GET /api/v2/session/{id}/node-instances | One row for each node with its state, and a count for each state. Poll it until the nodes you need are Succeeded. |
| View the dashboard | GET /api/v2/dashboard/{dimensionId}, /layout-config and /data | Dimension ids come from GET /api/v2/session/{id}. |
| Download results | GET /api/v2/node-instance/{nodeInstanceId}/outputs/latest/data | The newest output of a node. List every output with GET /api/v2/node-instance/{nodeInstanceId}/outputs. |
| Read and write session metadata | GET /api/v2/session/{id}, PATCH /api/v2/session/{id} | Metadata is also on every row of the session list. |
| Find sessions later | GET /api/v2/session | Paged, with project, session template and text filters. |
| Export a summary of many sessions | Reports API | CSV or XLSX built from session metadata. |
| Collect a scheduled analysis | GET /api/v2/dashboard/statics | Gives the backing session of each system dashboard. See Cross-session analysis. |
The HEAT v2 API reference documents each route with its roles, parameters and responses.
The surfaces
HEAT v2 API
The v2 API is the supported external HTTP surface. It covers session templates, sessions and the session list, node instance progress, uploads and outputs, projects, platform configuration, system dashboards, dashboard catalog routes, reports and offline token administration. Every call carries Authorization: Bearer <token>.
Read the HEAT v2 API reference for authentication, endpoints, request and response shapes and error handling. The reference states where a contract is still settling.
Reports API
The Reports API is the part of the v2 API that exports assessment results. A report is a table with one row per session dashboard and user, and columns that an administrator or developer defines. It downloads as CSV or XLSX, ready for a learning record system or a spreadsheet. A report reads fixed per-session records and the session metadata. It is not a query over session data, so a session template writes the values you want to report into the session metadata.
Read Reports API for the catalog, the download route and report definitions.
Offline tokens
An offline token is a HEAT Auth token that lives for twelve months and is meant for capture devices and unattended uploaders. An administrator creates it once, stores it on the device, and the device presents it on every upload. Offline tokens can upload, list and edit. They cannot administer users or create further tokens.
Read Offline tokens for creation, listing, revocation and the security notes.
Which to use
| You are building | Use | Why |
|---|---|---|
| An application, service or simulator plug-in in any language that pushes data into HEAT | v2 API | Plain HTTP with bearer tokens. Any HTTP client works. |
| A capture device or unattended uploader that cannot sign in each time | v2 API with an offline token | Twelve-month lifetime, upload-scoped by design |
| A scheduled job or external system that collects a high-level summary of sessions | Reports API | One CSV or XLSX file across sessions, filtered by date and user. Reads the key metrics each session template wrote into session metadata. |
| Deep analysis across many sessions, such as one trainee’s history or every session of one kind | Not an API query. Author a cross-session analysis template | The analysis runs on the platform’s runners and can run on a schedule. You find its session with GET /api/v2/dashboard/statics and download the report artefact through the v2 outputs routes. |
| A one-off script to list or fetch the outputs of a node instance | v2 API outputs routes | Read-only, no processing is triggered |
| A fixed sender that should not know about projects or templates | An Ingest | A managed upload URL configured by an operator in the Control Centre. No API knowledge needed on the sender. |
| A processing step that runs on data already in HEAT | Not an API. Author a node in the template, or an Arbex script | Processing happens inside the platform through runners |
| Your own processing step, as a runner image you build, test and ship yourself | The HEAT Runner SDK | Registers node templates for your runner and runs them against the v2 runner routes, inside the cluster or from your own hosts |
Runtimes that are not client APIs
HEAT has runtime libraries, and none of them is a client API for integrators.
- The HEAT Runner SDK is for building runners of your own: install it, write a processor, test it against captured fixtures, and run it from your machine or ship it as an image. It talks only to the v2 runner routes with a runner token. It is not a way to create sessions or upload data. See Building runners with the HEAT Runner SDK.
- The Python
heat-runtimelibrary is what the platform’s own runners use inside the cluster. It is documented under Building your own runner for teams that build runners alongside the platform. - Sandboxed JavaScript that runs inside the platform is the
system-arbex-jsnode template, documented under Arbex. It cannot call the platform or the network. - The platform’s own services and tools share internal libraries. Those are not distributed and are not a supported integration surface.
Client libraries for the integration routes of the v2 API are not available today. Use the v2 API reference with any HTTP client.
Related
- HEAT v2 API
- Reports API
- Offline tokens
- Ingests in the Control Centre
- Build your first data flow, which uploads through both an ingest and the v2 API