ChatKit

Domain Types

ChatKit Workflow

class ChatKitWorkflow:

Workflow metadata and state returned for the session.
- String id
  
  Identifier of the workflow backing the session.
- Optional<StateVariables> stateVariables
  
  State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
  - String
  - boolean
  - double
- Tracing tracing
  
  Tracing settings applied to the workflow.
  - boolean enabled
    
    Indicates whether tracing is enabled.
- Optional<String> version
  
  Specific workflow version used for the session. Defaults to null when using the latest deployment.

Sessions

Cancel chat session

ChatSession beta().chatkit().sessions().cancel(SessionCancelParamsparams = SessionCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

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.

Parameters

SessionCancelParams params
- Optional<String> sessionId

Returns

class ChatSession:

Represents a ChatKit session and its resolved configuration.
- String id
  
  Identifier for the ChatKit session.
- ChatSessionChatKitConfiguration chatkitConfiguration
  
  Resolved ChatKit feature configuration for the session.
  - ChatSessionAutomaticThreadTitling automaticThreadTitling
    
    Automatic thread titling preferences.
    - boolean enabled
      
      Whether automatic thread titling is enabled.
  - ChatSessionFileUpload fileUpload
    
    Upload settings for the session.
    - boolean enabled
      
      Indicates if uploads are enabled for the session.
    - Optional<Long> maxFileSize
      
      Maximum upload size in megabytes.
    - Optional<Long> maxFiles
      
      Maximum number of uploads allowed during the session.
  - ChatSessionHistory history
    
    History retention configuration.
    - boolean enabled
      
      Indicates if chat history is persisted for the session.
    - Optional<Long> recentThreads
      
      Number of prior threads surfaced in history views. Defaults to null when all history is retained.
- String clientSecret
  
  Ephemeral client secret that authenticates session requests.
- long expiresAt
  
  Unix timestamp (in seconds) for when the session expires.
- long maxRequestsPer1Minute
  
  Convenience copy of the per-minute request limit.
- JsonValue; object_ "chatkit.session"constant
  
  Type discriminator that is always chatkit.session.
  - CHATKIT_SESSION("chatkit.session")
- ChatSessionRateLimits rateLimits
  
  Resolved rate limit values.
  - long maxRequestsPer1Minute
    
    Maximum allowed requests per one-minute window.
- ChatSessionStatus status
  
  Current lifecycle state of the session.
  - ACTIVE("active")
  - EXPIRED("expired")
  - CANCELLED("cancelled")
- String user
  
  User identifier associated with the session.
- ChatKitWorkflow workflow
  
  Workflow metadata for the session.
  - String id
    
    Identifier of the workflow backing the session.
  - Optional<StateVariables> stateVariables
    
    State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
    - String
    - boolean
    - double
  - Tracing tracing
    
    Tracing settings applied to the workflow.
    - boolean enabled
      
      Indicates whether tracing is enabled.
  - Optional<String> version
    
    Specific workflow version used for the session. Defaults to null when using the latest deployment.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.SessionCancelParams;
import com.openai.models.beta.chatkit.threads.ChatSession;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123");
    }
}

Response

{
  "id": "id",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 0,
      "max_files": 0
    },
    "history": {
      "enabled": true,
      "recent_threads": 0
    }
  },
  "client_secret": "client_secret",
  "expires_at": 0,
  "max_requests_per_1_minute": 0,
  "object": "chatkit.session",
  "rate_limits": {
    "max_requests_per_1_minute": 0
  },
  "status": "active",
  "user": "user",
  "workflow": {
    "id": "id",
    "state_variables": {
      "foo": "string"
    },
    "tracing": {
      "enabled": true
    },
    "version": "version"
  }
}

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.SessionCancelParams;
import com.openai.models.beta.chatkit.threads.ChatSession;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123");
    }
}

Response

{
  "id": "cksess_123",
  "object": "chatkit.session",
  "workflow": {
    "id": "workflow_alpha",
    "version": "1"
  },
  "scope": {
    "customer_id": "cust_456"
  },
  "max_requests_per_1_minute": 30,
  "ttl_seconds": 900,
  "status": "cancelled",
  "cancelled_at": 1712345678
}

Create ChatKit session

ChatSession beta().chatkit().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

post /chatkit/sessions

Create a ChatKit session.

Parameters

SessionCreateParams params
- String user
  
  A free-form string that identifies your end user; ensures this Session can access other objects that have the same user scope.
- ChatSessionWorkflowParam workflow
  
  Workflow that powers the session.
- Optional<ChatSessionChatKitConfigurationParam> chatkitConfiguration
  
  Optional overrides for ChatKit runtime configuration features
- Optional<ChatSessionExpiresAfterParam> expiresAfter
  
  Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.
- Optional<ChatSessionRateLimitsParam> rateLimits
  
  Optional override for per-minute request limits. When omitted, defaults to 10.

Returns

class ChatSession:

Represents a ChatKit session and its resolved configuration.
- String id
  
  Identifier for the ChatKit session.
- ChatSessionChatKitConfiguration chatkitConfiguration
  
  Resolved ChatKit feature configuration for the session.
  - ChatSessionAutomaticThreadTitling automaticThreadTitling
    
    Automatic thread titling preferences.
    - boolean enabled
      
      Whether automatic thread titling is enabled.
  - ChatSessionFileUpload fileUpload
    
    Upload settings for the session.
    - boolean enabled
      
      Indicates if uploads are enabled for the session.
    - Optional<Long> maxFileSize
      
      Maximum upload size in megabytes.
    - Optional<Long> maxFiles
      
      Maximum number of uploads allowed during the session.
  - ChatSessionHistory history
    
    History retention configuration.
    - boolean enabled
      
      Indicates if chat history is persisted for the session.
    - Optional<Long> recentThreads
      
      Number of prior threads surfaced in history views. Defaults to null when all history is retained.
- String clientSecret
  
  Ephemeral client secret that authenticates session requests.
- long expiresAt
  
  Unix timestamp (in seconds) for when the session expires.
- long maxRequestsPer1Minute
  
  Convenience copy of the per-minute request limit.
- JsonValue; object_ "chatkit.session"constant
  
  Type discriminator that is always chatkit.session.
  - CHATKIT_SESSION("chatkit.session")
- ChatSessionRateLimits rateLimits
  
  Resolved rate limit values.
  - long maxRequestsPer1Minute
    
    Maximum allowed requests per one-minute window.
- ChatSessionStatus status
  
  Current lifecycle state of the session.
  - ACTIVE("active")
  - EXPIRED("expired")
  - CANCELLED("cancelled")
- String user
  
  User identifier associated with the session.
- ChatKitWorkflow workflow
  
  Workflow metadata for the session.
  - String id
    
    Identifier of the workflow backing the session.
  - Optional<StateVariables> stateVariables
    
    State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
    - String
    - boolean
    - double
  - Tracing tracing
    
    Tracing settings applied to the workflow.
    - boolean enabled
      
      Indicates whether tracing is enabled.
  - Optional<String> version
    
    Specific workflow version used for the session. Defaults to null when using the latest deployment.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.SessionCreateParams;
import com.openai.models.beta.chatkit.threads.ChatSession;
import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionCreateParams params = SessionCreateParams.builder()
            .user("x")
            .workflow(ChatSessionWorkflowParam.builder()
                .id("id")
                .build())
            .build();
        ChatSession chatSession = client.beta().chatkit().sessions().create(params);
    }
}

Response

{
  "id": "id",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 0,
      "max_files": 0
    },
    "history": {
      "enabled": true,
      "recent_threads": 0
    }
  },
  "client_secret": "client_secret",
  "expires_at": 0,
  "max_requests_per_1_minute": 0,
  "object": "chatkit.session",
  "rate_limits": {
    "max_requests_per_1_minute": 0
  },
  "status": "active",
  "user": "user",
  "workflow": {
    "id": "id",
    "state_variables": {
      "foo": "string"
    },
    "tracing": {
      "enabled": true
    },
    "version": "version"
  }
}

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.SessionCreateParams;
import com.openai.models.beta.chatkit.threads.ChatSession;
import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionCreateParams params = SessionCreateParams.builder()
            .user("user")
            .workflow(ChatSessionWorkflowParam.builder()
                .id("id")
                .build())
            .build();
        ChatSession chatSession = client.beta().chatkit().sessions().create(params);
    }
}

Response

{
  "client_secret": "chatkit_token_123",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": "2024-10-01"
  },
  "scope": {
    "project": "alpha",
    "environment": "staging"
  },
  "max_requests_per_1_minute": 60,
  "max_requests_per_session": 500,
  "status": "active"
}

Threads

List ChatKit thread items

ThreadListItemsPage beta().chatkit().threads().listItems(ThreadListItemsParamsparams = ThreadListItemsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /chatkit/threads/{thread_id}/items

List items that belong to a ChatKit thread.

Parameters

ThreadListItemsParams params
- Optional<String> threadId
- Optional<String> after
  
  List items created after this thread item ID. Defaults to null for the first page.
- Optional<String> before
  
  List items created before this thread item ID. Defaults to null for the newest results.
- Optional<Long> limit
  
  Maximum number of thread items to return. Defaults to 20.
- Optional<Order> order
  
  Sort order for results by creation time. Defaults to desc.
  - ASC("asc")
  - DESC("desc")

Returns

class Data: A class that can be one of several variants.union

User-authored messages within a thread.
- class ChatKitThreadUserMessageItem:
  
  User-authored messages within a thread.
  - String id
    
    Identifier of the thread item.
  - List<ChatKitAttachment> attachments
    
    Attachments associated with the user message. Defaults to an empty list.
    - String id
      
      Identifier for the attachment.
    - String mimeType
      
      MIME type of the attachment.
    - String name
      
      Original display name for the attachment.
    - Optional<String> previewUrl
      
      Preview URL for rendering the attachment inline.
    - Type type
      
      Attachment discriminator.
      - IMAGE("image")
      - FILE("file")
  - List<Content> content
    
    Ordered content elements supplied by the user.
    - class InputText:
      
      Text block that a user contributed to the thread.
      - String text
        
        Plain-text content supplied by the user.
      - JsonValue; type "input_text"constant
        
        Type discriminator that is always input_text.
        
        INPUT_TEXT("input_text")
    - class QuotedText:
      
      Quoted snippet that the user referenced in their message.
      - String text
        
        Quoted text content.
      - JsonValue; type "quoted_text"constant
        
        Type discriminator that is always quoted_text.
        
        QUOTED_TEXT("quoted_text")
  - long createdAt
    
    Unix timestamp (in seconds) for when the item was created.
  - Optional<InferenceOptions> inferenceOptions
    
    Inference overrides applied to the message. Defaults to null when unset.
    - Optional<String> model
      
      Model name that generated the response. Defaults to null when using the session default.
    - Optional<ToolChoice> toolChoice
      
      Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
      - String id
        
        Identifier of the requested tool.
  - JsonValue; object_ "chatkit.thread_item"constant
    
    Type discriminator that is always chatkit.thread_item.
    - CHATKIT_THREAD_ITEM("chatkit.thread_item")
  - String threadId
    
    Identifier of the parent thread.
  - JsonValue; type "chatkit.user_message"constant
    - CHATKIT_USER_MESSAGE("chatkit.user_message")
- class ChatKitThreadAssistantMessageItem:
  
  Assistant-authored message within a thread.
  - String id
    
    Identifier of the thread item.
  - List<ChatKitResponseOutputText> content
    
    Ordered assistant response segments.
    - List<Annotation> annotations
      
      Ordered list of annotations attached to the response text.
      - class File:
        
        Annotation that references an uploaded file.
        
        Source source
        
        File attachment referenced by the annotation.
        
        String filename
        
        Filename referenced by the annotation.
        
        JsonValue; type "file"constant
        
        Type discriminator that is always file.
        
        FILE("file")
        
        JsonValue; type "file"constant
        
        Type discriminator that is always file for this annotation.
        
        FILE("file")
      - class Url:
        
        Annotation that references a URL.
        
        Source source
        
        URL referenced by the annotation.
        
        JsonValue; type "url"constant
        
        Type discriminator that is always url.
        
        URL("url")
        
        String url
        
        URL referenced by the annotation.
        
        JsonValue; type "url"constant
        
        Type discriminator that is always url for this annotation.
        
        URL("url")
    - String text
      
      Assistant generated text.
    - JsonValue; type "output_text"constant
      
      Type discriminator that is always output_text.
      - OUTPUT_TEXT("output_text")
  - long createdAt
    
    Unix timestamp (in seconds) for when the item was created.
  - JsonValue; object_ "chatkit.thread_item"constant
    
    Type discriminator that is always chatkit.thread_item.
    - CHATKIT_THREAD_ITEM("chatkit.thread_item")
  - String threadId
    
    Identifier of the parent thread.
  - JsonValue; type "chatkit.assistant_message"constant
    
    Type discriminator that is always chatkit.assistant_message.
    - CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")
- class ChatKitWidgetItem:
  
  Thread item that renders a widget payload.
  - String id
    
    Identifier of the thread item.
  - long createdAt
    
    Unix timestamp (in seconds) for when the item was created.
  - JsonValue; object_ "chatkit.thread_item"constant
    
    Type discriminator that is always chatkit.thread_item.
    - CHATKIT_THREAD_ITEM("chatkit.thread_item")
  - String threadId
    
    Identifier of the parent thread.
  - JsonValue; type "chatkit.widget"constant
    
    Type discriminator that is always chatkit.widget.
    - CHATKIT_WIDGET("chatkit.widget")
  - String widget
    
    Serialized widget payload rendered in the UI.
- class ChatKitClientToolCall:
  
  Record of a client side tool invocation initiated by the assistant.
  - String id
    
    Identifier of the thread item.
  - String arguments
    
    JSON-encoded arguments that were sent to the tool.
  - String callId
    
    Identifier for the client tool call.
  - long createdAt
    
    Unix timestamp (in seconds) for when the item was created.
  - String name
    
    Tool name that was invoked.
  - JsonValue; object_ "chatkit.thread_item"constant
    
    Type discriminator that is always chatkit.thread_item.
    - CHATKIT_THREAD_ITEM("chatkit.thread_item")
  - Optional<String> output
    
    JSON-encoded output captured from the tool. Defaults to null while execution is in progress.
  - Status status
    
    Execution status for the tool call.
    - IN_PROGRESS("in_progress")
    - COMPLETED("completed")
  - String threadId
    
    Identifier of the parent thread.
  - JsonValue; type "chatkit.client_tool_call"constant
    
    Type discriminator that is always chatkit.client_tool_call.
    - CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")
- class ChatKitTask:
  
  Task emitted by the workflow to show progress and status updates.
  - String id
    
    Identifier of the thread item.
  - long createdAt
    
    Unix timestamp (in seconds) for when the item was created.
  - Optional<String> heading
    
    Optional heading for the task. Defaults to null when not provided.
  - JsonValue; object_ "chatkit.thread_item"constant
    
    Type discriminator that is always chatkit.thread_item.
    - CHATKIT_THREAD_ITEM("chatkit.thread_item")
  - Optional<String> summary
    
    Optional summary that describes the task. Defaults to null when omitted.
  - TaskType taskType
    
    Subtype for the task.
    - CUSTOM("custom")
    - THOUGHT("thought")
  - String threadId
    
    Identifier of the parent thread.
  - JsonValue; type "chatkit.task"constant
    
    Type discriminator that is always chatkit.task.
    - CHATKIT_TASK("chatkit.task")
- class ChatKitTaskGroup:
  
  Collection of workflow tasks grouped together in the thread.
  - String id
    
    Identifier of the thread item.
  - long createdAt
    
    Unix timestamp (in seconds) for when the item was created.
  - JsonValue; object_ "chatkit.thread_item"constant
    
    Type discriminator that is always chatkit.thread_item.
    - CHATKIT_THREAD_ITEM("chatkit.thread_item")
  - List<Task> tasks
    
    Tasks included in the group.
    - Optional<String> heading
      
      Optional heading for the grouped task. Defaults to null when not provided.
    - Optional<String> summary
      
      Optional summary that describes the grouped task. Defaults to null when omitted.
    - Type type
      
      Subtype for the grouped task.
      - CUSTOM("custom")
      - THOUGHT("thought")
  - String threadId
    
    Identifier of the parent thread.
  - JsonValue; type "chatkit.task_group"constant
    
    Type discriminator that is always chatkit.task_group.
    - CHATKIT_TASK_GROUP("chatkit.task_group")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ThreadListItemsPage;
import com.openai.models.beta.chatkit.threads.ThreadListItemsParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123");
    }
}

