Getting started with the Esper REST API — authentication and your first call

This guide walks you through authenticating with the Esper REST API and making your first request. If you're building an integration, automating fleet tasks, or pulling device data into your own systems, this is where to start.

Before you begin

You'll need:

• An Esper account with API access enabled
• Your Enterprise ID — visible in the Esper console URL: https://YOUR-SUBDOMAIN.esper.cloud
• An API key — create one in the console at Settings → API Keys → Create New Key

When creating your API key, select only the scopes you need. If you're building a read-only reporting integration, don't request write permissions.

Base URL

https://YOUR_SUBDOMAIN.api.esper.io

Authentication

All requests use a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your first request — list devices

curl

curl -X GET \
  "https://YOUR_SUBDOMAIN.api.esper.io/api/v0/enterprise/YOUR_ENTERPRISE_ID/device/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Python

import requests
import os

BASE_URL     = "https://YOUR_SUBDOMAIN.api.esper.io"
ENTERPRISE   = "YOUR_ENTERPRISE_ID"
API_KEY      = os.environ["ESPER_API_KEY"]   # never hardcode keys

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{BASE_URL}/api/v0/enterprise/{ENTERPRISE}/device/",
    headers=headers
)

data = response.json()
print(f"Total devices: {data['count']}")
for device in data["results"]:
    print(f"  {device['device_name']} — {device['state']}")

Response (200 OK)

{
  "count": 42,
  "next": "https://...",
  "previous": null,
  "results": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "device_name": "KIOSK-001",
      "state": "Active",
      "status": 1
    }
  ]
}

Useful query parameters

Next steps

• Run a command on a device: POST /api/v0/enterprise/{id}/command/
• Get device details: GET /api/v0/enterprise/{id}/device/{device_id}/
• List all groups: GET /api/v0/enterprise/{id}/devicegroup/
• Full reference: api.esper.io

Security reminder: Never post your actual API key in community threads. Use YOUR_API_KEY as a placeholder in all code examples.