thread_idstringrequired
The ID of the thread to delete.
Delete a thread.
delete
https://api.openai.com/v1/threads/{thread_id}
Path Parameters
Response
200 application/json
Response
200 application/json
OK
DeleteThreadResponse
idstringrequired
deletedbooleanrequired
objectstringrequired
Allowed values:thread.deleted
delete/threads/{thread_id}
Authentication
Path Parameters
200 application/json
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
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
Authentication
Path Parameters
Query Parameters
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
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
content
One Ofrequired
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
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
content
One Ofarrayrequired
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
Authentication
Path Parameters
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
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
content
One Ofarrayrequired
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}
Authentication
Path Parameters
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
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
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
content
One Ofarrayrequired
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}
Authentication
Path Parameters
Body
{}
200 application/json