OpenAI API (unofficial showcase)
POST/chatkit/sessions

Create a ChatKit session

Creates a ChatKit session powered by a specified workflow. Supply workflow with its required id and a non-empty user identifier; optionally configure expiration, rate limits, tracing, and ChatKit features. The response includes the session's client secret, expiration time, and resolved configuration.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields

ChatKit session configuration, including the required workflow and end-user identifier, with optional expiration, rate limit, and runtime feature overrides.

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

4 status codes
200Returns the created ChatKit session object, including its identifier, client secret, expiration timestamp, workflow metadata, status, rate limits, and resolved 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.
400Returned when the request is invalid or the required ChatKit beta header is missing or invalid.
errorobjectrequired
404Returned when the requested workflow or workflow version is not found or is not accessible.
errorobjectrequired
429Returned when the request rate limit has been exceeded.
errorobjectrequired

Error handling

A 400 is returned when the request is invalid or the required ChatKit beta header is missing or invalid. A 404 is returned when the workflow or requested workflow version is not found or accessible. A 429 is returned when the request rate limit is exceeded. workflow and user are required, and workflow.id is required; user must contain at least one character. If provided, expires_after requires anchor to be created_at and seconds to be between 1 and 600; rate_limits.max_requests_per_1_minute must be at least 1.