---
title: "Create Room For Agent"
method: POST
path: "/api/v1/memory/rooms"
tags: ["memory"]
---

# Create Room For Agent

`POST /api/v1/memory/rooms`

## Request

- Base URL: `https://core.mnemoverse.com`
- URL: `https://core.mnemoverse.com/api/v1/memory/rooms`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Create a room owned by the AUTHENTICATED account (Rooms Wave 2).

Unlike the portal-plane ``/rooms`` routes (which require ``X-Admin-Key`` + a
verified session), this endpoint lives on the tenant ``router`` and derives
the owner from ``request.state.claims`` — the org that the auth middleware
(DB-backed ``mk_live_`` key / JWT) populated. So an agent holding only its
``mk_live_`` key can provision its own room. The owner is taken from the
key's claims (``_get_org_id``), NEVER the request body (the schema also
forbids a body-supplied ``owner_org_id``) — the same anti-self-grant
invariant the portal path enforces from the session.

Note: this path is NOT in the middleware's portal-prefix bypass list
(``/admin``/``/rooms``/``/projects``), so tenant-key auth runs here as normal.
A fresh room seeds its owner as a ``read_write`` member (see
``RoomStore.create_room``), so the owner can immediately read/write it via
the ``xroom:<room_id>`` address; inviting OTHER accounts is a separate step.

## Request body

- CreateRoomRequestSchema: Body for an agent creating a room with its own tenant key (Rooms Wave 2). Deliberately has NO ``owner_org_id`` — the owner is derived from the authenticated key's claims, never the request body (anti-self-grant, the same invariant the portal path enforces from the session). ``extra="forbid"`` rejects a smuggled ``owner_org_id`` outright.
  - `name` string, required: Room name (unique within your account).
  - `description` string, nullable: Optional human description.

## Response `200`

Successful Response

- RoomCreatedSchema: Response for a freshly created room — carries the ready-to-use address AND actionable next steps. Agents read tool output, not documentation: the response itself must teach how to use the room and how a second account joins, or the room dead-ends with its creator.
  - `room_id` string, required: The room's public id (room_<ulid>).
  - `address` string, required: Ready-to-use domain address: xroom:<room_id>.
  - `name` string, required: The room name as stored.
  - `next_steps` string, required: Human/agent-readable guidance: how to use the room now and how to bring other accounts in.

## Other responses

- `400`: Validation error
- `401`: Caller org not identified
- `403`: Forbidden
- `404`: Not found
- `409`: Room name already exists for this account
- `422`: Validation Error
- `429`: Rate limited
- `500`: Internal server error
- `503`: Rooms require the database backend

---

[API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)