Skip to content

Migrating to Signal API v2

Upcoming

Signal API v2 is not yet available in production. This page describes an upcoming release, and details can still change until it ships. You can already plan your migration, and your existing v1 or v1.1 integration keeps working unchanged. Questions go to h2-stations@clean-hydrogen.europa.eu.

Signal API v2 replaces the single availability endpoint with one endpoint per signal category (availability, usage, hydrogen storage, pricing) and moves from fuelling-option identifiers to the station's registered layout. This page walks an existing v1 or v1.1 integration through the change.

The full field reference for every v2 endpoint lives in Sending Signals (API v2).

What changes at a glance

Aspect v1 / v1.1 v2
Availability endpoint POST /import/v1/hrs-availability (or /import/v1.1/hrs-availability) POST /import/v2/signal/availability/ (note the trailing slash)
Signal categories Availability only Availability, usage, hydrogen storage, pricing, each on its own endpoint
What you address Fuelling options (fuel_type per dispenser entry) Registered nozzle and dispenser identifiers (storages and products for the new categories)
Station flags Top level (maintenance, limitedly_available) Nested under a station object, availability signal only
Token v1 token, one per originator New v2 token, v1 tokens do not work on v2
Batch behaviour Valid signals accepted even when the response is 400 All or nothing, one invalid transmission rejects the whole request
Error body Batch-aligned JSON array Batch-aligned JSON array (unchanged)
Assignment to stations One active signal originator per station Per signal type: live or testing per station and category
Test mode Not available dry_run flag per transmission
Rate limit None enforced 300 requests per minute per originator
Station list endpoint GET /import/v1.1/active-stations (v1.1 only) GET /import/v2/active-stations/, grouped per signal type

v1 and v1.1 stay available during the transition. Your existing integration keeps working unchanged while you build against v2.

Before and after: the availability payload

The same station state, sent to v1 and to v2.

v1 (POST https://api.h2-stations.eu/import/v1/hrs-availability):

[
  {
    "hrs": "ABCDE",
    "datetime": "2026-07-11T09:41:00+02:00",
    "dispensers": [
      {"fuel_type": "700ld", "available": true},
      {"fuel_type": "350hd", "available": false}
    ],
    "maintenance": false,
    "limitedly_available": false
  }
]

v2 (POST https://api.h2-stations.eu/import/v2/signal/availability/):

[
  {
    "hrs": "ABCDE",
    "datetime": "2026-07-11T09:41:00+02:00",
    "nozzles": [
      {"id": "NOZ-01", "available": true},
      {"id": "NOZ-02", "available": false}
    ],
    "station": {
      "maintenance": false,
      "limitedly_available": false
    }
  }
]

The structural moves:

  1. dispensers[*].fuel_type becomes nozzles[*].id, a nozzle identifier from the station's registered layout. If your telemetry is per dispenser rather than per nozzle, send {"dispenser_id": "DISP-01", "available": true} instead and the platform fans the value out to that dispenser's nozzles.
  2. The station-wide flags move under a station object. Both remain required.
  3. The envelope gains optional dry_run, and transmission_id carries over unchanged.

The platform continues to derive per-fuelling-option statuses for the map and the export API from your nozzle-level data, you do not need to send fuelling options anymore.

Why identifiers instead of fuelling options

v1 assumed a station had at most one state per fuelling option. Real stations have several dispensers and nozzles per option, and the new signal categories (usage, storage, pricing) need to reference physical entities and products. v2 therefore reports against the station's registered layout: every nozzle, dispenser, storage, and product you reference must be registered in the portal for that station before signals against it will resolve.

This adds one prerequisite to your onboarding: the station layout must be registered and confirmed by the operator before you can send v2 signals. Where the operator has not done this yet, coordinate with them or with H2-Stations. The identifier values themselves are agreed with the operator (they typically mirror your internal dispenser and nozzle naming).

Authentication: new tokens

v2 uses a new token system. The header format is unchanged (Authorization: Bearer <token>), but v1 tokens are rejected on v2 endpoints with a 401, and v2 tokens do not work on v1.

If your organisation has a portal account with originator management rights, you create v2 tokens yourself under API tokens in the portal. Pick a name and an expiry, and the token value is shown once on the confirmation page. Otherwise H2-Stations issues the token for you during onboarding and emails you a personal, single-use link that reveals it once.

Either way the value is never stored in readable form, so a token that is lost has to be replaced rather than looked up. Unlike v1, one originator can hold several active v2 tokens, so you can rotate tokens or use separate tokens per transmitter without coordinating a switchover with us. You can hold up to five active import tokens at a time. Treat each token as an opaque secret.

You can also change a token's expiry date or revoke it from the same page. Revoking takes effect immediately. H2-Stations emails the token owner when a token is created or revoked, and again 30 days and 7 days before it expires.

Per-type assignments and testing

In v1, a station had one active signal originator, full stop. In v2, the operator assigns an originator per signal type, and each assignment is either live (published) or testing (accepted and validated, not published). You can be live for availability while still testing pricing on the same station.

GET /import/v2/active-stations/ shows your current assignments, grouped per signal type. See the reference for the response format.

Suggested migration path

  1. Coordinate layout registration. Make sure the stations you report on have their layout (and products, if you will send pricing) registered and confirmed in the portal.
  2. Get a v2 token from H2-Stations.
  3. Build against dry_run. Send availability transmissions with "dry_run": true from your integration. A 204 means the payload, identifiers, and token all check out, and nothing is stored.
  4. Go to testing. Have the operator assign your system for availability in testing state and send real signals. Verify them together with the operator in the portal.
  5. Flip availability to live. From this moment your v2 signals drive the public status. Stop sending v1 signals for that station at the same time, running both in parallel is not necessary.
  6. Add the new categories (usage, hydrogen storage, pricing) one by one, each through the same dry-run, testing, live sequence.

Keep the error reference at hand during step 3, most first-time rejections are unregistered identifiers or stale datetime values.

Contact

Questions, a migration timeline to agree on, or feedback on the API: h2-stations@clean-hydrogen.europa.eu