---
title: "Embed Session"
method: POST
path: "/api/embed/{agent_identity_id}/session"
tags: ["agent-embed"]
---

# Embed Session

`POST /api/embed/{agent_identity_id}/session`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/embed/{agent_identity_id}/session`
- Auth: none declared

Bootstrap a visitor and their chat, for the chromeless chat UI (TOS-3161).

The two existing embed routes (``turn``, ``forget``) are a write-only
echo: the reply comes back in the response to the visitor's own POST, and
there is no way to read history or watch a reply stream. Reusing the
product's real chat surface fixes that, but the real surface needs a
``chat_id`` and a ``vis_`` bearer token to authenticate against
``GET/POST /api/chats/{chat_id}/...`` BEFORE the visitor has said
anything - the UI wants to mount and show a composer immediately, not
only after a first message.

This is that bootstrap, and only that: authorize the origin, mint-or-
resolve the visitor, guarantee they have a chat, and hand back exactly
what the chat UI needs to mount. No budget check, because no model call
happens here - a visitor who loads the widget and never sends anything
must not cost the agent owner a turn. The daily and per-visitor ceilings
are still claimed inside ``send_message``/``stream_message`` themselves
the ordinary way every chat turn claims them, unaffected by this route.

## Path parameters

- `agent_identity_id` string, uuid, required

## Headers

- `origin` string, nullable
- `x-agent-visitor` string, nullable

## Response `200`

Successful Response

- SessionResponse: A visitor's token, identity and the chat they'll talk in - nothing else. Deliberately the entire payload. This endpoint mints identity, not conversation: no message is sent, no ceiling is spent, no model is called.
  - `visitor_token` string, nullable, required
  - `chat_id` string, required
  - `visitor_identity_id` string, required
  - `entry_profile` EmbedEntryProfile, required
    - `display_name` string, nullable, required
    - `introduction` string, nullable, required
    - `starter_prompts` string[], required
  - `page_awareness` 'manual' | 'text' | 'text_and_picture', required
  - `visitor_screen_share` boolean, required

## Other responses

- `422`: Validation Error

---

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