Create a conversation

Create a conversation to store and retrieve conversation state across Response API calls.

POST /api/v1/llm/conversations

Python (SDK)

Python

from mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.llm.conversations.create(metadata={
        "session_id": "sess_abc123",
        "user_type": "premium",
    })

    # Handle response
    print(res)

200

{
  "id": "conv_abc123",
  "object": "conversation",
  "created_at": 1704067200,
  "metadata": {
    "session_id": "sess_abc123",
    "user_type": "premium"
  }
}

Authorizations

Authorization · string · header · required

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Headers

X-On-Behalf-Of · string

Optional external end-user identifier forwarded by the API gateway.

Body

application/json

items · (Input message item · object | Output message item · object | Output audio item · object | File search call item · object | Computer call item · object | Computer call output item · object | Web search call item · object | Function call item · object | Function call output item · object | Reasoning item · object | Image generation call item · object | Code interpreter call item · object | Local shell call item · object | Local shell call output item · object | Shell call item · object | Shell call output item · object | MCP list tools item · object | MCP approval request item · object | MCP approval response item · object | MCP call item · object | Custom tool call item · object | Custom tool call output item · object | Item reference item · object | Compaction item · object)[]

Initial items to include in the conversation context. Max 20 items at a time.

Maximum array length: 20

Input message item: A message with role and content. Use this for user, assistant, system, or developer turns in structured inputs.

Input message item

Output message item

Output audio item

File search call item

Computer call item

Computer call output item

Web search call item

Function call item

Function call output item

Reasoning item

Image generation call item

Code interpreter call item

Local shell call item

Local shell call output item

Shell call item

Shell call output item

MCP list tools item

MCP approval request item

MCP approval response item

MCP call item

Custom tool call item

Custom tool call output item

Item reference item

Compaction item

Show child attributes

metadata · object

Show child attributes

Response

200 - application/json

OK

id · string · required

The unique ID of the conversation

object · any · required

The object type, always 'conversation'

created_at · number · required

Unix timestamp of when the conversation was created

metadata · object

Show child attributes

identity · string

Identity of the conversation owner. Either a SHA256 hash or raw userId:externalUserId depending on IDENTITY_MODE.