> ## Documentation Index > Fetch the complete documentation index at: https://docs.ridergy.com/llms.txt > Use this file to discover all available pages before exploring further. # Apply a schedule to every location in a cluster > Applies the same `LimitProfileRequest` to every location in the cluster (equivalent to calling `POST /locations/{locationId}/schedules` for each member). ## OpenAPI ````yaml /api-reference/energy-management/openapi.en.yaml POST /clusters/{clusterId}/schedules openapi: 3.1.0 info: title: RiDERgy Energy Management API version: '1.0' license: name: Proprietary identifier: LicenseRef-Proprietary description: > Programmatic control of charging power limits across locations, individual chargers, organizations, and cross-location clusters. ## Authentication Every endpoint except `GET /health` requires an `x-api-key` header. The key determines your tenant — it is never read from the request body or any other header, so a key for one tenant cannot access another tenant's data. Your tenant must have the Energy Management API feature enabled, otherwise requests fail with `403 FEATURE_NOT_ENABLED`. Contact RiDERgy to enable it. ## Priority model Location and charger limits are controlled via **priority-windowed profiles**: - Priorities range from **0 (lowest) to 10 (highest)**, OCPP-stack-style. - A target (location or charger connector) can have up to 11 profiles, one per priority level, each with its own `[startTime, endTime)` window. - At any moment, the **effective limit** is the `limitKw` of the highest-priority profile whose window is currently active. - If no profile is active, a location falls back to its `permanentLimitKw`. - Submitting a profile at a priority that already has one for that target **replaces** it. - Profiles are applied and reverted automatically at their `startTime`/`endTime` — no further API calls are needed once a profile is created. Profile records are never deleted, so history remains queryable. ## Errors All errors share this shape: ```json { "error": { "code": "LOCATION_NOT_FOUND", "message": "Location 123 was not found for the provided tenant", "requestId": "b1f6e6b0-..." } } ``` servers: - url: https://api.ridergy.com/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Health description: Unauthenticated service health check. - name: Locations description: Read and set location-level power limits and priority profiles. - name: Chargers description: >- Lock individual charger connectors to a fixed power limit for a time window. - name: Organizations description: Tenant-wide cap profiles (recorded only — enforcement not yet active). - name: Clusters description: Group locations under a shared kW cap and apply schedules across them. paths: /clusters/{clusterId}/schedules: post: tags: - Clusters summary: Apply a schedule to every location in a cluster description: | Applies the same `LimitProfileRequest` to every location in the cluster (equivalent to calling `POST /locations/{locationId}/schedules` for each member). operationId: applyClusterSchedule parameters: - $ref: '#/components/parameters/ClusterId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LimitProfileRequest' examples: example: value: startTime: '2026-06-12T08:00:00Z' endTime: '2026-06-12T18:00:00Z' limitKw: 50 priority: 5 responses: '200': description: Schedule applied to at least one location content: application/json: schema: $ref: '#/components/schemas/ClusterScheduleResponse' '400': description: Cluster is inactive, empty, or the request body is invalid content: application/json: schema: $ref: '#/components/schemas/Error' examples: clusterInactive: summary: CLUSTER_INACTIVE value: error: code: CLUSTER_INACTIVE message: Cluster clst_20260612_a1b2c3d4 is inactive requestId: b1f6e6b0-1234-4abc-9def-000000000000 clusterEmpty: summary: CLUSTER_EMPTY value: error: code: CLUSTER_EMPTY message: Cluster has no locations requestId: b1f6e6b0-1234-4abc-9def-000000000000 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/FeatureNotEnabled' '404': $ref: '#/components/responses/ClusterNotFound' components: parameters: ClusterId: name: clusterId in: path required: true schema: type: string example: clst_20260612_a1b2c3d4 schemas: LimitProfileRequest: type: object required: - startTime - endTime - limitKw properties: startTime: type: string format: date-time description: ISO-8601 UTC timestamp. Required. example: '2026-06-12T08:00:00Z' endTime: type: string format: date-time description: >- ISO-8601 UTC timestamp. Must be after `startTime` and in the future. Required. example: '2026-06-12T18:00:00Z' limitKw: type: number format: float exclusiveMinimum: 0 description: Power limit in kW. Must be greater than 0. Required. example: 50 priority: type: integer minimum: 0 maximum: 10 default: 0 description: | OCPP-stack-style priority level, 0 (lowest) to 10 (highest). Submitting a profile at a priority that already exists for this target replaces it. example: 5 ClusterScheduleResponse: type: object properties: clusterId: type: string example: clst_20260612_a1b2c3d4 applied: type: array items: allOf: - type: object properties: locationId: type: string - $ref: '#/components/schemas/LocationScheduleResponse' errors: type: array items: type: object properties: locationId: type: string error: $ref: '#/components/schemas/Error' totalLocations: type: integer example: 2 Error: type: object properties: error: type: object properties: code: type: string example: LOCATION_NOT_FOUND message: type: string example: Location 123 was not found for the provided tenant requestId: type: string format: uuid LocationScheduleResponse: type: object properties: locationId: type: string example: '3632155' priority: type: integer example: 5 limitKw: type: number example: 50 startTime: type: string format: date-time endTime: type: string format: date-time status: $ref: '#/components/schemas/ProfileStatus' permanentLimitKw: type: - number - 'null' example: 100 effectiveLimitKw: type: - number - 'null' example: 50 ProfileStatus: type: string enum: - SCHEDULED - ACTIVE - EXPIRED responses: Unauthorized: description: Missing, invalid, or expired API key content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: error: code: UNAUTHORIZED message: Invalid or inactive API key requestId: b1f6e6b0-1234-4abc-9def-000000000000 FeatureNotEnabled: description: Tenant does not have the Energy Management API enabled content: application/json: schema: $ref: '#/components/schemas/Error' examples: featureNotEnabled: value: error: code: FEATURE_NOT_ENABLED message: >- The Energy Management API is not enabled for your account. Contact RiDERgy to enable this feature. requestId: b1f6e6b0-1234-4abc-9def-000000000000 ClusterNotFound: description: Cluster not found content: application/json: schema: $ref: '#/components/schemas/Error' examples: clusterNotFound: value: error: code: CLUSTER_NOT_FOUND message: Cluster clst_20260612_a1b2c3d4 not found requestId: b1f6e6b0-1234-4abc-9def-000000000000 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Per-tenant API key. Tenant is derived from the key — never from the request. ````