# API Reference Overview

> Overview of the Cephable REST API and real-time device hub for receiving adaptive input commands.

Source: https://developers.cephable.com/docs/api-reference/overview

---
## Base URL

```
https://services.cephable.com/
```

All requests must be made over HTTPS. The API uses JSON for both request and response bodies.

For the full, interactive API reference see the **[Swagger UI](https://services.cephable.com/swagger)**.

## Authentication overview

Cephable uses **OAuth 2.0 Authorization Code** flow. Your application redirects users to the Cephable login page, receives an authorization code on redirect, and exchanges it for access and refresh tokens.

You will need:
- **OAuth Client ID** — obtained from the [Cephable Portal](https://portal.cephable.com)
- **OAuth Client Secret** — obtained from the [Cephable Portal](https://portal.cephable.com)
- **Device Type ID** — the ID of the device type you registered in the [Cephable Portal](https://portal.cephable.com)

See [Authentication](/docs/api-reference/authentication) for the full details.

## Device API

The device API manages **User Devices** — virtual controllers that appear in a user's Cephable app after they authenticate.

### Create a User Device

```http
POST https://services.cephable.com/api/Device/userDevices/new/{deviceTypeId}?name={deviceName}
Authorization: Bearer {userAccessToken}
```

**Response:**

```json
{
  "id": "...",
  "nameOverride": "Web-Sample",
  "isVerified": false,
  "isConnected": false,
  "isListening": false,
  "isAutoListen": false,
  "isOptimisticModel": false,
  "currentProfile": null
}
```

### Create a Device Token

Once you have a user device, create a device token to authenticate the SignalR hub connection:

```http
POST https://services.cephable.com/api/Device/userDevices/{userDeviceId}/tokens
Authorization: Bearer {userAccessToken}
```

**Response:**

```json
{
  "id": "...",
  "userDeviceId": "...",
  "token": "...",
  "isDisabled": false
}
```

The `token` value is used as the `X-Device-Token` header (and bearer token) when connecting to the device hub.

## Device Hub (SignalR)

After creating a device token, connect to the real-time hub to receive commands from the Cephable app. The hub uses **ASP.NET Core SignalR**.

### Hub URL

```
https://services.cephable.com/device
```

### Connecting

Pass the device token as both a bearer token and the `X-Device-Token` header:

```javascript
// JavaScript (using @microsoft/signalr)
const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://services.cephable.com/device", {
    accessTokenFactory: () => deviceToken,
    headers: { "X-Device-Token": deviceToken },
  })
  .withAutomaticReconnect()
  .build();

await connection.start();
// Identify device to hub
const device = await connection.invoke("VerifySelf");
```

### Incoming events (hub → client)

| Event | Description |
|-------|-------------|
| `DeviceCommand` | User triggered an input command — carries the command string |
| `DeviceProfileUpdate` | User's active profile changed — carries updated `UserDevice` |
| `DeviceSettingsUpdate` | Device settings changed |
| `DeviceType` | Device type information |
| `StartListening` | Hub instructed device to start listening |
| `StopListening` | Hub instructed device to stop listening |

#### DeviceCommand

```javascript
connection.on("DeviceCommand", (command, macro) => {
  console.log("Command: " + command);
  console.log("Macro: " + JSON.stringify(macro));
});
```

#### DeviceProfileUpdate

```javascript
connection.on("DeviceProfileUpdate", (device) => {
  const profile = device.currentProfile?.configuration;
  // update local state with new profile
});
```

### Outgoing messages (client → hub)

| Method | Description |
|--------|-------------|
| `VerifySelf` | Identifies the connected device; returns the current `UserDevice` |
| `GetLatestDevice` | Requests the latest device state |
| `DeviceStartedListening` | Notifies the hub that the device is ready to receive commands |
| `DeviceStoppedListening` | Notifies the hub that the device has stopped listening |

```javascript
await connection.invoke("VerifySelf");
await connection.invoke("DeviceStartedListening");
```

## UserDevice data model

```json
{
  "id": "string",
  "nameOverride": "string",
  "isVerified": true,
  "isConnected": true,
  "isListening": true,
  "isAutoListen": false,
  "isOptimisticModel": false,
  "currentProfile": {
    "id": "string",
    "name": "string",
    "userId": "string",
    "profileType": "string",
    "configuration": {
      "profileType": "string",
      "commandKeyMappings": [],
      "macros": [],
      "hotkeys": [],
      "dictationCommands": [],
      "audioEvents": []
    }
  }
}
```

## Macro event types

When a user triggers a command, the hub delivers both the command string and the associated macro. Macro events have the following types:

```json
["KeyPress", "Pause", "Type", "MouseMove", "JoysticksMove", "PlayAudio",
 "KeyRelease", "StopOutputs", "KeyToggle", "DeviceTypeCustomAction"]
```

Example macro payload:

```json
{
  "id": "2c13dc42-6e06-4e03-a780-798cb86cef1a",
  "name": "Move Forward",
  "commands": ["move forward", "go forward", "head_tilt_forward"],
  "events": [
    {
      "eventType": "KeyPress",
      "keys": ["w"],
      "holdTimeMilliseconds": 0,
      "isKeyLatch": false
    }
  ]
}
```

## Next steps

- [Authentication](/docs/api-reference/authentication) — OAuth flow details
- [Swagger UI](https://services.cephable.com/swagger) — Full interactive API reference
- [Virtual Controller Integration](/docs/game-integrations/virtual-controller) — Use the hub in your app