Create message

POST /threads/{thread_id}/messages

Create a message.

Path parameters

application/json

Body Required

  • role string Required

    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.

    Values are user or assistant.

  • content string | array[object] Required

    One of:
    Text content string Array of content parts array[object]

    The text contents of the message.

    An array of content parts with a defined type, each can be of type text or images can be passed with image_url or image_file. Image types are only supported on Vision-compatible models.

    At least 1 element.

    One of:
    Image file object Image URL object Text object
  • attachments array[object] | null

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

    Hide attachments attributes Show attachments attributes object
    • file_id string

      The ID of the file to attach to the message.

    • tools array[object]

      The tools to add this file to.

      One of:
      Code interpreter tool object FileSearch tool object
  • metadata object | 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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

  • Additional properties are NOT allowed

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • id string Required

      The identifier, which can be referenced in API endpoints.

    • object string Required

      The object type, which is always thread.message.

      Value is thread.message.

    • created_at integer Required

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

    • thread_id string Required

      The thread ID that this message belongs to.

    • status string Required

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

      Values are in_progress, incomplete, or completed.

    • incomplete_details object | null Required

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

      Hide incomplete_details attribute Show incomplete_details attribute object | null
      • reason string Required

        The reason the message is incomplete.

        Values are content_filter, max_tokens, run_cancelled, run_expired, or run_failed.

    • completed_at integer | null Required

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

    • incomplete_at integer | null Required

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

    • role string Required

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

      Values are user or assistant.

    • content array[object] Required

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

      One of:
      Image file object Image URL object Text object
    • assistant_id string | null Required

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

    • run_id string | null Required

      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.

    • attachments array[object] | null Required

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

      Hide attachments attributes Show attachments attributes object
      • file_id string

        The ID of the file to attach to the message.

      • tools array[object]

        The tools to add this file to.

        One of:
        Code interpreter tool object FileSearch tool object
    • metadata object | null Required

      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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
POST /threads/{thread_id}/messages 
curl \
 -X POST https://api.openai.com/v1/threads/{thread_id}/messages \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"role":"user","content":"string","attachments":[{"file_id":"string","tools":[{"type":"code_interpreter"}]}],"metadata":{}}'
Request example 
{
  "role": "user",
  "content": "string",
  "attachments": [
    {
      "file_id": "string",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {}
}
Response examples (200) 
{
  "id": "string",
  "object": "thread.message",
  "created_at": 42,
  "thread_id": "string",
  "status": "in_progress",
  "incomplete_details": {
    "reason": "content_filter"
  },
  "completed_at": 42,
  "incomplete_at": 42,
  "role": "user",
  "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "string",
        "detail": "auto"
      }
    }
  ],
  "assistant_id": "string",
  "run_id": "string",
  "attachments": [
    {
      "file_id": "string",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {}
}