Response

{
  "data": [
    {
      "id": "id",
      "attachments": [
        {
          "id": "id",
          "mime_type": "mime_type",
          "name": "name",
          "preview_url": "https://example.com",
          "type": "image"
        }
      ],
      "content": [
        {
          "text": "text",
          "type": "input_text"
        }
      ],
      "created_at": 0,
      "inference_options": {
        "model": "model",
        "tool_choice": {
          "id": "id"
        }
      },
      "object": "chatkit.thread_item",
      "thread_id": "thread_id",
      "type": "chatkit.user_message"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ThreadListItemsPage;
import com.openai.models.beta.chatkit.threads.ThreadListItemsParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123");
    }
}

Response

{
  "data": [
    {
      "id": "cthi_user_001",
      "object": "chatkit.thread_item",
      "type": "user_message",
      "content": [
        {
          "type": "input_text",
          "text": "I need help debugging an onboarding issue."
        }
      ],
      "attachments": []
    },
    {
      "id": "cthi_assistant_002",
      "object": "chatkit.thread_item",
      "type": "assistant_message",
      "content": [
        {
          "type": "output_text",
          "text": "Let's start by confirming the workflow version you deployed."
        }
      ]
    }
  ],
  "has_more": false,
  "object": "list"
}

Retrieve ChatKit thread

ChatKitThread beta().chatkit().threads().retrieve(ThreadRetrieveParamsparams = ThreadRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /chatkit/threads/{thread_id}

Retrieve a ChatKit thread by its identifier.

Parameters

ThreadRetrieveParams params
- Optional<String> threadId

Returns

class ChatKitThread:

Represents a ChatKit thread and its current status.
- String id
  
  Identifier of the thread.
- long createdAt
  
  Unix timestamp (in seconds) for when the thread was created.
- JsonValue; object_ "chatkit.thread"constant
  
  Type discriminator that is always chatkit.thread.
  - CHATKIT_THREAD("chatkit.thread")
- Status status
  
  Current status for the thread. Defaults to active for newly created threads.
  - JsonValue;
    - JsonValue; type "active"constant
      
      Status discriminator that is always active.
      - ACTIVE("active")
  - class Locked:
    
    Indicates that a thread is locked and cannot accept new input.
    - Optional<String> reason
      
      Reason that the thread was locked. Defaults to null when no reason is recorded.
    - JsonValue; type "locked"constant
      
      Status discriminator that is always locked.
      - LOCKED("locked")
  - class Closed:
    
    Indicates that a thread has been closed.
    - Optional<String> reason
      
      Reason that the thread was closed. Defaults to null when no reason is recorded.
    - JsonValue; type "closed"constant
      
      Status discriminator that is always closed.
      - CLOSED("closed")
- Optional<String> title
  
  Optional human-readable title for the thread. Defaults to null when no title has been generated.
- String user
  
  Free-form string that identifies your end user who owns the thread.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ChatKitThread;
import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123");
    }
}

Response

{
  "id": "cthr_def456",
  "created_at": 1712345600,
  "object": "chatkit.thread",
  "status": {
    "type": "active"
  },
  "title": "Demo feedback",
  "user": "user_456"
}

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ChatKitThread;
import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123");
    }
}

Response

{
  "id": "cthr_abc123",
  "object": "chatkit.thread",
  "title": "Customer escalation",
  "items": {
    "data": [
      {
        "id": "cthi_user_001",
        "object": "chatkit.thread_item",
        "type": "user_message",
        "content": [
          {
            "type": "input_text",
            "text": "I need help debugging an onboarding issue."
          }
        ],
        "attachments": []
      },
      {
        "id": "cthi_assistant_002",
        "object": "chatkit.thread_item",
        "type": "assistant_message",
        "content": [
          {
            "type": "output_text",
            "text": "Let's start by confirming the workflow version you deployed."
          }
        ]
      }
    ],
    "has_more": false
  }
}

Delete ChatKit thread

ThreadDeleteResponse beta().chatkit().threads().delete(ThreadDeleteParamsparams = ThreadDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

delete /chatkit/threads/{thread_id}

Delete a ChatKit thread along with its items and stored attachments.

Parameters

ThreadDeleteParams params
- Optional<String> threadId

Returns

class ThreadDeleteResponse:

Confirmation payload returned after deleting a thread.
- String id
  
  Identifier of the deleted thread.
- boolean deleted
  
  Indicates that the thread has been deleted.
- JsonValue; object_ "chatkit.thread.deleted"constant
  
  Type discriminator that is always chatkit.thread.deleted.
  - CHATKIT_THREAD_DELETED("chatkit.thread.deleted")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ThreadDeleteParams;
import com.openai.models.beta.chatkit.threads.ThreadDeleteResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ThreadDeleteResponse thread = client.beta().chatkit().threads().delete("cthr_123");
    }
}

Response

{
  "id": "id",
  "deleted": true,
  "object": "chatkit.thread.deleted"
}

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chat_kit.threads.ThreadDeleteParams;
import com.openai.models.beta.chat_kit.threads.ThreadDeleteResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ThreadDeleteResponse thread = client.beta().chat_kit().threads().delete("cthr_123");
    }
}

List ChatKit threads

ThreadListPage beta().chatkit().threads().list(ThreadListParamsparams = ThreadListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /chatkit/threads

List ChatKit threads with optional pagination and user filters.

Parameters

ThreadListParams params
- Optional<String> after
  
  List items created after this thread item ID. Defaults to null for the first page.
- Optional<String> before
  
  List items created before this thread item ID. Defaults to null for the newest results.
- Optional<Long> limit
  
  Maximum number of thread items to return. Defaults to 20.
- Optional<Order> order
  
  Sort order for results by creation time. Defaults to desc.
  - ASC("asc")
  - DESC("desc")
- Optional<String> user
  
  Filter threads that belong to this user identifier. Defaults to null to return all users.

Returns

class ChatKitThread:

Represents a ChatKit thread and its current status.
- String id
  
  Identifier of the thread.
- long createdAt
  
  Unix timestamp (in seconds) for when the thread was created.
- JsonValue; object_ "chatkit.thread"constant
  
  Type discriminator that is always chatkit.thread.
  - CHATKIT_THREAD("chatkit.thread")
- Status status
  
  Current status for the thread. Defaults to active for newly created threads.
  - JsonValue;
    - JsonValue; type "active"constant
      
      Status discriminator that is always active.
      - ACTIVE("active")
  - class Locked:
    
    Indicates that a thread is locked and cannot accept new input.
    - Optional<String> reason
      
      Reason that the thread was locked. Defaults to null when no reason is recorded.
    - JsonValue; type "locked"constant
      
      Status discriminator that is always locked.
      - LOCKED("locked")
  - class Closed:
    
    Indicates that a thread has been closed.
    - Optional<String> reason
      
      Reason that the thread was closed. Defaults to null when no reason is recorded.
    - JsonValue; type "closed"constant
      
      Status discriminator that is always closed.
      - CLOSED("closed")
- Optional<String> title
  
  Optional human-readable title for the thread. Defaults to null when no title has been generated.
- String user
  
  Free-form string that identifies your end user who owns the thread.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ThreadListPage;
import com.openai.models.beta.chatkit.threads.ThreadListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ThreadListPage page = client.beta().chatkit().threads().list();
    }
}

Response

{
  "data": [
    {
      "id": "cthr_def456",
      "created_at": 1712345600,
      "object": "chatkit.thread",
      "status": {
        "type": "active"
      },
      "title": "Demo feedback",
      "user": "user_456"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.threads.ThreadListPage;
import com.openai.models.beta.chatkit.threads.ThreadListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ThreadListPage page = client.beta().chatkit().threads().list();
    }
}

Response

{
  "data": [
    {
      "id": "cthr_abc123",
      "object": "chatkit.thread",
      "title": "Customer escalation"
    },
    {
      "id": "cthr_def456",
      "object": "chatkit.thread",
      "title": "Demo feedback"
    }
  ],
  "has_more": false,
  "object": "list"
}

Domain Types

Chat Session

class ChatSession:

Represents a ChatKit session and its resolved configuration.
- String id
  
  Identifier for the ChatKit session.
- ChatSessionChatKitConfiguration chatkitConfiguration
  
  Resolved ChatKit feature configuration for the session.
  - ChatSessionAutomaticThreadTitling automaticThreadTitling
    
    Automatic thread titling preferences.
    - boolean enabled
      
      Whether automatic thread titling is enabled.
  - ChatSessionFileUpload fileUpload
    
    Upload settings for the session.
    - boolean enabled
      
      Indicates if uploads are enabled for the session.
    - Optional<Long> maxFileSize
      
      Maximum upload size in megabytes.
    - Optional<Long> maxFiles
      
      Maximum number of uploads allowed during the session.
  - ChatSessionHistory history
    
    History retention configuration.
    - boolean enabled
      
      Indicates if chat history is persisted for the session.
    - Optional<Long> recentThreads
      
      Number of prior threads surfaced in history views. Defaults to null when all history is retained.
- String clientSecret
  
  Ephemeral client secret that authenticates session requests.
- long expiresAt
  
  Unix timestamp (in seconds) for when the session expires.
- long maxRequestsPer1Minute
  
  Convenience copy of the per-minute request limit.
- JsonValue; object_ "chatkit.session"constant
  
  Type discriminator that is always chatkit.session.
  - CHATKIT_SESSION("chatkit.session")
- ChatSessionRateLimits rateLimits
  
  Resolved rate limit values.
  - long maxRequestsPer1Minute
    
    Maximum allowed requests per one-minute window.
- ChatSessionStatus status
  
  Current lifecycle state of the session.
  - ACTIVE("active")
  - EXPIRED("expired")
  - CANCELLED("cancelled")
- String user
  
  User identifier associated with the session.
- ChatKitWorkflow workflow
  
  Workflow metadata for the session.
  - String id
    
    Identifier of the workflow backing the session.
  - Optional<StateVariables> stateVariables
    
    State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
    - String
    - boolean
    - double
  - Tracing tracing
    
    Tracing settings applied to the workflow.
    - boolean enabled
      
      Indicates whether tracing is enabled.
  - Optional<String> version
    
    Specific workflow version used for the session. Defaults to null when using the latest deployment.

Chat Session Automatic Thread Titling

class ChatSessionAutomaticThreadTitling:

Automatic thread title preferences for the session.
- boolean enabled
  
  Whether automatic thread titling is enabled.

Chat Session ChatKit Configuration

class ChatSessionChatKitConfiguration:

ChatKit configuration for the session.
- ChatSessionAutomaticThreadTitling automaticThreadTitling
  
  Automatic thread titling preferences.
  - boolean enabled
    
    Whether automatic thread titling is enabled.
- ChatSessionFileUpload fileUpload
  
  Upload settings for the session.
  - boolean enabled
    
    Indicates if uploads are enabled for the session.
  - Optional<Long> maxFileSize
    
    Maximum upload size in megabytes.
  - Optional<Long> maxFiles
    
    Maximum number of uploads allowed during the session.
- ChatSessionHistory history
  
  History retention configuration.
  - boolean enabled
    
    Indicates if chat history is persisted for the session.
  - Optional<Long> recentThreads
    
    Number of prior threads surfaced in history views. Defaults to null when all history is retained.

Chat Session ChatKit Configuration Param

class ChatSessionChatKitConfigurationParam:

Optional per-session configuration settings for ChatKit behavior.
- Optional<AutomaticThreadTitling> automaticThreadTitling
  
  Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.
  - Optional<Boolean> enabled
    
    Enable automatic thread title generation. Defaults to true.
- Optional<FileUpload> fileUpload
  
  Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).
  - Optional<Boolean> enabled
    
    Enable uploads for this session. Defaults to false.
  - Optional<Long> maxFileSize
    
    Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.
  - Optional<Long> maxFiles
    
    Maximum number of files that can be uploaded to the session. Defaults to 10.
