> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage conversations

> Store conversation state in the MKA1 API, add message items, and continue a response flow without resending the full history.

Use the Conversations resource when you want the MKA1 API to keep conversation state between Responses requests.
This is useful for multi-turn chats, support threads, and workflows where you want to fetch or edit the saved history later.

## Create a conversation

Create a conversation first.
You can attach metadata to keep your own session or routing context.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm conversations create \
    -H 'X-On-Behalf-Of: <end-user-id>' \
    --body '{
      "metadata": {
        "session_id": "web-42",
        "channel": "support"
      }
    }'
  ```

  ```ts MKA1 SDK theme={null}
  import { SDK } from '@meetkai/mka1';

  const mka1 = new SDK({
    bearerAuth: `Bearer ${YOUR_API_KEY}`,
  });

  const conv = await mka1.llm.conversations.create({
    xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
    createConversationRequest: {
      metadata: {
        session_id: 'web-42',
        channel: 'support',
      },
    },
  });
  ```

  ```ts OpenAI SDK theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    apiKey: '<mka1-api-key>',
    baseURL: 'https://apigw.mka1.com/api/v1/llm/',
    defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
  });

  const conv = await openai.conversations.create({
    metadata: {
      session_id: 'web-42',
      channel: 'support',
    },
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var conv = await sdk.Llm.Conversations.CreateAsync(new CreateConversationRequest()
  {
      Metadata = new Dictionary<string, string> { { "session_id", "web-42" } },
  });
  ```

  ```python Python SDK theme={null}
  from mka1 import SDK

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  conv = sdk.llm.conversations.create(
      metadata={"session_id": "web-42"},
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/conversations \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "metadata": {
        "session_id": "web-42",
        "channel": "support"
      }
    }'
  ```
</CodeGroup>

If your request is not tied to a specific end user, omit `X-On-Behalf-Of`.
See the [authentication guide](/docs/authentication) for the full pattern.

## Add items to the conversation

Add one or more items with `POST /api/v1/llm/conversations/{conversation_id}/items`.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm conversations create-items \
    --conversation-id conv_abc123 \
    --body '{
      "items": [
        {
          "type": "message",
          "role": "user",
          "content": "Summarize the latest support ticket."
        }
      ]
    }'
  ```

  ```ts MKA1 SDK theme={null}
  const items = await mka1.llm.conversations.createItems({
    conversationId: 'conv_abc123',
    xOnBehalfOf: '<end-user-id>',
    createItemsRequest: {
      items: [
        {
          type: 'message',
          role: 'user',
          content: 'Summarize the latest support ticket.',
        },
      ],
    },
  });
  ```

  ```ts OpenAI SDK theme={null}
  const items = await openai.conversations.items.create('conv_abc123', {
    items: [
      {
        type: 'message',
        role: 'user',
        content: 'Summarize the latest support ticket.',
      },
    ],
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var items = await sdk.Llm.Conversations.CreateItemsAsync("conv_abc123", new CreateItemsRequest()
  {
      Items = new List<Item>
      {
          Item.CreateInputMessage(new InputMessage()
          {
              Role = InputMessageRole.User,
              Content = InputMessageContent1.CreateStr("Summarize the latest support ticket."),
          }),
      },
  });
  ```

  ```python Python SDK theme={null}
  sdk.llm.conversations.create_items(
      conversation_id="conv_abc123",
      items=[
          {"type": "message", "role": "user", "content": "Summarize the latest support ticket."},
      ],
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/conversations/conv_abc123/items \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "items": [
        {
          "type": "message",
          "role": "user",
          "content": "Summarize the latest support ticket."
        }
      ]
    }'
  ```
</CodeGroup>

Use this endpoint when you want to write the history explicitly before you call the Responses resource.

## Continue the flow with the Responses resource

Pass the conversation ID in your next Responses request.
This lets the MKA1 API use the saved conversation state.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm responses create \
    --model auto \
    --conversation conv_abc123 \
    --input '"Turn that summary into a customer-ready reply."'
  ```

  ```ts MKA1 SDK theme={null}
  const result = await mka1.llm.responses.create({
    responsesCreateRequest: {
      model: 'auto',
      conversation: 'conv_abc123',
      input: 'Turn that summary into a customer-ready reply.',
    },
  });
  ```

  ```ts OpenAI SDK theme={null}
  const response = await openai.responses.create({
    model: 'auto',
    conversation: 'conv_abc123',
    input: 'Turn that summary into a customer-ready reply.',
    stream: false,
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var conv = await sdk.Llm.Conversations.CreateAsync(new CreateConversationRequest()
  {
      Metadata = new Dictionary<string, string> { { "session_id", "csharp-test" } },
  });

  var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "auto",
      Conversation = ResponsesCreateRequestConversation.CreateStr(conv.ConversationObject!.Id),
      Input = ResponsesCreateRequestInput.CreateStr("Turn that summary into a customer-ready reply."),
  });
  ```

  ```python Python SDK theme={null}
  res = sdk.llm.responses.create(
      model="auto",
      conversation="conv_abc123",
      input="Turn that summary into a customer-ready reply.",
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "model": "auto",
      "conversation": "conv_abc123",
      "input": "Turn that summary into a customer-ready reply."
    }'
  ```
</CodeGroup>

You can also keep adding items to the same conversation as the exchange grows.

## Read, update, or clean up a conversation

Use the Conversations endpoints to:

* List conversations for the current account or end user (`GET /api/v1/llm/conversations`).
* Filter lists with `after`, `limit`, `order`, `metadata`, and `search`.
* Fetch one conversation by ID (`GET /api/v1/llm/conversations/{conversation_id}`).
* Update conversation metadata (`POST /api/v1/llm/conversations/{conversation_id}`).
* List items in a conversation (`GET /api/v1/llm/conversations/{conversation_id}/items`).
* Fetch a single item (`GET /api/v1/llm/conversations/{conversation_id}/items/{item_id}`).
* Delete items (single or many) via:
  * `DELETE /api/v1/llm/conversations/{conversation_id}/items/{item_id}`
  * `DELETE /api/v1/llm/conversations/{conversation_id}/items` with `{ "item_ids": ["item_..."] }`
* Delete the conversation (`DELETE /api/v1/llm/conversations/{conversation_id}`).

Note: deleting a conversation does **not** delete its items.

Use the API Reference tab for the exact request and response shapes for each operation.

## When to use conversations vs `previous_response_id`

Use a conversation when:

* You want a reusable container for many turns.
* You need to list or manage saved items later.
* You want to attach metadata to the ongoing thread.

Use `previous_response_id` when:

* You only need to continue from one earlier response.
* You do not need a separate stored conversation resource.

For the response-side pattern, see [generate a response](/docs/generate-a-response).