Introduction

Welcome to the Tether Partner API, which allows partners to manage vehicles, chargers and events.

overview diagram

Authentication

The Tether Partner API uses API Keys for authentication. The API Key must be included in each requests using a specific header:

x-api-key: {your-api-key}

You may request a new API Key using our Contact Us page.

Chargers

Create or replace a charger

curl 'https://api.tetherev.io/chargers/C0229' \
    -X PUT \
    -H 'x-api-key: {your-api-key}' \
    -d '
    {
      "id": "C0229",
      "chargePowers": [ 11 ],
      "latitude": 62.268302,
      "longitude": 17.448415
    }'

201
{
  "id": "C0229"
}

Request

PUT https://api.tetherev.io/chargers/{id}

Parameter	Description
id	The identifier of the charger to create/replace

For the body schema and its validation rules see Charger Schema (PUT).

Response

Code	Description	Body Type	Details
200	OK
201	Created	Created Entity Schema
400	Bad Request	Error Schema	Charger Constrainsts
403	Forbidden	Error Schema
429	Too Many Requests	Error Schema

Partially update a charger

curl 'https://api.tetherev.io/chargers/C0229' \
    -X PATCH \
    -H 'x-api-key: {your-api-key}' \
    -d '
    {
      "chargePowers": [ 11, 22 ],
    }'

Request

PATCH https://api.tetherev.io/chargers/{id}

Parameter	Description
id	The identifier of the charger to update

For the body schema and its validation rules see Charger Schema (PATCH).

Response

Code	Description	Body Type	Details
200	OK
400	Bad Request	Error Schema	Charger Constrainsts
403	Forbidden	Error Schema
404	Not Found	Error Schema
429	Too Many Requests	Error Schema

Get all chargers

Get a charger

curl 'https://api.tetherev.io/chargers/C0229' \
  -H 'x-api-key: {your-api-key}'

200
{
  "id": "C0229",
  "chargePowers": [ 11, 22 ],
  "latitude": 62.268302,
  "longitude": 17.448415
}

Request

GET https://api.tetherev.io/chargers/{id}

Parameter	Descriptions
id	The identifier of the charger to retrieve

Response

Code	Description	Body Type
200	OK	Charger Schema (GET)
403	Forbidden	Error Schema
404	Not Found	Error Schema
429	Too Many Requests	Error Schema

Events

Create an event

curl 'https://api.tetherev.io/events' \
  -X POST \
  -H 'x-api-key: {your-api-key}' \
  -d '
  {
    "type": "VEHICLE_CONNECTED",
    "chargerId": "C1408",
    "vehicleId": "V0313",
    "stateOfCharge": 22.0,
    "timestamp": "2023-05-11T22:06:40.738Z"
  }'

201
{
  "id": "b8ae8cae-8fe0-4cd4-8394-76ead74e2258"
}

Request

POST https://api.tetherev.io/events

For the body schema and its validation rules see Event Schema (POST).

Response

Code	Description	Body Type
201	Created	Created Entity Schema
400	Bad Request	Error Schema
403	Forbidden	Error Schema
409	Conflict	Error Schema
429	Too Many Requests	Error Schema

Get all events

Get an event

curl 'https://api.tetherev.io/events/b8ae8cae-8fe0-4cd4-8394-76ead74e2258' \
  -H 'x-api-key: {your-api-key}'

200
{
  "id": "a0b20ee7-2720-46e9-bb1f-3be28e69ca03",
  "type": "VEHICLE_CONNECTED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "stateOfCharge": 22.0,
  "timestamp": "2023-05-11T22:06:40.738Z"
}

Request

GET https://api.tetherev.io/events/{id}

Parameter	Description
id	The identifier of the event to retrieve

Response

Code	Description	Body Type
200	OK	Event Schema (GET)
403	Forbidden	Error Schema
404	Not Found	Error Schema
429	Too Many Requests	Error Schema

Vehicles

Create or replace a vehicle

curl 'https://api.tetherev.io/vehicles/V0313' \
  -X PUT \
  -H 'x-api-key: {your-api-key}' \
  -d '
  {
    "id": "V0313",
    "chargeCapacity": 74.8,
    "chargePowers": [ 11 ]
  }'

201
{
  "id": "V0313"
}

Request

PUT https://api.tetherev.io/vehicles/{id}

Parameter	Description
id	The identifier of the vehicle to create/replace

For the body schema and its validation rules see Vehicle Schema (PUT).

Response

Code	Description	Body Type	Details
200	OK
201	Created	Created Entity Schema
400	Bad Request	Error Schema	Vehicle Constrainsts
403	Forbidden	Error Schema
429	Too Many Requests	Error Schema

Partially update a vehicle

