---
title: "Register Machine"
method: POST
path: "/api/v1/machines/register"
tags: ["machines"]
---

# Register Machine

`POST /api/v1/machines/register`

Register a new daemon machine or re-register an existing one.

Creates the machine record if it does not already exist. Returns a
short-lived machine token that the daemon uses to authenticate its
WebSocket connection.

## Request body

- MachineRegisterRequest — Request to register or re-register a daemon machine.
  - `machine_id` string, nullable — Existing machine identifier when re-registering
  - `machine_name` string, required — Friendly name unique per user
  - `hostname` string, required — OS hostname of the machine
  - `platform` string, required — Operating system platform (e.g. linux, darwin)
  - `architecture` string, required — CPU architecture (e.g. x86_64, arm64)
  - `daemon_version` string, required — Semantic version of the running daemon
  - `directories` string[] — Absolute paths reported by the daemon
  - `metadata` object, nullable — Arbitrary key-value metadata about the machine

## Response `201`

Successful Response

- MachineRegisterResponse — Response after a successful machine registration.
  - `machine` MachineDescriptor, required — Serialized machine entity returned to API clients.
    - `id` string, required — Unique machine identifier
    - `name` string, required — Friendly name unique per user
    - `hostname` string, nullable — OS hostname of the machine
    - `platform` string, nullable — Operating system platform (e.g. linux, darwin)
    - `architecture` string, nullable — CPU architecture (e.g. x86_64, arm64)
    - `daemon_version` string, nullable — Semantic version of the running daemon
    - `status` string, required — Current machine status (online, offline, etc.)
    - `last_seen_at` string, date-time, nullable — Timestamp of the last heartbeat from this machine
    - `created_at` string, date-time, required — Timestamp when the machine was first registered
    - `updated_at` string, date-time, required — Timestamp of the most recent update
    - `metadata` object, nullable — Arbitrary key-value metadata about the machine
  - `machine_token` string, required — Short-lived JWT token for machine WebSocket authentication
  - `machine_token_expires_in` integer, required — Seconds until the machine token expires
  - `machine_ws_path` string, required — WebSocket path the daemon should connect to

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/omnara/apis/omnara-api.md) · [All operations](https://skmtc.dev/omnara/apis/omnara-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnara/omnara-api/revisions/624048e40cad/schema)