Partner API — Overview
How an ESM partner connects to Voke — the two transports, the seven message families, the HTTP reverse channel Voke uses to talk back, and where to go for each.
Partner API overview
This page is the map. It names the surfaces a partner integrator needs to know about — the two transports, the message families flowing each way, and the HTTP channel Voke uses to call back into your platform. Each section ends with pointers to the dedicated page where the wire-level detail lives.
Runnable examples on GitHub: lefteq/voke-partner-examples
has verified, clone-and-run Java (Spring Boot) and TypeScript clients covering everything on these
pages — AMQPS telemetry, REST reads, and HMAC-signed commands.
You are an ESM
An ESM (energy system management) partner is an external platform that dispatches optimisation commands to energy assets — solar inverters, battery systems, EV chargers — and consumes the telemetry, alarms, and command results those assets produce. Voke sits between you and the hardware.
The scope boundary is firm: Voke handles the broker, the persistence, and last-mile delivery to plants. You never connect to Mosquitto. You speak to Voke in Voke's wire format (VCP); one credential bundle gets you both transports.
Where to start. If your org admin has provisioned an API key for you, the bundle they handed
over (AMQPS URI + raw key + signing key) is everything you need — jump to
Quick start. If they haven't, ask them to walk through
/orgs/<orgId>/settings/connections?tab=api-keys → Connect partner.
You connect via AMQPS + REST
Production partners use two transports against the same set of public hostnames.
| Transport | Endpoint | Carries |
|---|---|---|
| AMQPS | amqp.voke.turena.cz:5671 | All real-time message exchange — commands you publish, events Voke publishes back |
| REST | https://api.voke.turena.cz/api/v1/vcp/sites | Historical telemetry, site config, meter readings, schedules, command history |
Your org admin mints a single API key for your integration via the Connect partner wizard. The reveal screen returns a bundle containing the AMQPS URI (org slug as username, key as password, per-key vhost partner-{keyId} as path — all pre-encoded), the raw API key, and — for orgs with write scopes — an HMAC signing key. The bundle is shown exactly once.
→ Auth detail: API keys & auth · REST authentication · AMQP authentication
What you send to Voke
Three message families travel partner → Voke over AMQPS. Each family has its own dedicated queue and a routing-key family prefixed with your org slug.
| Family | Queue | Example routing keys |
|---|---|---|
| Command | vcp.{slug}.command | {slug}.command.site-setpoint, {slug}.command.device, {slug}.command.emergency |
| Config | vcp.{slug}.config | {slug}.config.constraints, {slug}.config.topology, {slug}.config.fallback |
| Schedule | vcp.{slug}.schedule | {slug}.schedule.create, {slug}.schedule.cancel |
Site setpoints are authenticated by the AMQP credential pair and the vcp:write:setpoint scope alone. Higher-risk routes (command.device, command.mode, schedule.*) also require an HMAC signature.
→ Commands · VCP data model · VCP message integrity
What you receive from Voke
Four message families travel Voke → partner on dedicated outbound queues. You consume; Voke publishes.
| Family | Queue | Example routing keys |
|---|---|---|
| Telemetry | vcp.{slug}.event.telemetry | {slug}.event.telemetry.realtime.{siteId}, {slug}.event.telemetry.meter.{siteId} |
| Status (ACK / NACK) | vcp.{slug}.event.status | {slug}.event.command.ack, {slug}.event.mode.*, {slug}.event.schedule.* |
| Alarm | vcp.{slug}.event.alarm | {slug}.event.alarm.* |
| Execution | vcp.{slug}.event.execution | {slug}.event.execution.* |
Telemetry covers both real-time samples and 1-minute meter readings. Status carries the lifecycle for every command you publish — ACK/NACK plus mode and schedule state transitions. Alarm covers operational alarms Voke raises against the site. Execution carries progress updates for dispatched commands.
→ Telemetry ingress · Alarms · Errors & retries
What Voke pulls from you (HTTP reverse channel)
In addition to the AMQPS message exchange, Voke periodically calls your ESM's HTTP API to fetch site configuration and time-block schedules. This is a reverse channel — Voke is the HTTP client, you are the server.
Your ESM must expose four endpoints under whichever base URL you give to Voke at onboarding time:
| Method | Path | Purpose |
|---|---|---|
POST | /trading/token | Token endpoint. Accepts JSON { clientId, clientSecret }; returns { accessToken, expiresIn }. The token is a JWT that Voke uses as a bearer credential on the other three endpoints. |
GET | /trading/plant/list | Lists the plants your ESM manages for this org. |
GET | /trading/plant/config?plantId={externalId} | Returns the current time-config blocks (e.g. allowable charge/discharge windows + SOC limits) for a plant. |
POST | /trading/plant/config/update | Accepts a config-update request and returns a result code (terminal / non-terminal). |
Your org admin registers your ESM API URL, client ID, and client secret on the Voke side once; Voke calls these endpoints on a schedule from then on.
Next: Quick start
The Quick start walks you from zero to live telemetry in about 15 minutes using the Voke ESM sandbox built into every Voke deployment — no real partner hardware required.