Conversations

POST, GET, and DELETE /v1/conversations. OpenAI-compatible conversation containers that group related items and responses.

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

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

metadataobject

Arbitrary key-value metadata to attach. Optional; an empty body is accepted.

curl

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

Response

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

idstring

The conversation id, conv_....

objectstring

Always "conversation".

created_atinteger

Unix timestamp (seconds).

metadataobject

The metadata you supplied, echoed back.

Retrieve a conversation

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

conversation_idstringpathrequired

The conv_... id.

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

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

Delete a conversation

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

{ "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 surface is the richer tool. Conversations stay a thin OpenAI-compatible container.

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.