Sample - OpenAI API
POST/chatkit/sessions

Create a ChatKit session

Creates a ChatKit session powered by a specified workflow. Supply workflow.id and user to associate the session with a workflow and end user, and use the optional configuration objects to override expiration, rate limits, tracing, and ChatKit features. The response provides an ephemeral client secret and the resolved session configuration.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

5 body fields

ChatKit session creation parameters. workflow and user are required; optional settings override session expiration, rate limits, and ChatKit runtime features.

workflowobjectrequired
Workflow that powers the session.
userstringrequired
A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.
expires_afterobjectoptional
Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.
rate_limitsobjectoptional
Optional override for per-minute request limits. When omitted, defaults to 10.
chatkit_configurationobjectoptional
Optional overrides for ChatKit runtime configuration features

1 status code
200Returns the created ChatKit session object with its identifier, object type, expiration timestamp, ephemeral client secret, workflow metadata, user, resolved rate limits, lifecycle status, and ChatKit configuration.
idstringrequired
Identifier for the ChatKit session.
objectstringrequired
Type discriminator that is always `chatkit.session`.
Allowed:chatkit.sessionDefault:chatkit.session
expires_atintegerrequired
Unix timestamp (in seconds) for when the session expires.
client_secretstringrequired
Ephemeral client secret that authenticates session requests.
workflowobjectrequired
Workflow metadata for the session.
userstringrequired
User identifier associated with the session.
rate_limitsobjectrequired
Resolved rate limit values.
max_requests_per_1_minuteintegerrequired
Convenience copy of the per-minute request limit.
statusstringrequired
Current lifecycle state of the session.
Allowed:activeexpiredcancelled
chatkit_configurationobjectrequired
Resolved ChatKit feature configuration for the session.

Error handling

workflow and user are required, and workflow.id must be provided. expires_after requires both anchor and seconds, with anchor set to created_at and seconds between 1 and 600; state_variables supports at most 64 properties and max_requests_per_1_minute must be at least 1.