Create a conversation¶

Create a local conversation with metadata and optional item summaries.

POST https://token.moi.matrixorigin.cn/v1/conversations

Before you begin¶

Prepare a personal access token with Genesis access.

Request body¶

Set $GENESIS_ACCESS_TOKEN to your personal access token.

Request example

curl -X POST "https://token.moi.matrixorigin.cn/v1/conversations" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "purpose": "support"
  },
  "items": [
    {
      "type": "message",
      "role": "user"
    }
  ]
}'

Parameters

Local items retain summaries such as type, role, and status. Store message bodies in your application.

Parameter	Type	Required	Description
`metadata`	object	No	Custom conversation metadata.
`metadata.<key>`	any	No	Caller-defined keys and values, such as `purpose`.
`items`	array of object	No	Item summaries to add when creating the conversation.
`items[].type`	string	No	Item type, such as `message`.
`items[].role`	string	No	Item role, such as `user`.
`items[].status`	string	No	Item status; defaults to `active` when omitted.

Successful response¶

A successful request returns the new conversation and its metadata.

Response example

{
  "id": "$CONVERSATION_ID",
  "object": "conversation",
  "metadata": {
    "purpose": "support"
  },
  "status": "active",
  "created_at": 1780000000,
  "updated_at": 1780000000
}

Fields

Field	Type	Description
`id`	string	Conversation identifier for retrieval, updates, and deletion.
`object`	string	Always `conversation`.
`metadata`	object	Custom conversation metadata.
`metadata.<key>`	any	Caller-defined keys and values, such as `purpose`.
`status`	string	Conversation status; `active` after creation.
`created_at`	integer	Creation time as a Unix timestamp in seconds.
`updated_at`	integer	Last update time as a Unix timestamp in seconds.

Error response¶

HTTP 400 is returned when the request body is not a JSON object. Send an object before retrying.

Response example

{
  "error": {
    "message": "request body must be a JSON object",
    "type": "invalid_request",
    "code": "invalid_request"
  }
}

Fields

Field	Type	Description
`error`	object	Error details.
`error.message`	string	Error description.
`error.type`	string	Error type.
`error.code`	string	Error code.

Next steps¶

Keep the returned id to Retrieve a conversation or Create a conversation item.

Last updated on Sep 15, 2026