curl -X POST 'https://api.openai.com/v1/threads/thread-id/messages' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": "user",
  "content": "example-content"
}'

# POST /threads/{thread_id}/messages (OpenAI API)
Base URL: https://api.openai.com/v1
Auth: Authorization; OpenAI API key; required.
Request formats: application/json.
Last verified: 2026-10-20

> Create message

## Critical Gotchas
* The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.
* Audio transcription uploads use multipart form data rather than a JSON request body.

## cURL
curl -X POST 'https://api.openai.com/v1/threads/thread-id/messages' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": "user",
  "content": "example-content"
}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| thread_id | path | string | Yes | The ID of the [thread](https://developers.openai.com/api/docs/assistants/migr... |
| role | body | string | Yes | The role of the entity that is creating the message. Allowed values include:... |
| content | body | string | Yes | The text contents of the message. |
| attachments | body | object[] | No | A list of files attached to the message, and the tools they should be added to. |
| metadata | body | object | No | Set of 16 key-value pairs that can be attached to an object. This can be usef... |

## Response example
{"id":"string","object":"thread.message"}

---
Need an API key? Get one at https://platform.openai.com/api-keys

POST

POST /threads/{thread_id}/messages — OpenAI API

OpenAI API key (required); https://api.openai.com/v1

OpenAI API

Create message

Base URL: https://api.openai.com/v1
Auth: Authorization: Bearer <OPENAI_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 296 tokens · Vary: Accept

Critical gotchas

The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.

Audio transcription uploads use multipart form data rather than a JSON request body.

cURL

curl -X POST 'https://api.openai.com/v1/threads/thread-id/messages' \  -H "Authorization: Bearer $OPENAI_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "role": "user",  "content": "example-content"}'

Parameters

Name	In	Type	Required	Description
thread_id	path	string	Yes	The ID of the [thread](https://developers.openai.com/api/docs/assistants/migration) to create a message for.
role	body	string	Yes	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.
content	body	string	Yes	The text contents of the message.
attachments	body	object[]	No	A list of files attached to the message, and the tools they should be added to.
metadata	body	object	No	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 OK

{
  "id": "string",
  "object": "thread.message",
  "created_at": 0,
  "thread_id": "string",
  "status": "in_progress",
  "incomplete_details": {
    "reason": "content_filter"
  },
  "completed_at": 0,
  "incomplete_at": 0,
  "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": {}
}

Get a free OpenAI API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.