# Create a new machine (Xentr staff only — organization_admin must submit a provisioning request instead) (/docs/api-reference/machines/MachinesController_create)

`POST /api/factories/{factoryId}/machines`

Base URL: https://api.xentr.ai

Authentication: bearer token (`Authorization: Bearer <token>`).

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `factoryId` | path | yes | string | Factory ID |

## Request body

Required.

Content type: `application/json`

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Unique machine code",
      "example": "CNC-001"
    },
    "name": {
      "type": "string",
      "description": "Machine display name",
      "example": "CNC Lathe #1"
    },
    "machineType": {
      "type": "string",
      "description": "Type of machine",
      "example": "cnc_lathe"
    },
    "templateId": {
      "type": "string",
      "description": "Device-type template ID. When set, machineType + protocol are DERIVED from the template (any dto.machineType/protocol are ignored).",
      "example": "fanuc-31i-b-machining-center"
    },
    "protocol": {
      "type": "string",
      "description": "Communication protocol (canonical vocabulary)",
      "enum": [
        "fanuc-focas",
        "opc-ua",
        "modbus-tcp",
        "mtconnect",
        "mqtt",
        "andon",
        "manual"
      ],
      "example": "mqtt",
      "default": "mqtt"
    },
    "connectionConfig": {
      "type": "object",
      "description": "Connection configuration",
      "example": {
        "host": "192.168.1.100",
        "port": 1883
      }
    },
    "location": {
      "type": "string",
      "description": "Physical location",
      "example": "Building A, Line 3"
    },
    "tier": {
      "type": "string",
      "description": "Subscription tier",
      "enum": [
        "basic",
        "iot",
        "ai"
      ],
      "example": "basic",
      "default": "basic"
    },
    "workAreaId": {
      "type": "string",
      "description": "Work area ID this machine belongs to",
      "example": "a1b2c3d4-..."
    },
    "isActive": {
      "type": "boolean",
      "description": "Whether the machine is active",
      "default": true
    }
  },
  "required": [
    "code",
    "name"
  ]
}
```

## Responses

### 201: Machine created