---
title: "Create items."
method: POST
path: "/v1/conversations/{conversation_id}/items"
tags: ["Conversations"]
---

# Create items.

`POST /v1/conversations/{conversation_id}/items`

Create items in the conversation.

## Path parameters

- `conversation_id` string, required — The conversation identifier.

## Request body

- AddItemsRequest — Request model for adding items to a conversation.
  - `items` union[], required — Items to include in the conversation context. You may add up to 20 items at a time.
    - union
      - OpenAIResponseMessageInput — Corresponds to the various Message types in the Responses API. They are all under one type because the Responses API gives them all the same "type" value, and there is no way to tell them apart in certain scenarios.
        - `content` union, required
          - string
          - union[]
            - union
              - …
          - union[]
            - union
              - …
        - `role` union, required
          - 'system'
          - 'developer'
          - 'user'
          - 'assistant'
        - `type` 'message'
        - `id` string, nullable
        - `status` string, nullable
      - OpenAIResponseOutputMessageWebSearchToolCallInput — Web search tool call output message for OpenAI responses.
        - `id` string, required
        - `status` string, required
        - `type` 'web_search_call'
        - `action` union
          - WebSearchActionSearch — Web search action: performs a search query.
            - `type` 'search'
            - `query` string, required
            - `queries` string[], nullable
            - `sources` WebSearchSource[], nullable
              - …
          - WebSearchActionOpenPage — Web search action: opens a specific URL from search results.
            - `type` 'open_page'
            - `url` string, nullable
          - WebSearchActionFind — Web search action: searches for a pattern within a loaded page.
            - `type` 'find_in_page'
            - `url` string, required
            - `pattern` string, required
      - OpenAIResponseOutputMessageFileSearchToolCall — File search tool call output message for OpenAI responses.
        - `id` string, required
        - `queries` string[], required
        - `status` string, required
        - `type` 'file_search_call'
        - `results` OpenAIResponseOutputMessageFileSearchToolCallResults[], nullable
          - `attributes` object, required
          - `file_id` string, required
          - `filename` string, required
          - `score` number, required
          - `text` string, required
      - OpenAIResponseOutputMessageFunctionToolCall — Function tool call output message for OpenAI responses.
        - `call_id` string, required
        - `name` string, required
        - `arguments` string, required
        - `type` 'function_call'
        - `id` string, nullable
        - `status` string, nullable
      - OpenAIResponseInputFunctionToolCallOutput — This represents the output of a function call that gets passed back to the model.
        - `call_id` string, required
        - `output` union, required
          - string
          - union[]
            - union
              - …
        - `type` 'function_call_output'
        - `id` string, nullable
        - `status` string, nullable
      - OpenAIResponseMCPApprovalRequest — A request for human approval of a tool invocation.
        - `arguments` string, required
        - `id` string, required
        - `name` string, required
        - `server_label` string, required
        - `type` 'mcp_approval_request'
      - OpenAIResponseMCPApprovalResponse — A response to an MCP approval request.
        - `approval_request_id` string, required
        - `approve` boolean, required
        - `type` 'mcp_approval_response'
        - `id` string, nullable
        - `reason` string, nullable
      - OpenAIResponseOutputMessageMCPCall — Model Context Protocol (MCP) call output message for OpenAI responses.
        - `id` string, required
        - `type` 'mcp_call'
        - `arguments` string, required
        - `name` string, required
        - `server_label` string, required
        - `error` string, nullable
        - `output` string, nullable
      - OpenAIResponseOutputMessageMCPListTools — MCP list tools output message containing available tools from an MCP server.
        - `id` string, required
        - `type` 'mcp_list_tools'
        - `server_label` string, required
        - `tools` MCPListToolsTool[], required
          - `input_schema` object, required
          - `name` string, required
          - `description` string, nullable
      - OpenAIResponseOutputMessageReasoningItem — Reasoning output from the model, representing the model's thinking process.
        - `id` string, required — Unique identifier for the reasoning output item.
        - `summary` OpenAIResponseOutputMessageReasoningSummary[], required — Summary of the reasoning output.
          - `text` string, required — The summary text of the reasoning output.
          - `type` 'summary_text' — The type identifier, always 'summary_text'.
        - `type` 'reasoning' — The type identifier, always 'reasoning'.
        - `content` OpenAIResponseOutputMessageReasoningContent[], nullable — The reasoning content from the model.
          - `text` string, required — The reasoning text content from the model.
          - `type` 'reasoning_text' — The type identifier, always 'reasoning_text'.
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the reasoning output.
      - OpenAIResponseCompaction — A compaction item that summarizes prior conversation context.
        - `type` 'compaction'
        - `encrypted_content` string, required
        - `id` string, nullable

## Response `200`

List of created items.

