Run a charging journey

A conformance suite checks that each endpoint obeys the specification. A charging journey drives a whole story against your partner: a session that starts, meters energy, completes and produces a CDR, with the tester judging the sequence as well as each exchange. Journeys run against a registered connection, take minutes rather than seconds, and stream evidence while they go. The flow is always the same four steps: browse the catalogue, preview a plan, start the run, follow it to a verdict.

1. Browse the catalogue

curl -fsS "https://evsim.synergyboat.com/api/v1/testing/journeys?targetId=$CONNECTION_ID" \
  -H "Authorization: Bearer $EVRT_KEY"

Returns the journey packs, scenarios and templates. With targetId, the list is filtered to what that connection can actually run, based on its OCPI version, its role and the modules it advertises, and the response includes the target’s capability summary. Omit targetId to see the full catalogue.

2. Preview a plan

A journey is described by a manifest: which template, against which target, on what clock. Previewing compiles it into an immutable plan and tells you whether it can run, before anything touches your partner.

curl -fsS -X POST "https://evsim.synergyboat.com/api/v1/testing/journeys/preview" \
  -H "Authorization: Bearer $EVRT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": 1,
    "journey": "first-successful-charge",
    "targetId": "'"$CONNECTION_ID"'",
    "roleUnderTest": "CPO",
    "journeyPack": "core-charging",
    "topology": { "kind": "direct", "profile": "core-ocpi" },
    "ocpiVersion": "2.2.1",
    "clock": { "mode": "accelerated", "durationSeconds": 1800, "accelerationFactor": 60 },
    "session": { "cadenceSeconds": 60, "strategy": "put-and-patch", "updates": ["kwh", "status"] },
    "completion": { "cdrDelaySeconds": 0 },
    "seed": "ci-2026-07-16"
  }'

The response carries the compiled plan and the two values the start call needs:

{
  "success": true,
  "data": {
    "planId": "...",
    "planHash": "...",
    "expiresInSeconds": 3600,
    "runAllowed": true,
    "plan": {}
  }
}

A plan expires after an hour. runAllowed: false means the preflight found a reason the run cannot proceed (an unregistered target, a module the target does not advertise); the plan spells out which.

3. Start the run, idempotently

curl -fsS -X POST "https://evsim.synergyboat.com/api/v1/testing/journey-runs" \
  -H "Authorization: Bearer $EVRT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-${CI_PIPELINE_ID}-journey" \
  -d "{\"planId\": \"$PLAN_ID\", \"planHash\": \"$PLAN_HASH\"}"

A 202 means the run was admitted and is active work, not a verdict:

{
  "success": true,
  "data": {
    "runId": "...",
    "reportId": "...",
    "status": "queued",
    "repeated": false,
    "statusUrl": "/api/v1/testing/journey-runs/...",
    "eventsUrl": "/api/v1/testing/journey-runs/.../events",
    "streamUrl": "/api/v1/testing/journey-runs/.../stream"
  }
}

Always send Idempotency-Key from CI. A repeated start with the same key returns the original run with repeated: true instead of creating a second one, so a retried pipeline step cannot double-charge your quota or hit your partner twice. The same key with a different body answers 409. The starts that do not admit a run:

Status	Meaning
`409`	The plan expired or its hash changed. Preview again and start with the fresh `planId` and `planHash`.
`429`	Your plan’s run quota is full. Each in-flight journey holds one run slot until it finishes, and a run waiting on a recovery decision keeps holding its slot until you decide. The `Retry-After` header says when to try again.
`503`	Our runner is unavailable. This is a statement about our service, never about your partner. Nothing was admitted and nothing reached the target. Start again later with the same `Idempotency-Key`; the key makes that safe.

4. Follow it to a verdict

curl -fsS "https://evsim.synergyboat.com/api/v1/testing/journey-runs/$REPORT_ID?wait=60" \
  -H "Authorization: Bearer $EVRT_KEY"

?wait=<seconds> long-polls until the run reaches a terminal state or the wait expires. The response carries status, the compiled plan, the current stage, the run’s verdicts once they exist, and the two fields the next two sections explain: runIntegrity and recoveryOptions.

What each status means

Status	Meaning
`queued`	Admitted, waiting for a runner.
`running`	The journey is executing against your partner.
`recovering`	Our runner restarted and is resuming from its checkpoint. No request is repeated; you do not need to do anything.
`recovery_required`	The delivery of one action is uncertain and the run is paused for your decision. See below.
`completed`	The journey finished and the verdicts are in. Finished is not the same as passed: read the verdicts.
`failed`	The journey could not finish.
`cancelled`	You cancelled it.
`interrupted`	The run ended early with its evidence preserved, for example because you chose to stop it during recovery.

Run integrity is about our evidence, not their conduct

runIntegrity states how complete our record of the run is:

Value	Meaning
`valid`	Every action’s outcome was observed. The verdicts rest on complete evidence.
`degraded`	Part of the run is unobservable, for example because you chose to continue past an uncertain action. Verdicts that depend on the gap say so.
`invalid`	The evidence cannot support verdicts.

A degraded or invalid run is never a statement that your partner failed. Target failures show up as failed verdicts with the exchange attached, exactly as in a conformance run.

Stream the events

Page through events with the sequence number as the cursor:

curl -fsS "https://evsim.synergyboat.com/api/v1/testing/journey-runs/$REPORT_ID/events?after=0&limit=100" \
  -H "Authorization: Bearer $EVRT_KEY"

The response’s meta.nextAfter tells you where to resume; pass it as the next after. Or hold one connection open with server-sent events:

curl -fsSN "https://evsim.synergyboat.com/api/v1/testing/journey-runs/$REPORT_ID/stream" \
  -H "Authorization: Bearer $EVRT_KEY" \
  -H "Accept: text/event-stream"

