curl -X POST 'https://api.openai.com/v1/chatkit/sessions' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "workflow": {
    "id": "example-id",
    "version": "example-version",
    "state_variables": {},
    "tracing": {
      "enabled": true
    }
  },
  "user": "example-user"
}'

# POST /chatkit/sessions (OpenAI API)
Base URL: https://api.openai.com/v1
Auth: Authorization; OpenAI API key; required.
Request formats: application/json.
Last verified: 2026-10-20

> Create a ChatKit session

## Critical Gotchas
* The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.
* Audio transcription uploads use multipart form data rather than a JSON request body.

## cURL
curl -X POST 'https://api.openai.com/v1/chatkit/sessions' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "workflow": {
    "id": "example-id",
    "version": "example-version",
    "state_variables": {},
    "tracing": {
      "enabled": true
    }
  },
  "user": "example-user"
}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| workflow | body | object | Yes | Workflow reference and overrides applied to the chat session. |
| user | body | string | Yes | A free-form string that identifies your end user; ensures this Session can ac... |
| expires_after | body | object | No | Controls when the session expires relative to an anchor timestamp. |
| rate_limits | body | object | No | Controls request rate limits for the session. |
| chatkit_configuration | body | object | No | Optional per-session configuration settings for ChatKit behavior. |

## Response example
{"id":"cksess_123","object":"chatkit.session"}

---
Need an API key? Get one at https://platform.openai.com/api-keys

POST

POST /chatkit/sessions — OpenAI API

OpenAI API key (required); https://api.openai.com/v1

OpenAI API

Create a ChatKit session

Base URL: https://api.openai.com/v1
Auth: Authorization: Bearer <OPENAI_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 301 tokens · Vary: Accept

Critical gotchas

The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.

Audio transcription uploads use multipart form data rather than a JSON request body.

cURL

curl -X POST 'https://api.openai.com/v1/chatkit/sessions' \  -H "Authorization: Bearer $OPENAI_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "workflow": {    "id": "example-id",    "version": "example-version",    "state_variables": {},    "tracing": {      "enabled": true    }  },  "user": "example-user"}'

Parameters

Name	In	Type	Required	Description
workflow	body	object	Yes	Workflow reference and overrides applied to the chat session.
user	body	string	Yes	A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.
expires_after	body	object	No	Controls when the session expires relative to an anchor timestamp.
rate_limits	body	object	No	Controls request rate limits for the session.
chatkit_configuration	body	object	No	Optional per-session configuration settings for ChatKit behavior.

Response 200 OK

{
  "id": "cksess_123",
  "object": "chatkit.session",
  "client_secret": "ek_token_123",
  "expires_at": 1712349876,
  "workflow": {
    "id": "workflow_alpha",
    "version": "2024-10-01",
    "state_variables": {
      "message": "hello"
    },
    "tracing": {
      "enabled": true
    }
  },
  "user": "user_789",
  "rate_limits": {
    "max_requests_per_1_minute": 60
  },
  "max_requests_per_1_minute": 60,
  "status": "active",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 16,
      "max_files": 20
    },
    "history": {
      "enabled": true,
      "recent_threads": 10
    }
  }
}

Get a free OpenAI API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.