sessions

Create Session

Create new session with optional initial messages.

Supports three access levels for agents/teams:

PUBLIC: No authentication required
PASSWORD_PROTECTED: X-Access-Password header required
PRIVATE: User authentication required

Supports team_identifier and agent_identifier strings to lookup team_id and agent_id. If identifiers are provided and found, the corresponding IDs will be set. If not found, team_id and agent_id will remain NULL.

X-Access-Passwordstring nullable

Request body

session_idstring required

team_idinteger nullable

agent_idinteger nullable

team_identifierstring nullable

agent_identifierstring nullable

summarystring nullable

summary_metadataobject nullable

Metadata from summary generation: key_topics, sentiment, action_items, primary_intent

session_type'USER' | 'INTERNAL' | 'DEBUG'

Session type for visibility control.

Following SOLID principles:

Single Responsibility: Each type has one clear visibility pattern
Open/Closed: New types can be added without modifying existing code

channel'JOINA_CHAT' | 'QR' | 'WIDGET' | 'INTERNAL' | 'API'

Origin channel a session was created on — informational display metadata.

Set once at creation on the client-known surface (POST /sessions) and surfaced on reads so the Collected Data inbox can render "via joina.chat" per record. Mirrors SessionType's varchar+StrEnum shape MINUS the index.

INFORMATIONAL AND FORGEABLE BY DESIGN: it rides a public unauthenticated POST /sessions and is enum-validated (invalid → 422) but NEVER drives authorization or visibility — that stays session_type. Do not "fix" this as a security hole.

Response

Successful Response