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

# REST API Overview

> Interactive API reference, playground, and authentication models for Qumo Deploy.

# Qumo Deploy REST API

The Qumo Deploy REST API provides programmatic control over edge relay clusters, ephemeral token issuance, tenant lifecycle, bot machine identities, and billing.

***

## Base URLs

| Environment           | Base URL                |
| :-------------------- | :---------------------- |
| **Production**        | `https://api.qumo.dev`  |
| **Local Development** | `http://localhost:8080` |

***

## Authentication

The REST API supports two authentication mechanisms depending on the endpoint category:

### 1. API Keys (`X-API-Key`)

Used for direct machine-to-machine interactions and relay token issuance (`POST /api/v1/credentials`).
Format: `qumo_live_<64 hex chars>` or `qumo_test_<64 hex chars>`.

```bash theme={null}
curl -X POST https://api.qumo.dev/api/v1/credentials \
  -H "X-API-Key: qumo_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["relay:session"], "ttl_seconds": 3600}'
```

### 2. Bearer Authentication (`Authorization: Bearer <token>`)

Used for administrative routes under `/admin/v1/`, including project creation, bot management, and billing operations. Accepts:

* **Bot tokens** (`POST /admin/v1/projects/{project_id}/bots/{id}/keys`)
* **CLI / OAuth 2.0 Device Flow tokens** (`qumod login`)

```bash theme={null}
curl https://api.qumo.dev/admin/v1/projects \
  -H "Authorization: Bearer sec_live_..."
```

***

## Interactive API Playground

You can explore and execute live test requests against all REST endpoints directly within the documentation playground using the endpoints listed in the navigation menu:

* **System & Probes**: `/healthz`, `/readyz`, `/v1/pricing`, `/v1/plans`
* **Authentication & Sessions**: `GET /admin/v1/auth/session`
* **Projects & Workspaces**: `GET/POST /admin/v1/projects`
* **Relay Credentials**: `POST /api/v1/credentials`, `POST /admin/v1/credentials/{jti}/revoke`
* **Machine Identities (Bots)**: `GET/POST /admin/v1/projects/{project_id}/bots`

***

## OpenAPI Specification File

The complete OpenAPI 3.1 schema is maintained directly in the repository at [openapi.yaml](/api-reference/openapi.yaml).