API Reference

Conversations

Items

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create items

$ openai conversations:items create

POST/conversations/{conversation_id}/items

Create items in a conversation with the given ID.

ParametersExpand Collapse

--conversation-id: string

Path param: The ID of the conversation to add the item to.

--item: array of ResponseInputItem

Body param: The items to add to the conversation. You may add up to 20 items at a time.

--include: optional array of ResponseIncludable

Query param: Additional fields to include in the response. See the include parameter for listing Conversation items above for more information.

ReturnsExpand Collapse

conversation_item_list: object { data, first_id, has_more, 2 more }

A list of Conversation items.

data: array of ConversationItem

A list of conversation items.

first_id: string

The ID of the first item in the list.

has_more: boolean

Whether there are more items available.

last_id: string

The ID of the last item in the list.

object: "list"

The type of object returned, must be list.

Create items

CLI Tool

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

openai conversations:items create \
  --api-key 'My API Key' \
  --conversation-id conv_123 \
  --item '{content: string, role: user, type: message}'

{
  "object": "list",
  "data": [
    {
      "type": "message",
      "id": "msg_abc",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Hello!"}
      ]
    },
    {
      "type": "message",
      "id": "msg_def",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "How are you?"}
      ]
    }
  ],
  "first_id": "msg_abc",
  "last_id": "msg_def",
  "has_more": false
}

Returns Examples

{
  "object": "list",
  "data": [
    {
      "type": "message",
      "id": "msg_abc",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Hello!"}
      ]
    },
    {
      "type": "message",
      "id": "msg_def",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "How are you?"}
      ]
    }
  ],
  "first_id": "msg_abc",
  "last_id": "msg_def",
  "has_more": false
}