Managing Threads

POST /v1/threads

Python

from openai import OpenAI
client = OpenAI()

# Create a thread
thread = client.beta.threads.create(
    messages=[
        {
            "role": "user",
            "content": "Explain quantum computing in simple terms."
        }
    ]
)

print(thread.id)

import OpenAI from "openai";
const openai = new OpenAI();

// Create a thread
const thread = await openai.beta.threads.create({
  messages: [
    {
      role: "user",
      content: "Explain quantum computing in simple terms."
    }
  ]
});

console.log(thread.id);

curl https://api.openai.com/v1/threads \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -H "OpenAI-Beta: assistants=v2" \\
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ]
  }'

{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699012949,
  "metadata": {},
  "tool_resources": {}
}

The Assistants API is deprecated in favor of the Responses API.

Create a thread for conversations with an assistant.

Create Thread

Request Body

messages · array

A list of messages to start the thread with.

Show Message object

role · string · required

The role of the entity creating the message. Either user or assistant.

content · string · required

The text contents of the message.

attachments · array

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

metadata · object

Set of 16 key-value pairs that can be attached to an object.

tool_resources · object

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.

metadata · object

Set of 16 key-value pairs that can be attached to an object.

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

Response

Returns a Thread object.

id · string

The thread identifier.

object · string

The object type, always thread.

created_at · integer

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

metadata · object

Set of 16 key-value pairs attached to the object.

Retrieve Thread

GET https://api.openai.com/v1/threads/{thread_id}

Retrieves a thread.

Update Thread

POST https://api.openai.com/v1/threads/{thread_id}

Modifies a thread.

Delete Thread

DELETE https://api.openai.com/v1/threads/{thread_id}

Delete a thread.

Python

from openai import OpenAI
client = OpenAI()

# Create a thread
thread = client.beta.threads.create(
    messages=[
        {
            "role": "user",
            "content": "Explain quantum computing in simple terms."
        }
    ]
)

print(thread.id)

import OpenAI from "openai";
const openai = new OpenAI();

// Create a thread
const thread = await openai.beta.threads.create({
  messages: [
    {
      role: "user",
      content: "Explain quantum computing in simple terms."
    }
  ]
});

console.log(thread.id);

curl https://api.openai.com/v1/threads \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -H "OpenAI-Beta: assistants=v2" \\
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ]
  }'

{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699012949,
  "metadata": {},
  "tool_resources": {}
}