---
title: "Create Connection"
method: POST
path: "/v1/connections"
tags: ["connections"]
---

# Create Connection

`POST /v1/connections`

## Request

- Base URL: `https://api.cyberdesk.io`
- URL: `https://api.cyberdesk.io/v1/connections`
- Auth: HTTP bearer

Create a new connection (typically done by the WebSocket handler).

The machine must exist and belong to the authenticated organization.

## Headers

- `Idempotency-Key` string

## Request body

- ConnectionCreate: Schema for creating a connection
  - `websocket_id` string, required
  - `ip_address` string, nullable
  - `user_agent` string, nullable
  - `machine_id` string, uuid, required

## Response `201`

Successful Response

- ConnectionResponse: Connection response schema
  - `websocket_id` string, required
  - `ip_address` string, nullable
  - `user_agent` string, nullable
  - `id` string, uuid, required
  - `machine_id` string, uuid, required
  - `connected_at` string, date-time, required
  - `disconnected_at` string, date-time, nullable, required
  - `last_ping` string, date-time, required
  - `status` 'connected' | 'disconnected' | 'error', required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cyberdesk-hq/apis/cyberdesk-cloud.md) - [All operations](https://skmtc.dev/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/cyberdesk-hq/apis/cyberdesk-cloud/revisions/5579352ae05e?raw)