---
title: "Create a conversation."
method: POST
path: "/v1/conversations"
tags: ["Conversations"]
---

# Create a conversation.

`POST /v1/conversations`

Create a conversation.

## Request body

- CreateConversationRequest — Request model for creating a conversation.
  - `items` union[], nullable — Initial items to include in the conversation context.
    - 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
  - `metadata` object, nullable — Set of key-value pairs that can be attached to an object.

## Response `200`

The created conversation object.

- Conversation — OpenAI-compatible conversation object.
  - `id` string, required — The unique ID of the conversation.
  - `object` 'conversation' — The object type, which is always conversation.
  - `created_at` integer, required — The time at which the conversation was created, measured in seconds since the Unix epoch.
  - `metadata` object, nullable — 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.

## 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)