- Optional<History> history
  
  Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null).
  - Optional<Boolean> enabled
    
    Enables chat users to access previous ChatKit threads. Defaults to true.
  - Optional<Long> recentThreads
    
    Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.

Chat Session Expires After Param

class ChatSessionExpiresAfterParam:

Controls when the session expires relative to an anchor timestamp.
- JsonValue; anchor "created_at"constant
  
  Base timestamp used to calculate expiration. Currently fixed to created_at.
  - CREATED_AT("created_at")
- long seconds
  
  Number of seconds after the anchor when the session expires.

Chat Session File Upload

class ChatSessionFileUpload:

Upload permissions and limits applied to the session.
- boolean enabled
  
  Indicates if uploads are enabled for the session.
- Optional<Long> maxFileSize
  
  Maximum upload size in megabytes.
- Optional<Long> maxFiles
  
  Maximum number of uploads allowed during the session.

Chat Session History

class ChatSessionHistory:

History retention preferences returned for the session.
- boolean enabled
  
  Indicates if chat history is persisted for the session.
- Optional<Long> recentThreads
  
  Number of prior threads surfaced in history views. Defaults to null when all history is retained.

Chat Session Rate Limits

class ChatSessionRateLimits:

Active per-minute request limit for the session.
- long maxRequestsPer1Minute
  
  Maximum allowed requests per one-minute window.

Chat Session Rate Limits Param

class ChatSessionRateLimitsParam:

Controls request rate limits for the session.
- Optional<Long> maxRequestsPer1Minute
  
  Maximum number of requests allowed per minute for the session. Defaults to 10.

Chat Session Status

enum ChatSessionStatus:
- ACTIVE("active")
- EXPIRED("expired")
- CANCELLED("cancelled")

Chat Session Workflow Param

class ChatSessionWorkflowParam:

Workflow reference and overrides applied to the chat session.
- String id
  
  Identifier for the workflow invoked by the session.
- Optional<StateVariables> stateVariables
  
  State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object.
  - String
  - boolean
  - double
- Optional<Tracing> tracing
  
  Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default.
  - Optional<Boolean> enabled
    
    Whether tracing is enabled during the session. Defaults to true.
- Optional<String> version
  
  Specific workflow version to run. Defaults to the latest deployed version.

ChatKit Attachment

class ChatKitAttachment:

Attachment metadata included on thread items.
- String id
  
  Identifier for the attachment.
- String mimeType
  
  MIME type of the attachment.
- String name
  
  Original display name for the attachment.
- Optional<String> previewUrl
  
  Preview URL for rendering the attachment inline.
- Type type
  
  Attachment discriminator.
  - IMAGE("image")
  - FILE("file")

ChatKit Response Output Text

class ChatKitResponseOutputText:

Assistant response text accompanied by optional annotations.
- List<Annotation> annotations
  
  Ordered list of annotations attached to the response text.
  - class File:
    
    Annotation that references an uploaded file.
    - Source source
      
      File attachment referenced by the annotation.
      - String filename
        
        Filename referenced by the annotation.
      - JsonValue; type "file"constant
        
        Type discriminator that is always file.
        
        FILE("file")
    - JsonValue; type "file"constant
      
      Type discriminator that is always file for this annotation.
      - FILE("file")
  - class Url:
    
    Annotation that references a URL.
    - Source source
      
      URL referenced by the annotation.
      - JsonValue; type "url"constant
        
        Type discriminator that is always url.
        
        URL("url")
      - String url
        
        URL referenced by the annotation.
    - JsonValue; type "url"constant
      
      Type discriminator that is always url for this annotation.
      - URL("url")
- String text
  
  Assistant generated text.
- JsonValue; type "output_text"constant
  
  Type discriminator that is always output_text.
  - OUTPUT_TEXT("output_text")

ChatKit Thread

class ChatKitThread:

Represents a ChatKit thread and its current status.
- String id
  
  Identifier of the thread.
- long createdAt
  
  Unix timestamp (in seconds) for when the thread was created.
- JsonValue; object_ "chatkit.thread"constant
  
  Type discriminator that is always chatkit.thread.
  - CHATKIT_THREAD("chatkit.thread")
- Status status
  
  Current status for the thread. Defaults to active for newly created threads.
  - JsonValue;
    - JsonValue; type "active"constant
      
      Status discriminator that is always active.
      - ACTIVE("active")
  - class Locked:
    
    Indicates that a thread is locked and cannot accept new input.
    - Optional<String> reason
      
      Reason that the thread was locked. Defaults to null when no reason is recorded.
    - JsonValue; type "locked"constant
      
      Status discriminator that is always locked.
      - LOCKED("locked")
  - class Closed:
    
    Indicates that a thread has been closed.
    - Optional<String> reason
      
      Reason that the thread was closed. Defaults to null when no reason is recorded.
    - JsonValue; type "closed"constant
      
      Status discriminator that is always closed.
      - CLOSED("closed")
- Optional<String> title
  
  Optional human-readable title for the thread. Defaults to null when no title has been generated.
- String user
  
  Free-form string that identifies your end user who owns the thread.

ChatKit Thread Assistant Message Item

class ChatKitThreadAssistantMessageItem:

Assistant-authored message within a thread.
- String id
  
  Identifier of the thread item.
- List<ChatKitResponseOutputText> content
  
  Ordered assistant response segments.
  - List<Annotation> annotations
    
    Ordered list of annotations attached to the response text.
    - class File:
      
      Annotation that references an uploaded file.
      - Source source
        
        File attachment referenced by the annotation.
        
        String filename
        
        Filename referenced by the annotation.
        
        JsonValue; type "file"constant
        
        Type discriminator that is always file.
        
        FILE("file")
      - JsonValue; type "file"constant
        
        Type discriminator that is always file for this annotation.
        
        FILE("file")
    - class Url:
      
      Annotation that references a URL.
      - Source source
        
        URL referenced by the annotation.
        
        JsonValue; type "url"constant
        
        Type discriminator that is always url.
        
        URL("url")
        
        String url
        
        URL referenced by the annotation.
      - JsonValue; type "url"constant
        
        Type discriminator that is always url for this annotation.
        
        URL("url")
  - String text
    
    Assistant generated text.
  - JsonValue; type "output_text"constant
    
    Type discriminator that is always output_text.
    - OUTPUT_TEXT("output_text")
- long createdAt
  
  Unix timestamp (in seconds) for when the item was created.
- JsonValue; object_ "chatkit.thread_item"constant
  
  Type discriminator that is always chatkit.thread_item.
  - CHATKIT_THREAD_ITEM("chatkit.thread_item")
- String threadId
  
  Identifier of the parent thread.
- JsonValue; type "chatkit.assistant_message"constant
  
  Type discriminator that is always chatkit.assistant_message.
  - CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")

ChatKit Thread Item List

class ChatKitThreadItemList:

A paginated list of thread items rendered for the ChatKit API.
- List<Data> data
  
  A list of items
  - class ChatKitThreadUserMessageItem:
    
    User-authored messages within a thread.
    - String id
      
      Identifier of the thread item.
    - List<ChatKitAttachment> attachments
      
      Attachments associated with the user message. Defaults to an empty list.
      - String id
        
        Identifier for the attachment.
      - String mimeType
        
        MIME type of the attachment.
      - String name
        
        Original display name for the attachment.
      - Optional<String> previewUrl
        
        Preview URL for rendering the attachment inline.
      - Type type
        
        Attachment discriminator.
        
        IMAGE("image")
        
        FILE("file")
    - List<Content> content
      
      Ordered content elements supplied by the user.
      - class InputText:
        
        Text block that a user contributed to the thread.
        
        String text
        
        Plain-text content supplied by the user.
        
        JsonValue; type "input_text"constant
        
        Type discriminator that is always input_text.
        
        INPUT_TEXT("input_text")
      - class QuotedText:
        
        Quoted snippet that the user referenced in their message.
        
        String text
        
        Quoted text content.
        
        JsonValue; type "quoted_text"constant
        
        Type discriminator that is always quoted_text.
        
        QUOTED_TEXT("quoted_text")
    - long createdAt
      
      Unix timestamp (in seconds) for when the item was created.
    - Optional<InferenceOptions> inferenceOptions
      
      Inference overrides applied to the message. Defaults to null when unset.
      - Optional<String> model
        
        Model name that generated the response. Defaults to null when using the session default.
      - Optional<ToolChoice> toolChoice
        
        Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
        
        String id
        
        Identifier of the requested tool.
    - JsonValue; object_ "chatkit.thread_item"constant
      
      Type discriminator that is always chatkit.thread_item.
      - CHATKIT_THREAD_ITEM("chatkit.thread_item")
    - String threadId
      
      Identifier of the parent thread.
    - JsonValue; type "chatkit.user_message"constant
      - CHATKIT_USER_MESSAGE("chatkit.user_message")
  - class ChatKitThreadAssistantMessageItem:
    
    Assistant-authored message within a thread.
    - String id
      
      Identifier of the thread item.
    - List<ChatKitResponseOutputText> content
      
      Ordered assistant response segments.
      - List<Annotation> annotations
        
        Ordered list of annotations attached to the response text.
        
        class File:
        
        Annotation that references an uploaded file.
        
        Source source
        
        File attachment referenced by the annotation.
        
        String filename
        
        Filename referenced by the annotation.
        
        JsonValue; type "file"constant
        
        Type discriminator that is always file.
        
        FILE("file")
        
        JsonValue; type "file"constant
        
        Type discriminator that is always file for this annotation.
        
        FILE("file")
        
        class Url:
        
        Annotation that references a URL.
        
        Source source
        
        URL referenced by the annotation.
        
        JsonValue; type "url"constant
        
        Type discriminator that is always url.
        
        URL("url")
        
        String url
        
        URL referenced by the annotation.
        
        JsonValue; type "url"constant
        
        Type discriminator that is always url for this annotation.
        
        URL("url")
      - String text
        
        Assistant generated text.
      - JsonValue; type "output_text"constant
        
        Type discriminator that is always output_text.
        
        OUTPUT_TEXT("output_text")
    - long createdAt
      
      Unix timestamp (in seconds) for when the item was created.
    - JsonValue; object_ "chatkit.thread_item"constant
      
      Type discriminator that is always chatkit.thread_item.
      - CHATKIT_THREAD_ITEM("chatkit.thread_item")
    - String threadId
      
      Identifier of the parent thread.
    - JsonValue; type "chatkit.assistant_message"constant
      
      Type discriminator that is always chatkit.assistant_message.
      - CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")
  - class ChatKitWidgetItem:
    
    Thread item that renders a widget payload.
    - String id
      
      Identifier of the thread item.
    - long createdAt
      
      Unix timestamp (in seconds) for when the item was created.
    - JsonValue; object_ "chatkit.thread_item"constant
      
      Type discriminator that is always chatkit.thread_item.
      - CHATKIT_THREAD_ITEM("chatkit.thread_item")
    - String threadId
      
      Identifier of the parent thread.
    - JsonValue; type "chatkit.widget"constant
      
      Type discriminator that is always chatkit.widget.
      - CHATKIT_WIDGET("chatkit.widget")
    - String widget
      
      Serialized widget payload rendered in the UI.
  - class ChatKitClientToolCall:
    
    Record of a client side tool invocation initiated by the assistant.
    - String id
      
      Identifier of the thread item.
    - String arguments
      
      JSON-encoded arguments that were sent to the tool.
    - String callId
      
      Identifier for the client tool call.
    - long createdAt
      
      Unix timestamp (in seconds) for when the item was created.
    - String name
      
      Tool name that was invoked.
    - JsonValue; object_ "chatkit.thread_item"constant
      
      Type discriminator that is always chatkit.thread_item.
      - CHATKIT_THREAD_ITEM("chatkit.thread_item")
    - Optional<String> output
      
      JSON-encoded output captured from the tool. Defaults to null while execution is in progress.
    - Status status
      
      Execution status for the tool call.
      - IN_PROGRESS("in_progress")
      - COMPLETED("completed")
    - String threadId
      
      Identifier of the parent thread.
    - JsonValue; type "chatkit.client_tool_call"constant
      
      Type discriminator that is always chatkit.client_tool_call.
      - CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")
  - class ChatKitTask:
    
    Task emitted by the workflow to show progress and status updates.
    - String id
      
      Identifier of the thread item.
    - long createdAt
      
      Unix timestamp (in seconds) for when the item was created.
    - Optional<String> heading
      
      Optional heading for the task. Defaults to null when not provided.
    - JsonValue; object_ "chatkit.thread_item"constant
      
      Type discriminator that is always chatkit.thread_item.
      - CHATKIT_THREAD_ITEM("chatkit.thread_item")
    - Optional<String> summary
      
      Optional summary that describes the task. Defaults to null when omitted.
    - TaskType taskType
      
      Subtype for the task.
      - CUSTOM("custom")
      - THOUGHT("thought")
    - String threadId
      
      Identifier of the parent thread.
    - JsonValue; type "chatkit.task"constant
      
      Type discriminator that is always chatkit.task.
      - CHATKIT_TASK("chatkit.task")
  - class ChatKitTaskGroup:
    
    Collection of workflow tasks grouped together in the thread.
    - String id
      
      Identifier of the thread item.
    - long createdAt
      
      Unix timestamp (in seconds) for when the item was created.
    - JsonValue; object_ "chatkit.thread_item"constant
      
      Type discriminator that is always chatkit.thread_item.
      - CHATKIT_THREAD_ITEM("chatkit.thread_item")
    - List<Task> tasks
      
      Tasks included in the group.
      - Optional<String> heading
        
        Optional heading for the grouped task. Defaults to null when not provided.
      - Optional<String> summary
        
        Optional summary that describes the grouped task. Defaults to null when omitted.
      - Type type
        
        Subtype for the grouped task.
        
        CUSTOM("custom")
        
        THOUGHT("thought")
    - String threadId
      
      Identifier of the parent thread.
    - JsonValue; type "chatkit.task_group"constant
      
      Type discriminator that is always chatkit.task_group.
      - CHATKIT_TASK_GROUP("chatkit.task_group")
