Search
K
OpenAI API

Returns a list of messages for a given thread.

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

Query Parameters

limitinteger

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

Default:20

orderstring

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

Allowed values:ascdesc

Default:desc

afterstring

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

beforestring

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

run_idstring

Filter messages by the run ID that generated them.

Path Parameters

thread_idstringrequired

The ID of the thread the messages belong to.

Response

200 application/json

OK

ListMessagesResponse

objectstringrequired

Example:list

dataarray[object]required

Represents a message within a thread.

Show Child Parameters
first_idstringrequired

Example:msg_abc123

last_idstringrequired

Example:msg_abc123

has_morebooleanrequired

Example:false

get/threads/{thread_id}/messages
 
200 application/json

Create a message.

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

Path Parameters

thread_idstringrequired

The ID of the thread to create a message for.

Body

application/json

CreateMessageRequest

* Additional properties are NOT allowed.
rolestringrequired

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.

Allowed values:userassistant

contentOne Of
required
Text contentstring

The text contents of the message.

attachmentsarray | null[object]

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

Show Child Parameters
metadataobject | null

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.

Response

200 application/json

OK

The message object

Represents a message within a thread.

idstringrequired

The identifier, which can be referenced in API endpoints.

objectstringrequired

The object type, which is always thread.message.

Allowed values:thread.message

created_atintegerrequired

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

thread_idstringrequired

The thread ID that this message belongs to.

statusstringrequired

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

Allowed values:in_progressincompletecompleted

incomplete_detailsobject | nullrequired

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

Show Child Parameters
completed_atinteger | nullrequired

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

incomplete_atinteger | nullrequired

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

rolestringrequired

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

Allowed values:userassistant

contentOne Of
arrayrequired

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

Image fileobject

References an image File in the content of a message.

Show Child Parameters
assistant_idstring | nullrequired

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

run_idstring | nullrequired

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.

attachmentsarray | null[object]required

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

Show Child Parameters
metadataobject | nullrequired

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.

post/threads/{thread_id}/messages

Body

{ "role": "user", "content": {} }
 
200 application/json

Retrieve a message.

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

Path Parameters

thread_idstringrequired

The ID of the thread to which this message belongs.

message_idstringrequired

The ID of the message to retrieve.

Response

200 application/json

OK

The message object

Represents a message within a thread.

idstringrequired

The identifier, which can be referenced in API endpoints.

objectstringrequired

The object type, which is always thread.message.

Allowed values:thread.message

created_atintegerrequired

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

thread_idstringrequired

The thread ID that this message belongs to.

statusstringrequired

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

Allowed values:in_progressincompletecompleted

incomplete_detailsobject | nullrequired

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

Show Child Parameters
completed_atinteger | nullrequired

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

incomplete_atinteger | nullrequired

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

rolestringrequired

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

Allowed values:userassistant

contentOne Of
arrayrequired

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

Image fileobject

References an image File in the content of a message.

Show Child Parameters
assistant_idstring | nullrequired

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

run_idstring | nullrequired

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.

attachmentsarray | null[object]required

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

Show Child Parameters
metadataobject | nullrequired

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.

get/threads/{thread_id}/messages/{message_id}
 
200 application/json

Modifies a message.

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

Path Parameters

thread_idstringrequired

The ID of the thread to which this message belongs.

message_idstringrequired

The ID of the message to modify.

Body

application/json

ModifyMessageRequest

* Additional properties are NOT allowed.
metadataobject | null

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.

Response

200 application/json

OK

The message object

Represents a message within a thread.

idstringrequired

The identifier, which can be referenced in API endpoints.

objectstringrequired

The object type, which is always thread.message.

Allowed values:thread.message

created_atintegerrequired

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

thread_idstringrequired

The thread ID that this message belongs to.

statusstringrequired

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

Allowed values:in_progressincompletecompleted

incomplete_detailsobject | nullrequired

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

Show Child Parameters
completed_atinteger | nullrequired

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

incomplete_atinteger | nullrequired

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

rolestringrequired

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

Allowed values:userassistant

contentOne Of
arrayrequired

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

Image fileobject

References an image File in the content of a message.

Show Child Parameters
assistant_idstring | nullrequired

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

run_idstring | nullrequired

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.

attachmentsarray | null[object]required

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

Show Child Parameters
metadataobject | nullrequired

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.

post/threads/{thread_id}/messages/{message_id}

Body

{}
 
200 application/json

Deletes a message.

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

Path Parameters

thread_idstringrequired

The ID of the thread to which this message belongs.

message_idstringrequired

The ID of the message to delete.

Response

200 application/json

OK

DeleteMessageResponse

idstringrequired
deletedbooleanrequired
objectstringrequired

Allowed values:thread.message.deleted

delete/threads/{thread_id}/messages/{message_id}
 
200 application/json