Thread Messages

POST /v1/threads/{thread_id}/messages

Python

from openai import OpenAI
client = OpenAI()

# Create a message
message = client.beta.threads.messages.create(
    thread_id="thread_abc123",
    role="user",
    content="How does AI work? Explain it in simple terms."
)

# List messages
messages = client.beta.threads.messages.list(
    thread_id="thread_abc123"
)

for msg in messages:
    print(msg.role, msg.content)

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

// Create a message
const message = await openai.beta.threads.messages.create(
  "thread_abc123",
  {
    role: "user",
    content: "How does AI work? Explain it in simple terms."
  }
);

// List messages
const messages = await openai.beta.threads.messages.list(
  "thread_abc123"
);

for (const msg of messages.data) {
  console.log(msg.role, msg.content);
}

curl https://api.openai.com/v1/threads/thread_abc123/messages \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -H "OpenAI-Beta: assistants=v2" \\
  -d '{
    "role": "user",
    "content": "How does AI work? Explain it in simple terms."
  }'

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}

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

Create a message in a thread.

Path Parameters

thread_id · string · required

The ID of the thread to create a message for.

Request Body

role · string · required

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

• user: Indicates the message is sent by an actual user
• assistant: Indicates the message is generated by the 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.

Show Attachment object

file_id · string

The ID of the file to attach to the message.

tools · array

The tools to add this file to.

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 Message object.

id · string

The message identifier.

object · string

The object type, always thread.message.

created_at · integer

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

thread_id · string

The thread ID that this message belongs to.

role · string

The entity that produced the message. One of user or assistant.

content · array

The content of the message in array of text and/or images.

List Messages

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

Returns a list of messages for a given thread.

Query Parameters

limit · integer · default: "20"

A limit on the number of objects to be returned. Limit can range between 1 and 100.

order · string · default: "desc"

Sort order by the created_at timestamp. asc for ascending order and desc for descending order.

after · string

A cursor for use in pagination.

before · string

A cursor for use in pagination.

run_id · string

Filter messages by the run ID that generated them.

Python

from openai import OpenAI
client = OpenAI()

# Create a message
message = client.beta.threads.messages.create(
    thread_id="thread_abc123",
    role="user",
    content="How does AI work? Explain it in simple terms."
)

# List messages
messages = client.beta.threads.messages.list(
    thread_id="thread_abc123"
)

for msg in messages:
    print(msg.role, msg.content)

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

// Create a message
const message = await openai.beta.threads.messages.create(
  "thread_abc123",
  {
    role: "user",
    content: "How does AI work? Explain it in simple terms."
  }
);

// List messages
const messages = await openai.beta.threads.messages.list(
  "thread_abc123"
);

for (const msg of messages.data) {
  console.log(msg.role, msg.content);
}

curl https://api.openai.com/v1/threads/thread_abc123/messages \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -H "OpenAI-Beta: assistants=v2" \\
  -d '{
    "role": "user",
    "content": "How does AI work? Explain it in simple terms."
  }'

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}