Programmatic battery control,
for optimisers.

Juicy assigns specific batteries to your account. You see only those batteries; the API rejects access to anything you don't own.

You control batteries by submitting flex plans — a list of time-bounded blocks describing what the battery should do during each window. The agent on each battery applies the active block; outside any block, it falls back to the customer's local control mode.

Plans are snapshot: every POST .../flex-plan replaces the previous plan for that battery in full. Agents pick up changes within ~30 seconds (WebSocket push) and back-stop with a 5-minute poll, so a missed push never strands a battery in stale steering.

Step 1 — Generate a keypair and CSR

You generate the keypair on your side. Your private key never leaves your infrastructure — non-repudiation is the foundation of the trust model.

# 1. Private key (4096-bit RSA; keep this file safe)
openssl genrsa -out partner.key 4096

# 2. Certificate Signing Request
#    Use your company name or service name as the Common Name.
openssl req -new -key partner.key -out partner.csr \
    -subj "/CN=your-company"

Step 2 — Send us the CSR

Email chris@juicy.energy with partner.csr attached. We'll sign it with the Juicy Partner CA and return a PEM certificate via a secure channel.

Keep your partner.key private. Never email it. Never check it in; it's what proves you are you, and we'll keep an audit trail of actions intiated by this key. - If you think the key has been compromised contact us immediately and we'll revoke it's access.

Step 3 — Use the signed cert

Save the cert we send back as partner.crt. Pair it with your private key on every request:

curl --cert partner.crt --key partner.key \
     https://partner.juicy.energy/v1/optimiser/batteries

Step 4 — Confirm assignment

We'll let you know once batteries have been assigned to you. Until then, the list will be empty (HTTP 200 with []).

The platform doesn't just prove that a request could have come from you — it ties every action to a specific, named partner certificate whose private key only you hold. Here's how that maps to the four classical non-repudiation primitives:

Strategies

Limits

• Up to 2000 blocks per plan.
• Block end_time_ms must be in the future (60-second grace for clock skew) and within a 7-day horizon from now.
• Blocks within a single submission must not overlap — we reject the whole plan with HTTP 422 if any pair overlaps.
• setpoint_w / max_power_w may not exceed the battery's max_power_kw × 1000. Read the battery's limits first via GET /v1/optimiser/batteries/{id}.
• FCR / aFRR strategies are not supported in v1 — submissions are rejected with 422.

Submitting a plan

POST /v1/optimiser/batteries/<battery-id>/flex-plan
Content-Type: application/json

{
  "blocks": [
    {
      "start_time_ms": 1715600000000,
      "end_time_ms":   1715603600000,
      "strategy": "self_consumption"
    },
    {
      "start_time_ms": 1715603600000,
      "end_time_ms":   1715607200000,
      "strategy": "fixed_power_setpoint",
      "setpoint_w": -3000
    }
  ]
}

Response:

{
  "battery_id": "…",
  "revision": 7,
  "accepted_block_count": 2,
  "effective_at": "2026-05-13T10:15:42Z"
}

Clearing

DELETE /v1/optimiser/batteries/<battery-id>/flex-plan

Clears the plan and falls the battery back to local control.

Checking current plan (idempotency)

GET /v1/optimiser/batteries/<battery-id>/flex-plan

Returns the latest revision plus the full block list. Useful before a resubmit to confirm you're not double-applying.

• Agent reconnects. If a battery's agent goes offline and comes back, the API immediately re-pushes the current plan. You don't need to retransmit on connectivity blips.
• WS push best-effort. Treat the post-POST window as eventually-consistent within ~5 minutes (agent's poll interval). For tight timing, schedule blocks at least a few seconds in the future.
• Only operates when AUTO. If a customer manually forces their battery into charge/discharge/idle from the Juicy UI, partner steering yields until they return to AUTO.
• No rate limiting in v1, but please be sensible — 1 req/s/battery is plenty for any normal optimisation cadence.