---
title: "Register an organization host"
method: POST
path: "/api/v0beta1/hosts"
tags: ["Hosts"]
---

# Register an organization host

`POST /api/v0beta1/hosts`

## Request

- Base URL: `https://app.amika.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://app.amika.dev/api/v0beta1/hosts`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `wos-session`

Idempotent by hostname: registering a hostname the organization already has returns that host with 200 and leaves its stored secret and sizes unchanged. Use PUT to rotate the secret or replace the sizes.

## Request body

- CreateHostRequest
  - `hostname` string, required
  - `url` string, uri, nullable
  - `secret` string, required
  - `sizes` object
  - `transport_mode` 'listen' | 'tunnel'

## Response `200`

Host already registered. The secret value is never returned.

- Host
  - `id` string, required
  - `hostname` string, required
  - `url` string, nullable, required
  - `org_id` string, required
  - `sizes` object, required
  - `transport_mode` 'listen' | 'tunnel', required
  - `created_at` union, required
    - string
    - string, date-time
  - `updated_at` union, required
    - string
    - string, date-time

## Other responses

- `201`: Created host. The secret value is never returned.
- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Error
- `409`: Error

## Changes

- **2026-10-23** `c46868fd7b41`: 4 info
  - added the new optional request property `transport_mode`
  - added the non-success response with the status `409`
  - added the required property `transport_mode` to the response with the `200` status
  - added the required property `transport_mode` to the response with the `201` status
- **2026-10-03** `a122301d00e0`: 1 breaking, 1 info
  - added the pattern `^[\x21-\x7e]{32,}$` to the request property `secret`
  - the `secret` request property's minLength was decreased from `1` to `0`
- **2026-09-30** `f9bd53246a8c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/amika/apis/amika-api/changes/api/v0beta1/hosts/post.md)

---

[API](https://skmtc.dev/amika/apis/amika-api.md) - [All operations](https://skmtc.dev/amika/apis/amika-api/llms.txt) - [OpenAPI document](https://skmtc.dev/amika/apis/amika-api/revisions/86f031a957c1?raw)