Create thread

Deprecated

beta.threads.create(**kwargs) -> Thread { id, created_at, metadata, 2 more }

POST/threads

Create a thread.

ParametersExpand Collapse

messages: Array[{ content, role, attachments, metadata}]

A list of messages to start the thread with.

content: String | Array[MessageContentPartParam]

The text contents of the message.

One of the following:

String

The text contents of the message.

Array[MessageContentPartParam]

An array of content parts with a defined type, each can be of type text or images can be passed with image_url or image_file. Image types are only supported on Vision-compatible models.

One of the following:

class ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }

file_id: String

The File ID of the image in the message content. Set purpose="vision" when uploading the File if you need to later display the file content.

detail: :auto | :low | :high

Specifies the detail level of the image if specified by the user. low uses fewer tokens, you can opt in to high resolution using high.

One of the following:

:auto

:low

:high

type: :image_file

Always image_file.

class ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }

url: String

The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.

formaturi

detail: :auto | :low | :high

Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high. Default value is auto

One of the following:

:auto

:low

:high

type: :image_url

The type of the content part.

class TextContentBlockParam { text, type }

The text content that is part of a message.

text: String

Text content to be sent to the model

type: :text

Always text.

role: :user | :assistant

The role of the entity that is creating the message. Allowed values include:

user: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
assistant: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.

One of the following:

:user

:assistant

attachments: Array[{ file_id, tools}]

A list of files attached to the message, and the tools they should be added to.

file_id: String

The ID of the file to attach to the message.

tools: Array[CodeInterpreterTool { type } | { type}]

The tools to add this file to.

One of the following:

class CodeInterpreterTool { type }

type: :code_interpreter

The type of tool being defined: code_interpreter

class FileSearch { type }

type: :file_search

The type of tool being defined: file_search

metadata: Metadata

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

metadata: Metadata

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

tool_resources: { code_interpreter, file_search}

A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

code_interpreter: { file_ids}

file_ids: Array[String]

A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.

file_search: { vector_store_ids, vector_stores}

vector_store_ids: Array[String]

The vector store attached to this thread. There can be a maximum of 1 vector store attached to the thread.

vector_stores: Array[{ chunking_strategy, file_ids, metadata}]

A helper to create a vector store with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread.

chunking_strategy: { type} | { static, type}

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.

One of the following:

class Auto { type }

The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.

type: :auto

Always auto.

class Static { static, type }

static: { chunk_overlap_tokens, max_chunk_size_tokens}

chunk_overlap_tokens: Integer

The number of tokens that overlap between chunks. The default value is 400.

Note that the overlap must not exceed half of max_chunk_size_tokens.

max_chunk_size_tokens: Integer

The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.

minimum100

maximum4096

type: :static

Always static.

file_ids: Array[String]

A list of file IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files.

metadata: Metadata

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

ReturnsExpand Collapse

class Thread { id, created_at, metadata, 2 more }

Represents a thread that contains messages.

id: String

The identifier, which can be referenced in API endpoints.

created_at: Integer

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

metadata: Metadata

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

object: :thread

The object type, which is always thread.

tool_resources: { code_interpreter, file_search}

code_interpreter: { file_ids}

file_ids: Array[String]

A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.

file_search: { vector_store_ids}

vector_store_ids: Array[String]

The vector store attached to this thread. There can be a maximum of 1 vector store attached to the thread.

Create thread

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

thread = openai.beta.threads.create

puts(thread)

{
  "id": "id",
  "created_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "thread",
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "string"
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "string"
      ]
    }
  }
}

Returns Examples

{
  "id": "id",
  "created_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "thread",
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "string"
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "string"
      ]
    }
  }
}

Suggested

Create thread

ParametersExpand Collapse

ReturnsExpand Collapse

Create thread

Returns Examples