Skip to content
Primary navigation

Suggested
API Dashboard
API Reference
Beta
Threads

Messages

Build Assistants that can call models and use tools.

List messages
Deprecated
beta.threads.messages.list(thread_id, **kwargs) -> CursorPage<Message { id, assistant_id, attachments, 11 more } >
GET/threads/{thread_id}/messages
Create message
Deprecated
beta.threads.messages.create(thread_id, **kwargs) -> Message { id, assistant_id, attachments, 11 more }
POST/threads/{thread_id}/messages
Modify message
Deprecated
beta.threads.messages.update(message_id, **kwargs) -> Message { id, assistant_id, attachments, 11 more }
POST/threads/{thread_id}/messages/{message_id}
Retrieve message
Deprecated
beta.threads.messages.retrieve(message_id, **kwargs) -> Message { id, assistant_id, attachments, 11 more }
GET/threads/{thread_id}/messages/{message_id}
Delete message
Deprecated
beta.threads.messages.delete(message_id, **kwargs) -> MessageDeleted { id, deleted, object }
DELETE/threads/{thread_id}/messages/{message_id}
ModelsExpand Collapse
Annotation = FileCitationAnnotation { end_index, file_citation, start_index, 2 more } | FilePathAnnotation { end_index, file_path, start_index, 2 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

One of the following:
class FileCitationAnnotation { end_index, file_citation, start_index, 2 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

end_index: Integer
minimum0
file_citation: { file_id}
file_id: String

The ID of the specific File the citation is from.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

type: :file_citation

Always file_citation.

class FilePathAnnotation { end_index, file_path, start_index, 2 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

end_index: Integer
minimum0
file_path: { file_id}
file_id: String

The ID of the file that was generated.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

type: :file_path

Always file_path.

AnnotationDelta = FileCitationDeltaAnnotation { index, type, end_index, 3 more } | FilePathDeltaAnnotation { index, type, end_index, 3 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

One of the following:
class FileCitationDeltaAnnotation { index, type, end_index, 3 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

index: Integer

The index of the annotation in the text content part.

type: :file_citation

Always file_citation.

end_index: Integer
minimum0
file_citation: { file_id, quote}
file_id: String

The ID of the specific File the citation is from.

quote: String

The specific quote in the file.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

class FilePathDeltaAnnotation { index, type, end_index, 3 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

index: Integer

The index of the annotation in the text content part.

type: :file_path

Always file_path.

end_index: Integer
minimum0
file_path: { file_id}
file_id: String

The ID of the file that was generated.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

class FileCitationAnnotation { end_index, file_citation, start_index, 2 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

end_index: Integer
minimum0
file_citation: { file_id}
file_id: String

The ID of the specific File the citation is from.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

type: :file_citation

Always file_citation.

class FileCitationDeltaAnnotation { index, type, end_index, 3 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

index: Integer

The index of the annotation in the text content part.

type: :file_citation

Always file_citation.

end_index: Integer
minimum0
file_citation: { file_id, quote}
file_id: String

The ID of the specific File the citation is from.

quote: String

The specific quote in the file.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

class FilePathAnnotation { end_index, file_path, start_index, 2 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

end_index: Integer
minimum0
file_path: { file_id}
file_id: String

The ID of the file that was generated.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

type: :file_path

Always file_path.

class FilePathDeltaAnnotation { index, type, end_index, 3 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

index: Integer

The index of the annotation in the text content part.

type: :file_path

Always file_path.

end_index: Integer
minimum0
file_path: { file_id}
file_id: String

The ID of the file that was generated.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

class ImageFile { file_id, detail }
file_id: String

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.

detail: :auto | :low | :high

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.

One of the following:
:auto
:low
:high
class ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }
type: :image_file

Always image_file.

class ImageFileDelta { detail, file_id }
detail: :auto | :low | :high

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.

One of the following:
:auto
:low
:high
file_id: String

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.

class ImageFileDeltaBlock { index, type, image_file }

References an image File in the content of a message.

index: Integer

The index of the content part in the message.

type: :image_file

Always image_file.

image_file: ImageFileDelta { detail, file_id }
class ImageURL { url, detail }
url: String

The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.

formaturi
detail: :auto | :low | :high

Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high. Default value is auto

One of the following:
:auto
:low
:high
class ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }
type: :image_url

The type of the content part.

class ImageURLDelta { detail, url }
detail: :auto | :low | :high

Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high.

One of the following:
:auto
:low
:high
url: String

The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.

class ImageURLDeltaBlock { index, type, image_url }

References an image URL in the content of a message.

index: Integer

The index of the content part in the message.

type: :image_url

Always image_url.

image_url: ImageURLDelta { detail, url }
class Message { id, assistant_id, attachments, 11 more }

Represents a message within a thread.

id: String

The identifier, which can be referenced in API endpoints.

assistant_id: String

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

attachments: Array[{ file_id, tools}]

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

file_id: String

The ID of the file to attach to the message.

tools: Array[CodeInterpreterTool { type } | { type}]

The tools to add this file to.

One of the following:
class CodeInterpreterTool { type }
type: :code_interpreter

The type of tool being defined: code_interpreter

class AssistantToolsFileSearchTypeOnly { type }
type: :file_search

The type of tool being defined: file_search

completed_at: Integer

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

content: Array[MessageContent]

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

One of the following:
class ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }
type: :image_file

Always image_file.

class ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }
type: :image_url

The type of the content part.

class TextContentBlock { text, type }

The text content that is part of a message.

text: Text { annotations, value }
type: :text

Always text.

class RefusalContentBlock { refusal, type }

The refusal content generated by the assistant.

refusal: String
type: :refusal

Always refusal.

created_at: Integer

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

incomplete_at: Integer

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

incomplete_details: { reason}

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

reason: :content_filter | :max_tokens | :run_cancelled | 2 more

The reason the message is incomplete.

One of the following:
:content_filter
:max_tokens
:run_cancelled
:run_expired
:run_failed
metadata: 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, 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.

object: :"thread.message"

The object type, which is always thread.message.

role: :user | :assistant

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

One of the following:
:user
:assistant
run_id: String

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.

status: :in_progress | :incomplete | :completed

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

One of the following:
:in_progress
:incomplete
:completed
thread_id: String

The thread ID that this message belongs to.

MessageContent = ImageFileContentBlock { image_file, type } | ImageURLContentBlock { image_url, type } | TextContentBlock { text, type } | RefusalContentBlock { refusal, type }

References an image File in the content of a message.

One of the following:
class ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }
type: :image_file

Always image_file.

class ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }
type: :image_url

The type of the content part.

class TextContentBlock { text, type }

The text content that is part of a message.

text: Text { annotations, value }
type: :text

Always text.

class RefusalContentBlock { refusal, type }

The refusal content generated by the assistant.

refusal: String
type: :refusal

Always refusal.

MessageContentDelta = ImageFileDeltaBlock { index, type, image_file } | TextDeltaBlock { index, type, text } | RefusalDeltaBlock { index, type, refusal } | ImageURLDeltaBlock { index, type, image_url }

References an image File in the content of a message.

One of the following:
class ImageFileDeltaBlock { index, type, image_file }

References an image File in the content of a message.

index: Integer

The index of the content part in the message.

type: :image_file

Always image_file.

image_file: ImageFileDelta { detail, file_id }
class TextDeltaBlock { index, type, text }

The text content that is part of a message.

index: Integer

The index of the content part in the message.

type: :text

Always text.

text: TextDelta { annotations, value }
class RefusalDeltaBlock { index, type, refusal }

The refusal content that is part of a message.

index: Integer

The index of the refusal part in the message.

type: :refusal

Always refusal.

refusal: String
class ImageURLDeltaBlock { index, type, image_url }

References an image URL in the content of a message.

index: Integer

The index of the content part in the message.

type: :image_url

Always image_url.

image_url: ImageURLDelta { detail, url }
MessageContentPartParam = ImageFileContentBlock { image_file, type } | ImageURLContentBlock { image_url, type } | TextContentBlockParam { text, type }

References an image File in the content of a message.

One of the following:
class ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }
type: :image_file

Always image_file.

class ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }
type: :image_url

The type of the content part.

class TextContentBlockParam { text, type }

The text content that is part of a message.

text: String

Text content to be sent to the model

type: :text

Always text.

class MessageDeleted { id, deleted, object }
id: String
deleted: bool
object: :"thread.message.deleted"
class MessageDelta { content, role }

The delta containing the fields that have changed on the Message.

content: Array[MessageContentDelta]

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

One of the following:
class ImageFileDeltaBlock { index, type, image_file }

References an image File in the content of a message.

index: Integer

The index of the content part in the message.

type: :image_file

Always image_file.

image_file: ImageFileDelta { detail, file_id }
class TextDeltaBlock { index, type, text }

The text content that is part of a message.

index: Integer

The index of the content part in the message.

type: :text

Always text.

text: TextDelta { annotations, value }
class RefusalDeltaBlock { index, type, refusal }

The refusal content that is part of a message.

index: Integer

The index of the refusal part in the message.

type: :refusal

Always refusal.

refusal: String
class ImageURLDeltaBlock { index, type, image_url }

References an image URL in the content of a message.

index: Integer

The index of the content part in the message.

type: :image_url

Always image_url.

image_url: ImageURLDelta { detail, url }
role: :user | :assistant

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

One of the following:
:user
:assistant
class MessageDeltaEvent { id, delta, object }

Represents a message delta i.e. any changed fields on a message during streaming.

id: String

The identifier of the message, which can be referenced in API endpoints.

delta: MessageDelta { content, role }

The delta containing the fields that have changed on the Message.

object: :"thread.message.delta"

The object type, which is always thread.message.delta.

class RefusalContentBlock { refusal, type }

The refusal content generated by the assistant.

refusal: String
type: :refusal

Always refusal.

class RefusalDeltaBlock { index, type, refusal }

The refusal content that is part of a message.

index: Integer

The index of the refusal part in the message.

type: :refusal

Always refusal.

refusal: String
class Text { annotations, value }
annotations: Array[Annotation]
One of the following:
class FileCitationAnnotation { end_index, file_citation, start_index, 2 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

end_index: Integer
minimum0
file_citation: { file_id}
file_id: String

The ID of the specific File the citation is from.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

type: :file_citation

Always file_citation.

class FilePathAnnotation { end_index, file_path, start_index, 2 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

end_index: Integer
minimum0
file_path: { file_id}
file_id: String

The ID of the file that was generated.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

type: :file_path

Always file_path.

value: String

The data that makes up the text.

class TextContentBlock { text, type }

The text content that is part of a message.

text: Text { annotations, value }
type: :text

Always text.

class TextContentBlockParam { text, type }

The text content that is part of a message.

text: String

Text content to be sent to the model

type: :text

Always text.

class TextDelta { annotations, value }
annotations: Array[AnnotationDelta]
One of the following:
class FileCitationDeltaAnnotation { index, type, end_index, 3 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

index: Integer

The index of the annotation in the text content part.

type: :file_citation

Always file_citation.

end_index: Integer
minimum0
file_citation: { file_id, quote}
file_id: String

The ID of the specific File the citation is from.

quote: String

The specific quote in the file.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

class FilePathDeltaAnnotation { index, type, end_index, 3 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

index: Integer

The index of the annotation in the text content part.

type: :file_path

Always file_path.

end_index: Integer
minimum0
file_path: { file_id}
file_id: String

The ID of the file that was generated.

start_index: Integer
minimum0
text: String

The text in the message content that needs to be replaced.

value: String

The data that makes up the text.

class TextDeltaBlock { index, type, text }

The text content that is part of a message.

index: Integer

The index of the content part in the message.

type: :text

Always text.

text: TextDelta { annotations, value }