- Optional<String> firstId
  
  The ID of the first item in the list.
- boolean hasMore
  
  Whether there are more items available.
- Optional<String> lastId
  
  The ID of the last item in the list.
- JsonValue; object_ "list"constant
  
  The type of object returned, must be list.
  - LIST("list")

ChatKit Thread User Message Item

class ChatKitThreadUserMessageItem:

User-authored messages within a thread.
- String id
  
  Identifier of the thread item.
- List<ChatKitAttachment> attachments
  
  Attachments associated with the user message. Defaults to an empty list.
  - String id
    
    Identifier for the attachment.
  - String mimeType
    
    MIME type of the attachment.
  - String name
    
    Original display name for the attachment.
  - Optional<String> previewUrl
    
    Preview URL for rendering the attachment inline.
  - Type type
    
    Attachment discriminator.
    - IMAGE("image")
    - FILE("file")
- List<Content> content
  
  Ordered content elements supplied by the user.
  - class InputText:
    
    Text block that a user contributed to the thread.
    - String text
      
      Plain-text content supplied by the user.
    - JsonValue; type "input_text"constant
      
      Type discriminator that is always input_text.
      - INPUT_TEXT("input_text")
  - class QuotedText:
    
    Quoted snippet that the user referenced in their message.
    - String text
      
      Quoted text content.
    - JsonValue; type "quoted_text"constant
      
      Type discriminator that is always quoted_text.
      - QUOTED_TEXT("quoted_text")
- long createdAt
  
  Unix timestamp (in seconds) for when the item was created.
- Optional<InferenceOptions> inferenceOptions
  
  Inference overrides applied to the message. Defaults to null when unset.
  - Optional<String> model
    
    Model name that generated the response. Defaults to null when using the session default.
  - Optional<ToolChoice> toolChoice
    
    Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
    - String id
      
      Identifier of the requested tool.
- JsonValue; object_ "chatkit.thread_item"constant
  
  Type discriminator that is always chatkit.thread_item.
  - CHATKIT_THREAD_ITEM("chatkit.thread_item")
- String threadId
  
  Identifier of the parent thread.
- JsonValue; type "chatkit.user_message"constant
  - CHATKIT_USER_MESSAGE("chatkit.user_message")

class ChatKitWidgetItem:

Thread item that renders a widget payload.
- String id
  
  Identifier of the thread item.
- long createdAt
  
  Unix timestamp (in seconds) for when the item was created.
- JsonValue; object_ "chatkit.thread_item"constant
  
  Type discriminator that is always chatkit.thread_item.
  - CHATKIT_THREAD_ITEM("chatkit.thread_item")
- String threadId
  
  Identifier of the parent thread.
- JsonValue; type "chatkit.widget"constant
  
  Type discriminator that is always chatkit.widget.
  - CHATKIT_WIDGET("chatkit.widget")
- String widget
  
  Serialized widget payload rendered in the UI.

java/resources/beta/subresources/chatkit/index.md +2655 −0 created

1# ChatKit

3## Domain Types

5### ChatKit Workflow

7- `class ChatKitWorkflow:`

9 Workflow metadata and state returned for the session.

11 - `String id`

13 Identifier of the workflow backing the session.

15 - `Optional<StateVariables> stateVariables`

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

19 - `String`

21 - `boolean`

23 - `double`

25 - `Tracing tracing`

27 Tracing settings applied to the workflow.

29 - `boolean enabled`

31 Indicates whether tracing is enabled.

33 - `Optional<String> version`

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

37# Sessions

39## Cancel chat session

41`ChatSession beta().chatkit().sessions().cancel(SessionCancelParamsparams = SessionCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

43**post** `/chatkit/sessions/{session_id}/cancel`

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

47Cancelling prevents new requests from using the issued client secret.

49### Parameters

51- `SessionCancelParams params`

53 - `Optional<String> sessionId`

55### Returns

57- `class ChatSession:`

59 Represents a ChatKit session and its resolved configuration.

61 - `String id`

63 Identifier for the ChatKit session.

65 - `ChatSessionChatKitConfiguration chatkitConfiguration`

67 Resolved ChatKit feature configuration for the session.

69 - `ChatSessionAutomaticThreadTitling automaticThreadTitling`

71 Automatic thread titling preferences.

73 - `boolean enabled`

75 Whether automatic thread titling is enabled.

77 - `ChatSessionFileUpload fileUpload`

79 Upload settings for the session.

81 - `boolean enabled`

83 Indicates if uploads are enabled for the session.

85 - `Optional<Long> maxFileSize`

87 Maximum upload size in megabytes.

89 - `Optional<Long> maxFiles`

91 Maximum number of uploads allowed during the session.

93 - `ChatSessionHistory history`

95 History retention configuration.

97 - `boolean enabled`

99 Indicates if chat history is persisted for the session.

100

101 - `Optional<Long> recentThreads`

102

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

104

105 - `String clientSecret`

106

107 Ephemeral client secret that authenticates session requests.

108

109 - `long expiresAt`

110

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

112

113 - `long maxRequestsPer1Minute`

114

115 Convenience copy of the per-minute request limit.

116

117 - `JsonValue; object_ "chatkit.session"constant`

118

119 Type discriminator that is always `chatkit.session`.

120

121 - `CHATKIT_SESSION("chatkit.session")`

122

123 - `ChatSessionRateLimits rateLimits`

124

125 Resolved rate limit values.

126

127 - `long maxRequestsPer1Minute`

128

129 Maximum allowed requests per one-minute window.

130

131 - `ChatSessionStatus status`

132

133 Current lifecycle state of the session.

134

135 - `ACTIVE("active")`

136

137 - `EXPIRED("expired")`

138

139 - `CANCELLED("cancelled")`

140

141 - `String user`

142

143 User identifier associated with the session.

144

145 - `ChatKitWorkflow workflow`

146

147 Workflow metadata for the session.

148

149 - `String id`

150

151 Identifier of the workflow backing the session.

152

153 - `Optional<StateVariables> stateVariables`

154

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

156

157 - `String`

158

159 - `boolean`

160

161 - `double`

162

163 - `Tracing tracing`

164

165 Tracing settings applied to the workflow.

166

167 - `boolean enabled`

168

169 Indicates whether tracing is enabled.

170

171 - `Optional<String> version`

172

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

174

175### Example

176

177```java

178package com.openai.example;

179

180import com.openai.client.OpenAIClient;

181import com.openai.client.okhttp.OpenAIOkHttpClient;

182import com.openai.models.beta.chatkit.sessions.SessionCancelParams;

183import com.openai.models.beta.chatkit.threads.ChatSession;

184

185public final class Main {

186 private Main() {}

187

188 public static void main(String[] args) {

189 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

190

191 ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123");

192 }

193}

194```

195

196#### Response

197

198```json

199{

200 "id": "id",

201 "chatkit_configuration": {

202 "automatic_thread_titling": {

203 "enabled": true

204 },

205 "file_upload": {

206 "enabled": true,

207 "max_file_size": 0,

208 "max_files": 0

209 },

210 "history": {

211 "enabled": true,

212 "recent_threads": 0

213 }

214 },

215 "client_secret": "client_secret",

216 "expires_at": 0,

217 "max_requests_per_1_minute": 0,

218 "object": "chatkit.session",

219 "rate_limits": {

220 "max_requests_per_1_minute": 0

221 },

222 "status": "active",

223 "user": "user",

224 "workflow": {

225 "id": "id",

226 "state_variables": {

227 "foo": "string"

228 },

229 "tracing": {

230 "enabled": true

231 },

232 "version": "version"

233 }

234}

235```

236

237### Example

238

239```java

240package com.openai.example;

241

242import com.openai.client.OpenAIClient;

243import com.openai.client.okhttp.OpenAIOkHttpClient;

244import com.openai.models.beta.chatkit.sessions.SessionCancelParams;

245import com.openai.models.beta.chatkit.threads.ChatSession;

246

247public final class Main {

248 private Main() {}

249

250 public static void main(String[] args) {

251 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

252

253 ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123");

254 }

255}

256```

257

258#### Response

259

260```json

261{

262 "id": "cksess_123",

263 "object": "chatkit.session",

264 "workflow": {

265 "id": "workflow_alpha",

266 "version": "1"

267 },

268 "scope": {

269 "customer_id": "cust_456"

270 },

271 "max_requests_per_1_minute": 30,

272 "ttl_seconds": 900,

273 "status": "cancelled",

274 "cancelled_at": 1712345678

275}

276```

277

278## Create ChatKit session

279

280`ChatSession beta().chatkit().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

281

282**post** `/chatkit/sessions`

283

284Create a ChatKit session.

285

286### Parameters

287

288- `SessionCreateParams params`

289

290 - `String user`

291

292 A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.

293

294 - `ChatSessionWorkflowParam workflow`

295

296 Workflow that powers the session.

297

298 - `Optional<ChatSessionChatKitConfigurationParam> chatkitConfiguration`

299

300 Optional overrides for ChatKit runtime configuration features

301

302 - `Optional<ChatSessionExpiresAfterParam> expiresAfter`

303

304 Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.

305

306 - `Optional<ChatSessionRateLimitsParam> rateLimits`

307

308 Optional override for per-minute request limits. When omitted, defaults to 10.

309

310### Returns

311

312- `class ChatSession:`

313

314 Represents a ChatKit session and its resolved configuration.

315

316 - `String id`

317

318 Identifier for the ChatKit session.

319

320 - `ChatSessionChatKitConfiguration chatkitConfiguration`

321

322 Resolved ChatKit feature configuration for the session.

323

324 - `ChatSessionAutomaticThreadTitling automaticThreadTitling`

325

326 Automatic thread titling preferences.

327

328 - `boolean enabled`

329

330 Whether automatic thread titling is enabled.

331

332 - `ChatSessionFileUpload fileUpload`

333

334 Upload settings for the session.

335

336 - `boolean enabled`

337

338 Indicates if uploads are enabled for the session.

339

340 - `Optional<Long> maxFileSize`

341

342 Maximum upload size in megabytes.

343

344 - `Optional<Long> maxFiles`

345

346 Maximum number of uploads allowed during the session.

347

348 - `ChatSessionHistory history`

349

350 History retention configuration.

351

352 - `boolean enabled`

353

354 Indicates if chat history is persisted for the session.

355

356 - `Optional<Long> recentThreads`

357

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

359

360 - `String clientSecret`

361

362 Ephemeral client secret that authenticates session requests.

363

364 - `long expiresAt`

365

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

367

368 - `long maxRequestsPer1Minute`

369

370 Convenience copy of the per-minute request limit.

371

372 - `JsonValue; object_ "chatkit.session"constant`

373

374 Type discriminator that is always `chatkit.session`.

375

376 - `CHATKIT_SESSION("chatkit.session")`

377

378 - `ChatSessionRateLimits rateLimits`

379

380 Resolved rate limit values.

381

382 - `long maxRequestsPer1Minute`

383

384 Maximum allowed requests per one-minute window.

385

386 - `ChatSessionStatus status`

387

388 Current lifecycle state of the session.

389

390 - `ACTIVE("active")`

391

392 - `EXPIRED("expired")`

393

394 - `CANCELLED("cancelled")`

395

396 - `String user`

397

398 User identifier associated with the session.

399

400 - `ChatKitWorkflow workflow`

401

402 Workflow metadata for the session.

403

404 - `String id`

405

406 Identifier of the workflow backing the session.

407

408 - `Optional<StateVariables> stateVariables`

409

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

411

412 - `String`

413

414 - `boolean`

415

416 - `double`

417

418 - `Tracing tracing`

419

420 Tracing settings applied to the workflow.

421

422 - `boolean enabled`

423

424 Indicates whether tracing is enabled.

425

426 - `Optional<String> version`

427

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

429

430### Example

431

432```java

433package com.openai.example;

434

435import com.openai.client.OpenAIClient;

436import com.openai.client.okhttp.OpenAIOkHttpClient;

437import com.openai.models.beta.chatkit.sessions.SessionCreateParams;

438import com.openai.models.beta.chatkit.threads.ChatSession;

439import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;

440

441public final class Main {

442 private Main() {}

443

444 public static void main(String[] args) {

445 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

446

447 SessionCreateParams params = SessionCreateParams.builder()

448 .user("x")

449 .workflow(ChatSessionWorkflowParam.builder()

450 .id("id")

451 .build())

452 .build();

453 ChatSession chatSession = client.beta().chatkit().sessions().create(params);

454 }

455}

456```

