Create end user session for alias
POST/v2/agent_aliases/:alias_key/end_user_sessions
Creates a session owned by the calling end user, routed through this alias's policy. The session's owning principal is the caller's authenticated identity.
An administrator calling this operation is bound to the sessions it owns like every other caller; the operator endpoints are the administrative view of an alias's sessions.
Ownership binds to the alias key, not the resolved agent, so it is unaffected by a later change to the alias's routing weights.
Anonymous widget visitors authenticate by presenting X-Visitor-Id instead of an Authorization credential; the platform mints an identity holding agent_end_user on the addressed alias, which satisfies this operation's role requirement.
The session takes its idle lifetime from its widget connector's session_tti_minutes, reported on the returned session.
Returns 429 when the caller reaches the live-session or hourly session-creation cap, or when the customer-wide anonymous session-creation ceiling is reached.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 422
- 429
The newly created session.
The addressed alias has no enabled widget connector to bind the session to.
The request carries no valid credential — no Authorization, and for anonymous callers a missing, malformed, or badly signed X-Visitor-Id.
Permissions do not allow creating sessions for this alias. For an anonymous visitor, also returned when the widget connector its token was minted through no longer admits visitors or does not front this alias.
Alias not found.
No session was created. Either the requested session key or name is already taken, or the resolved agent's run_condition evaluated to false. A collision names itself in messages and needs a different key or name. A run_condition refusal carries a generic message on this surface, and the same request succeeds once the expression, or the metadata it reads, changes.
No session was created. A session_enrichment tool call on the resolved agent has an invalid configuration or its transform raised an error, or the resolved agent's run_condition returned a non-boolean. messages carries a generic failure message on this surface and does not identify the cause. createAgentSession (POST /v2/agents/{agent_key}/sessions) reports the specific cause.
The request exceeds the caller's live-session or hourly session-creation cap.