# Conversations (/api-v1/conversations)



A conversation is a lightweight container that groups related items and responses. Zumik mirrors OpenAI's conversation shape exactly: `id`, `object`, `created_at`, and `metadata`. Retrieval returns precisely what you created.

## Create a conversation [#create-a-conversation]

```
POST https://api.zumik.ai/v1/conversations
```

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata to attach. Optional; an empty body is accepted.
</ParamField>

<CodeGroup>
  ```bash title="curl"
  curl https://api.zumik.ai/v1/conversations \
    -H "Authorization: Bearer zk_live_..." \
    -H "Content-Type: application/json" \
    -d '{"metadata":{"topic":"patch-review"}}'
  ```

  ```python title="Zumik SDK"
  from zumik import Zumik

  zk = Zumik(api_key="zk_live_...")
  conv = zk.conversations.create(metadata={"topic": "patch-review"})
  print(conv.id)
  ```
</CodeGroup>

### Response [#response]

```json
{
  "id": "conv_01jy7n3q8v6m4k2x...",
  "object": "conversation",
  "created_at": 1750000123,
  "metadata": { "topic": "patch-review" }
}
```

<ResponseField name="id" type="string">
  The conversation id, `conv_...`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"conversation"`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp (seconds).
</ResponseField>

<ResponseField name="metadata" type="object">
  The metadata you supplied, echoed back.
</ResponseField>

## Retrieve a conversation [#retrieve-a-conversation]

```
GET https://api.zumik.ai/v1/conversations/{conversation_id}
```

<ParamField path="conversation_id" type="string">
  The `conv_...` id.
</ParamField>

Returns the stored conversation object. `404` if it does not exist for this project.

```bash
curl https://api.zumik.ai/v1/conversations/conv_01jy... \
  -H "Authorization: Bearer zk_live_..."
```

## Delete a conversation [#delete-a-conversation]

```
DELETE https://api.zumik.ai/v1/conversations/{conversation_id}
```

```json
{ "id": "conv_01jy...", "object": "conversation.deleted", "deleted": true }
```

`404` if the conversation does not exist for this project.

<Tip>
  For multi-turn agent state with append-only history and optimistic concurrency, the native [sessions](/api-v2/sessions) surface is the richer tool. Conversations stay a thin OpenAI-compatible container.
</Tip>

## Errors [#errors]

| HTTP | `code`            | When                                                 |
| ---- | ----------------- | ---------------------------------------------------- |
| 401  | `invalid_api_key` | Missing or invalid bearer key.                       |
| 404  | (none)            | The conversation id does not exist for this project. |

See the full [error reference](/api-reference/errors).