> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charlemagnelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> The Charley REST API — base URL, authentication, and conventions

The Charley API is a RESTful HTTP API that powers the dashboard. You can use it to build custom integrations, automate device management, or pull analytics into your own systems.

## Base URL

```
https://dash.charlemagnelabs.ai
```

All endpoints are prefixed with `/api`. Example: `https://dash.charlemagnelabs.ai/api/devices`.

## Authentication

The API uses **Bearer token authentication** with Auth0-issued JWTs.

```bash theme={null}
curl https://dash.charlemagnelabs.ai/api/session \
  -H "Authorization: Bearer <your_token>"
```

To obtain a token programmatically, use the Auth0 [Client Credentials flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) with your organization's API audience.

<Note>
  Tokens are short-lived (typically 24 hours). Your application should handle token refresh automatically.
</Note>

## Response Format

All responses return JSON. Successful responses return a 2xx status code. Error responses include a `message` field:

```json theme={null}
{
  "message": "Device not found"
}
```

## Common Status Codes

| Code  | Meaning                                 |
| ----- | --------------------------------------- |
| `200` | OK                                      |
| `201` | Created                                 |
| `204` | No Content (successful delete)          |
| `400` | Bad Request — check your request body   |
| `401` | Unauthorized — missing or invalid token |
| `403` | Forbidden — insufficient role           |
| `404` | Not Found                               |
| `500` | Internal Server Error                   |

## Rate Limiting

The API does not currently enforce rate limits, but we recommend no more than **60 requests per minute** per organization for polling use cases.

## Versioning

The API is currently unversioned. Breaking changes will be communicated in advance via email and the changelog.