Conversations

A conversation is a first-class, listable handle on a thread of runs: create one, drive turns inside it, and read its transcript back — so an in-app chat tab gets a history list, titles, and delete without storing any of that yourself. It maps onto the OpenAI Conversations API, so the openai client library talks to it unchanged.

A conversation is independent of memory. Memory is durable facts a smith carries across every conversation; a conversation is one thread of turns. A conversation works whether or not the smith has any memory, and deleting one never touches memory.

The object

{
  "id": "cnv_7Yh…",
  "object": "conversation",
  "created_at": 1718900000,
  "updated_at": 1718900042,
  "title": "What did I spend on travel in May?",
  "smith_id": "smt_3xK…",
  "metadata": {}
}

created_at / updated_at are unix seconds (every OpenAI object is). title, smith_id, and updated_at are Ingram Cloud extensions — OpenAI's object has no title and no list endpoint, both of which a console history list needs. title is null until the first turn, then auto-set from the first user message; set it yourself any time.

A conversation belongs to one smith. A smith token acts on its own conversations; a tenant-admin token names the smith with an IC-Smith-Id header.

Create one

# Authorization: smith token (browser-safe, scoped to one smith)
curl https://api.cloud.ingram.tech/v1/conversations \
  -H "Authorization: Bearer $IC_SMITH_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Travel spend" }'

title and metadata are both optional — POST /v1/conversations with an empty body mints an untitled conversation you can run in straight away.

Run inside it

Pass the cnv_ id as conversation on the Responses API. You send only the new input; Ingram Cloud replays the conversation's prior turns for the model, stamps the run onto the conversation, and auto-titles it from the first user turn.

# Authorization: smith token (browser-safe, scoped to one smith)
curl https://api.cloud.ingram.tech/v1/responses \
  -H "Authorization: Bearer $IC_SMITH_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "", "conversation": "cnv_7Yh…",
        "input": "What did I spend on travel in May?" }'

Read the transcript

GET /v1/conversations/{cnvId}/items returns the conversation's messages, reconstructed from its runs, in OpenAI's list envelope — oldest first, or ?order=desc for newest first.

{
  "object": "list",
  "data": [
    { "id": "run_9…​.i0", "type": "message", "role": "user",
      "status": "completed",
      "content": [{ "type": "input_text", "text": "What did I spend on travel in May?" }] },
    { "id": "run_9…​.o", "type": "message", "role": "assistant",
      "status": "completed",
      "content": [{ "type": "output_text", "text": "€412 across 3 trips." }] }
  ],
  "first_id": "run_9…​.i0",
  "last_id": "run_9…​.o",
  "has_more": false
}

Items are read-only — they accrue from the runs you drive over the Responses API; there is no write-item endpoint. Item ids are opaque and stable.

List, rename, delete

# List — newest first, paginated like every list (limit + cursor → data/next_cursor/has_more)
curl "https://api.cloud.ingram.tech/v1/conversations?limit=20" \
  -H "Authorization: Bearer $IC_SMITH_TOKEN" -H "IC-Api-Version: 2026-05-01"

# Rename (or merge metadata)
curl https://api.cloud.ingram.tech/v1/conversations/cnv_7Yh… \
  -H "Authorization: Bearer $IC_SMITH_TOKEN" -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" -d '{ "title": "May travel" }'

# Delete — removes the handle; the underlying runs are untouched
curl -X DELETE https://api.cloud.ingram.tech/v1/conversations/cnv_7Yh… \
  -H "Authorization: Bearer $IC_SMITH_TOKEN" -H "IC-Api-Version: 2026-05-01"

Delete returns the OpenAI { "id": …, "object": "conversation.deleted", "deleted": true } acknowledgement.

Scopes

conversations:read for GET; conversations:write for create, update, and delete. A smith token carries the scopes minted into it; see Auth & tokens.