Trackable Devices

Manage AirTags and other trackable devices with the AirPinpoint API.

List Trackable Devices

Retrieve a list of all trackable devices associated with your account, including their latest location and battery information.

Endpoint

GET /v1/trackables

Query Parameters

skip (optional): Number of items to skip for pagination (default: 0)
limit (optional): Maximum number of items to return (1-100, default: 50)

Example Request

curl -X GET "https://api.airpinpoint.com/v1/trackables?limit=20" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "model": "AirTag",
    "name": "Car Keys",
    "enabled": true,
    "createdAt": "2023-06-15T14:30:00.000Z",
    "pairedAt": "2023-06-10T09:15:22Z",
    "lastKnownLocation": {
      "id": "loc123456-7890-abcd-ef12-123456789012",
      "trackableId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "altitude": null,
      "horizontalAccuracy": 10,
      "verticalAccuracy": null,
      "batteryLevel": 0,
      "timestamp": "2023-06-15T14:30:00Z",
      "isOld": false,
      "isInaccurate": false,
      "createdAt": "2023-06-15T14:30:05.123Z",
      "updatedAt": "2023-06-15T14:30:05.123Z",
      "deletedAt": null
    },
    "batteryInfo": {
      "lastBatteryReset": "2023-01-01T00:00:00.000Z",
      "batteryMonths": 12,
      "estimatedDaysRemaining": 200,
      "batteryPercentage": 55
    }
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-2345678901cd",
    "model": "iPhone 13",
    "name": "My Phone",
    "enabled": true,
    "createdAt": "2023-05-20T10:15:30.000Z",
    "pairedAt": "2023-05-20T10:15:30Z",
    "lastKnownLocation": {
      "id": "loc234567-8901-bcde-f123-2345678901de",
      "trackableId": "b2c3d4e5-f6a7-8901-bcde-2345678901cd",
      "latitude": 37.3382,
      "longitude": -121.8863,
      "altitude": 12.5,
      "horizontalAccuracy": 5,
      "verticalAccuracy": 3,
      "batteryLevel": 0.75,
      "timestamp": "2023-06-15T14:25:00Z",
      "isOld": false,
      "isInaccurate": false,
      "createdAt": "2023-06-15T14:25:05.456Z",
      "updatedAt": "2023-06-15T14:25:05.456Z",
      "deletedAt": null
    },
    "batteryInfo": null
  }
]

Get Trackable Device Details

Retrieve detailed information about a specific trackable device, including its latest location and battery status.

Endpoint

GET /v1/trackables/{trackable_id}

Example Request

curl -X GET "https://api.airpinpoint.com/v1/trackables/a1b2c3d4-e5f6-7890-abcd-1234567890ab" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "model": "AirTag",
  "name": "Backpack",
  "enabled": true,
  "createdAt": "2023-06-15T14:30:00.000Z",
  "pairedAt": "2023-06-10T09:15:22Z",
  "lastKnownLocation": {
    "id": "loc123456-7890-abcd-ef12-123456789012",
    "trackableId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": null,
    "horizontalAccuracy": 10,
    "verticalAccuracy": null,
    "batteryLevel": 0.85,
    "timestamp": "2023-06-15T14:30:00Z",
    "isOld": false,
    "isInaccurate": false,
    "createdAt": "2023-06-15T14:30:05.123Z",
    "updatedAt": "2023-06-15T14:30:05.123Z",
    "deletedAt": null
  },
  "batteryInfo": {
    "lastBatteryReset": "2023-01-01T00:00:00.000Z",
    "batteryMonths": 12,
    "estimatedDaysRemaining": 200,
    "batteryPercentage": 55
  }
}

Get Current Location

Retrieve the most recent location for a specific trackable device.

Endpoint

GET /v1/trackables/{trackable_id}/current_location

Example Request

curl -X GET "https://api.airpinpoint.com/v1/trackables/tag_123456/current_location" \
     -H "Authorization: Bearer YOUR_API_KEY"

Get Location History

Retrieve location history for a specific trackable device.

Endpoint

GET /v1/trackables/{trackable_id}/locations

Query Parameters

skip (optional): Number of items to skip (default: 0)
limit (optional): Maximum number of items to return (1-1000, default: 10)
start_time (optional): Start of time range (ISO 8601 format)
end_time (optional): End of time range (ISO 8601 format)

Example Request

curl -X GET "https://api.airpinpoint.com/v1/trackables/a1b2c3d4-e5f6-7890-abcd-1234567890ab/locations?limit=50" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": "loc123456-7890-abcd-ef12-123456789012",
    "trackableId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": null,
    "horizontalAccuracy": 10,
    "verticalAccuracy": null,
    "batteryLevel": 0.85,
    "timestamp": "2023-06-15T14:30:00Z",
    "isOld": false,
    "isInaccurate": false,
    "createdAt": "2023-06-15T14:30:05.123Z",
    "updatedAt": "2023-06-15T14:30:05.123Z",
    "deletedAt": null
  },
  {
    "id": "loc234567-8901-bcde-f123-2345678901de",
    "trackableId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "latitude": 37.7750,
    "longitude": -122.4195,
    "altitude": null,
    "horizontalAccuracy": 12,
    "verticalAccuracy": null,
    "batteryLevel": 0.85,
    "timestamp": "2023-06-15T14:00:00Z",
    "isOld": false,
    "isInaccurate": false,
    "createdAt": "2023-06-15T14:00:05.456Z",
    "updatedAt": "2023-06-15T14:00:05.456Z",
    "deletedAt": null
  }
]

Get Battery Information

Retrieve battery information for a specific trackable device.

Endpoint

GET /v1/trackables/{trackable_id}/battery

Authentication

API key required in the Authorization header.

Path Parameters

Parameter	Type	Description
trackable_id	string	ID of the trackable device

Example Request

curl -X GET "https://api.airpinpoint.com/v1/trackables/abc123/battery" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Status Code	Description
200	Battery information retrieved successfully
404	Trackable not found or battery information unavailable
401	Unauthorized

Example Response

{
  "lastBatteryReset": "2023-06-15T10:30:00Z",
  "batteryMonths": 12,
  "estimatedDaysRemaining": 280
}

Reset Battery Life

Reset the battery life for a specific trackable device.

Endpoint

POST /v1/trackables/{trackable_id}/battery

Authentication

API key required in the Authorization header.

Path Parameters

Parameter	Type	Description
trackable_id	string	ID of the trackable device

Request Body

Field	Type	Description
batteryMonths	integer	Expected battery life in months

Example Request

curl -X POST "https://api.airpinpoint.com/v1/trackables/abc123/battery" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"batteryMonths": 12}'

Response

Status Code	Description
200	Battery reset successful
404	Trackable not found
401	Unauthorized

Example Response

{
  "message": "Battery reset successful"
}

Location Tracking Geofencing