Every SSE message carries its sequence as the event id. If the connection drops, resume without a gap by reconnecting with the standard Last-Event-ID header set to the last id you saw; the stream replays from there and closes itself when the run reaches a terminal state.

Cancel a run

curl -fsS -X POST "https://evsim.synergyboat.com/api/v1/testing/journey-runs/$REPORT_ID/cancel" \
  -H "Authorization: Bearer $EVRT_KEY"

Answers 202: cancellation is a request, and the run winds down at the next safe point rather than mid-exchange.

When a run pauses for a recovery decision

Sometimes the runner sends a mutating OCPI request and cannot learn whether it arrived: the connection died between dispatch and response. Resending it automatically could duplicate a session or a CDR on your partner’s side, so the tester never replays an uncertain mutation on its own. The run pauses as recovery_required, holds its slot, and asks you to choose. Read the run to see the choices. They are computed by the server for that specific uncertain action; only what the run read offers is valid:

curl -fsS "https://evsim.synergyboat.com/api/v1/testing/journey-runs/$REPORT_ID" \
  -H "Authorization: Bearer $EVRT_KEY" | jq '{status: .data.status, recoveryVersion: .data.recoveryVersion, options: .data.recoveryOptions}'

Decision	What it does
`reconcile`	Issue a safe read to find out whether the uncertain object reached the target, then continue on complete evidence. Offered when the action has a safe read.
`continue_without_replay`	Carry on without resending. The affected stage stays unobservable and the run’s integrity becomes `degraded`.
`stop`	End the run as `interrupted`, preserving all evidence collected so far.
`rerun_plan`	Start a separate, fresh run from the same immutable plan. The paused run keeps its evidence.

Apply one with the recoveryVersion from the same read:

curl -fsS -X POST "https://evsim.synergyboat.com/api/v1/testing/journey-runs/$REPORT_ID/recovery" \
  -H "Authorization: Bearer $EVRT_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"recoveryVersion\": $RECOVERY_VERSION, \"decision\": \"reconcile\"}"

A 409 means your recoveryVersion is stale: the run moved on since you read it, perhaps because a colleague decided first. Re-read the run and decide against the current state. This is deliberate; two people cannot apply conflicting decisions to the same uncertain action.

Put it in CI

#!/usr/bin/env bash
set -euo pipefail

BASE="https://evsim.synergyboat.com"
AUTH="Authorization: Bearer $EVRT_KEY"

# 1. Compile the plan.
PREVIEW=$(curl -fsS -X POST "$BASE/api/v1/testing/journeys/preview" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d @journey-manifest.json)

PLAN_ID=$(printf '%s' "$PREVIEW" | jq -r '.data.planId')
PLAN_HASH=$(printf '%s' "$PREVIEW" | jq -r '.data.planHash')

# 2. Start it. The Idempotency-Key makes a retried job return this same run.
START=$(curl -fsS -X POST "$BASE/api/v1/testing/journey-runs" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-${CI_PIPELINE_ID}-journey" \
  -d "{\"planId\": \"$PLAN_ID\", \"planHash\": \"$PLAN_HASH\"}")

REPORT_ID=$(printf '%s' "$START" | jq -r '.data.reportId')

# 3. Long-poll to a terminal state. Each 200 with a non-terminal status is
#    active work, not an outcome.
while true; do
  RUN=$(curl -fsS "$BASE/api/v1/testing/journey-runs/$REPORT_ID?wait=60" -H "$AUTH")
  RUN_STATUS=$(printf '%s' "$RUN" | jq -r '.data.status')
  case "$RUN_STATUS" in
    completed) break ;;
    failed|cancelled|interrupted)
      echo "Journey ended without a verdict: $RUN_STATUS"
      exit 2 ;;
    recovery_required)
      echo "Journey paused for a recovery decision. Decide via the API, then re-run this job."
      exit 2 ;;
    *) ;; # queued, running, recovering: keep waiting
  esac
done

# 4. Gate on the evidence.
INTEGRITY=$(printf '%s' "$RUN" | jq -r '.data.runIntegrity')
if [ "$INTEGRITY" != "valid" ]; then
  echo "Run integrity is $INTEGRITY: our evidence is incomplete. Not a target verdict."
  exit 2
fi

FAILED=$(printf '%s' "$RUN" | jq '.data.verdicts.conformance.failed')
if [ "$FAILED" -gt 0 ]; then
  echo "Charging journey: $FAILED required checks failed"
  exit 1
fi

echo "Charging journey: compliant"

Exit 1 is “the target broke a rule”. Exit 2 is “we do not have an answer”, which covers our own unavailability, a cancellation, and a pending recovery decision. A build log should never turn “we do not know” into “your partner is broken”.

Read your report, and see Troubleshooting for the status codes journeys can answer.

Get started

Guides

API reference

1. Browse the catalogue

2. Preview a plan

3. Start the run, idempotently

4. Follow it to a verdict

What each status means

Run integrity is about our evidence, not their conduct

Stream the events

Cancel a run

When a run pauses for a recovery decision

Put it in CI

Next

​1. Browse the catalogue

​2. Preview a plan

​3. Start the run, idempotently

​4. Follow it to a verdict

​What each status means

​Run integrity is about our evidence, not their conduct

​Stream the events

​Cancel a run

​When a run pauses for a recovery decision

​Put it in CI

​Next

1. Browse the catalogue

2. Preview a plan

3. Start the run, idempotently

4. Follow it to a verdict

What each status means

Run integrity is about our evidence, not their conduct

Stream the events

Cancel a run

When a run pauses for a recovery decision

Put it in CI

Next