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. A visitor id is customer-scoped, so it need not have been minted through the connector named in the request body; that connector must still admit anonymous visitors (403 otherwise). The connector's allowed_origins also applies to anonymous and signed-in callers; requests without an Origin header are admitted.
The session binds to the connector named by the request body's connector_id and takes its idle lifetime from that 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 request body's connector_id does not name an enabled widget connector on the addressed alias, or the addressed alias is disabled.
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 connector named in the request body does not admit anonymous visitors. Also returned when the request Origin is not in the connector's allowed_origins.
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.