---
title: "Register Relay Instance"
method: POST
path: "/api/v1/relay/register"
tags: ["relay"]
---

# Register Relay Instance

`POST /api/v1/relay/register`

Register a relay client and return a short-lived relay token.

The relay token is used to authenticate the client's WebSocket
connection to the session relay channel.

## Request body

- RelayRegisterRequest — Request to register a new relay client for a user session.
  - `user_session_id` string, required — Identifier of the user session the relay client will operate within.
  - `client_kind` 'cli' | 'web' | 'mobile' | 'voice' — Type of client connecting to the relay.

## Response `200`

Successful Response

- RelayRegisterResponse — Response containing relay connection credentials after registration.
  - `user_session_id` string, required — Identifier of the user session scoped to this relay token.
  - `relay_token` string, required — Short-lived relay token for websocket authentication.
  - `relay_token_expires_in` integer, required — Seconds until the relay token expires.
  - `relay_ws_path` string, required — WebSocket path for the relay endpoint.
  - `relay_heartbeat_interval_sec` integer, required — Heartbeat interval clients should respect.

## 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)