# Devices

Device management

## Fetch a list of Devices

`GET /devices`

Without any params, returns a list of the user's devices

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Parameters:

- `all` (query, boolean, optional) - Can only be used by admins or managers to fetch all entities
  Type: boolean

- `userId` (query, integer, optional) - Standard users can use this only with their own _userId_
  Type: integer

- `id` (query, integer, optional) - To fetch one or more devices. Multiple params can be passed like `id=31&id=42`
  Type: integer

- `uniqueId` (query, string, optional) - To fetch one or more devices. Multiple params can be passed like `uniqueId=333331&uniqieId=44442`
  Type: string

- `excludeAttributes` (query, boolean, optional) - Exclude attributes field from device payload
  Type: boolean

- `limit` (query, integer, optional) - Limit the number of returned results
  Type: integer

- `offset` (query, integer, optional) - Offset for pagination
  Type: integer

- `keyword` (query, string, optional) - Search keyword filter (searches name, uniqueId, phone, model, contact)
  Type: string

Responses:

- 200: OK

Content type: application/json

Type: Array<Device>

Items:
  Reference: [Device](https://sourcey-traccar.pages.dev/api-reference/models/device/index.md); Type: Device

- 400: No permission

## Examples

### cURL

```bash
curl -X GET 'https://demo.traccar.org/api/devices' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE'
```

### JavaScript

```javascript
const response = await fetch('https://demo.traccar.org/api/devices', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://demo.traccar.org/api/devices',
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    },
)
print(response.text)
```


## Create a Device

`POST /devices`

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Request body: application/json (required)

Type: Device

Schema: [Device](https://sourcey-traccar.pages.dev/api-reference/models/device/index.md)

- `id` (optional)
  Type: integer, int64
  
  Unique identifier assigned by Traccar

- `name` (optional)
  Type: string
  
  Human friendly device label

- `uniqueId` (optional)
  Type: string
  
  Hardware or protocol specific unique identifier

- `status` (optional)
  Type: string
  
  Current connection status such as `online`, `offline`, or `unknown`

- `disabled` (optional)
  Type: boolean
  
  Whether the device is disabled by an administrator

- `lastUpdate` (optional)
  Type: string, date-time; nullable
  
  in ISO 8601 format. eg. `1963-11-22T18:30:00Z`

- `positionId` (optional)
  Type: integer, int64; nullable
  
  Identifier of the last known position

- `groupId` (optional)
  Type: integer, int64; nullable
  
  Parent group identifier when the device is assigned to a group

- `phone` (optional)
  Type: string; nullable
  
  Contact phone number used for SMS commands

- `model` (optional)
  Type: string; nullable
  
  Device model or hardware revision

- `contact` (optional)
  Type: string; nullable
  
  Responsible person's contact information

- `category` (optional)
  Type: string; nullable
  
  Free form category used for grouping devices in the UI

- `attributes` (optional)
  Type: object
  
  Custom attributes for protocol or business specific data

Responses:

- 200: OK

Content type: application/json

Type: Device

Schema: [Device](https://sourcey-traccar.pages.dev/api-reference/models/device/index.md)

- `id` (optional)
  Type: integer, int64
  
  Unique identifier assigned by Traccar

- `name` (optional)
  Type: string
  
  Human friendly device label

- `uniqueId` (optional)
  Type: string
  
  Hardware or protocol specific unique identifier

- `status` (optional)
  Type: string
  
  Current connection status such as `online`, `offline`, or `unknown`

- `disabled` (optional)
  Type: boolean
  
  Whether the device is disabled by an administrator

- `lastUpdate` (optional)
  Type: string, date-time; nullable
  
  in ISO 8601 format. eg. `1963-11-22T18:30:00Z`

- `positionId` (optional)
  Type: integer, int64; nullable
  
  Identifier of the last known position

- `groupId` (optional)
  Type: integer, int64; nullable
  
  Parent group identifier when the device is assigned to a group

- `phone` (optional)
  Type: string; nullable
  
  Contact phone number used for SMS commands

- `model` (optional)
  Type: string; nullable
  
  Device model or hardware revision

- `contact` (optional)
  Type: string; nullable
  
  Responsible person's contact information

- `category` (optional)
  Type: string; nullable
  
  Free form category used for grouping devices in the UI

- `attributes` (optional)
  Type: object
  
  Custom attributes for protocol or business specific data

- 400: Bad request

- 401: Unauthorized

## Examples

### cURL

```bash
curl -X POST 'https://demo.traccar.org/api/devices' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2024-01-15T09:30:00Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": {}
}'
```

### JavaScript

```javascript
const body = `{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2024-01-15T09:30:00Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": {}
}`;

const response = await fetch('https://demo.traccar.org/api/devices', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2024-01-15T09:30:00Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": {}
}'''

response = requests.post(
    'https://demo.traccar.org/api/devices',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Fetch a Device

`GET /devices/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: OK

Content type: application/json

Type: Device

Schema: [Device](https://sourcey-traccar.pages.dev/api-reference/models/device/index.md)

- `id` (optional)
  Type: integer, int64
  
  Unique identifier assigned by Traccar

- `name` (optional)
  Type: string
  
  Human friendly device label

- `uniqueId` (optional)
  Type: string
  
  Hardware or protocol specific unique identifier

- `status` (optional)
  Type: string
  
  Current connection status such as `online`, `offline`, or `unknown`

- `disabled` (optional)
  Type: boolean
  
  Whether the device is disabled by an administrator

- `lastUpdate` (optional)
  Type: string, date-time; nullable
  
  in ISO 8601 format. eg. `1963-11-22T18:30:00Z`

- `positionId` (optional)
  Type: integer, int64; nullable
  
  Identifier of the last known position

- `groupId` (optional)
  Type: integer, int64; nullable
  
  Parent group identifier when the device is assigned to a group

- `phone` (optional)
  Type: string; nullable
  
  Contact phone number used for SMS commands

- `model` (optional)
  Type: string; nullable
  
  Device model or hardware revision

- `contact` (optional)
  Type: string; nullable
  
  Responsible person's contact information

- `category` (optional)
  Type: string; nullable
  
  Free form category used for grouping devices in the UI

- `attributes` (optional)
  Type: object
  
  Custom attributes for protocol or business specific data

- 401: Unauthorized

- 404: Not found

## Examples

### cURL

```bash
curl -X GET 'https://demo.traccar.org/api/devices/0' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE'
```

### JavaScript

```javascript
const response = await fetch('https://demo.traccar.org/api/devices/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://demo.traccar.org/api/devices/0',
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    },
)
print(response.text)
```


## Update a Device

`PUT /devices/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: Device

Schema: [Device](https://sourcey-traccar.pages.dev/api-reference/models/device/index.md)

- `id` (optional)
  Type: integer, int64
  
  Unique identifier assigned by Traccar

- `name` (optional)
  Type: string
  
  Human friendly device label

- `uniqueId` (optional)
  Type: string
  
  Hardware or protocol specific unique identifier

- `status` (optional)
  Type: string
  
  Current connection status such as `online`, `offline`, or `unknown`

- `disabled` (optional)
  Type: boolean
  
  Whether the device is disabled by an administrator

- `lastUpdate` (optional)
  Type: string, date-time; nullable
  
  in ISO 8601 format. eg. `1963-11-22T18:30:00Z`

- `positionId` (optional)
  Type: integer, int64; nullable
  
  Identifier of the last known position

- `groupId` (optional)
  Type: integer, int64; nullable
  
  Parent group identifier when the device is assigned to a group

- `phone` (optional)
  Type: string; nullable
  
  Contact phone number used for SMS commands

- `model` (optional)
  Type: string; nullable
  
  Device model or hardware revision

- `contact` (optional)
  Type: string; nullable
  
  Responsible person's contact information

- `category` (optional)
  Type: string; nullable
  
  Free form category used for grouping devices in the UI

- `attributes` (optional)
  Type: object
  
  Custom attributes for protocol or business specific data

Responses:

- 200: OK

Content type: application/json

Type: Device

Schema: [Device](https://sourcey-traccar.pages.dev/api-reference/models/device/index.md)

- `id` (optional)
  Type: integer, int64
  
  Unique identifier assigned by Traccar

- `name` (optional)
  Type: string
  
  Human friendly device label

- `uniqueId` (optional)
  Type: string
  
  Hardware or protocol specific unique identifier

- `status` (optional)
  Type: string
  
  Current connection status such as `online`, `offline`, or `unknown`

- `disabled` (optional)
  Type: boolean
  
  Whether the device is disabled by an administrator

- `lastUpdate` (optional)
  Type: string, date-time; nullable
  
  in ISO 8601 format. eg. `1963-11-22T18:30:00Z`

- `positionId` (optional)
  Type: integer, int64; nullable
  
  Identifier of the last known position

- `groupId` (optional)
  Type: integer, int64; nullable
  
  Parent group identifier when the device is assigned to a group

- `phone` (optional)
  Type: string; nullable
  
  Contact phone number used for SMS commands

- `model` (optional)
  Type: string; nullable
  
  Device model or hardware revision

- `contact` (optional)
  Type: string; nullable
  
  Responsible person's contact information

- `category` (optional)
  Type: string; nullable
  
  Free form category used for grouping devices in the UI

- `attributes` (optional)
  Type: object
  
  Custom attributes for protocol or business specific data

- 400: Bad request

- 401: Unauthorized

## Examples

### cURL

```bash
curl -X PUT 'https://demo.traccar.org/api/devices/0' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2024-01-15T09:30:00Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": {}
}'
```

### JavaScript

```javascript
const body = `{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2024-01-15T09:30:00Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": {}
}`;

const response = await fetch('https://demo.traccar.org/api/devices/0', {
  method: 'PUT',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2024-01-15T09:30:00Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": {}
}'''

response = requests.put(
    'https://demo.traccar.org/api/devices/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Delete a Device

`DELETE /devices/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 204: No Content

- 401: Unauthorized

## Examples

### cURL

```bash
curl -X DELETE 'https://demo.traccar.org/api/devices/0' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE'
```

### JavaScript

```javascript
const response = await fetch('https://demo.traccar.org/api/devices/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://demo.traccar.org/api/devices/0',
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    },
)
print(response.text)
```


## Update total distance and hours of the Device

`PUT /devices/{id}/accumulators`

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: DeviceAccumulators

Schema: [DeviceAccumulators](https://sourcey-traccar.pages.dev/api-reference/models/deviceaccumulators/index.md)

- `deviceId` (optional)
  Type: integer, int64
  
  Device identifier for the accumulator entry

- `totalDistance` (optional)
  Type: number
  
  in meters

- `hours` (optional)
  Type: number
  
  Total engine hours recorded by the device

Responses:

- 204: No Content

- 400: Bad request

- 401: Unauthorized

## Examples

### cURL

```bash
curl -X PUT 'https://demo.traccar.org/api/devices/0/accumulators' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "deviceId": 0,
  "totalDistance": 0,
  "hours": 0
}'
```

### JavaScript

```javascript
const body = `{
  "deviceId": 0,
  "totalDistance": 0,
  "hours": 0
}`;

const response = await fetch('https://demo.traccar.org/api/devices/0/accumulators', {
  method: 'PUT',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "deviceId": 0,
  "totalDistance": 0,
  "hours": 0
}'''

response = requests.put(
    'https://demo.traccar.org/api/devices/0/accumulators',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Upload/Update Device image

`POST /devices/{id}/image`

Authentication (security requirement alternatives):

```json
[
  {
    "BasicAuth": []
  },
  {
    "ApiKey": []
  }
]
```

- BasicAuth: http (basic)
- ApiKey: http (bearer)

Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: image/* (required)

Type: string, binary

Responses:

- 200: OK

Content type: text/plain

Type: string

```json
"device.png"
```

- 400: Invalid image type or size

- 404: Device not found

## Examples

### cURL

```bash
curl -X POST 'https://demo.traccar.org/api/devices/0/image' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE'
```

### JavaScript

```javascript
const response = await fetch('https://demo.traccar.org/api/devices/0/image', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://demo.traccar.org/api/devices/0/image',
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    },
)
print(response.text)
```