curl 'https://api.tetherev.io/vehicles/V0313' \
  -X PATCH \
  -H 'x-api-key: {your-api-key}' \
  -d '
  {
    "chargePowers": [ 11, 22 ]
  }'

Request

PATCH https://api.tetherev.io/vehicles/{id}

Parameter	Description
id	The identifier of the vehicle to update

For the body schema and its validation rules see Vehicle Schema (PATCH).

Response

Code	Description	Body Type	Details
200	OK
400	Bad Request	Error Schema	Vehicle Constrainsts
403	Forbidden	Error Schema
404	Not Found	Error Schema
429	Too Many Requests	Error Schema

Get all vehicles

Get a vehicle

curl 'https://api.tetherev.io/vehicles/V0313' \
  -H 'x-api-key: {your-api-key}'

200
{
  "id": "V0313",
  "chargeCapacity": 74.8,
  "chargePowers": [ 11, 22 ]
}

Request

GET https://api.tetherev.io/vehicles/{id}

Parameter	Description
id	The identifier of the vehicle to retrieve

Response

Code	Description	Body Type
200	OK	Vehicle Schema (GET)
403	Forbidden	Error Schema
404	Not Found	Error Schema
429	Too Many Requests	Error Schema

Schemas

Properties marked with ★ are always mandatory.

Properties marked with ✰ are only mandatory under certain conditions (see the notes following each schema for details).

All other properties are optional but the API logic might populate them if they're missing (e.g. the timestamp property of an event).

Charger Schema (GET)

{
  "id": "C0229",
  "chargePowers": [ 11 ],
  "latitude": 62.268302,
  "longitude": 17.448415
}

{
  "id": "C0216",
  "minChargePower": 11,
  "maxChargePower": 22,
}

{
  "id": "C1408",
  "chargePowers": [ 11, 22 ],
  "dischargePowers": [ 11, 22 ],
  "latitude": 62.268302,
  "longitude": 17.448415
}

Property	Type	Unit	Description
id ★	string		unique charger identifier
chargePowers ✰	[decimal]	KW	list of discreet supported charge powers
chargePowerMin ✰	decimal	KW	lowest supported charge power
chargePowerMax ✰	decimal	KW	highest supported charge power
dischargePowers ✰	[decimal]	KW	list of discreet supported discharge powers
dischargePowerMin ✰	decimal	KW	lowest supported discharge power
dischargePowerMax ✰	decimal	KW	highest supported discharge power
latitude ✰	decimal	deg	latitude coordinate of charger location
longitude ✰	decimal	deg	longitude coordinate of charger location

Charger Schema (PATCH)

{
  "chargePowers": [ 11 ],
}

{
  "minChargePower": 11,
  "maxChargePower": 22,
}

{
  "chargePowers": [ 11, 22 ],
  "longitude": 17.448415
}

Property	Type	Unit	Description
chargePowers ✰	[decimal]	KW	list of discreet supported charge powers
chargePowerMin ✰	decimal	KW	lowest supported charge power
chargePowerMax ✰	decimal	KW	highest supported charge power
dischargePowers ✰	[decimal]	KW	list of discreet supported discharge powers
dischargePowerMin ✰	decimal	KW	lowest supported discharge power
dischargePowerMax ✰	decimal	KW	highest supported discharge power
latitude ✰	decimal	deg	latitude coordinate of charger location
longitude ✰	decimal	deg	longitude coordinate of charger location

Charger Constraints (PATCH)

See Charger Constraints (PUT).

Charger Schema (PUT)

{
  "chargePowers": [ 11 ],
  "latitude": 62.268302,
  "longitude": 17.448415
}

{
  "minChargePower": 11,
  "maxChargePower": 22,
}

{
  "id": "C1408",
  "chargePowers": [ 11, 22 ],
  "dischargePowers": [ 11, 22 ],
  "latitude": 62.268302,
  "longitude": 17.448415
}

Property	Type	Unit	Description
id ★	string		unique charger identifier
chargePowers ✰	[decimal]	KW	list of discreet supported charge powers
chargePowerMin ✰	decimal	KW	lowest supported charge power
chargePowerMax ✰	decimal	KW	highest supported charge power
dischargePowers ✰	[decimal]	KW	list of discreet supported discharge powers
dischargePowerMin ✰	decimal	KW	lowest supported discharge power
dischargePowerMax ✰	decimal	KW	highest supported discharge power
latitude ✰	decimal		latitude coordinate charger location
longitude ✰	decimal		longitude coordinate charger location

Charger Constraints (PUT)

