# GameCloud API documentation

The HexaHost GameCloud REST API is documented with OpenAPI (Swagger) and served by the API process.

## Interactive documentation

When the API is running:

| Environment | URL |
|-------------|-----|
| Local development | http://localhost:3001/api/v1/docs |
| Production | https://api.example.net/api/v1/docs |

Replace `api.example.net` with your `API_HOST` / `API_URL` hostname.

The OpenAPI JSON spec is available at `/api/v1/docs-json` on the same host.

## Authentication

| Audience | Method |
|----------|--------|
| Customer panel / users | Session cookie or bearer token after `POST /api/v1/auth/login` |
| WHMCS integration | HMAC-signed requests — see [WHMCS security](../integrations/whmcs/security.md) |
| Node agent | mTLS + enrollment token on WebSocket |
| Admin | Elevated role on session |

Public health endpoints (`/api/v1/health/*`) require no authentication.

## Versioning

All routes are prefixed with `/api/v1/`. Breaking changes require a new major prefix; WHMCS modules declare compatible `APIVersion` in module metadata.

## Code location

- Controllers: `apps/api/src/**/*.controller.ts`
- Swagger setup: `apps/api/src/main.ts` (`SwaggerModule.setup('api/v1/docs', ...)`)
- DTOs: colocated with controllers and in `packages/shared`

## Generating a static export

```bash
curl -s http://localhost:3001/api/v1/docs-json -o openapi.json
```

Use with codegen tools or import into Postman/Insomnia.

## Related

- [Control plane operations](../operations/control-plane.md)
- [WHMCS integration](../integrations/whmcs/installation.md)
- [Threat model](../security/threat-model.md)