Skip to main content
A handful of conventions hold across every endpoint in the Spirii API. Learn them once and you can read any endpoint’s reference without relearning the basics.

​
Base URL and format

All requests go to the production API:
Requests and responses are JSON (application/json).

​
Versioning

The major version is part of the path — current endpoints sit under /v2:
See Versioning for the current version and how changes are managed. The earlier Spirii legacy API remains available for existing integrations; new work should use the current version.

​
Authentication

Every request is authenticated with an API key, sent as a bearer token in the Authorization header. See Authentication for how to create and send it.

​
Methods

The API follows REST conventions: A resource’s ID goes in the path, for example PATCH /v2/tokens/{id}.

​
Naming and casing

Property names and query parameters are camelCase — nextPageCursor, locationIds, startedAt. Enum values are the exception: their casing varies between fields, so copy each value exactly as the endpoint’s reference lists it rather than assuming a style.

​
Data formats

  • Timestamps are ISO 8601, in UTC — 2025-12-31T23:59:59.999Z. Parse them with a standard date-time parser rather than by hand.
  • Numbers are JSON numbers with a dot decimal separator, such as 100.5. This is the wire format, distinct from how a value is displayed to a person.
  • Money is a numeric amount alongside an ISO 4217 currency code — EUR, not a symbol.
  • Quantities are numeric, with the unit given in the field’s description — energy in kWh, power in kW, current in A, voltage in V, durations in seconds.
  • Identifiers are numbers or strings depending on the resource, and several encode structured information. See Identifiers for the formats and what they mean.

​
Null and optional fields

Optional values may come back as null or be left out of the response entirely. Some fields are returned only when you request them. Treat the reference for each field as the source of truth.
Where this page and an endpoint’s reference disagree, the reference is authoritative for that endpoint.

Authentication

Create and send your API key.

Versioning

The current version and how changes are managed.

Identifiers

The ID formats each resource uses.

Pagination

Page through list results.

Filtering

Narrow and sort list results.

Errors

Status codes and how to handle them.