Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Cancel a ChatKit session

POST
/chatkit/sessions/{session_id}/cancel

Cancel an active ChatKit session and return its most recent metadata.

Cancelling prevents new requests from using the issued client secret.

Path Parameters
session_id: string
Returns
ChatSession object { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

id: string

Identifier for the ChatKit session.

chatkit_configuration: ChatSessionChatKitConfiguration { automatic_thread_titling, file_upload, history }

Resolved ChatKit feature configuration for the session.

automatic_thread_titling: ChatSessionAutomaticThreadTitling { enabled }

Automatic thread titling preferences.

enabled: boolean

Whether automatic thread titling is enabled.

file_upload: ChatSessionFileUpload { enabled, max_file_size, max_files }

Upload settings for the session.

enabled: boolean

Indicates if uploads are enabled for the session.

max_file_size: number or null

Maximum upload size in megabytes.

max_files: number or null

Maximum number of uploads allowed during the session.

history: ChatSessionHistory { enabled, recent_threads }

History retention configuration.

enabled: boolean

Indicates if chat history is persisted for the session.

recent_threads: number or null

Number of prior threads surfaced in history views. Defaults to null when all history is retained.

client_secret: string

Ephemeral client secret that authenticates session requests.

expires_at: number

Unix timestamp (in seconds) for when the session expires.

formatunixtime
max_requests_per_1_minute: number

Convenience copy of the per-minute request limit.

object: "chatkit.session"

Type discriminator that is always chatkit.session.

rate_limits: ChatSessionRateLimits { max_requests_per_1_minute }

Resolved rate limit values.

max_requests_per_1_minute: number

Maximum allowed requests per one-minute window.

status: ChatSessionStatus

Current lifecycle state of the session.

One of the following:
"active"
"expired"
"cancelled"
user: string

User identifier associated with the session.

workflow: ChatKitWorkflow { id, state_variables, tracing, version }

Workflow metadata for the session.

id: string

Identifier of the workflow backing the session.

state_variables: map[string or boolean or number] or null

State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.

One of the following:
string
boolean
number
tracing: object { enabled }

Tracing settings applied to the workflow.

enabled: boolean

Indicates whether tracing is enabled.

version: string or null

Specific workflow version used for the session. Defaults to null when using the latest deployment.

Cancel a ChatKit session

curl -X POST \
  https://api.openai.com/v1/chatkit/sessions/cksess_123/cancel \
  -H "OpenAI-Beta: chatkit_beta=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

{
  "id": "cksess_123",
  "object": "chatkit.session",
  "client_secret": "",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": null,
    "state_variables": null,
    "tracing": {
      "enabled": true
    }
  },
  "user": "user_123",
  "rate_limits": {
    "max_requests_per_1_minute": 10
  },
  "max_requests_per_1_minute": 10,
  "status": "cancelled",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": false,
      "max_file_size": 512,
      "max_files": 10
    },
    "history": {
      "enabled": true,
      "recent_threads": null
    }
  }
}
Returns Examples
{
  "id": "cksess_123",
  "object": "chatkit.session",
  "client_secret": "",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": null,
    "state_variables": null,
    "tracing": {
      "enabled": true
    }
  },
  "user": "user_123",
  "rate_limits": {
    "max_requests_per_1_minute": 10
  },
  "max_requests_per_1_minute": 10,
  "status": "cancelled",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": false,
      "max_file_size": 512,
      "max_files": 10
    },
    "history": {
      "enabled": true,
      "recent_threads": null
    }
  }
}