Create a conversation item¶

Add an item summary containing a type, role, and status to a local conversation.

POST https://token.moi.matrixorigin.cn/v1/conversations/{conversation_id}/items

Before you begin¶

Prepare a personal access token with Genesis access.
Use the credential used to Create a conversation, and choose a local conversation that has not been deleted or bound to an upstream model.

Request example¶

Replace $GENESIS_ACCESS_TOKEN and $CONVERSATION_ID with your personal access token and the selected conversation ID.

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

Path parameters¶

Parameter	Type	Required	Description
`conversation_id`	string	Yes	The `id` returned when creating the conversation.

Request body¶

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

Parameter	Type	Required	Description
`type`	string	No	Item type, such as `message`.
`role`	string	No	Item role, such as `user`.
`status`	string	No	Item status; defaults to `active` when omitted.

Successful response¶

A successful request returns the newly created item summary.

Response example

{
  "id": "$ITEM_ID",
  "object": "conversation.item",
  "conversation_id": "$CONVERSATION_ID",
  "type": "message",
  "role": "user",
  "status": "active",
  "created_at": 1780000000
}

Fields

Field	Type	Description
`id`	string	Item identifier.
`object`	string	Always `conversation.item`.
`conversation_id`	string	Identifier of the conversation containing this item.
`type`	string	Item type, such as `message`.
`role`	string	Item role, such as `user`.
`status`	string	Item status; defaults to `active` when omitted.
`created_at`	integer	Creation time as a Unix timestamp in seconds.

Error response¶

The request returns 404 when the resource is missing, deleted, or inaccessible to the current credential.

Response example

{
  "error": {
    "message": "conversation not found",
    "type": "conversation_not_found",
    "code": "conversation_not_found"
  }
}

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 item or Delete a conversation item.

Last updated on Sep 15, 2026