chargePowers and dischargePowers are not considered provided if empty arrays
chargePowerMin and chargePowerMax must either be both omitted or provided
either chargePowers (discreet values) or <chargePowerMin, chargePowerMax> (range values) must be provided
chargePowers and <chargePowerMin, chargePowerMax> cannot be both provided
dischargePowerMin and dischargePowerMax must be both either omitted or provided
dischargePowers and <dischargePowerMin, dischargePowerMax> cannot be both provided
latitude and longitude must either be both omitted or provided

Created Entity Schema

{
  "id": "C0408"
}

{
  "id": "a0b20ee7-2720-46e9-bb1f-3be28e69ca03"
}

Property	Type	Description
id ★	string	entity identifier

Error Schema

{
  "message": "Not Found"
}

{
  "message": "Parameter {stateOfCharge} is invalid."
}

Property	Type	Description
message ★	string	error details

Event Schema (GET)

{
  "id": "a0b20ee7-2720-46e9-bb1f-3be28e69ca03",
  "type": "VEHICLE_CONNECTED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "stateOfCharge": 25.6,
  "timestamp": "2023-05-11T22:06:40.738Z"
}

Property	Type	Unit	Description
id ★	string		unique event identifier
type ★	string		VEHICLE_CONNECTED VEHICLE_DISCONNECTED VEHICLE_CHARGE_STARTED VEHICLE_CHARGE_STOPPED VEHICLE_CHARGE_UPDATED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge	decimal	%	current state of charge of the vehicle
chargePower	decimal	KW	the power used for charging
chargedEnergy	decimal	KWh	amount of energy charged in the last charge period
chargedTime	decimal	sec	duration of the last charge period
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Event Schema (POST)

Property	Type	Unit	Description
type ★	string		VEHICLE_CONNECTED VEHICLE_DISCONNECTED VEHICLE_CHARGE_STARTED VEHICLE_CHARGE_STOPPED VEHICLE_CHARGE_UPDATED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge ✰	decimal	%	current state of charge of the vehicle
chargePower	decimal	KW	the power used for charging
chargedEnergy	decimal	KWh	amount of energy charged in the last charge period
chargedTime	decimal	sec	duration of the last charge period
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Event Constraints

chargerId must refer to an existing charger
vehicleId must refer to an existing vehicler

Schema for `type = VEHICLE_CONNECTED`

{
  "type": "VEHICLE_CONNECTED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "stateOfCharge": 25.6,
  "timestamp": "2023-05-11T22:06:40.738Z"
}

Property	Type	Unit	Description
type ★	string		VEHICLE_CONNECTED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge	decimal	%	current state of charge of the vehicle
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Schema for `type = VEHICLE_DISCONNECTED`

{
  "type": "VEHICLE_DISCONNECTED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "stateOfCharge": 95.6,
  "timestamp": "2023-05-11T22:06:40.738Z"
}

Property	Type	Unit	Description
type ★	string		VEHICLE_DISCONNECTED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge	decimal	%	current state of charge of the vehicle
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Schema for `type = VEHICLE_CHARGE_STARTED`

{
  "type": "VEHICLE_CHARGE_STARTED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "stateOfCharge": 25.6,
  "chargePower": 11.0,
  "timestamp": "2023-05-11T22:06:46.276Z"
}

Property	Type	Unit	Description
type ★	string		VEHICLE_CHARGE_STARTED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge	decimal	%	current state of charge of the vehicle
chargePower	decimal	KW	the power used for charging
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Schema for `type = VEHICLE_CHARGE_STOPPED`

{
  "type": "VEHICLE_CHARGE_STOPPED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "chargedEnergy": 58.3,
  "chargeTime": 27658.362,
  "stateOfCharge": 95.6,
  "timestamp": "2023-05-12T07:42:12.110Z"
}

Property	Type	Unit	Description
type ★	string		VEHICLE_CHARGE_STOPPED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge	decimal	%	current state of charge of the vehicle
chargedEnergy	decimal	KWh	amount of energy charged in the last charge period
chargedTime	decimal	sec	duration of the last charge period
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Schema for `type = VEHICLE_CHARGE_UPDATED`

{
  "type": "VEHICLE_CHARGE_UPDATED",
  "chargerId": "C1408",
  "vehicleId": "V0313",
  "stateOfCharge": 49.1,
  "chargePower": 11.0,
  "timestamp": "2023-05-11T23:09:11.387Z"
}

