API Overview
Choose an OpenUI Cloud API and configure the shared authentication, clients, models, and persistence behavior.
OpenUI Cloud exposes four related API surfaces. Choose the generation shape and state model that fit your application, then use the focused API guide for implementation details.
Choose an API
| API | Endpoint | Use it for |
|---|---|---|
| Responses | POST /v1/embed/responses | New agent applications, hosted tools, persistent conversations, and artifacts inside the agent stream. |
| Chat Completions (Embed) | POST /v1/embed/chat/completions | Existing Chat Completions applications, plain text, managed or self-hosted generative UI, and app-run function tools. |
| Chat Completions (Artifacts) | POST /v1/artifact/chat/completions | Standalone slide or report generation and explicit program-based edits. |
| Conversations | /v1/conversations | Persistent Responses threads, items, and the storage plane used by AgentInterface. |
Responses is the recommended starting point for new agent applications. The two Chat Completions endpoints let existing integrations keep their message format, while Conversations provides persistent state for Responses.
Authenticate
Create an API key in the Thesys console and configure THESYS_API_KEY on your server. Server-side requests use:
Authorization: Bearer $THESYS_API_KEYNever expose this key to browser code. Browser access to conversations and artifacts uses a scoped, short-lived frontend token instead; see the Conversations API.
Configure the clients
The generation endpoints and core Conversations operations are compatible with the stock OpenAI SDK. Use a client for each base URL your application needs:
import OpenAI from "openai";
const common = { apiKey: process.env.THESYS_API_KEY };
export const embedClient = new OpenAI({
...common,
baseURL: "https://api.thesys.dev/v1/embed",
});
export const artifactClient = new OpenAI({
...common,
baseURL: "https://api.thesys.dev/v1/artifact",
});
export const conversationClient = new OpenAI({
...common,
baseURL: "https://api.thesys.dev/v1",
});The Embed and Artifact generation endpoints support streaming and non-streaming requests.
Choose a state model
| Flow | Where history lives |
|---|---|
Responses with conversation and store: true | OpenUI Cloud stores the persistent conversation and response items. |
Responses with previous_response_id | OpenUI Cloud chains stored responses without a named conversation. |
Responses with full input history | Your application stores and resends history. |
| Embed Chat Completions | Your application stores and resends the messages array. |
| Artifact Chat Completions | Each edit request includes the current artifact program explicitly. |
Shared configuration
- Use
{provider}/{model}model IDs across generation endpoints. See Models and BYOK for supported models and provider credentials. - Use the built-in chat library or provide your own components. See Component Library.
- Keep generation behind a server route and match the browser adapter to the selected response protocol. See Adapters and message formats.
- For the relationship between generation, storage, and rendering, see How it works.