Chargers

GET `/chargers` List chargers

Parameters

Name	In	Type
`page`	query	integer
`per_page`	query	integer
`status`	query	ChargerStatus `pending` `online` `offline`
`location_id`	query	string
`vendor`	query	string

Responses

200 Charger list

Property Type Required Description

data array<Charger>

Property Type Required Description

id string required

serial string required

vendor string required

model string required

firmware_version stringnullable

status

ChargerStatus

pending
online
offline

required

pending: registered but charger hasn't connected yet (claim expires in 48h) online: charger has an active WebSocket connection offline: charger was previously connected but is currently disconnected

location_id stringnullable

tariff_id stringnullable Optional charger-level tariff. Tariff resolution at session start is charger → location → org default; the first non-null wins. If all three are null, the session produces an `unbillable` CDR.

claim_expires_at stringnullableformat: date-time When the pending claim expires (null if charger is active/offline)

sockets array<Socket> required

Property	Type	Required	Description
`id`	string	required
`connector_id`	integer	required	Physical connector number on the charger (1, 2, etc.)
`type`	enum `Type1` `Type2` `CCS1` `CCS2` `CHAdeMO` `Other`	required
`status`	ConnectorStatus `Available` `Preparing` `Charging` `SuspendedEV` `SuspendedEVSE` `Finishing` `Faulted` `Unavailable`	required
`current_session_id`	stringnullable

created_at stringformat: date-time required

pagination Pagination

Property	Type	Required
`total`	integer	required
`page`	integer	required
`per_page`	integer	required
`has_more`	boolean	required

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X GET "https://api.ampr.dev/v1/chargers" \
  -H "Authorization: Bearer $AMPR_API_KEY"

const res = await fetch('https://api.ampr.dev/v1/chargers', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
  },
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

POST `/chargers` Register a new charger

Request body

Property	Type	Required	Description
`serial`	string	required
`vendor`	string	required
`model`	string	required
`location_id`	stringnullable
`tariff_id`	stringnullable		Optional charger-level tariff binding. Must belong to the same org.

Responses

201 Charger created

Property Type Required Description

data Charger

Property Type Required Description

id string required

serial string required

vendor string required

model string required

firmware_version stringnullable

status

ChargerStatus

pending
online
offline

required

pending: registered but charger hasn't connected yet (claim expires in 48h) online: charger has an active WebSocket connection offline: charger was previously connected but is currently disconnected

location_id stringnullable

claim_expires_at stringnullableformat: date-time When the pending claim expires (null if charger is active/offline)

sockets array<Socket> required

Property	Type	Required	Description
`id`	string	required
`connector_id`	integer	required	Physical connector number on the charger (1, 2, etc.)
`type`	enum `Type1` `Type2` `CCS1` `CCS2` `CHAdeMO` `Other`	required
`status`	ConnectorStatus `Available` `Preparing` `Charging` `SuspendedEV` `SuspendedEVSE` `Finishing` `Faulted` `Unavailable`	required
`current_session_id`	stringnullable

created_at stringformat: date-time required

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

409 Resource conflict (e.g., duplicate serial, active session) application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

422 Request understood but cannot be processed (e.g., invalid state) application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X POST "https://api.ampr.dev/v1/chargers" \
  -H "Authorization: Bearer $AMPR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serial": "string",
    "vendor": "string",
    "model": "string",
    "location_id": "string",
    "tariff_id": "trf_example"
  }'

const res = await fetch('https://api.ampr.dev/v1/chargers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "serial": "string",
    "vendor": "string",
    "model": "string",
    "location_id": "string",
    "tariff_id": "trf_example"
  }),
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

GET `/chargers/stats` Fleet stats rollup

Organization-scoped point-in-time fleet aggregate (chargers and sockets by status, active session count, and energy delivered today) for dashboard KPI tiles. Produced by a small fixed set of bounded grouped-COUNT/SUM queries — it does not paginate the fleet or read per-charger live state.

Responses

200 Fleet stats aggregate

Property Type Required Description

data FleetStats required Point-in-time organization-scoped fleet aggregate for dashboard KPI tiles. Every known status key is always present (defaulting to 0) so the shape is stable regardless of which statuses currently have rows.

Property Type Required Description

chargers object required

Property Type Required Description

total integer required

by_status object required

Property	Type	Required
`pending`	integer	required
`online`	integer	required
`offline`	integer	required

sockets object required

Property Type Required Description

total integer required

by_status object required

Property	Type	Required
`Available`	integer	required
`Preparing`	integer	required
`Charging`	integer	required
`SuspendedEV`	integer	required
`SuspendedEVSE`	integer	required
`Finishing`	integer	required
`Faulted`	integer	required
`Unavailable`	integer	required

sessions object required

Property	Type	Required	Description
`active`	integer	required	Count of the organization's sessions currently in the active state

