> ## Documentation Index > Fetch the complete documentation index at: https://docs.spirii.com/llms.txt > Use this file to discover all available pages before exploring further. # Control Request > Single endpoint accepting all control command types. Since processing is asynchronous, the HTTP response only reflects whether the request was accepted for processing (authenticated, well-formed) — the actual outcome of applying the request is delivered later as a `controlResponse` message correlated by `request_id`. ### Rate limiting Limited to 1 request every 5 seconds, tracked independently for each connector and action — i.e. `SET_EVSE_INPUT_LIMIT` is tracked separately from `CLEAR_EVSE_INPUT_LIMIT` and individually per asset. Exceeding it produces a `controlResponse` with `result: TOO_MANY_REQUESTS`. ## AsyncAPI ````yaml openapi/smart-charging/asyncapi.yaml controlRequest id: controlRequest title: Control Request description: > Single endpoint accepting all control command types. Since processing is asynchronous, the HTTP response only reflects whether the request was accepted for processing (authenticated, well-formed) — the actual outcome of applying the request is delivered later as a `controlResponse` message correlated by `request_id`. ### Rate limiting Limited to 1 request every 5 seconds, tracked independently for each connector and action — i.e. `SET_EVSE_INPUT_LIMIT` is tracked separately from `CLEAR_EVSE_INPUT_LIMIT` and individually per asset. Exceeding it produces a `controlResponse` with `result: TOO_MANY_REQUESTS`. servers: - id: http protocol: http host: api.spirii.com bindings: [] variables: [] address: control-request parameters: [] bindings: - protocol: http version: 0.3.0 value: {} schemaProperties: [] operations: - &ref_0 id: sendControlRequest title: Send a control request description: Submit an EVSE input limit or circuit fuse limit command. type: send messages: - &ref_1 id: setEvseInputLimitRequest contentType: application/json payload: - name: Set EVSE Input Limit description: >- Set the maximum input current/power an EVSE may draw from the grid. type: object properties: - name: request_id type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. required: true - name: actor_uid type: string description: >- Unique id of the actor sending the request, issued at actor registration. required: true - name: asset_id type: integer description: Chargebox id. required: true - name: action type: string description: SET_EVSE_INPUT_LIMIT required: true - name: connector_id type: integer required: true - name: limit type: number description: Maximum input current or power, in the unit given by `unit`. required: true - name: unit type: string description: W = watts, A = amps. enumValues: - W - A required: true - name: valid_to type: string description: > ISO 8601 timestamp until which the limit stays in effect. Must be at least 15 seconds in the future. required: true - name: input_phases type: integer description: > Overrides Spirii's known phase count for the connector, used for W/A conversion. Only meaningful when `unit` is `W`. Useful when the site conditions fluctuate and high precision is needed. required: false - name: input_voltage type: number description: > Overrides Spirii's known voltage for the connector, used for W/A conversion. Only meaningful when `unit` is `W`. Useful when the site conditions fluctuate and high precision is needed. required: false - name: distribution_strategy type: string description: > Affects how the circuit fuse capacity is balanced when the target EVSE is on a circuit with dynamic load management: - `HOLD`: the capacity difference between the previous and new limit is held and not redistributed to other connectors, reducing overall circuit consumption. - `DISTRIBUTE` (default): the capacity difference is redistributed among other connectors on the circuit, keeping overall circuit utilization high and only limiting power on the target EVSE. enumValues: - HOLD - DISTRIBUTE required: false - name: description type: string description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. required: false headers: [] jsonPayloadSchema: type: object description: > Sets the maximum input current the EVSE can draw from the grid, reducing the power output of the connector. The limit can be provided in either power (`W`) or current (`A`). **Constraints:** - Can only be applied to connectors currently `Charging`, `SuspendedEVSE`, or `SuspendedEV` (`SuspendedEVSE` can itself result from other factors such as an active schedule — applying this limit does not guarantee a transition to `Charging`). - Only limits the EVSE's input potential power draw; does not guarantee the EV will actually draw that much power. - Cannot exceed hard limitations on the EVSE (hardware limits, user-set limits). - Is overridden by active schedules and dynamic load management — the effective limit is 0 outside the schedule period, and may be reduced by DLM if the circuit is shared with other EVSEs. properties: request_id: type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. x-parser-schema-id: actor_uid: type: string description: >- Unique id of the actor sending the request, issued at actor registration. x-parser-schema-id: asset_id: type: integer description: Chargebox id. x-parser-schema-id: action: type: string const: SET_EVSE_INPUT_LIMIT x-parser-schema-id: connector_id: type: integer x-parser-schema-id: limit: type: number description: Maximum input current or power, in the unit given by `unit`. x-parser-schema-id: unit: description: W = watts, A = amps. type: string enum: - W - A x-parser-schema-id: valid_to: type: string format: date-time description: > ISO 8601 timestamp until which the limit stays in effect. Must be at least 15 seconds in the future. x-parser-schema-id: input_phases: type: integer minimum: 1 description: > Overrides Spirii's known phase count for the connector, used for W/A conversion. Only meaningful when `unit` is `W`. Useful when the site conditions fluctuate and high precision is needed. x-parser-schema-id: input_voltage: type: number minimum: 1 description: > Overrides Spirii's known voltage for the connector, used for W/A conversion. Only meaningful when `unit` is `W`. Useful when the site conditions fluctuate and high precision is needed. x-parser-schema-id: distribution_strategy: type: string enum: - HOLD - DISTRIBUTE default: DISTRIBUTE description: > Affects how the circuit fuse capacity is balanced when the target EVSE is on a circuit with dynamic load management: - `HOLD`: the capacity difference between the previous and new limit is held and not redistributed to other connectors, reducing overall circuit consumption. - `DISTRIBUTE` (default): the capacity difference is redistributed among other connectors on the circuit, keeping overall circuit utilization high and only limiting power on the target EVSE. x-parser-schema-id: metadata: description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. x-parser-schema-id: required: - request_id - actor_uid - asset_id - action - connector_id - limit - unit - valid_to x-parser-schema-id: SetEvseInputLimitRequest title: Set EVSE Input Limit description: Set the maximum input current/power an EVSE may draw from the grid. example: |- { "request_id": "a1b2c3d4-0000-0000-0000-000000000001", "actor_uid": "actor_a1b2c3", "asset_id": 123456, "connector_id": 1, "action": "SET_EVSE_INPUT_LIMIT", "limit": 16, "unit": "A", "valid_to": "2026-10-31T09:00:00.000Z", "distribution_strategy": "DISTRIBUTE", "metadata": { "reason": "Low solar power output" } } bindings: [] extensions: - id: x-parser-unique-object-id value: setEvseInputLimitRequest - &ref_2 id: clearEvseInputLimitRequest contentType: application/json payload: - name: Clear EVSE Input Limit description: Remove a previously set EVSE input limit. type: object properties: - name: request_id type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. required: true - name: actor_uid type: string description: >- Unique id of the actor sending the request, issued at actor registration. required: true - name: asset_id type: integer description: Chargebox id. required: true - name: action type: string description: CLEAR_EVSE_INPUT_LIMIT required: true - name: connector_id type: integer required: true - name: description type: string description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. required: false headers: [] jsonPayloadSchema: type: object description: > Removes a previously set EVSE input limit. If the limit has expired, it will already be removed and this request will be rejected with `INVALID_ASSET_STATE` and `description`: `Control limit not found`. properties: request_id: type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. x-parser-schema-id: actor_uid: type: string description: >- Unique id of the actor sending the request, issued at actor registration. x-parser-schema-id: asset_id: type: integer description: Chargebox id. x-parser-schema-id: action: type: string const: CLEAR_EVSE_INPUT_LIMIT x-parser-schema-id: connector_id: type: integer x-parser-schema-id: metadata: description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. x-parser-schema-id: required: - request_id - actor_uid - asset_id - action - connector_id x-parser-schema-id: ClearEvseInputLimitRequest title: Clear EVSE Input Limit description: Remove a previously set EVSE input limit. example: |- { "request_id": "a1b2c3d4-0000-0000-0000-000000000001", "actor_uid": "actor_a1b2c3", "asset_id": 123456, "connector_id": 1, "action": "CLEAR_EVSE_INPUT_LIMIT", "metadata": { "reason": "The power limit is no longer needed" } } bindings: [] extensions: - id: x-parser-unique-object-id value: clearEvseInputLimitRequest - &ref_3 id: setCircuitFuseLimitRequest contentType: application/json payload: - name: Set Circuit Fuse Limit description: Temporarily override a circuit's fuse capacity. type: object properties: - name: request_id type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. required: true - name: actor_uid type: string description: >- Unique id of the actor sending the request, issued at actor registration. required: true - name: asset_id type: integer description: Circuit id. required: true - name: action type: string description: SET_CIRCUIT_FUSE_LIMIT required: true - name: limit type: number description: New fuse capacity limit, in Amps. required: true - name: valid_to type: string description: > ISO 8601 timestamp until which the limit stays in effect. Must be at least 15 seconds in the future. required: true - name: fallback_limit type: object description: >- Limit to apply automatically after `apply_after` seconds, lasting until `valid_to`. required: false properties: - name: limit type: number description: Fallback fuse capacity limit, in Amps. required: true - name: apply_after type: integer description: >- Seconds from now after which the fallback limit takes effect. required: true - name: description type: string description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. required: false headers: [] jsonPayloadSchema: type: object description: > Sets a temporary limit that overrides the circuit's actual fuse capacity, e.g. to match a real-world change in available grid power. Requires dynamic load management (DLM) to be enabled on the target circuit, otherwise the request has no effect. If power demand exceeds supply, chargers on the circuit may reduce charging speed or pause until more energy becomes available. **Constraints:** - Cannot exceed the circuit capacity. - Cannot be set lower than 0. ### Fallback mechanism To account for communication issues, an optional `fallback_limit` can be provided: a new overriding limit that takes effect automatically once the main limit expires. - If `fallback_limit` is omitted, any existing fallback for this circuit is cleared. - If provided, it replaces both the value and timing of any previously defined fallback for this circuit. - `fallback_limit.apply_after` (seconds from now) must resolve to a time before `valid_to`, otherwise the request is rejected. properties: request_id: type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. x-parser-schema-id: actor_uid: type: string description: >- Unique id of the actor sending the request, issued at actor registration. x-parser-schema-id: asset_id: type: integer description: Circuit id. x-parser-schema-id: action: type: string const: SET_CIRCUIT_FUSE_LIMIT x-parser-schema-id: limit: type: number minimum: 0 description: New fuse capacity limit, in Amps. x-parser-schema-id: valid_to: type: string format: date-time description: > ISO 8601 timestamp until which the limit stays in effect. Must be at least 15 seconds in the future. x-parser-schema-id: fallback_limit: type: object description: >- Limit to apply automatically after `apply_after` seconds, lasting until `valid_to`. properties: limit: type: number minimum: 0 description: Fallback fuse capacity limit, in Amps. x-parser-schema-id: apply_after: type: integer minimum: 0 description: >- Seconds from now after which the fallback limit takes effect. x-parser-schema-id: required: - limit - apply_after x-parser-schema-id: metadata: description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. x-parser-schema-id: required: - request_id - actor_uid - asset_id - action - limit - valid_to x-parser-schema-id: SetCircuitFuseLimitRequest title: Set Circuit Fuse Limit description: Temporarily override a circuit's fuse capacity. example: |- { "request_id": "a1b2c3d4-0000-0000-0000-000000000001", "actor_uid": "actor_a1b2c3", "asset_id": 42, "action": "SET_CIRCUIT_FUSE_LIMIT", "limit": 200, "valid_to": "2026-10-31T09:00:00.000Z", "fallback_limit": { "limit": 100, "apply_after": 300 }, "metadata": { "reason": "Location booster battery at 10%" } } bindings: [] extensions: - id: x-parser-unique-object-id value: setCircuitFuseLimitRequest - &ref_4 id: clearCircuitFuseLimitRequest contentType: application/json payload: - name: Clear Circuit Fuse Limit description: Remove a previously set circuit fuse limit override. type: object properties: - name: request_id type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. required: true - name: actor_uid type: string description: >- Unique id of the actor sending the request, issued at actor registration. required: true - name: asset_id type: integer description: Circuit id. required: true - name: action type: string description: CLEAR_CIRCUIT_FUSE_LIMIT required: true - name: description type: string description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. required: false headers: [] jsonPayloadSchema: type: object description: >- Removes a previously set circuit fuse limit override (and any pending fallback). properties: request_id: type: string description: >- Correlation id chosen by the actor. Echoed back in the corresponding `controlResponse` message. x-parser-schema-id: actor_uid: type: string description: >- Unique id of the actor sending the request, issued at actor registration. x-parser-schema-id: asset_id: type: integer description: Circuit id. x-parser-schema-id: action: type: string const: CLEAR_CIRCUIT_FUSE_LIMIT x-parser-schema-id: metadata: description: >- Arbitrary actor-supplied data, echoed back unchanged in the corresponding control response. x-parser-schema-id: required: - request_id - actor_uid - asset_id - action x-parser-schema-id: ClearCircuitFuseLimitRequest title: Clear Circuit Fuse Limit description: Remove a previously set circuit fuse limit override. example: |- { "request_id": "a1b2c3d4-0000-0000-0000-000000000001", "actor_uid": "actor_a1b2c3", "asset_id": 42, "action": "CLEAR_CIRCUIT_FUSE_LIMIT", "metadata": { "reason": "Location booster battery at 75%" } } bindings: [] extensions: - id: x-parser-unique-object-id value: clearCircuitFuseLimitRequest bindings: [] extensions: - id: x-parser-unique-object-id value: controlRequest sendOperations: [] receiveOperations: - *ref_0 sendMessages: [] receiveMessages: - *ref_1 - *ref_2 - *ref_3 - *ref_4 extensions: - id: x-parser-unique-object-id value: controlRequest securitySchemes: - id: apiKey name: x-api-key type: httpApiKey description: | API key issued to the Actor during registration. Spirii can revoke and reissue keys at any time. in: header extensions: [] ````