457

458#### Response

459

460```json

461{

462 "id": "id",

463 "chatkit_configuration": {

464 "automatic_thread_titling": {

465 "enabled": true

466 },

467 "file_upload": {

468 "enabled": true,

469 "max_file_size": 0,

470 "max_files": 0

471 },

472 "history": {

473 "enabled": true,

474 "recent_threads": 0

475 }

476 },

477 "client_secret": "client_secret",

478 "expires_at": 0,

479 "max_requests_per_1_minute": 0,

480 "object": "chatkit.session",

481 "rate_limits": {

482 "max_requests_per_1_minute": 0

483 },

484 "status": "active",

485 "user": "user",

486 "workflow": {

487 "id": "id",

488 "state_variables": {

489 "foo": "string"

490 },

491 "tracing": {

492 "enabled": true

493 },

494 "version": "version"

495 }

496}

497```

498

499### Example

500

501```java

502package com.openai.example;

503

504import com.openai.client.OpenAIClient;

505import com.openai.client.okhttp.OpenAIOkHttpClient;

506import com.openai.models.beta.chatkit.sessions.SessionCreateParams;

507import com.openai.models.beta.chatkit.threads.ChatSession;

508import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;

509

510public final class Main {

511 private Main() {}

512

513 public static void main(String[] args) {

514 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

515

516 SessionCreateParams params = SessionCreateParams.builder()

517 .user("user")

518 .workflow(ChatSessionWorkflowParam.builder()

519 .id("id")

520 .build())

521 .build();

522 ChatSession chatSession = client.beta().chatkit().sessions().create(params);

523 }

524}

525```

526

527#### Response

528

529```json

530{

531 "client_secret": "chatkit_token_123",

532 "expires_at": 1735689600,

533 "workflow": {

534 "id": "workflow_alpha",

535 "version": "2024-10-01"

536 },

537 "scope": {

538 "project": "alpha",

539 "environment": "staging"

540 },

541 "max_requests_per_1_minute": 60,

542 "max_requests_per_session": 500,

543 "status": "active"

544}

545```

546

547# Threads

548

549## List ChatKit thread items

550

551`ThreadListItemsPage beta().chatkit().threads().listItems(ThreadListItemsParamsparams = ThreadListItemsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

552

553**get** `/chatkit/threads/{thread_id}/items`

554

555List items that belong to a ChatKit thread.

556

557### Parameters

558

559- `ThreadListItemsParams params`

560

561 - `Optional<String> threadId`

562

563 - `Optional<String> after`

564

565 List items created after this thread item ID. Defaults to null for the first page.

566

567 - `Optional<String> before`

568

569 List items created before this thread item ID. Defaults to null for the newest results.

570

571 - `Optional<Long> limit`

572

573 Maximum number of thread items to return. Defaults to 20.

574

575 - `Optional<Order> order`

576

577 Sort order for results by creation time. Defaults to `desc`.

578

579 - `ASC("asc")`

580

581 - `DESC("desc")`

582

583### Returns

584

585- `class Data: A class that can be one of several variants.union`

586

587 User-authored messages within a thread.

588

589 - `class ChatKitThreadUserMessageItem:`

590

591 User-authored messages within a thread.

592

593 - `String id`

594

595 Identifier of the thread item.

596

597 - `List<ChatKitAttachment> attachments`

598

599 Attachments associated with the user message. Defaults to an empty list.

600

601 - `String id`

602

603 Identifier for the attachment.

604

605 - `String mimeType`

606

607 MIME type of the attachment.

608

609 - `String name`

610

611 Original display name for the attachment.

612

613 - `Optional<String> previewUrl`

614

615 Preview URL for rendering the attachment inline.

616

617 - `Type type`

618

619 Attachment discriminator.

620

621 - `IMAGE("image")`

622

623 - `FILE("file")`

624

625 - `List<Content> content`

626

627 Ordered content elements supplied by the user.

628

629 - `class InputText:`

630

631 Text block that a user contributed to the thread.

632

633 - `String text`

634

635 Plain-text content supplied by the user.

636

637 - `JsonValue; type "input_text"constant`

638

639 Type discriminator that is always `input_text`.

640

641 - `INPUT_TEXT("input_text")`

642

643 - `class QuotedText:`

644

645 Quoted snippet that the user referenced in their message.

646

647 - `String text`

648

649 Quoted text content.

650

651 - `JsonValue; type "quoted_text"constant`

652

653 Type discriminator that is always `quoted_text`.

654

655 - `QUOTED_TEXT("quoted_text")`

656

657 - `long createdAt`

658

659 Unix timestamp (in seconds) for when the item was created.

660

661 - `Optional<InferenceOptions> inferenceOptions`

662

663 Inference overrides applied to the message. Defaults to null when unset.

664

665 - `Optional<String> model`

666

667 Model name that generated the response. Defaults to null when using the session default.

668

669 - `Optional<ToolChoice> toolChoice`

670

671 Preferred tool to invoke. Defaults to null when ChatKit should auto-select.

672

673 - `String id`

674

675 Identifier of the requested tool.

676

677 - `JsonValue; object_ "chatkit.thread_item"constant`

678

679 Type discriminator that is always `chatkit.thread_item`.

680

681 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

682

683 - `String threadId`

684

685 Identifier of the parent thread.

686

687 - `JsonValue; type "chatkit.user_message"constant`

688

689 - `CHATKIT_USER_MESSAGE("chatkit.user_message")`

690

691 - `class ChatKitThreadAssistantMessageItem:`

692

693 Assistant-authored message within a thread.

694

695 - `String id`

696

697 Identifier of the thread item.

698

699 - `List<ChatKitResponseOutputText> content`

700

701 Ordered assistant response segments.

702

703 - `List<Annotation> annotations`

704

705 Ordered list of annotations attached to the response text.

706

707 - `class File:`

708

709 Annotation that references an uploaded file.

710

711 - `Source source`

712

713 File attachment referenced by the annotation.

714

715 - `String filename`

716

717 Filename referenced by the annotation.

718

719 - `JsonValue; type "file"constant`

720

721 Type discriminator that is always `file`.

722

723 - `FILE("file")`

724

725 - `JsonValue; type "file"constant`

726

727 Type discriminator that is always `file` for this annotation.

728

729 - `FILE("file")`

730

731 - `class Url:`

732

733 Annotation that references a URL.

734

735 - `Source source`

736

737 URL referenced by the annotation.

738

739 - `JsonValue; type "url"constant`

740

741 Type discriminator that is always `url`.

742

743 - `URL("url")`

744

745 - `String url`

746

747 URL referenced by the annotation.

748

749 - `JsonValue; type "url"constant`

750

751 Type discriminator that is always `url` for this annotation.

752

753 - `URL("url")`

754

755 - `String text`

756

757 Assistant generated text.

758

759 - `JsonValue; type "output_text"constant`

760

761 Type discriminator that is always `output_text`.

762

763 - `OUTPUT_TEXT("output_text")`

764

765 - `long createdAt`

766

767 Unix timestamp (in seconds) for when the item was created.

768

769 - `JsonValue; object_ "chatkit.thread_item"constant`

770

771 Type discriminator that is always `chatkit.thread_item`.

772

773 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

774

775 - `String threadId`

776

777 Identifier of the parent thread.

778

779 - `JsonValue; type "chatkit.assistant_message"constant`

780

781 Type discriminator that is always `chatkit.assistant_message`.

782

783 - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")`

784

785 - `class ChatKitWidgetItem:`

786

787 Thread item that renders a widget payload.

788

789 - `String id`

790

791 Identifier of the thread item.

792

793 - `long createdAt`

794

795 Unix timestamp (in seconds) for when the item was created.

796

797 - `JsonValue; object_ "chatkit.thread_item"constant`

798

799 Type discriminator that is always `chatkit.thread_item`.

800

801 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

802

803 - `String threadId`

804

805 Identifier of the parent thread.

806

807 - `JsonValue; type "chatkit.widget"constant`

808

809 Type discriminator that is always `chatkit.widget`.

810

811 - `CHATKIT_WIDGET("chatkit.widget")`

812

813 - `String widget`

814

815 Serialized widget payload rendered in the UI.

816

817 - `class ChatKitClientToolCall:`

818

819 Record of a client side tool invocation initiated by the assistant.

820

821 - `String id`

822

823 Identifier of the thread item.

824

825 - `String arguments`

826

827 JSON-encoded arguments that were sent to the tool.

828

829 - `String callId`

830

831 Identifier for the client tool call.

832

833 - `long createdAt`

834

835 Unix timestamp (in seconds) for when the item was created.

836

837 - `String name`

838

839 Tool name that was invoked.

840

841 - `JsonValue; object_ "chatkit.thread_item"constant`

842

843 Type discriminator that is always `chatkit.thread_item`.

844

845 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

846

847 - `Optional<String> output`

848

849 JSON-encoded output captured from the tool. Defaults to null while execution is in progress.

850

851 - `Status status`

852

853 Execution status for the tool call.

854

855 - `IN_PROGRESS("in_progress")`

856

857 - `COMPLETED("completed")`

858

859 - `String threadId`

860

861 Identifier of the parent thread.

862

863 - `JsonValue; type "chatkit.client_tool_call"constant`

864

865 Type discriminator that is always `chatkit.client_tool_call`.

866

867 - `CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")`

868

869 - `class ChatKitTask:`

870

871 Task emitted by the workflow to show progress and status updates.

872

873 - `String id`

874

875 Identifier of the thread item.

876

877 - `long createdAt`

878

879 Unix timestamp (in seconds) for when the item was created.

880

881 - `Optional<String> heading`

882

883 Optional heading for the task. Defaults to null when not provided.

884

885 - `JsonValue; object_ "chatkit.thread_item"constant`

886

887 Type discriminator that is always `chatkit.thread_item`.

888

889 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

890

891 - `Optional<String> summary`

892

893 Optional summary that describes the task. Defaults to null when omitted.

894

895 - `TaskType taskType`

896

897 Subtype for the task.

898

899 - `CUSTOM("custom")`

900

901 - `THOUGHT("thought")`

902

903 - `String threadId`

904

905 Identifier of the parent thread.

906

907 - `JsonValue; type "chatkit.task"constant`

908

909 Type discriminator that is always `chatkit.task`.

910

911 - `CHATKIT_TASK("chatkit.task")`

912

913 - `class ChatKitTaskGroup:`

914

915 Collection of workflow tasks grouped together in the thread.

916

917 - `String id`

918

919 Identifier of the thread item.

920

921 - `long createdAt`

922

923 Unix timestamp (in seconds) for when the item was created.

924

925 - `JsonValue; object_ "chatkit.thread_item"constant`

926

927 Type discriminator that is always `chatkit.thread_item`.

928

929 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

930

931 - `List<Task> tasks`

932

933 Tasks included in the group.

934

935 - `Optional<String> heading`

936

937 Optional heading for the grouped task. Defaults to null when not provided.

938

939 - `Optional<String> summary`

940

941 Optional summary that describes the grouped task. Defaults to null when omitted.

942

943 - `Type type`

944

945 Subtype for the grouped task.

946

947 - `CUSTOM("custom")`

948

949 - `THOUGHT("thought")`

950

951 - `String threadId`

952

953 Identifier of the parent thread.

954

955 - `JsonValue; type "chatkit.task_group"constant`

956

957 Type discriminator that is always `chatkit.task_group`.

958

959 - `CHATKIT_TASK_GROUP("chatkit.task_group")`

960

961### Example

962

963```java

964package com.openai.example;

965

966import com.openai.client.OpenAIClient;

967import com.openai.client.okhttp.OpenAIOkHttpClient;

968import com.openai.models.beta.chatkit.threads.ThreadListItemsPage;

969import com.openai.models.beta.chatkit.threads.ThreadListItemsParams;

970

971public final class Main {

972 private Main() {}

973

974 public static void main(String[] args) {

975 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

976

977 ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123");

978 }

979}

980```

981

982#### Response

983

984```json

985{

986 "data": [

987 {

988 "id": "id",

989 "attachments": [

990 {

991 "id": "id",

992 "mime_type": "mime_type",

993 "name": "name",

994 "preview_url": "https://example.com",

995 "type": "image"

996 }

997 ],

998 "content": [

999 {

1000 "text": "text",

1001 "type": "input_text"

1002 }

1003 ],

1004 "created_at": 0,

1005 "inference_options": {

1006 "model": "model",

1007 "tool_choice": {

1008 "id": "id"

1009 }

1010 },

1011 "object": "chatkit.thread_item",

1012 "thread_id": "thread_id",

1013 "type": "chatkit.user_message"

1014 }

1015 ],

1016 "first_id": "first_id",

1017 "has_more": true,

1018 "last_id": "last_id",

1019 "object": "list"

1020}

1021```

1022

1023### Example

1024

1025```java

1026package com.openai.example;

1027

1028import com.openai.client.OpenAIClient;

1029import com.openai.client.okhttp.OpenAIOkHttpClient;

1030import com.openai.models.beta.chatkit.threads.ThreadListItemsPage;

1031import com.openai.models.beta.chatkit.threads.ThreadListItemsParams;

1032

1033public final class Main {

1034 private Main() {}

1035

1036 public static void main(String[] args) {

1037 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1038

1039 ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123");

1040 }

1041}

1042```

1043

1044#### Response

1045

