Skip to content
Lucero

Create a message.

POST
/threads/{thread_id}/messages

Authorizations

Parameters

Path Parameters

thread_id
required
string

The ID of the thread to create a message for.

Request Body required

object
role
required

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.
string
Allowed values: user assistant
content
required
One of:

The text contents of the message.

string
attachments

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

Array<object>
nullable
object
file_id

The ID of the file to attach to the message.

string
tools

The tools to add this file to.

Array
One of:
object
type
required

The type of tool being defined: code_interpreter

string
Allowed values: code_interpreter
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. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

object

Responses

200

OK

Represents a message within a thread.

object
id
required

The identifier, which can be referenced in API endpoints.

string
object
required

The object type, which is always thread.message.

string
Allowed values: thread.message
created_at
required

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

integer
thread_id
required

The thread ID that this message belongs to.

string
status
required

The status of the message, which can be either in_progress, incomplete, or completed.

string
Allowed values: in_progress incomplete completed
incomplete_details
required

On an incomplete message, details about why the message is incomplete.

object
reason
required

The reason the message is incomplete.

string
Allowed values: content_filter max_tokens run_cancelled run_expired run_failed
completed_at
required

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

integer
nullable
incomplete_at
required

The Unix timestamp (in seconds) for when the message was marked as incomplete.

integer
nullable
role
required

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

string
Allowed values: user assistant
content
required

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

Array
One of:

References an image File in the content of a message.

object
type
required

Always image_file.

string
Allowed values: image_file
image_file
required
object
file_id
required

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.

string
detail

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.

string
default: auto
Allowed values: auto low high
assistant_id
required

If applicable, the ID of the assistant that authored this message.

string
nullable
run_id
required

The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.

string
nullable
attachments
required

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

Array<object>
nullable
object
file_id

The ID of the file to attach to the message.

string
tools

The tools to add this file to.

Array
One of:
object
type
required

The type of tool being defined: code_interpreter

string
Allowed values: code_interpreter
metadata
required

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. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

object