# Create a conversation

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Create a local conversation with metadata and optional item summaries.

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

## Before you begin

Prepare a [personal access token](../../../../guides/billing/credentials.md#personal-access-token) with Genesis access.

## Request body

Set `$GENESIS_ACCESS_TOKEN` to your personal access token.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
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"
    }
  ]
}'
```

:::::
:::::{tab-item} Parameters

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

::::{div} mo-api-parameter-table

| 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.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} 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.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} 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](get-conversation.md) or [Create a conversation item](create-item.md).