1046```json

1047{

1048 "data": [

1049 {

1050 "id": "cthi_user_001",

1051 "object": "chatkit.thread_item",

1052 "type": "user_message",

1053 "content": [

1054 {

1055 "type": "input_text",

1056 "text": "I need help debugging an onboarding issue."

1057 }

1058 ],

1059 "attachments": []

1060 },

1061 {

1062 "id": "cthi_assistant_002",

1063 "object": "chatkit.thread_item",

1064 "type": "assistant_message",

1065 "content": [

1066 {

1067 "type": "output_text",

1068 "text": "Let's start by confirming the workflow version you deployed."

1069 }

1070 ]

1071 }

1072 ],

1073 "has_more": false,

1074 "object": "list"

1075}

1076```

1077

1078## Retrieve ChatKit thread

1079

1080`ChatKitThread beta().chatkit().threads().retrieve(ThreadRetrieveParamsparams = ThreadRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

1081

1082**get** `/chatkit/threads/{thread_id}`

1083

1084Retrieve a ChatKit thread by its identifier.

1085

1086### Parameters

1087

1088- `ThreadRetrieveParams params`

1089

1090 - `Optional<String> threadId`

1091

1092### Returns

1093

1094- `class ChatKitThread:`

1095

1096 Represents a ChatKit thread and its current status.

1097

1098 - `String id`

1099

1100 Identifier of the thread.

1101

1102 - `long createdAt`

1103

1104 Unix timestamp (in seconds) for when the thread was created.

1105

1106 - `JsonValue; object_ "chatkit.thread"constant`

1107

1108 Type discriminator that is always `chatkit.thread`.

1109

1110 - `CHATKIT_THREAD("chatkit.thread")`

1111

1112 - `Status status`

1113

1114 Current status for the thread. Defaults to `active` for newly created threads.

1115

1116 - `JsonValue;`

1117

1118 - `JsonValue; type "active"constant`

1119

1120 Status discriminator that is always `active`.

1121

1122 - `ACTIVE("active")`

1123

1124 - `class Locked:`

1125

1126 Indicates that a thread is locked and cannot accept new input.

1127

1128 - `Optional<String> reason`

1129

1130 Reason that the thread was locked. Defaults to null when no reason is recorded.

1131

1132 - `JsonValue; type "locked"constant`

1133

1134 Status discriminator that is always `locked`.

1135

1136 - `LOCKED("locked")`

1137

1138 - `class Closed:`

1139

1140 Indicates that a thread has been closed.

1141

1142 - `Optional<String> reason`

1143

1144 Reason that the thread was closed. Defaults to null when no reason is recorded.

1145

1146 - `JsonValue; type "closed"constant`

1147

1148 Status discriminator that is always `closed`.

1149

1150 - `CLOSED("closed")`

1151

1152 - `Optional<String> title`

1153

1154 Optional human-readable title for the thread. Defaults to null when no title has been generated.

1155

1156 - `String user`

1157

1158 Free-form string that identifies your end user who owns the thread.

1159

1160### Example

1161

1162```java

1163package com.openai.example;

1164

1165import com.openai.client.OpenAIClient;

1166import com.openai.client.okhttp.OpenAIOkHttpClient;

1167import com.openai.models.beta.chatkit.threads.ChatKitThread;

1168import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams;

1169

1170public final class Main {

1171 private Main() {}

1172

1173 public static void main(String[] args) {

1174 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1175

1176 ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123");

1177 }

1178}

1179```

1180

1181#### Response

1182

1183```json

1184{

1185 "id": "cthr_def456",

1186 "created_at": 1712345600,

1187 "object": "chatkit.thread",

1188 "status": {

1189 "type": "active"

1190 },

1191 "title": "Demo feedback",

1192 "user": "user_456"

1193}

1194```

1195

1196### Example

1197

1198```java

1199package com.openai.example;

1200

1201import com.openai.client.OpenAIClient;

1202import com.openai.client.okhttp.OpenAIOkHttpClient;

1203import com.openai.models.beta.chatkit.threads.ChatKitThread;

1204import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams;

1205

1206public final class Main {

1207 private Main() {}

1208

1209 public static void main(String[] args) {

1210 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1211

1212 ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123");

1213 }

1214}

1215```

1216

1217#### Response

1218

1219```json

1220{

1221 "id": "cthr_abc123",

1222 "object": "chatkit.thread",

1223 "title": "Customer escalation",

1224 "items": {

1225 "data": [

1226 {

1227 "id": "cthi_user_001",

1228 "object": "chatkit.thread_item",

1229 "type": "user_message",

1230 "content": [

1231 {

1232 "type": "input_text",

1233 "text": "I need help debugging an onboarding issue."

1234 }

1235 ],

1236 "attachments": []

1237 },

1238 {

1239 "id": "cthi_assistant_002",

1240 "object": "chatkit.thread_item",

1241 "type": "assistant_message",

1242 "content": [

1243 {

1244 "type": "output_text",

1245 "text": "Let's start by confirming the workflow version you deployed."

1246 }

1247 ]

1248 }

1249 ],

1250 "has_more": false

1251 }

1252}

