Sample - OpenAI API
POST/threads/{thread_id}/messages

Create a message in a thread

Creates a message in a specified thread. Supply role and content, and optionally attach files or metadata to the new message.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 4 body fields
thread_idstringrequired
The identifier of the thread in which to create the message.

Message data containing its role and content, with optional attachments and metadata.

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:userassistant
contentstringrequired
The message text or an array of text and image content parts; an array must contain at least one item.
attachmentsarray<object>optional
Files to attach to the message and the tools to which they should be added.
metadataobjectoptional
String key-value pairs attached to the message; keys can be up to 64 characters, with up to 16 pairs.

2 status codes
200Returns the created message object with its identifier, thread association, status, role, content, attachments, and metadata.
idstringrequired
The identifier, which can be referenced in API endpoints.
objectstringrequired
The object type, which is always `thread.message`.
Allowed:thread.message
created_atintegerrequired
The Unix timestamp (in seconds) for when the message was created.
thread_idstringrequired
The [thread](https://developers.openai.com/api/docs/assistants/migration) ID that this message belongs to.
statusstringrequired
The status of the message, which can be either `in_progress`, `incomplete`, or `completed`.
Allowed:in_progressincompletecompleted
incomplete_detailsobjectrequired
On an incomplete message, details about why the message is incomplete.
completed_atintegerrequired
The Unix timestamp (in seconds) for when the message was completed.
incomplete_atintegerrequired
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:userassistant
contentarray<ImageFile>required
The content of the message in array of text and/or images.
assistant_idstringrequired
If applicable, the ID of the [assistant](https://developers.openai.com/api/docs/assistants/migration) that authored this message.
run_idstringrequired
The ID of the [run](https://developers.openai.com/api/docs/assistants/migration) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints.
attachmentsarray<object>required
A list of files attached to the message, and the tools they were added to.
metadataobjectrequired
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.
429Returned when the request was rejected because a rate limit was exceeded.
errorobjectrequired

Error handling

A 429 is returned when the request exceeds the rate limit. role must be user or assistant, and both role and content are required; array content must contain at least one item.