OpenAI API (unofficial showcase)
POST/threads/{thread_id}/messages

Create a message in a thread

Creates a message in a thread. Provide the message role and content, and optionally include file attachments or metadata. Use this operation to add a user or assistant message to an existing conversation thread.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

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

Message content and role, with optional attachments and metadata. role and content are required.

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 as a string or an array of content parts. An array must contain at least one item; image content is supported only on vision-compatible models.
attachmentsarray<object>optional
Files to attach to the message, with the tools they should be added to.
metadataobjectoptional
Up to 16 key-value pairs to attach to the message; keys can be at most 64 characters and values are strings.

2 status codes
200Returns the created message object with its ID, thread ID, 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 is rejected because a rate limit was exceeded.
errorobjectrequired

Error handling

A 429 is returned when the request exceeds a rate limit. The thread_id path parameter identifies the thread for the new message. role and content are required; role must be user or assistant, and an array of content parts must contain at least one item.