Charging Priority
How electricity is shared out when a circuit cannot supply everything asked of it — an organization's default priority weight and starvation floor, one session's weight override and charge-by deadline, and the reset for a station's actuation latch. User reads, Admin writes: every write here re-weights who gets electricity, or releases the latch that keeps the platform from hammering a station which cannot take limits. Each setting is genuinely three-state — configured, configured to the value that happens to equal the platform default, and not configured at all — so GET answers 204 for the third and DELETE is the only way to reach it.
13 endpoints
Clears a station's actuation status, releasing the `notAccepting` latch.
delete/v1/charging-stations/{chargingStationId}/actuation-statusRequires a bearer token
After a station refuses several SetChargingProfile attempts in a row,
the platform latches it as not accepting limits and stops trying —
which is what keeps the platform from hammering a station that cannot
take them. Nothing clears that latch on its own, so a station that was
fixed (firmware updated, hardware swapped behind the same id) stayed
permanently skipped. This is the way back.
Read the status through GET /charging-stations/{id}, which already
composes it in as actuationStatus; there is deliberately no GET for
this resource on its own.
Requires the caller to be an Owner or Admin of the station's
organization: releasing the latch changes what the platform will
attempt against a physical station. It still sends nothing itself — the
next planning cycle does, now that the gate no longer refuses it.
Parameters
| Name | In | Type | Description |
|---|
| chargingStationId* | path | string<uuid> | ChargingStation id |
Responses
| Status | Body | Description |
|---|
| 204 | — | The latch is cleared (whether or not it was set) |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the station's organization but below the required role |
| 404 | ErrorBody | No charging station with this id exists, or the caller cannot access its environment |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Reads the organization's default priority weight.
get/v1/organizations/{organizationId}/charging-priorityRequires a bearer token
204 means no weight has been configured, so the platform default of 1
applies — equal weight everywhere, which reduces to an equal share. Any
member of the organization may read this.
Parameters
| Name | In | Type | Description |
|---|
| organizationId* | path | string<uuid> | Organization id |
Responses
| Status | Body | Description |
|---|
| 200 | PriorityWeightBody | The configured default weight |
| 204 | — | No weight configured; the platform default of 1 applies |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment |
Sets the organization's default priority weight.
put/v1/organizations/{organizationId}/charging-priorityRequires a bearer token
Requires the caller to be an Owner or Admin of the organization.
Parameters
| Name | In | Type | Description |
|---|
| organizationId* | path | string<uuid> | Organization id |
Request bodyPriorityWeightBody
| Field | Type | Description |
|---|
| weight* | number<double> | Must be a finite number greater than 0 and no greater than 1000 —
the bound is enforced by energy-controller, which answers 422
through this endpoint if it is violated. The upper bound is not
cosmetic: an unbounded weight overflows the circuit's weight sum and
hands every connector on it a NaN share. |
Responses
| Status | Body | Description |
|---|
| 200 | PriorityWeightBody | The weight as now configured |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 422 | ErrorBody | The weight is not a finite number in (0, 1000] (invalidValue) |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Removes the organization's configured priority weight.
delete/v1/organizations/{organizationId}/charging-priorityRequires a bearer token
Restores the platform default of 1. Requires the caller to be an Owner
or Admin of the organization. Idempotent — clearing an already-absent
weight still succeeds.
Parameters
| Name | In | Type | Description |
|---|
| organizationId* | path | string<uuid> | Organization id |
Responses
| Status | Body | Description |
|---|
| 204 | — | No weight is configured (whether or not one was) |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Reads the organization's starvation floor.
get/v1/organizations/{organizationId}/starvation-floorRequires a bearer token
204 means no floor has ever been configured — the platform default,
which is no floor at all. A floor that was configured and then switched
off comes back 200 with floorEnabled: false; those are different,
distinguishable answers.
Parameters
| Name | In | Type | Description |
|---|
| organizationId* | path | string<uuid> | Organization id |
Responses
| Status | Body | Description |
|---|
| 200 | StarvationFloorBody | The configured floor |
| 204 | — | No floor configured; the platform default of no floor applies |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Sets the organization's starvation floor.
put/v1/organizations/{organizationId}/starvation-floorRequires a bearer token
Requires the caller to be an Owner or Admin of the organization. A
floor is what stops a low-weight session from being allocated
essentially nothing on a busy circuit, so raising it takes current away
from everyone else on that circuit.
Parameters
| Name | In | Type | Description |
|---|
| organizationId* | path | string<uuid> | Organization id |
Request bodyStarvationFloorBody
| Field | Type | Description |
|---|
| floorAmps | number | null<double> | The per-connector guaranteed current, in amps. Only consulted while
floorEnabled, but validated regardless: an unusable amount stored
against a switched-off floor is a landmine that arms itself the
moment somebody switches it back on. May be omitted for "enabled, no
amount chosen yet", which the underlying row permits. |
| floorEnabled* | boolean | Whether the floor is in force. Switching it off is not the same
as DELETEing this resource: off is a configuration an operator
chose and can switch back on with its amount intact, while absent is
the platform default of no floor at all. GET tells the two apart —
200 with floorEnabled: false versus 204. |
Responses
| Status | Body | Description |
|---|
| 200 | StarvationFloorBody | The floor as now configured |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 422 | ErrorBody | floorAmps is not a finite positive number within range (invalidValue) |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Removes the organization's starvation floor configuration entirely.
delete/v1/organizations/{organizationId}/starvation-floorRequires a bearer token
Restores "no floor was ever configured". Requires the caller to be an
Owner or Admin of the organization. Idempotent. To keep the amount but
stop applying it, PUT with floorEnabled: false instead — this
endpoint forgets the amount too.
Parameters
| Name | In | Type | Description |
|---|
| organizationId* | path | string<uuid> | Organization id |
Responses
| Status | Body | Description |
|---|
| 204 | — | No floor is configured (whether or not one was) |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Reads a session's priority override.
get/v1/transactions/{transactionId}/charging-priorityRequires a bearer token
204 means this session has no override, so its organization's default
applies. This deliberately does not resolve that inheritance and
report an effective weight: a caller that cannot tell an override from
an inherited default cannot tell whether clearing the override would
change anything.
Parameters
| Name | In | Type | Description |
|---|
| transactionId* | path | string<uuid> | Transaction id |
Responses
| Status | Body | Description |
|---|
| 200 | PriorityWeightBody | The session's override weight |
| 204 | — | No override; the organization's default applies |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No transaction with this id exists, or you cannot access its environment |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Overrides one session's priority weight.
put/v1/transactions/{transactionId}/charging-priorityRequires a bearer token
Requires the caller to be an Owner or Admin of the station's
organization — a stricter role than PUT /transactions/{id}/limit
(which only caps a session's own draw), because this raises a session's
claim on a shared circuit at every other session's expense, and
overrides a default only an Owner or Admin could have set.
Parameters
| Name | In | Type | Description |
|---|
| transactionId* | path | string<uuid> | Transaction id |
Request bodyPriorityWeightBody
| Field | Type | Description |
|---|
| weight* | number<double> | Must be a finite number greater than 0 and no greater than 1000 —
the bound is enforced by energy-controller, which answers 422
through this endpoint if it is violated. The upper bound is not
cosmetic: an unbounded weight overflows the circuit's weight sum and
hands every connector on it a NaN share. |
Responses
| Status | Body | Description |
|---|
| 200 | PriorityWeightBody | The override as now configured |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the station's organization but below the required role |
| 404 | ErrorBody | No transaction with this id exists, or you cannot access its environment |
| 422 | ErrorBody | The weight is not a finite number in (0, 1000] (invalidValue) |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Removes a session's priority override.
delete/v1/transactions/{transactionId}/charging-priorityRequires a bearer token
Returns it to the organization's default. Requires the caller to be an
Owner or Admin of the station's organization. Idempotent — clearing an
already-absent override still succeeds.
Parameters
| Name | In | Type | Description |
|---|
| transactionId* | path | string<uuid> | Transaction id |
Responses
| Status | Body | Description |
|---|
| 204 | — | No override is configured (whether or not one was) |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the station's organization but below the required role |
| 404 | ErrorBody | No transaction with this id exists, or you cannot access its environment |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Reads a session's charge-by deadline.
get/v1/transactions/{transactionId}/deadlineRequires a bearer token
204 is the normal case: nothing infers a deadline, this field is
always explicit, and a session without one is simply unaffected by
price.
Parameters
| Name | In | Type | Description |
|---|
| transactionId* | path | string<uuid> | Transaction id |
Responses
| Status | Body | Description |
|---|
| 200 | SessionDeadlineBody | The session's deadline |
| 204 | — | No deadline; this session is unaffected by price |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No transaction with this id exists, or you cannot access its environment |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Sets a session's charge-by deadline.
put/v1/transactions/{transactionId}/deadlineRequires a bearer token
Requires the caller to be an Owner or Admin of the station's
organization. A deadline buys the planner permission to slow this
session down in expensive hours, trading the driver's finishing time
against the fleet's energy cost.
Parameters
| Name | In | Type | Description |
|---|
| transactionId* | path | string<uuid> | Transaction id |
Request bodySessionDeadlineBody
| Field | Type | Description |
|---|
| chargeBy* | string<date-time> | When this session must be finished charging by, RFC 3339. Bounded
above by how far ahead a price forecast can be obtained (422
beyond that, naming the limit). Deliberately not bounded below:
a deadline already in the past is an ordinary operational state — a
session that overran — and the planner simply treats such a session
as unaffected by price, the same as one with no deadline. |
Responses
| Status | Body | Description |
|---|
| 200 | SessionDeadlineBody | The deadline as now configured |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the station's organization but below the required role |
| 404 | ErrorBody | No transaction with this id exists, or you cannot access its environment |
| 422 | ErrorBody | The deadline is further ahead than a price forecast can reach (invalidValue) |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
Removes a session's charge-by deadline.
delete/v1/transactions/{transactionId}/deadlineRequires a bearer token
Requires the caller to be an Owner or Admin of the station's
organization. Idempotent — clearing an already-absent deadline still
succeeds. This is the only way a deadline entered by mistake is removed
rather than merely corrected to some other time.
Parameters
| Name | In | Type | Description |
|---|
| transactionId* | path | string<uuid> | Transaction id |
Responses
| Status | Body | Description |
|---|
| 204 | — | No deadline is configured (whether or not one was) |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member of the station's organization but below the required role |
| 404 | ErrorBody | No transaction with this id exists, or you cannot access its environment |
| 429 | ErrorBody | The caller has exceeded its request budget. error is rateLimited. Wait Retry-After seconds before retrying — a prior successful response's own RateLimit-Remaining/RateLimit-Reset headers show this coming before it happens. |
| 500 | ErrorBody | An unexpected internal error. error is always internalError; message is deliberately the fixed string "an unexpected error occurred", never the real cause, which is logged server-side instead of being returned to the caller. |
| 503 | ErrorBody | energy-controller is not configured in this environment (energyControllerUnavailable) |