Property	Type	Unit	Description
type ★	string		VEHICLE_CHARGE_UPDATED
chargerId ★	string		charger identifier
vehicleId ★	string		vehicle identifier
stateOfCharge ★	decimal	%	current state of charge of the vehicle
chargePower	decimal	KW	the power used for charging
chargedEnergy	decimal	KWh	amount of energy charged in the last charge period
chargedTime	decimal	sec	duration of the last charge period
timestamp	string		{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{sss}Z

Vehicle Schema (GET)

{
  "id": "V0313",
  "chargeCapacity": 74.8,
  "chargePowers": [ 11 ]
}

{
  "id": "V1863",
  "chargeCapacity": 48.6,
  "minChargePower": 11,
  "maxChargePower": 22
}

{
  "id": "V0849",
  "chargeCapacity": 119.2,
  "chargePowers": [ 22 ],
  "dischargePowers": [ 22 ]
}

Property	Type	Unit	Description
id ★	string		unique vehicle identifier
chargeCapacity ★	decimal	KWh	amount of energy the vehicle can store
chargePowers ✰	[decimal]	KW	list of discreet supported charge powers
chargePowerMin ✰	decimal	KW	lowest supported charge power
chargePowerMax ✰	decimal	KW	highest supported charge power
dischargePowers ✰	[decimal]	KW	list of discreet supported discharge powers
dischargePowerMin ✰	decimal	KW	lowest supported discharge power
dischargePowerMax ✰	decimal	KW	highest supported discharge power

Vehicle Schema (PATCH)

{
  "chargeCapacity": 74.8,
}

{
  "minChargePower": 11,
}

{
  "chargePowers": [ 22 ],
  "dischargePowers": [ 22 ]
}

Property	Type	Unit	Description
chargeCapacity	decimal	KWh	amount of energy the vehicle can store
chargePowers ✰	[decimal]	KW	list of discreet supported charge powers
chargePowerMin ✰	decimal	KW	lowest supported charge power
chargePowerMax ✰	decimal	KW	highest supported charge power
dischargePowers ✰	[decimal]	KW	list of discreet supported discharge powers
dischargePowerMin ✰	decimal	KW	lowest supported discharge power
dischargePowerMax ✰	decimal	KW	highest supported discharge power

Vehicle Constraints (PATCH)

See Vehicle Constraints (PUT).

Vehicle Schema (PUT)

{
  "chargeCapacity": 74.8,
  "chargePowers": [ 11 ]
}

{
  "chargeCapacity": 48.6,
  "minChargePower": 11,
  "maxChargePower": 22
}

{
  "id": "V0849",
  "chargeCapacity": 119.2,
  "chargePowers": [ 22 ],
  "dischargePowers": [ 22 ]
}

Property	Type	Unit	Description
id ★	string		unique vehicle identifier
chargeCapacity ★	decimal	KWh	amount of energy the vehicle can store
chargePowers ✰	[decimal]	KW	list of discreet supported charge powers
chargePowerMin ✰	decimal	KW	lowest supported charge power
chargePowerMax ✰	decimal	KW	highest supported charge power
dischargePowers ✰	[decimal]	KW	list of discreet supported discharge powers
dischargePowerMin ✰	decimal	KW	lowest supported discharge power
dischargePowerMax ✰	decimal	KW	highest supported discharge power

Vehicle Constraints (PUT)

chargePowers and dischargePowers are not considered provided if empty arrays
chargePowerMin and chargePowerMax must either be both omitted or provided
either chargePowers (discreet values) or <chargePowerMin, chargePowerMax> (range values) must be provided
chargePowers and <chargePowerMin, chargePowerMax> cannot be both provided
dischargePowerMin and dischargePowerMax must be both either omitted or provided
dischargePowers and <dischargePowerMin, dischargePowerMax> cannot be both provided

Introduction

Authentication

Chargers

Create or replace a charger

Request

Response

Partially update a charger

Request

Response

Get all chargers

Get a charger

Request

Response

Events

Create an event

Request

Response

Get all events

Get an event

Request

Response

Vehicles

Create or replace a vehicle

Request

Response

Partially update a vehicle

Request

Response

Get all vehicles

Get a vehicle

Request

Response

Schemas

Charger Schema (GET)

Charger Schema (PATCH)

Charger Constraints (PATCH)

Charger Schema (PUT)

Charger Constraints (PUT)

Created Entity Schema

Error Schema

Event Schema (GET)

Event Schema (POST)

Event Constraints

Schema for type = VEHICLE_CONNECTED

Schema for type = VEHICLE_DISCONNECTED

Schema for type = VEHICLE_CHARGE_STARTED

Schema for type = VEHICLE_CHARGE_STOPPED

Schema for type = VEHICLE_CHARGE_UPDATED

Vehicle Schema (GET)

Vehicle Schema (PATCH)

Vehicle Constraints (PATCH)

Vehicle Schema (PUT)

Vehicle Constraints (PUT)

Schema for `type = VEHICLE_CONNECTED`

Schema for `type = VEHICLE_DISCONNECTED`

Schema for `type = VEHICLE_CHARGE_STARTED`

Schema for `type = VEHICLE_CHARGE_STOPPED`

Schema for `type = VEHICLE_CHARGE_UPDATED`