1253```

1254

1255## Delete ChatKit thread

1256

1257`ThreadDeleteResponse beta().chatkit().threads().delete(ThreadDeleteParamsparams = ThreadDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

1258

1259**delete** `/chatkit/threads/{thread_id}`

1260

1261Delete a ChatKit thread along with its items and stored attachments.

1262

1263### Parameters

1264

1265- `ThreadDeleteParams params`

1266

1267 - `Optional<String> threadId`

1268

1269### Returns

1270

1271- `class ThreadDeleteResponse:`

1272

1273 Confirmation payload returned after deleting a thread.

1274

1275 - `String id`

1276

1277 Identifier of the deleted thread.

1278

1279 - `boolean deleted`

1280

1281 Indicates that the thread has been deleted.

1282

1283 - `JsonValue; object_ "chatkit.thread.deleted"constant`

1284

1285 Type discriminator that is always `chatkit.thread.deleted`.

1286

1287 - `CHATKIT_THREAD_DELETED("chatkit.thread.deleted")`

1288

1289### Example

1290

1291```java

1292package com.openai.example;

1293

1294import com.openai.client.OpenAIClient;

1295import com.openai.client.okhttp.OpenAIOkHttpClient;

1296import com.openai.models.beta.chatkit.threads.ThreadDeleteParams;

1297import com.openai.models.beta.chatkit.threads.ThreadDeleteResponse;

1298

1299public final class Main {

1300 private Main() {}

1301

1302 public static void main(String[] args) {

1303 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1304

1305 ThreadDeleteResponse thread = client.beta().chatkit().threads().delete("cthr_123");

1306 }

1307}

1308```

1309

1310#### Response

1311

1312```json

1313{

1314 "id": "id",

1315 "deleted": true,

1316 "object": "chatkit.thread.deleted"

1317}

1318```

1319

1320### Example

1321

1322```java

1323package com.openai.example;

1324

1325import com.openai.client.OpenAIClient;

1326import com.openai.client.okhttp.OpenAIOkHttpClient;

1327import com.openai.models.beta.chat_kit.threads.ThreadDeleteParams;

1328import com.openai.models.beta.chat_kit.threads.ThreadDeleteResponse;

1329

1330public final class Main {

1331 private Main() {}

1332

1333 public static void main(String[] args) {

1334 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1335

1336 ThreadDeleteResponse thread = client.beta().chat_kit().threads().delete("cthr_123");

1337 }

1338}

1339```

1340

1341## List ChatKit threads

1342

1343`ThreadListPage beta().chatkit().threads().list(ThreadListParamsparams = ThreadListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

1344

1345**get** `/chatkit/threads`

1346

1347List ChatKit threads with optional pagination and user filters.

1348

1349### Parameters

1350

1351- `ThreadListParams params`

1352

1353 - `Optional<String> after`

1354

1355 List items created after this thread item ID. Defaults to null for the first page.

1356

1357 - `Optional<String> before`

1358

1359 List items created before this thread item ID. Defaults to null for the newest results.

1360

1361 - `Optional<Long> limit`

1362

1363 Maximum number of thread items to return. Defaults to 20.

1364

1365 - `Optional<Order> order`

1366

1367 Sort order for results by creation time. Defaults to `desc`.

1368

1369 - `ASC("asc")`

1370

1371 - `DESC("desc")`

1372

1373 - `Optional<String> user`

1374

1375 Filter threads that belong to this user identifier. Defaults to null to return all users.

1376

1377### Returns

1378

1379- `class ChatKitThread:`

1380

1381 Represents a ChatKit thread and its current status.

1382

1383 - `String id`

1384

1385 Identifier of the thread.

1386

1387 - `long createdAt`

1388

1389 Unix timestamp (in seconds) for when the thread was created.

1390

1391 - `JsonValue; object_ "chatkit.thread"constant`

1392

1393 Type discriminator that is always `chatkit.thread`.

1394

1395 - `CHATKIT_THREAD("chatkit.thread")`

1396

1397 - `Status status`

1398

1399 Current status for the thread. Defaults to `active` for newly created threads.

1400

1401 - `JsonValue;`

1402

1403 - `JsonValue; type "active"constant`

1404

1405 Status discriminator that is always `active`.

1406

1407 - `ACTIVE("active")`

1408

1409 - `class Locked:`

1410

1411 Indicates that a thread is locked and cannot accept new input.

1412

1413 - `Optional<String> reason`

1414

1415 Reason that the thread was locked. Defaults to null when no reason is recorded.

1416

1417 - `JsonValue; type "locked"constant`

1418

1419 Status discriminator that is always `locked`.

1420

1421 - `LOCKED("locked")`

1422

1423 - `class Closed:`

1424

1425 Indicates that a thread has been closed.

1426

1427 - `Optional<String> reason`

1428

1429 Reason that the thread was closed. Defaults to null when no reason is recorded.

1430

1431 - `JsonValue; type "closed"constant`

1432

1433 Status discriminator that is always `closed`.

1434

1435 - `CLOSED("closed")`

1436

1437 - `Optional<String> title`

1438

1439 Optional human-readable title for the thread. Defaults to null when no title has been generated.

1440

1441 - `String user`

1442

1443 Free-form string that identifies your end user who owns the thread.

1444

1445### Example

1446

1447```java

1448package com.openai.example;

1449

1450import com.openai.client.OpenAIClient;

1451import com.openai.client.okhttp.OpenAIOkHttpClient;

1452import com.openai.models.beta.chatkit.threads.ThreadListPage;

1453import com.openai.models.beta.chatkit.threads.ThreadListParams;

1454

1455public final class Main {

1456 private Main() {}

1457

1458 public static void main(String[] args) {

1459 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1460

1461 ThreadListPage page = client.beta().chatkit().threads().list();

1462 }

1463}

1464```

1465

1466#### Response

1467

1468```json

1469{

1470 "data": [

1471 {

1472 "id": "cthr_def456",

1473 "created_at": 1712345600,

1474 "object": "chatkit.thread",

1475 "status": {

1476 "type": "active"

1477 },

1478 "title": "Demo feedback",

1479 "user": "user_456"

1480 }

1481 ],

1482 "first_id": "first_id",

1483 "has_more": true,

1484 "last_id": "last_id",

1485 "object": "list"

1486}

1487```

1488

1489### Example

1490

1491```java

1492package com.openai.example;

1493

1494import com.openai.client.OpenAIClient;

1495import com.openai.client.okhttp.OpenAIOkHttpClient;

1496import com.openai.models.beta.chatkit.threads.ThreadListPage;

1497import com.openai.models.beta.chatkit.threads.ThreadListParams;

1498

1499public final class Main {

1500 private Main() {}

1501

1502 public static void main(String[] args) {

1503 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

1504

1505 ThreadListPage page = client.beta().chatkit().threads().list();

1506 }

1507}

1508```

1509

1510#### Response

1511

1512```json

1513{

1514 "data": [

1515 {

1516 "id": "cthr_abc123",

1517 "object": "chatkit.thread",

1518 "title": "Customer escalation"

1519 },

1520 {

1521 "id": "cthr_def456",

1522 "object": "chatkit.thread",

1523 "title": "Demo feedback"

1524 }

1525 ],

1526 "has_more": false,

1527 "object": "list"

1528}

1529```

1530

1531## Domain Types

1532

1533### Chat Session

1534

1535- `class ChatSession:`

1536

1537 Represents a ChatKit session and its resolved configuration.

1538

1539 - `String id`

1540

1541 Identifier for the ChatKit session.

1542

1543 - `ChatSessionChatKitConfiguration chatkitConfiguration`

1544

1545 Resolved ChatKit feature configuration for the session.

1546

1547 - `ChatSessionAutomaticThreadTitling automaticThreadTitling`

1548

1549 Automatic thread titling preferences.

1550

1551 - `boolean enabled`

1552

1553 Whether automatic thread titling is enabled.

1554

1555 - `ChatSessionFileUpload fileUpload`

1556

1557 Upload settings for the session.

1558

1559 - `boolean enabled`

1560

1561 Indicates if uploads are enabled for the session.

1562

1563 - `Optional<Long> maxFileSize`

1564

1565 Maximum upload size in megabytes.

1566

1567 - `Optional<Long> maxFiles`

1568

1569 Maximum number of uploads allowed during the session.

1570

1571 - `ChatSessionHistory history`

1572

1573 History retention configuration.

1574

1575 - `boolean enabled`

1576

1577 Indicates if chat history is persisted for the session.

1578

1579 - `Optional<Long> recentThreads`

1580

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

1582

1583 - `String clientSecret`

1584

1585 Ephemeral client secret that authenticates session requests.

1586

1587 - `long expiresAt`

1588

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

1590

1591 - `long maxRequestsPer1Minute`

1592

1593 Convenience copy of the per-minute request limit.

1594

1595 - `JsonValue; object_ "chatkit.session"constant`

1596

1597 Type discriminator that is always `chatkit.session`.

1598

1599 - `CHATKIT_SESSION("chatkit.session")`

1600

1601 - `ChatSessionRateLimits rateLimits`

1602

1603 Resolved rate limit values.

1604

1605 - `long maxRequestsPer1Minute`

1606

1607 Maximum allowed requests per one-minute window.

1608

1609 - `ChatSessionStatus status`

1610

1611 Current lifecycle state of the session.

1612

1613 - `ACTIVE("active")`

1614

1615 - `EXPIRED("expired")`

1616

1617 - `CANCELLED("cancelled")`

1618

1619 - `String user`

1620

1621 User identifier associated with the session.

1622

1623 - `ChatKitWorkflow workflow`

1624

1625 Workflow metadata for the session.

1626

1627 - `String id`

1628

1629 Identifier of the workflow backing the session.

1630

1631 - `Optional<StateVariables> stateVariables`

1632

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

1634

1635 - `String`

1636

1637 - `boolean`

1638

1639 - `double`

1640

1641 - `Tracing tracing`

1642

1643 Tracing settings applied to the workflow.

1644

1645 - `boolean enabled`

1646

1647 Indicates whether tracing is enabled.

1648

1649 - `Optional<String> version`

1650

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

1652

1653### Chat Session Automatic Thread Titling

1654

1655- `class ChatSessionAutomaticThreadTitling:`

1656

1657 Automatic thread title preferences for the session.

1658

1659 - `boolean enabled`

1660

1661 Whether automatic thread titling is enabled.

1662

1663### Chat Session ChatKit Configuration

1664

1665- `class ChatSessionChatKitConfiguration:`

1666

1667 ChatKit configuration for the session.

1668

1669 - `ChatSessionAutomaticThreadTitling automaticThreadTitling`

1670

1671 Automatic thread titling preferences.

1672

1673 - `boolean enabled`

1674

1675 Whether automatic thread titling is enabled.

1676

1677 - `ChatSessionFileUpload fileUpload`

1678

1679 Upload settings for the session.

1680

1681 - `boolean enabled`

1682

1683 Indicates if uploads are enabled for the session.

1684

1685 - `Optional<Long> maxFileSize`

1686

1687 Maximum upload size in megabytes.

1688

1689 - `Optional<Long> maxFiles`

1690

1691 Maximum number of uploads allowed during the session.

1692

1693 - `ChatSessionHistory history`

1694

1695 History retention configuration.

1696

1697 - `boolean enabled`

1698

1699 Indicates if chat history is persisted for the session.

1700

1701 - `Optional<Long> recentThreads`

1702

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

1704

1705### Chat Session ChatKit Configuration Param

1706

1707- `class ChatSessionChatKitConfigurationParam:`

1708

1709 Optional per-session configuration settings for ChatKit behavior.

1710

1711 - `Optional<AutomaticThreadTitling> automaticThreadTitling`

1712

1713 Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.

1714

1715 - `Optional<Boolean> enabled`

1716

1717 Enable automatic thread title generation. Defaults to true.

1718

1719 - `Optional<FileUpload> fileUpload`

1720

1721 Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).

1722

1723 - `Optional<Boolean> enabled`

1724

1725 Enable uploads for this session. Defaults to false.

1726

1727 - `Optional<Long> maxFileSize`

1728

1729 Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.

1730

1731 - `Optional<Long> maxFiles`

1732

1733 Maximum number of files that can be uploaded to the session. Defaults to 10.

1734

1735 - `Optional<History> history`

1736

1737 Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null).

1738

1739 - `Optional<Boolean> enabled`

1740

1741 Enables chat users to access previous ChatKit threads. Defaults to true.

1742

1743 - `Optional<Long> recentThreads`

1744

1745 Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.

1746

1747### Chat Session Expires After Param

1748

1749- `class ChatSessionExpiresAfterParam:`

1750

1751 Controls when the session expires relative to an anchor timestamp.

1752

1753 - `JsonValue; anchor "created_at"constant`

1754

1755 Base timestamp used to calculate expiration. Currently fixed to `created_at`.

1756

1757 - `CREATED_AT("created_at")`

1758

1759 - `long seconds`

1760

1761 Number of seconds after the anchor when the session expires.

1762

1763### Chat Session File Upload

1764

1765- `class ChatSessionFileUpload:`

1766

1767 Upload permissions and limits applied to the session.

1768

1769 - `boolean enabled`

1770

1771 Indicates if uploads are enabled for the session.

1772

1773 - `Optional<Long> maxFileSize`

1774

1775 Maximum upload size in megabytes.

1776

1777 - `Optional<Long> maxFiles`

1778

1779 Maximum number of uploads allowed during the session.

1780

1781### Chat Session History

1782

1783- `class ChatSessionHistory:`

1784

1785 History retention preferences returned for the session.

1786

1787 - `boolean enabled`

1788

1789 Indicates if chat history is persisted for the session.

1790

1791 - `Optional<Long> recentThreads`

1792

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

1794

1795### Chat Session Rate Limits

1796

1797- `class ChatSessionRateLimits:`

1798

1799 Active per-minute request limit for the session.

1800

1801 - `long maxRequestsPer1Minute`

1802

1803 Maximum allowed requests per one-minute window.

1804

1805### Chat Session Rate Limits Param

1806

1807- `class ChatSessionRateLimitsParam:`

1808

1809 Controls request rate limits for the session.

1810

1811 - `Optional<Long> maxRequestsPer1Minute`

1812

1813 Maximum number of requests allowed per minute for the session. Defaults to 10.

1814

1815### Chat Session Status

1816

1817- `enum ChatSessionStatus:`

1818

1819 - `ACTIVE("active")`

1820

1821 - `EXPIRED("expired")`

1822

1823 - `CANCELLED("cancelled")`

1824

1825### Chat Session Workflow Param

1826

1827- `class ChatSessionWorkflowParam:`

1828

1829 Workflow reference and overrides applied to the chat session.

1830

1831 - `String id`

1832

1833 Identifier for the workflow invoked by the session.

1834

1835 - `Optional<StateVariables> stateVariables`

1836

1837 State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object.

1838

1839 - `String`

1840

1841 - `boolean`

1842

1843 - `double`

1844

1845 - `Optional<Tracing> tracing`

1846

1847 Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default.

1848

1849 - `Optional<Boolean> enabled`

1850

1851 Whether tracing is enabled during the session. Defaults to true.

1852

1853 - `Optional<String> version`

1854

1855 Specific workflow version to run. Defaults to the latest deployed version.

1856

1857### ChatKit Attachment

1858

1859- `class ChatKitAttachment:`

1860

1861 Attachment metadata included on thread items.

1862

1863 - `String id`

1864

1865 Identifier for the attachment.

1866

1867 - `String mimeType`

1868

1869 MIME type of the attachment.

1870

1871 - `String name`

1872

1873 Original display name for the attachment.

1874

1875 - `Optional<String> previewUrl`

1876

1877 Preview URL for rendering the attachment inline.

1878

1879 - `Type type`

1880

1881 Attachment discriminator.

1882

1883 - `IMAGE("image")`

1884

1885 - `FILE("file")`

1886

1887### ChatKit Response Output Text

1888

1889- `class ChatKitResponseOutputText:`

1890

1891 Assistant response text accompanied by optional annotations.

1892

1893 - `List<Annotation> annotations`

1894

1895 Ordered list of annotations attached to the response text.

1896

1897 - `class File:`

1898

1899 Annotation that references an uploaded file.

1900

1901 - `Source source`

1902

1903 File attachment referenced by the annotation.

1904

1905 - `String filename`

1906

1907 Filename referenced by the annotation.

1908

1909 - `JsonValue; type "file"constant`

1910

1911 Type discriminator that is always `file`.

1912

1913 - `FILE("file")`

1914

1915 - `JsonValue; type "file"constant`

1916

1917 Type discriminator that is always `file` for this annotation.

1918

1919 - `FILE("file")`

1920

1921 - `class Url:`

1922

1923 Annotation that references a URL.

1924

1925 - `Source source`

1926

1927 URL referenced by the annotation.

1928

1929 - `JsonValue; type "url"constant`

1930

1931 Type discriminator that is always `url`.

1932

1933 - `URL("url")`

1934

1935 - `String url`

1936

1937 URL referenced by the annotation.

1938

1939 - `JsonValue; type "url"constant`

1940

1941 Type discriminator that is always `url` for this annotation.

1942

1943 - `URL("url")`

1944

1945 - `String text`

1946

1947 Assistant generated text.

1948

1949 - `JsonValue; type "output_text"constant`

1950

1951 Type discriminator that is always `output_text`.

1952

1953 - `OUTPUT_TEXT("output_text")`

1954

1955### ChatKit Thread

1956

1957- `class ChatKitThread:`

1958

1959 Represents a ChatKit thread and its current status.

1960

1961 - `String id`

1962

1963 Identifier of the thread.

1964

1965 - `long createdAt`

1966

1967 Unix timestamp (in seconds) for when the thread was created.

1968

1969 - `JsonValue; object_ "chatkit.thread"constant`

1970

1971 Type discriminator that is always `chatkit.thread`.

1972

1973 - `CHATKIT_THREAD("chatkit.thread")`

1974

1975 - `Status status`

1976

1977 Current status for the thread. Defaults to `active` for newly created threads.

1978

1979 - `JsonValue;`

1980

1981 - `JsonValue; type "active"constant`

1982

1983 Status discriminator that is always `active`.

1984

1985 - `ACTIVE("active")`

1986

1987 - `class Locked:`

1988

1989 Indicates that a thread is locked and cannot accept new input.

1990

1991 - `Optional<String> reason`

1992

1993 Reason that the thread was locked. Defaults to null when no reason is recorded.

1994

1995 - `JsonValue; type "locked"constant`

1996

1997 Status discriminator that is always `locked`.

1998

1999 - `LOCKED("locked")`

2000

2001 - `class Closed:`

2002

2003 Indicates that a thread has been closed.

2004

2005 - `Optional<String> reason`

2006

2007 Reason that the thread was closed. Defaults to null when no reason is recorded.

2008

2009 - `JsonValue; type "closed"constant`

2010

2011 Status discriminator that is always `closed`.

2012

2013 - `CLOSED("closed")`

2014

2015 - `Optional<String> title`

2016

2017 Optional human-readable title for the thread. Defaults to null when no title has been generated.

2018

2019 - `String user`

2020

2021 Free-form string that identifies your end user who owns the thread.

2022

2023### ChatKit Thread Assistant Message Item

2024

2025- `class ChatKitThreadAssistantMessageItem:`

2026

2027 Assistant-authored message within a thread.

2028

2029 - `String id`

2030

2031 Identifier of the thread item.

2032

2033 - `List<ChatKitResponseOutputText> content`

2034

2035 Ordered assistant response segments.

2036

2037 - `List<Annotation> annotations`

2038

2039 Ordered list of annotations attached to the response text.

2040

2041 - `class File:`

2042

2043 Annotation that references an uploaded file.

2044

2045 - `Source source`

2046

2047 File attachment referenced by the annotation.

2048

2049 - `String filename`

2050

2051 Filename referenced by the annotation.

2052

2053 - `JsonValue; type "file"constant`

2054

2055 Type discriminator that is always `file`.

2056

2057 - `FILE("file")`

2058

2059 - `JsonValue; type "file"constant`

2060

2061 Type discriminator that is always `file` for this annotation.

2062

2063 - `FILE("file")`

2064

2065 - `class Url:`

2066

2067 Annotation that references a URL.

2068

2069 - `Source source`

2070

2071 URL referenced by the annotation.

2072

2073 - `JsonValue; type "url"constant`

2074

2075 Type discriminator that is always `url`.

2076

2077 - `URL("url")`

2078

2079 - `String url`

2080

2081 URL referenced by the annotation.

2082

2083 - `JsonValue; type "url"constant`

2084

2085 Type discriminator that is always `url` for this annotation.

2086

2087 - `URL("url")`

2088

2089 - `String text`

2090

2091 Assistant generated text.

2092

2093 - `JsonValue; type "output_text"constant`

2094

2095 Type discriminator that is always `output_text`.

2096

2097 - `OUTPUT_TEXT("output_text")`

2098

2099 - `long createdAt`

2100

2101 Unix timestamp (in seconds) for when the item was created.

2102

2103 - `JsonValue; object_ "chatkit.thread_item"constant`

2104

2105 Type discriminator that is always `chatkit.thread_item`.

2106

2107 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2108

2109 - `String threadId`

2110

2111 Identifier of the parent thread.

2112

2113 - `JsonValue; type "chatkit.assistant_message"constant`

2114

2115 Type discriminator that is always `chatkit.assistant_message`.

2116

2117 - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")`

2118

2119### ChatKit Thread Item List

2120

2121- `class ChatKitThreadItemList:`

2122

2123 A paginated list of thread items rendered for the ChatKit API.

2124

2125 - `List<Data> data`

2126

2127 A list of items

2128

2129 - `class ChatKitThreadUserMessageItem:`

2130

2131 User-authored messages within a thread.

2132

2133 - `String id`

2134

2135 Identifier of the thread item.

2136

2137 - `List<ChatKitAttachment> attachments`

2138

2139 Attachments associated with the user message. Defaults to an empty list.

2140

2141 - `String id`

2142

2143 Identifier for the attachment.

2144

2145 - `String mimeType`

2146

2147 MIME type of the attachment.

2148

2149 - `String name`

2150

2151 Original display name for the attachment.

2152

2153 - `Optional<String> previewUrl`

2154

2155 Preview URL for rendering the attachment inline.

2156

2157 - `Type type`

2158

2159 Attachment discriminator.

2160

2161 - `IMAGE("image")`

2162

2163 - `FILE("file")`

2164

2165 - `List<Content> content`

2166

2167 Ordered content elements supplied by the user.

2168

2169 - `class InputText:`

2170

2171 Text block that a user contributed to the thread.

2172

2173 - `String text`

2174

2175 Plain-text content supplied by the user.

2176

2177 - `JsonValue; type "input_text"constant`

2178

2179 Type discriminator that is always `input_text`.

2180

2181 - `INPUT_TEXT("input_text")`

2182

2183 - `class QuotedText:`

2184

2185 Quoted snippet that the user referenced in their message.

2186

2187 - `String text`

2188

2189 Quoted text content.

2190

2191 - `JsonValue; type "quoted_text"constant`

2192

2193 Type discriminator that is always `quoted_text`.

2194

2195 - `QUOTED_TEXT("quoted_text")`

2196

2197 - `long createdAt`

2198

2199 Unix timestamp (in seconds) for when the item was created.

2200

2201 - `Optional<InferenceOptions> inferenceOptions`

2202

2203 Inference overrides applied to the message. Defaults to null when unset.

2204

2205 - `Optional<String> model`

2206

2207 Model name that generated the response. Defaults to null when using the session default.

2208

2209 - `Optional<ToolChoice> toolChoice`

2210

2211 Preferred tool to invoke. Defaults to null when ChatKit should auto-select.

2212

2213 - `String id`

2214

2215 Identifier of the requested tool.

2216

2217 - `JsonValue; object_ "chatkit.thread_item"constant`

2218

2219 Type discriminator that is always `chatkit.thread_item`.

2220

2221 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2222

2223 - `String threadId`

2224

2225 Identifier of the parent thread.

2226

2227 - `JsonValue; type "chatkit.user_message"constant`

2228

2229 - `CHATKIT_USER_MESSAGE("chatkit.user_message")`

2230

2231 - `class ChatKitThreadAssistantMessageItem:`

2232

2233 Assistant-authored message within a thread.

2234

2235 - `String id`

2236

2237 Identifier of the thread item.

2238

2239 - `List<ChatKitResponseOutputText> content`

2240

2241 Ordered assistant response segments.

2242

2243 - `List<Annotation> annotations`

2244

2245 Ordered list of annotations attached to the response text.

2246

2247 - `class File:`

2248

2249 Annotation that references an uploaded file.

2250

2251 - `Source source`

2252

2253 File attachment referenced by the annotation.

2254

2255 - `String filename`

2256

2257 Filename referenced by the annotation.

2258

2259 - `JsonValue; type "file"constant`

2260

2261 Type discriminator that is always `file`.

2262

2263 - `FILE("file")`

2264

2265 - `JsonValue; type "file"constant`

2266

2267 Type discriminator that is always `file` for this annotation.

2268

2269 - `FILE("file")`

2270

2271 - `class Url:`

2272

2273 Annotation that references a URL.

2274

2275 - `Source source`

2276

2277 URL referenced by the annotation.

2278

2279 - `JsonValue; type "url"constant`

2280

2281 Type discriminator that is always `url`.

2282

2283 - `URL("url")`

2284

2285 - `String url`

2286

2287 URL referenced by the annotation.

2288

2289 - `JsonValue; type "url"constant`

2290

2291 Type discriminator that is always `url` for this annotation.

2292

2293 - `URL("url")`

2294

2295 - `String text`

2296

2297 Assistant generated text.

2298

2299 - `JsonValue; type "output_text"constant`

2300

2301 Type discriminator that is always `output_text`.

2302

2303 - `OUTPUT_TEXT("output_text")`

2304

2305 - `long createdAt`

2306

2307 Unix timestamp (in seconds) for when the item was created.

2308

2309 - `JsonValue; object_ "chatkit.thread_item"constant`

2310

2311 Type discriminator that is always `chatkit.thread_item`.

2312

2313 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2314

2315 - `String threadId`

2316

2317 Identifier of the parent thread.

2318

2319 - `JsonValue; type "chatkit.assistant_message"constant`

2320

2321 Type discriminator that is always `chatkit.assistant_message`.

2322

2323 - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")`

2324

2325 - `class ChatKitWidgetItem:`

2326

2327 Thread item that renders a widget payload.

2328

2329 - `String id`

2330

2331 Identifier of the thread item.

2332

2333 - `long createdAt`

2334

2335 Unix timestamp (in seconds) for when the item was created.

2336

2337 - `JsonValue; object_ "chatkit.thread_item"constant`

2338

2339 Type discriminator that is always `chatkit.thread_item`.

2340

2341 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2342

2343 - `String threadId`

2344

2345 Identifier of the parent thread.

2346

2347 - `JsonValue; type "chatkit.widget"constant`

2348

2349 Type discriminator that is always `chatkit.widget`.

2350

2351 - `CHATKIT_WIDGET("chatkit.widget")`

2352

2353 - `String widget`

2354

2355 Serialized widget payload rendered in the UI.

2356

2357 - `class ChatKitClientToolCall:`

2358

2359 Record of a client side tool invocation initiated by the assistant.

2360

2361 - `String id`

2362

2363 Identifier of the thread item.

2364

2365 - `String arguments`

2366

2367 JSON-encoded arguments that were sent to the tool.

2368

2369 - `String callId`

2370

2371 Identifier for the client tool call.

2372

2373 - `long createdAt`

2374

2375 Unix timestamp (in seconds) for when the item was created.

2376

2377 - `String name`

2378

2379 Tool name that was invoked.

2380

2381 - `JsonValue; object_ "chatkit.thread_item"constant`

2382

2383 Type discriminator that is always `chatkit.thread_item`.

2384

2385 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2386

2387 - `Optional<String> output`

2388

2389 JSON-encoded output captured from the tool. Defaults to null while execution is in progress.

2390

2391 - `Status status`

2392

2393 Execution status for the tool call.

2394

2395 - `IN_PROGRESS("in_progress")`

2396

2397 - `COMPLETED("completed")`

2398

2399 - `String threadId`

2400

2401 Identifier of the parent thread.

2402

2403 - `JsonValue; type "chatkit.client_tool_call"constant`

2404

2405 Type discriminator that is always `chatkit.client_tool_call`.

2406

2407 - `CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")`

2408

2409 - `class ChatKitTask:`

2410

2411 Task emitted by the workflow to show progress and status updates.

2412

2413 - `String id`

2414

2415 Identifier of the thread item.

2416

2417 - `long createdAt`

2418

2419 Unix timestamp (in seconds) for when the item was created.

2420

2421 - `Optional<String> heading`

2422

2423 Optional heading for the task. Defaults to null when not provided.

2424

2425 - `JsonValue; object_ "chatkit.thread_item"constant`

2426

2427 Type discriminator that is always `chatkit.thread_item`.

2428

2429 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2430

2431 - `Optional<String> summary`

2432

2433 Optional summary that describes the task. Defaults to null when omitted.

2434

2435 - `TaskType taskType`

2436

2437 Subtype for the task.

2438

2439 - `CUSTOM("custom")`

2440

2441 - `THOUGHT("thought")`

2442

2443 - `String threadId`

2444

2445 Identifier of the parent thread.

2446

2447 - `JsonValue; type "chatkit.task"constant`

2448

2449 Type discriminator that is always `chatkit.task`.

2450

2451 - `CHATKIT_TASK("chatkit.task")`

2452

2453 - `class ChatKitTaskGroup:`

2454

2455 Collection of workflow tasks grouped together in the thread.

2456

2457 - `String id`

2458

2459 Identifier of the thread item.

2460

2461 - `long createdAt`

2462

2463 Unix timestamp (in seconds) for when the item was created.

2464

2465 - `JsonValue; object_ "chatkit.thread_item"constant`

2466

2467 Type discriminator that is always `chatkit.thread_item`.

2468

2469 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2470

2471 - `List<Task> tasks`

2472

2473 Tasks included in the group.

2474

2475 - `Optional<String> heading`

2476

2477 Optional heading for the grouped task. Defaults to null when not provided.

2478

2479 - `Optional<String> summary`

2480

2481 Optional summary that describes the grouped task. Defaults to null when omitted.

2482

2483 - `Type type`

2484

2485 Subtype for the grouped task.

2486

2487 - `CUSTOM("custom")`

2488

2489 - `THOUGHT("thought")`

2490

2491 - `String threadId`

2492

2493 Identifier of the parent thread.

2494

2495 - `JsonValue; type "chatkit.task_group"constant`

2496

2497 Type discriminator that is always `chatkit.task_group`.

2498

2499 - `CHATKIT_TASK_GROUP("chatkit.task_group")`

2500

2501 - `Optional<String> firstId`

2502

2503 The ID of the first item in the list.

2504

2505 - `boolean hasMore`

2506

2507 Whether there are more items available.

2508

2509 - `Optional<String> lastId`

2510

2511 The ID of the last item in the list.

2512

2513 - `JsonValue; object_ "list"constant`

2514

2515 The type of object returned, must be `list`.

2516

2517 - `LIST("list")`

2518

2519### ChatKit Thread User Message Item

2520

2521- `class ChatKitThreadUserMessageItem:`

2522

2523 User-authored messages within a thread.

2524

2525 - `String id`

2526

2527 Identifier of the thread item.

2528

2529 - `List<ChatKitAttachment> attachments`

2530

2531 Attachments associated with the user message. Defaults to an empty list.

2532

2533 - `String id`

2534

2535 Identifier for the attachment.

2536

2537 - `String mimeType`

2538

2539 MIME type of the attachment.

2540

2541 - `String name`

2542

2543 Original display name for the attachment.

2544

2545 - `Optional<String> previewUrl`

2546

2547 Preview URL for rendering the attachment inline.

2548

2549 - `Type type`

2550

2551 Attachment discriminator.

2552

2553 - `IMAGE("image")`

2554

2555 - `FILE("file")`

2556

2557 - `List<Content> content`

2558

2559 Ordered content elements supplied by the user.

2560

2561 - `class InputText:`

2562

2563 Text block that a user contributed to the thread.

2564

2565 - `String text`

2566

2567 Plain-text content supplied by the user.

2568

2569 - `JsonValue; type "input_text"constant`

2570

2571 Type discriminator that is always `input_text`.

2572

2573 - `INPUT_TEXT("input_text")`

2574

2575 - `class QuotedText:`

2576

2577 Quoted snippet that the user referenced in their message.

2578

2579 - `String text`

2580

2581 Quoted text content.

2582

2583 - `JsonValue; type "quoted_text"constant`

2584

2585 Type discriminator that is always `quoted_text`.

2586

2587 - `QUOTED_TEXT("quoted_text")`

2588

2589 - `long createdAt`

2590

2591 Unix timestamp (in seconds) for when the item was created.

2592

2593 - `Optional<InferenceOptions> inferenceOptions`

2594

2595 Inference overrides applied to the message. Defaults to null when unset.

2596

2597 - `Optional<String> model`

2598

2599 Model name that generated the response. Defaults to null when using the session default.

2600

2601 - `Optional<ToolChoice> toolChoice`

2602

2603 Preferred tool to invoke. Defaults to null when ChatKit should auto-select.

2604

2605 - `String id`

2606

2607 Identifier of the requested tool.

2608

2609 - `JsonValue; object_ "chatkit.thread_item"constant`

2610

2611 Type discriminator that is always `chatkit.thread_item`.

2612

2613 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2614

2615 - `String threadId`

2616

2617 Identifier of the parent thread.

2618

2619 - `JsonValue; type "chatkit.user_message"constant`

2620

2621 - `CHATKIT_USER_MESSAGE("chatkit.user_message")`

2622

2623### ChatKit Widget Item

2624

2625- `class ChatKitWidgetItem:`

2626

2627 Thread item that renders a widget payload.

2628

2629 - `String id`

2630

2631 Identifier of the thread item.

2632

2633 - `long createdAt`

2634

2635 Unix timestamp (in seconds) for when the item was created.

2636

2637 - `JsonValue; object_ "chatkit.thread_item"constant`

2638

2639 Type discriminator that is always `chatkit.thread_item`.

2640

2641 - `CHATKIT_THREAD_ITEM("chatkit.thread_item")`

2642

2643 - `String threadId`

2644

2645 Identifier of the parent thread.

2646

2647 - `JsonValue; type "chatkit.widget"constant`

2648

2649 Type discriminator that is always `chatkit.widget`.

2650

2651 - `CHATKIT_WIDGET("chatkit.widget")`

2652

2653 - `String widget`

2654

2655 Serialized widget payload rendered in the UI.

java/resources/beta/subresources/chatkit/index.md 2026-05-02 05:57 UTC to 2026-05-05 23:00 UTC

ChatKit

Domain Types

ChatKit Workflow

Sessions

Cancel chat session

Parameters

Returns

Example

Response

Example

Response

Create ChatKit session

Parameters

Returns

Example

Response

Example

Response

Threads

List ChatKit thread items

Parameters

Returns

Example

Response

Example

Response

Retrieve ChatKit thread

Parameters

Returns

Example

Response

Example

Response

Delete ChatKit thread

Parameters

Returns

Example

Response

Example

List ChatKit threads

Parameters

Returns

Example

Response

Example

Response

Domain Types

Chat Session

Chat Session Automatic Thread Titling

Chat Session ChatKit Configuration

Chat Session ChatKit Configuration Param

Chat Session Expires After Param

Chat Session File Upload

Chat Session History

Chat Session Rate Limits

Chat Session Rate Limits Param

Chat Session Status

Chat Session Workflow Param

ChatKit Attachment

ChatKit Response Output Text

ChatKit Thread

ChatKit Thread Assistant Message Item

ChatKit Thread Item List

ChatKit Thread User Message Item

ChatKit Widget Item