---
title: "File a visitor request as the host"
method: POST
path: "/api/guests"
tags: ["guests", "browser-session"]
---

# File a visitor request as the host

`POST /api/guests`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/guests`
- Auth: API key in cookie `__session`

Clerk-session only. Records a PENDING visitor request against the signed-in member as host; the authoritative visitor record is still cut operator-side, so a 200 here means 'queued', never 'your guest is cleared in'. `host_notified: true` reports that the intake was filed, not that a human has read it.

## Request body

- GuestVisitRequest
  - `name` string, required: The visitor's name.
  - `expected_at` string, required: ISO-8601 date or timestamp for the visit.
  - `purpose` string, required: Why they are coming.
  - `request_text` string: Anything else the host wants the floor to know.

## Response `200`

The request was queued.

- GuestVisitCreatedResponse
  - `ok` boolean, required
  - `id` string, required: The pending request id.
  - `host_notified` boolean, required: That the intake was filed — not that a human has read it.

## Other responses

- `400`: Body is not JSON, or name / expected_at / purpose is missing or malformed.
- `401`: Not signed in.
- `413`: Body exceeds the intake byte cap.
- `500`: KV write failed.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)