energy object required

Property	Type	Required	Description
`today_wh`	integer	required	Summed total_energy_wh of the org's sessions completed since the start of the current UTC day

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X GET "https://api.ampr.dev/v1/chargers/stats" \
  -H "Authorization: Bearer $AMPR_API_KEY"

const res = await fetch('https://api.ampr.dev/v1/chargers/stats', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
  },
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

GET `/chargers/{charger_id}` Get charger details with live state

Parameters

Name	In	Type	Required	Description
`charger_id`	path	string	required

Responses

200 Charger detail

Property Type Required Description

data Charger

Property Type Required Description

id string required

serial string required

vendor string required

model string required

firmware_version stringnullable

status

ChargerStatus

pending
online
offline

required

pending: registered but charger hasn't connected yet (claim expires in 48h) online: charger has an active WebSocket connection offline: charger was previously connected but is currently disconnected

location_id stringnullable

claim_expires_at stringnullableformat: date-time When the pending claim expires (null if charger is active/offline)

sockets array<Socket> required

Property	Type	Required	Description
`id`	string	required
`connector_id`	integer	required	Physical connector number on the charger (1, 2, etc.)
`type`	enum `Type1` `Type2` `CCS1` `CCS2` `CHAdeMO` `Other`	required
`status`	ConnectorStatus `Available` `Preparing` `Charging` `SuspendedEV` `SuspendedEVSE` `Finishing` `Faulted` `Unavailable`	required
`current_session_id`	stringnullable

created_at stringformat: date-time required

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

404 Resource not found application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X GET "https://api.ampr.dev/v1/chargers/chg_example" \
  -H "Authorization: Bearer $AMPR_API_KEY"

const res = await fetch('https://api.ampr.dev/v1/chargers/chg_example', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
  },
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

DELETE `/chargers/{charger_id}` Decommission a charger

Parameters

Name	In	Type	Required	Description
`charger_id`	path	string	required

Responses

204 Charger decommissioned

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

404 Resource not found application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

409 Resource conflict (e.g., duplicate serial, active session) application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X DELETE "https://api.ampr.dev/v1/chargers/chg_example" \
  -H "Authorization: Bearer $AMPR_API_KEY"

const res = await fetch('https://api.ampr.dev/v1/chargers/chg_example', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
  },
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

PATCH `/chargers/{charger_id}` Update charger metadata

Parameters

Name	In	Type	Required	Description
`charger_id`	path	string	required

Request body

Property	Type	Description
`label`	string
`location_id`	stringnullable
`tariff_id`	stringnullable	Set to rebind the charger's tariff; `null` clears the binding (falls back to location/org tariff resolution).

Responses

200 Charger updated

Property Type Required Description

data Charger

Property Type Required Description

id string required

serial string required

vendor string required

model string required

firmware_version stringnullable

status

ChargerStatus

pending
online
offline

required

pending: registered but charger hasn't connected yet (claim expires in 48h) online: charger has an active WebSocket connection offline: charger was previously connected but is currently disconnected

location_id stringnullable

claim_expires_at stringnullableformat: date-time When the pending claim expires (null if charger is active/offline)

sockets array<Socket> required

Property	Type	Required	Description
`id`	string	required
`connector_id`	integer	required	Physical connector number on the charger (1, 2, etc.)
`type`	enum `Type1` `Type2` `CCS1` `CCS2` `CHAdeMO` `Other`	required
`status`	ConnectorStatus `Available` `Preparing` `Charging` `SuspendedEV` `SuspendedEVSE` `Finishing` `Faulted` `Unavailable`	required
`current_session_id`	stringnullable

created_at stringformat: date-time required

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

404 Resource not found application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X PATCH "https://api.ampr.dev/v1/chargers/chg_example" \
  -H "Authorization: Bearer $AMPR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "string",
    "location_id": "string",
    "tariff_id": "trf_example"
  }'

const res = await fetch('https://api.ampr.dev/v1/chargers/chg_example', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "string",
    "location_id": "string",
    "tariff_id": "trf_example"
  }),
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

Chargers

GET /chargers List chargers

Parameters

Responses

Request example

POST /chargers Register a new charger

Request body

Responses

Request example

GET /chargers/stats Fleet stats rollup

Responses

Request example

GET /chargers/{charger_id} Get charger details with live state

Parameters

Responses

Request example

DELETE /chargers/{charger_id} Decommission a charger

Parameters

Responses

Request example

PATCH /chargers/{charger_id} Update charger metadata

Parameters

Request body

Responses

Request example

GET `/chargers` List chargers

POST `/chargers` Register a new charger

GET `/chargers/stats` Fleet stats rollup

GET `/chargers/{charger_id}` Get charger details with live state

DELETE `/chargers/{charger_id}` Decommission a charger

PATCH `/chargers/{charger_id}` Update charger metadata