Conversations API

The Conversations API stores persistent threads and their items. Responses can read and append to a conversation, while AgentInterface uses the same API to list threads and reload messages.

Base URL: https://api.thesys.dev/v1

Use the conversationClient from the API overview, which covers authentication and the shared OpenAI SDK clients.

Create a conversation

Create the conversation before the first stored response:

const conversation = await conversationClient.conversations.create({
  metadata: { workspace: "acme" },
});

Then send only the new turn to Responses and set store: true:

import { generateSystemPrompt } from "@openuidev/thesys-server";

const response = await embedClient.responses.create({
  model: "openai/gpt-5",
  conversation: conversation.id,
  input: "Compare quarterly revenue by region.",
  instructions: generateSystemPrompt(),
  store: true,
  stream: true,
});

Every later response with the same conversation ID can use the stored context without resending the full history.

Read conversation items

List the messages, tool calls, and tool outputs stored in a conversation:

const page = await conversationClient.conversations.items.list(conversation.id, {
  order: "asc",
  limit: 100,
});

for (const item of page.data) {
  console.log(item.type, item.id);
}

The OpenAI SDK also exposes retrieve, update, and delete for conversations, and create, retrieve, list, and delete operations for conversation items.

Endpoint summary

Server-side requests authenticate with the API key described in the API overview.

Connect Agent Interface

In the browser, use useOpenuiCloudStorage() instead of calling the raw endpoints. It lists conversations, loads their items, and persists artifact state for AgentInterface.

import { AgentInterface } from "@openuidev/react-ui";
import { useOpenuiCloudStorage } from "@openuidev/thesys";

export function Chat() {
  const storage = useOpenuiCloudStorage({
    token: "/api/frontend-token",
    apiBaseUrl: "https://api.thesys.dev",
    features: { artifact: true },
  });

  return <AgentInterface llm={llm} storage={storage} />;
}

The /api/frontend-token server route mints a short-lived token with POST /v1/frontend-tokens, binding it to your authenticated user_id and optional app_id. The browser sends that token as x-thesys-frontend-token; the server API key never leaves your backend.

Use the current frontend-token route and Cloud storage setup as complete references.