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.

CLI

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

If your request is not tied to a specific end user, omit X-On-Behalf-Of. See the authentication guide for the full pattern.

Add items to the conversation

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

CLI

mka1 llm conversations create-items \
  --conversation-id conv_abc123 \
  --body '{
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": "Summarize the latest support ticket."
      }
    ]
  }'

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.

CLI

mka1 llm responses create \
  --model auto \
  --conversation conv_abc123 \
  --input '"Turn that summary into a customer-ready reply."'

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.