- ConversationItemList — List of conversation items with pagination.
  - `object` 'list' — The type of object returned, must be list.
  - `data` union[], required — List of conversation items
    - union
      - OpenAIResponseMessageOutput — Corresponds to the various Message types in the Responses API. They are all under one type because the Responses API gives them all the same "type" value, and there is no way to tell them apart in certain scenarios.
        - `content` union, required
          - string
          - union[]
            - union
              - …
          - union[]
            - union
              - …
        - `role` union, required
          - 'system'
          - 'developer'
          - 'user'
          - 'assistant'
        - `type` 'message'
        - `id` string, nullable
        - `status` string, nullable
      - OpenAIResponseOutputMessageWebSearchToolCallOutput — Web search tool call output message for OpenAI responses.
        - `id` string, required
        - `status` string, required
        - `type` 'web_search_call'
        - `action` union
          - WebSearchActionSearch — Web search action: performs a search query.
            - `type` 'search'
            - `query` string, required
            - `queries` string[], nullable
            - `sources` WebSearchSource[], nullable
              - …
          - WebSearchActionOpenPage — Web search action: opens a specific URL from search results.
            - `type` 'open_page'
            - `url` string, nullable
          - WebSearchActionFind — Web search action: searches for a pattern within a loaded page.
            - `type` 'find_in_page'
            - `url` string, required
            - `pattern` string, required
      - OpenAIResponseOutputMessageFileSearchToolCall — File search tool call output message for OpenAI responses.
        - `id` string, required
        - `queries` string[], required
        - `status` string, required
        - `type` 'file_search_call'
        - `results` OpenAIResponseOutputMessageFileSearchToolCallResults[], nullable
          - `attributes` object, required
          - `file_id` string, required
          - `filename` string, required
          - `score` number, required
          - `text` string, required
      - OpenAIResponseOutputMessageFunctionToolCall — Function tool call output message for OpenAI responses.
        - `call_id` string, required
        - `name` string, required
        - `arguments` string, required
        - `type` 'function_call'
        - `id` string, nullable
        - `status` string, nullable
      - OpenAIResponseInputFunctionToolCallOutput — This represents the output of a function call that gets passed back to the model.
        - `call_id` string, required
        - `output` union, required
          - string
          - union[]
            - union
              - …
        - `type` 'function_call_output'
        - `id` string, nullable
        - `status` string, nullable
      - OpenAIResponseMCPApprovalRequest — A request for human approval of a tool invocation.
        - `arguments` string, required
        - `id` string, required
        - `name` string, required
        - `server_label` string, required
        - `type` 'mcp_approval_request'
      - OpenAIResponseMCPApprovalResponse — A response to an MCP approval request.
        - `approval_request_id` string, required
        - `approve` boolean, required
        - `type` 'mcp_approval_response'
        - `id` string, nullable
        - `reason` string, nullable
      - OpenAIResponseOutputMessageMCPCall — Model Context Protocol (MCP) call output message for OpenAI responses.
        - `id` string, required
        - `type` 'mcp_call'
        - `arguments` string, required
        - `name` string, required
        - `server_label` string, required
        - `error` string, nullable
        - `output` string, nullable
      - OpenAIResponseOutputMessageMCPListTools — MCP list tools output message containing available tools from an MCP server.
        - `id` string, required
        - `type` 'mcp_list_tools'
        - `server_label` string, required
        - `tools` MCPListToolsTool[], required
          - `input_schema` object, required
          - `name` string, required
          - `description` string, nullable
      - OpenAIResponseOutputMessageReasoningItem — Reasoning output from the model, representing the model's thinking process.
        - `id` string, required — Unique identifier for the reasoning output item.
        - `summary` OpenAIResponseOutputMessageReasoningSummary[], required — Summary of the reasoning output.
          - `text` string, required — The summary text of the reasoning output.
          - `type` 'summary_text' — The type identifier, always 'summary_text'.
        - `type` 'reasoning' — The type identifier, always 'reasoning'.
        - `content` OpenAIResponseOutputMessageReasoningContent[], nullable — The reasoning content from the model.
          - `text` string, required — The reasoning text content from the model.
          - `type` 'reasoning_text' — The type identifier, always 'reasoning_text'.
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the reasoning output.
      - OpenAIResponseCompaction — A compaction item that summarizes prior conversation context.
        - `type` 'compaction'
        - `encrypted_content` string, required
        - `id` string, nullable
  - `first_id` string, nullable, required — The ID of the first item in the list.
  - `last_id` string, nullable, required — The ID of the last item in the list.
  - `has_more` boolean, required — Whether there are more items available.

## Other responses

- `400` — The request was invalid or malformed
- `429` — The client has sent too many requests in a given amount of time
- `500` — The server encountered an unexpected error
- `default` — An error occurred

---

[API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/versions/f3f783962256/schema)