From dddcd542585fef803c4dcef5a0a8826b169ce5b6 Mon Sep 17 00:00:00 2001 From: Visharad Kashyap <154831195+vishxrad@users.noreply.github.com> Date: Thu, 13 Aug 2026 16:50:31 +0530 Subject: [PATCH 1/4] docs: document OpenUI Cloud APIs --- .../openui-cloud/api/chat-completions.mdx | 214 ++++++++++++++++++ .../docs/openui-cloud/api/responses.mdx | 157 +++++++++++++ .../content/docs/openui-cloud/get-started.mdx | 1 + .../docs/openui-cloud/how-it-works.mdx | 42 +++- docs/content/docs/openui-cloud/index.mdx | 13 ++ docs/content/docs/openui-cloud/meta.json | 3 + 6 files changed, 421 insertions(+), 9 deletions(-) create mode 100644 docs/content/docs/openui-cloud/api/chat-completions.mdx create mode 100644 docs/content/docs/openui-cloud/api/responses.mdx diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdx new file mode 100644 index 000000000..216412749 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/chat-completions.mdx @@ -0,0 +1,214 @@ +--- +title: Chat Completions API +description: "Use the OpenAI-compatible Chat Completions and artifact endpoints for text, OpenUI Lang, tools, slides, and reports." +--- + +The Chat Completions API is a drop-in OpenAI-compatible endpoint for applications that already use `chat.completions.create()`. It supports plain text, self-hosted generative UI, and managed generative UI without changing the application's message format. + +**Endpoint:** `POST https://api.thesys.dev/v1/embed/chat/completions` + +Use the [Responses API](/docs/openui-cloud/api/responses) instead when you need Cloud-managed conversations, hosted search or MCP tools, or artifacts inside the same agent stream. + +## Configure the client + +Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and change the OpenAI client configuration: + +```diff + const client = new OpenAI({ +- apiKey: process.env.OPENAI_API_KEY, ++ apiKey: process.env.THESYS_API_KEY, ++ baseURL: "https://api.thesys.dev/v1/embed", + }); +``` + +Both streaming and non-streaming requests are supported. + +## Plain text passthrough + +Use a `{provider}/{model}` model ID. OpenUI Cloud forwards the messages, including your system prompt, without injecting a generative UI prompt or component schema. + +```ts +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "system", content: "You are a concise product analyst." }, + { role: "user", content: "Summarize the risks in this launch plan." }, + ], +}); + +console.log(completion.choices[0].message.content); +``` + +OpenAI, Anthropic, and Google model IDs route to those providers. Unknown providers route through OpenRouter. + +## Generate UI with your component library + +Compile the system prompt in your application from a generated OpenUI library spec. The endpoint forwards that prompt verbatim; the model returns OpenUI Lang for your client-side `Renderer`. + +```ts +import { generateSystemPrompt } from "@openuidev/lang-core"; +import library from "./generated/library.spec.json"; + +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + library, + promptOptions, + }), + }, + ...messages, + ], + stream: true, +}); +``` + +Create `library.spec.json` with `openui generate --spec`, and render the streamed content with the same library. In this mode, prompt assembly and rendering are owned by your application. + +## Use managed generative UI + +Use the server helper to send the OpenUI Cloud configuration sentinel. OpenUI Cloud assembles the prompt and can use either its built-in component library or the custom library you send. + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [{ role: "system", content: generateSystemPrompt() }, ...messages], + stream: true, +}); +``` + +For a custom library: + +```ts +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + library, + promptOptions: { + additionalRules: ["Prefer compact layouts and concise labels."], + }, + }), + }, + ...messages, + ], + stream: true, +}); +``` + + + Managed generative UI requires a bare provider model such as `openai/gpt-5`. Do not combine the + `generateSystemPrompt()` sentinel with a versioned `c1/...` model; that request returns a 400. + + +## Manage conversation history + +Chat Completions requests are message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn. + +Use the [Responses API](/docs/openui-cloud/api/responses#manage-conversation-state) if you want to reference `previous_response_id` or a persistent Cloud conversation instead. + +## Use function tools + +Chat Completions accepts `function` tools only. The endpoint does not execute them. Run the standard loop in your application: + +1. Send the messages and function declarations. +2. Read `tool_calls` from the assistant message. +3. Execute each function in your application. +4. Append the assistant tool-call message and each `role: "tool"` result. +5. Repeat until the model returns a final response. + +Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#add-tools-and-artifacts), not Chat Completions. + +## Generate slides and reports + +Artifacts have a separate Chat Completions-compatible endpoint: + +**Endpoint:** `POST https://api.thesys.dev/v1/artifact/chat/completions` + +Point another OpenAI client at the artifact base URL. Every request must include `metadata.thesys` as a JSON string with your artifact `id` and a `c1_artifact_type` of `"slides"` or `"report"`. + +```ts +import OpenAI from "openai"; + +const artifactClient = new OpenAI({ + apiKey: process.env.THESYS_API_KEY, + baseURL: "https://api.thesys.dev/v1/artifact", +}); + +const artifact = await artifactClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [{ role: "user", content: "Create a three-slide deck on Q4 results." }], + metadata: { + thesys: JSON.stringify({ + id: "art_1", + c1_artifact_type: "slides", + }), + }, +}); + +const program = artifact.choices[0].message.content; +``` + +Provider models use the same native routing and BYOK behavior as the embed endpoint. The response content is a raw OpenUI Lang program rooted at `SlideShow` or `ReportView`. It is validated and repaired before being returned. Set `stream: true` to receive it progressively. + +### Render an artifact + +Render the returned program with the matching managed viewer: + +```tsx +import { Presentation, Report } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; + +export function Artifact({ kind, program }: { kind: "slides" | "report"; program: string }) { + return kind === "slides" ? ( + + ) : ( + + ); +} +``` + +Pass `isStreaming` while accumulating a streamed program. + +### Edit an artifact + +Send the current OpenUI Lang program as an assistant message, describe the change in the next user message, and set `is_edit: true`. + +```ts +const edited = await artifactClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "assistant", content: previousProgram }, + { role: "user", content: "Make slide 2 about European revenue." }, + ], + metadata: { + thesys: JSON.stringify({ + id: "art_1", + c1_artifact_type: "slides", + is_edit: true, + }), + }, + stream: true, +}); +``` + +The response is a patch-mode OpenUI Lang program merged against the assistant-message base. + +## Bring your own provider key + +For OpenUI Cloud, add the provider key on the [BYOK page in the Thesys console](https://console.thesys.dev/byok). When the model's provider matches, the configured key is selected automatically and nothing changes in the request. + +For a self-hosted key flow, encrypt the key with `POST /encryption/encrypt`, then include this object in the request body: + +```ts +byok: { + provider, + encryptedApiKey, +} +``` diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdx new file mode 100644 index 000000000..ed3fa7027 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/responses.mdx @@ -0,0 +1,157 @@ +--- +title: Responses API +description: "Use the OpenAI-compatible Responses API for managed generative UI, persistent conversations, hosted tools, and artifacts." +--- + +The Responses API is the recommended OpenUI Cloud endpoint for new agent applications. It combines managed generative UI with persistent conversations, hosted tools, and editable slide and report artifacts. + +**Endpoint:** `POST https://api.thesys.dev/v1/embed/responses` + +It uses the stock OpenAI SDK. Keep the Thesys API key and the request on your server. + +## Make a request + +Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and point the OpenAI client at the OpenUI Cloud base URL. + +```ts title="server.ts" +import { generateSystemPrompt } from "@openuidev/thesys-server"; +import OpenAI from "openai"; + +const client = new OpenAI({ + apiKey: process.env.THESYS_API_KEY, + baseURL: "https://api.thesys.dev/v1/embed", +}); + +const response = await client.responses.create({ + model: "openai/gpt-5", + input: "Compare quarterly revenue by region.", + instructions: generateSystemPrompt(), +}); + +console.log(response.output_text); +``` + +`generateSystemPrompt()` tells OpenUI Cloud to assemble the managed system prompt for its built-in component library. The returned `output_text` is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. + +For progressive rendering, set `stream: true`. The OpenUI Cloud scaffold already relays this event stream to `AgentInterface` with `openAIResponsesAdapter()`. + + + The fastest complete integration is `npx @openuidev/cli@latest create --template openui-cloud`. + See [Get Started](/docs/openui-cloud/get-started) for the generated application structure. + + +## Use a custom component library + +Generate a serializable library spec at build time: + +```bash +npx @openuidev/cli@latest generate --spec ./src/library.tsx --out ./src/generated/library.spec.json +``` + +Send the spec through the server helper. OpenUI Cloud uses it to assemble the prompt and validate the streamed output against your components. + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; +import library from "./generated/library.spec.json"; + +const response = await client.responses.create({ + model: "openai/gpt-5", + input: "Show revenue by region as an interactive dashboard.", + instructions: generateSystemPrompt({ + library, + promptOptions: { + additionalRules: ["Prefer compact layouts and concise labels."], + }, + }), + stream: true, +}); +``` + +## Manage conversation state + +The Responses API supports three history patterns: + +| Pattern | Use it when | +| -------------------------------- | --------------------------------------------------------------------------------------- | +| Send the full history in `input` | Your application owns all message storage. | +| Set `previous_response_id` | You want to chain turns without creating a named conversation. Use `store: true`. | +| Set `conversation` | You want a persistent thread that can be loaded by `AgentInterface`. Use `store: true`. | + +Chain a follow-up to an earlier response: + +```ts +const first = await client.responses.create({ + model: "openai/gpt-5", + input: "Compare quarterly revenue by region.", + instructions: generateSystemPrompt(), + store: true, +}); + +const followUp = await client.responses.create({ + model: "openai/gpt-5", + input: "Focus on Europe and explain the change.", + instructions: generateSystemPrompt(), + previous_response_id: first.id, + store: true, +}); +``` + +For a named Cloud conversation, send only the new turn on each request: + +```ts +const response = await client.responses.create({ + model: "openai/gpt-5", + conversation: threadId, + input: latestMessage, + instructions: generateSystemPrompt(), + store: true, + stream: true, +}); +``` + +## Add tools and artifacts + +OpenUI Cloud runs hosted tools inside the platform. App-owned function tools still run on your server. + +| Capability | Tool declaration | Runs on | +| -------------------- | --------------------------------------------------- | ------------ | +| Slides and reports | `artifactTool({ artifacts: ["slides", "report"] })` | OpenUI Cloud | +| Web search | `{ type: "web_search" }` | OpenUI Cloud | +| Image search | `{ type: "image_search" }` | OpenUI Cloud | +| Remote MCP server | `{ type: "mcp", server_label, server_url }` | OpenUI Cloud | +| Application function | `{ type: "function", name, parameters }` | Your server | + +```ts +import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server"; +import type { Tool } from "openai/resources/responses/responses"; + +const response = await client.responses.create({ + model: "openai/gpt-5", + input: "Research the market and create a three-slide summary.", + instructions: generateSystemPrompt(), + tools: [ + artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool, + { type: "web_search" }, + { type: "image_search" } as unknown as Tool, + { + type: "mcp", + server_label: "deepwiki", + server_url: "https://mcp.deepwiki.com/mcp", + } as unknown as Tool, + ], + stream: true, + store: true, +}); +``` + +The casts are needed because artifacts, image search, and MCP are OpenUI Cloud extensions to the stock OpenAI tool union. Artifacts are stored and can be edited automatically on follow-up turns in the same conversation. + +For a `function` tool, execute each returned `function_call` on your server and continue with a `function_call_output`. The Cloud scaffold includes a complete tool loop; see [Tools](/docs/agent/core-concepts/tools) for the execution model. + +## Bring your own provider key + +Add an OpenAI, Anthropic, or Google key on the [BYOK page in the Thesys console](https://console.thesys.dev/byok). When the requested model matches that provider, OpenUI Cloud uses the configured key automatically. The request body does not change. + +## When to use Chat Completions + +Use the [Chat Completions API](/docs/openui-cloud/api/chat-completions) when an existing application already speaks that protocol, when you want a plain model passthrough, or when your application owns its conversation history and function-tool loop. Use Responses for Cloud-managed conversations, hosted search or MCP tools, and artifacts inside the agent stream. diff --git a/docs/content/docs/openui-cloud/get-started.mdx b/docs/content/docs/openui-cloud/get-started.mdx index a3441cf12..0467047f6 100644 --- a/docs/content/docs/openui-cloud/get-started.mdx +++ b/docs/content/docs/openui-cloud/get-started.mdx @@ -61,6 +61,7 @@ Open [http://localhost:3000](http://localhost:3000) and send a message. Ask for ## What the scaffold includes - A working chat interface where responses render as interactive components. +- A server route connected to the [Responses API](/docs/openui-cloud/api/responses). - Slides and reports enabled out of the box. - Conversation history and artifact storage, with no database to set up. - A codebase ready to be shaped into a product. diff --git a/docs/content/docs/openui-cloud/how-it-works.mdx b/docs/content/docs/openui-cloud/how-it-works.mdx index 3da44c83f..ee875eb23 100644 --- a/docs/content/docs/openui-cloud/how-it-works.mdx +++ b/docs/content/docs/openui-cloud/how-it-works.mdx @@ -5,14 +5,15 @@ description: "Learn how OpenUI Cloud handles model access, automatic fallbacks, ## Overview -Generative UI puts model output directly in front of users, and raw model output is not reliable enough for that. OpenUI Cloud sits between the application and the model: generation requests go through it, and what comes back is validated, renderable UI. +Generative UI puts model output directly in front of users, and raw model output is not reliable enough for that. OpenUI Cloud sits between the application and the model. It can act as a compatible model gateway or assemble and validate renderable OpenUI Lang for generative UI. -OpenUI Cloud exposes two API surfaces: +OpenUI Cloud exposes three API surfaces: -- **Responses API:** The generation endpoint is compatible with the OpenAI Responses API, so existing OpenAI SDKs work against it. It accepts a conversation turn and streams validated UI as **OpenUI Lang**, the same open-source format rendered by OpenUI component libraries. Managed model access, automatic fallbacks, output validation, and slide and report generation happen behind this endpoint. +- **Responses API:** The recommended generation endpoint for new agent applications. It accepts a conversation turn and streams validated UI as **OpenUI Lang**, with persistent conversations, hosted tools, and slide and report generation in the same API. +- **Chat Completions API:** A drop-in endpoint for applications that already use the OpenAI Chat Completions message format. It supports plain text passthrough, self-hosted or managed generative UI, application-run function tools, and a dedicated Chat Completions-compatible artifact endpoint. - **Persistence API:** Provides read and write access to stored conversations, slides, and reports. The browser calls it directly using short-lived session tokens. -Both integrate with AgentInterface, OpenUI's chat surface: streaming, generative UI rendering, artifact panels, and thread history connect without additional wiring. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer. +The generation APIs integrate with AgentInterface through their matching stream adapters, while the Persistence API supplies thread history and stored artifacts. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer. Rendering stays in the browser: responses render client-side with the application's component library, exactly as in open-source OpenUI. @@ -24,6 +25,8 @@ flowchart LR end subgraph Cloud[OpenUI Cloud] R[Responses API] + C[Chat Completions API] + AR[Artifact endpoint] PA[Persistence API] M["Model routing and fallbacks"] V["Output validation and correction"] @@ -32,17 +35,24 @@ flowchart LR end A --> B B --> R + B --> C + B --> AR A -->|session token| PA R --> M R --> V R --> G R --> S + C --> M + C -. managed GenUI .-> V + AR --> M + AR --> V + AR --> G PA --> S `} /> -The application consists of product code, AgentInterface, and a backend route that holds the API key. OpenUI Cloud runs model routing, validation, artifact generation, and storage. +The application consists of product code, AgentInterface or a custom UI, and a backend route that holds the API key. OpenUI Cloud runs model routing, managed output validation, artifact generation, and storage. -## Request lifecycle +## Responses request lifecycle +## Choose an API + + + + The recommended API for new agents, with persistent conversations, hosted tools, managed + generative UI, slides, and reports in one stream. + + + A drop-in endpoint for existing OpenAI Chat Completions applications, with plain text, + self-hosted or managed generative UI, function tools, and a dedicated artifact endpoint. + + + ## Generative UI for agents Agents can respond with interfaces that match the task instead of returning only text. They can present a form to collect information, visualize data with a chart, or organize a detailed response with tabs and accordions. diff --git a/docs/content/docs/openui-cloud/meta.json b/docs/content/docs/openui-cloud/meta.json index 6715342fe..c1d55af1b 100644 --- a/docs/content/docs/openui-cloud/meta.json +++ b/docs/content/docs/openui-cloud/meta.json @@ -5,6 +5,9 @@ "index", "get-started", "how-it-works", + "---APIs---", + "api/responses", + "api/chat-completions", "models-and-byok", "---Features---", "build/chat", From 531cf4e880ddfe32e1a85a98fbeec877734dfaa2 Mon Sep 17 00:00:00 2001 From: Visharad Kashyap <154831195+vishxrad@users.noreply.github.com> Date: Thu, 13 Aug 2026 17:53:36 +0530 Subject: [PATCH 2/4] docs: align cloud API guides --- .../openui-cloud/api/chat-completions.mdx | 166 ++++++++++++------ .../docs/openui-cloud/api/responses.mdx | 110 ++++++++++-- 2 files changed, 200 insertions(+), 76 deletions(-) diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdx index 216412749..0f02a3e80 100644 --- a/docs/content/docs/openui-cloud/api/chat-completions.mdx +++ b/docs/content/docs/openui-cloud/api/chat-completions.mdx @@ -7,46 +7,60 @@ The Chat Completions API is a drop-in OpenAI-compatible endpoint for application **Endpoint:** `POST https://api.thesys.dev/v1/embed/chat/completions` -Use the [Responses API](/docs/openui-cloud/api/responses) instead when you need Cloud-managed conversations, hosted search or MCP tools, or artifacts inside the same agent stream. +It uses the stock OpenAI SDK. Keep the Thesys API key and the request on your server. ## Configure the client -Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and change the OpenAI client configuration: +Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and point the OpenAI client at the OpenUI Cloud base URL. -```diff - const client = new OpenAI({ -- apiKey: process.env.OPENAI_API_KEY, -+ apiKey: process.env.THESYS_API_KEY, -+ baseURL: "https://api.thesys.dev/v1/embed", - }); +```ts title="server.ts" +import OpenAI from "openai"; + +const client = new OpenAI({ + apiKey: process.env.THESYS_API_KEY, + baseURL: "https://api.thesys.dev/v1/embed", +}); ``` Both streaming and non-streaming requests are supported. -## Plain text passthrough +## Make a request -Use a `{provider}/{model}` model ID. OpenUI Cloud forwards the messages, including your system prompt, without injecting a generative UI prompt or component schema. +Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library. + +```ts title="server.ts" +import { generateSystemPrompt } from "@openuidev/thesys-server"; -```ts const completion = await client.chat.completions.create({ model: "openai/gpt-5", messages: [ - { role: "system", content: "You are a concise product analyst." }, - { role: "user", content: "Summarize the risks in this launch plan." }, + { role: "system", content: generateSystemPrompt() }, + { role: "user", content: "Compare quarterly revenue by region." }, ], }); console.log(completion.choices[0].message.content); ``` -OpenAI, Anthropic, and Google model IDs route to those providers. Unknown providers route through OpenRouter. +The returned message content is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. -## Generate UI with your component library + + Managed generative UI requires a bare provider model such as `openai/gpt-5`. Do not combine the + `generateSystemPrompt()` sentinel with a versioned `c1/...` model; that request returns a 400. + + +## Use a custom component library + +Generate a serializable library spec at build time: -Compile the system prompt in your application from a generated OpenUI library spec. The endpoint forwards that prompt verbatim; the model returns OpenUI Lang for your client-side `Renderer`. +```bash +npx @openuidev/cli@latest generate --spec ./src/library.tsx --out ./src/generated/library.spec.json +``` + +Send the spec through the server helper. OpenUI Cloud uses it to assemble the prompt and validate the streamed output against your components. ```ts -import { generateSystemPrompt } from "@openuidev/lang-core"; +import { generateSystemPrompt } from "@openuidev/thesys-server"; import library from "./generated/library.spec.json"; const completion = await client.chat.completions.create({ @@ -56,64 +70,50 @@ const completion = await client.chat.completions.create({ role: "system", content: generateSystemPrompt({ library, - promptOptions, + promptOptions: { + additionalRules: ["Prefer compact layouts and concise labels."], + }, }), }, - ...messages, + { role: "user", content: "Show revenue by region as an interactive dashboard." }, ], stream: true, }); ``` -Create `library.spec.json` with `openui generate --spec`, and render the streamed content with the same library. In this mode, prompt assembly and rendering are owned by your application. +Render the response with the same component library used to generate the spec. -## Use managed generative UI +## Stream and render responses -Use the server helper to send the OpenUI Cloud configuration sentinel. OpenUI Cloud assembles the prompt and can use either its built-in component library or the custom library you send. +Set `stream: true` on the server. In the browser, pair the Chat Completions stream adapter with the OpenAI message format: -```ts -import { generateSystemPrompt } from "@openuidev/thesys-server"; +```tsx title="cloud-chat.tsx" +"use client"; -const completion = await client.chat.completions.create({ - model: "openai/gpt-5", - messages: [{ role: "system", content: generateSystemPrompt() }, ...messages], - stream: true, -}); -``` - -For a custom library: +import { AgentInterface, fetchLLM, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui"; +import { chatLibrary } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; -```ts -const completion = await client.chat.completions.create({ - model: "openai/gpt-5", - messages: [ - { - role: "system", - content: generateSystemPrompt({ - library, - promptOptions: { - additionalRules: ["Prefer compact layouts and concise labels."], - }, - }), - }, - ...messages, - ], - stream: true, +const llm = fetchLLM({ + url: "/api/chat", + streamAdapter: openAIAdapter(), + messageFormat: openAIMessageFormat, }); + +export function Chat() { + return ; +} ``` - - Managed generative UI requires a bare provider model such as `openai/gpt-5`. Do not combine the - `generateSystemPrompt()` sentinel with a versioned `c1/...` model; that request returns a 400. - +Use `openAIAdapter()` when your route preserves the raw `data:` SSE response. If it returns the OpenAI SDK stream through `.toReadableStream()` instead, use `openAIReadableStreamAdapter()`. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for the exact pairings. ## Manage conversation history Chat Completions requests are message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn. -Use the [Responses API](/docs/openui-cloud/api/responses#manage-conversation-state) if you want to reference `previous_response_id` or a persistent Cloud conversation instead. +Use the [Responses API](/docs/openui-cloud/api/responses#manage-conversation-history) if you want to reference `previous_response_id` or a persistent Cloud conversation instead. -## Use function tools +## Use tools Chat Completions accepts `function` tools only. The endpoint does not execute them. Run the standard loop in your application: @@ -123,7 +123,7 @@ Chat Completions accepts `function` tools only. The endpoint does not execute th 4. Append the assistant tool-call message and each `role: "tool"` result. 5. Repeat until the model returns a final response. -Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#add-tools-and-artifacts), not Chat Completions. +Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#use-tools), not Chat Completions. ## Generate slides and reports @@ -202,9 +202,9 @@ The response is a patch-mode OpenUI Lang program merged against the assistant-me ## Bring your own provider key -For OpenUI Cloud, add the provider key on the [BYOK page in the Thesys console](https://console.thesys.dev/byok). When the model's provider matches, the configured key is selected automatically and nothing changes in the request. +Follow [Models and BYOK](/docs/openui-cloud/models-and-byok) to add an OpenAI, Anthropic, or Google key in the [Thesys console](https://console.thesys.dev/byok). When the requested model matches that provider, OpenUI Cloud selects the configured key automatically. The request body does not change. -For a self-hosted key flow, encrypt the key with `POST /encryption/encrypt`, then include this object in the request body: +For a request-level self-hosted key flow, encrypt the key with `POST /encryption/encrypt`, then include this object in the request body: ```ts byok: { @@ -212,3 +212,55 @@ byok: { encryptedApiKey, } ``` + +## Use other generation modes + +Managed generative UI is the closest match to the Responses API flow. Chat Completions also supports plain passthrough and application-managed prompt assembly. + +### Plain text passthrough + +Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt()` sentinel. OpenUI Cloud forwards the messages, including your system prompt, without injecting a generative UI prompt or component schema. + +```ts +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "system", content: "You are a concise product analyst." }, + { role: "user", content: "Summarize the risks in this launch plan." }, + ], +}); + +console.log(completion.choices[0].message.content); +``` + +OpenAI, Anthropic, and Google model IDs route to those providers. Unknown providers route through OpenRouter. + +### Self-hosted generative UI + +Compile the complete system prompt in your application from a generated OpenUI library spec. The endpoint forwards that prompt verbatim; the model returns OpenUI Lang for your client-side renderer. + +```ts +import { generateSystemPrompt } from "@openuidev/lang-core"; +import library from "./generated/library.spec.json"; + +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + library, + promptOptions, + }), + }, + ...messages, + ], + stream: true, +}); +``` + +In this mode, prompt assembly, output validation, and rendering are owned by your application. + +## When to use Responses + +Use the [Responses API](/docs/openui-cloud/api/responses) for new OpenUI Cloud applications, Cloud-managed conversations, hosted search or MCP tools, and artifacts inside the agent stream. Use Chat Completions when an existing application already speaks that protocol, when you want plain model passthrough or self-hosted prompt assembly, or when your application owns its conversation history and function-tool loop. diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdx index ed3fa7027..b26bda240 100644 --- a/docs/content/docs/openui-cloud/api/responses.mdx +++ b/docs/content/docs/openui-cloud/api/responses.mdx @@ -9,18 +9,27 @@ The Responses API is the recommended OpenUI Cloud endpoint for new agent applica It uses the stock OpenAI SDK. Keep the Thesys API key and the request on your server. -## Make a request +## Configure the client Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and point the OpenAI client at the OpenUI Cloud base URL. ```ts title="server.ts" -import { generateSystemPrompt } from "@openuidev/thesys-server"; import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.THESYS_API_KEY, baseURL: "https://api.thesys.dev/v1/embed", }); +``` + +Both streaming and non-streaming requests are supported. + +## Make a request + +Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library. + +```ts title="server.ts" +import { generateSystemPrompt } from "@openuidev/thesys-server"; const response = await client.responses.create({ model: "openai/gpt-5", @@ -31,14 +40,7 @@ const response = await client.responses.create({ console.log(response.output_text); ``` -`generateSystemPrompt()` tells OpenUI Cloud to assemble the managed system prompt for its built-in component library. The returned `output_text` is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. - -For progressive rendering, set `stream: true`. The OpenUI Cloud scaffold already relays this event stream to `AgentInterface` with `openAIResponsesAdapter()`. - - - The fastest complete integration is `npx @openuidev/cli@latest create --template openui-cloud`. - See [Get Started](/docs/openui-cloud/get-started) for the generated application structure. - +The returned `output_text` is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. ## Use a custom component library @@ -67,7 +69,38 @@ const response = await client.responses.create({ }); ``` -## Manage conversation state +Render the response with the same component library used to generate the spec. + +## Stream and render responses + +Set `stream: true` on the server. In the browser, pair the Responses stream adapter with the conversation message format: + +```tsx title="cloud-chat.tsx" +"use client"; + +import { + AgentInterface, + fetchLLM, + openAIConversationMessageFormat, + openAIResponsesAdapter, +} from "@openuidev/react-ui"; +import { chatLibrary } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; + +const llm = fetchLLM({ + url: "/api/chat", + streamAdapter: openAIResponsesAdapter(), + messageFormat: openAIConversationMessageFormat, +}); + +export function Chat() { + return ; +} +``` + +Your `/api/chat` route should forward the OpenUI Cloud response stream without changing its event shape. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for lower-level transport details. + +## Manage conversation history The Responses API supports three history patterns: @@ -109,7 +142,7 @@ const response = await client.responses.create({ }); ``` -## Add tools and artifacts +## Use tools OpenUI Cloud runs hosted tools inside the platform. App-owned function tools still run on your server. @@ -122,15 +155,13 @@ OpenUI Cloud runs hosted tools inside the platform. App-owned function tools sti | Application function | `{ type: "function", name, parameters }` | Your server | ```ts -import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server"; import type { Tool } from "openai/resources/responses/responses"; const response = await client.responses.create({ model: "openai/gpt-5", - input: "Research the market and create a three-slide summary.", + input: "Research the market and summarize the most important changes.", instructions: generateSystemPrompt(), tools: [ - artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool, { type: "web_search" }, { type: "image_search" } as unknown as Tool, { @@ -144,14 +175,55 @@ const response = await client.responses.create({ }); ``` -The casts are needed because artifacts, image search, and MCP are OpenUI Cloud extensions to the stock OpenAI tool union. Artifacts are stored and can be edited automatically on follow-up turns in the same conversation. +The casts are needed because image search and MCP are OpenUI Cloud extensions to the stock OpenAI tool union. + +For a `function` tool, execute each returned `function_call` on your server and continue with a `function_call_output`. The OpenUI Cloud scaffold includes a complete tool loop; see [Tools](/docs/agent/core-concepts/tools) for the execution model. + +## Generate slides and reports + +Add `artifactTool()` to generate editable slides or reports inside the agent stream: + +```ts +import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server"; +import type { Tool } from "openai/resources/responses/responses"; + +const response = await client.responses.create({ + model: "openai/gpt-5", + conversation: threadId, + input: "Create a three-slide deck on Q4 results.", + instructions: generateSystemPrompt(), + tools: [artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool], + store: true, + stream: true, +}); +``` + +Artifacts are stored separately from the chat messages. Register `presentationArtifactRenderer`, `reportArtifactRenderer`, and `useOpenuiCloudStorage()` with `AgentInterface` to render and persist them. The [OpenUI Cloud scaffold](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) contains the complete client setup. + +### Render an artifact + +`AgentInterface` opens artifacts returned by the tool with the registered presentation or report renderer. The renderer receives the stored artifact state and updates progressively while the response is streaming. + +### Edit an artifact -For a `function` tool, execute each returned `function_call` on your server and continue with a `function_call_output`. The Cloud scaffold includes a complete tool loop; see [Tools](/docs/agent/core-concepts/tools) for the execution model. +Send the requested change in the same stored conversation. OpenUI Cloud associates the follow-up with the existing artifact and applies the edit: + +```ts +const edited = await client.responses.create({ + model: "openai/gpt-5", + conversation: threadId, + input: "Make slide 2 about European revenue.", + instructions: generateSystemPrompt(), + tools: [artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool], + store: true, + stream: true, +}); +``` ## Bring your own provider key -Add an OpenAI, Anthropic, or Google key on the [BYOK page in the Thesys console](https://console.thesys.dev/byok). When the requested model matches that provider, OpenUI Cloud uses the configured key automatically. The request body does not change. +Follow [Models and BYOK](/docs/openui-cloud/models-and-byok) to add an OpenAI, Anthropic, or Google key in the [Thesys console](https://console.thesys.dev/byok). When the requested model matches that provider, OpenUI Cloud selects the configured key automatically. The request body does not change. ## When to use Chat Completions -Use the [Chat Completions API](/docs/openui-cloud/api/chat-completions) when an existing application already speaks that protocol, when you want a plain model passthrough, or when your application owns its conversation history and function-tool loop. Use Responses for Cloud-managed conversations, hosted search or MCP tools, and artifacts inside the agent stream. +Use the [Chat Completions API](/docs/openui-cloud/api/chat-completions) when an existing application already speaks that protocol, when you want plain model passthrough or self-hosted prompt assembly, or when your application owns its conversation history and function-tool loop. Use Responses for Cloud-managed conversations, hosted search or MCP tools, and artifacts inside the agent stream. From 2b80c7f62912c524a9f443d4c00fc4ce29977ad0 Mon Sep 17 00:00:00 2001 From: Visharad Kashyap <154831195+vishxrad@users.noreply.github.com> Date: Thu, 13 Aug 2026 18:39:29 +0530 Subject: [PATCH 3/4] docs: centralize component library guidance --- .../openui-cloud/api/chat-completions.mdx | 39 +--- .../docs/openui-cloud/api/responses.mdx | 29 +-- .../openui-cloud/build/component-library.mdx | 168 ++++++++++++++++++ docs/content/docs/openui-cloud/meta.json | 1 + 4 files changed, 171 insertions(+), 66 deletions(-) create mode 100644 docs/content/docs/openui-cloud/build/component-library.mdx diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdx index 0f02a3e80..695dc5365 100644 --- a/docs/content/docs/openui-cloud/api/chat-completions.mdx +++ b/docs/content/docs/openui-cloud/api/chat-completions.mdx @@ -44,44 +44,7 @@ console.log(completion.choices[0].message.content); The returned message content is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. - - Managed generative UI requires a bare provider model such as `openai/gpt-5`. Do not combine the - `generateSystemPrompt()` sentinel with a versioned `c1/...` model; that request returns a 400. - - -## Use a custom component library - -Generate a serializable library spec at build time: - -```bash -npx @openuidev/cli@latest generate --spec ./src/library.tsx --out ./src/generated/library.spec.json -``` - -Send the spec through the server helper. OpenUI Cloud uses it to assemble the prompt and validate the streamed output against your components. - -```ts -import { generateSystemPrompt } from "@openuidev/thesys-server"; -import library from "./generated/library.spec.json"; - -const completion = await client.chat.completions.create({ - model: "openai/gpt-5", - messages: [ - { - role: "system", - content: generateSystemPrompt({ - library, - promptOptions: { - additionalRules: ["Prefer compact layouts and concise labels."], - }, - }), - }, - { role: "user", content: "Show revenue by region as an interactive dashboard." }, - ], - stream: true, -}); -``` - -Render the response with the same component library used to generate the spec. +To use the built-in library on the client or bring your own components, see [Component Library](/docs/openui-cloud/build/component-library). ## Stream and render responses diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdx index b26bda240..3bd477bb7 100644 --- a/docs/content/docs/openui-cloud/api/responses.mdx +++ b/docs/content/docs/openui-cloud/api/responses.mdx @@ -42,34 +42,7 @@ console.log(response.output_text); The returned `output_text` is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. -## Use a custom component library - -Generate a serializable library spec at build time: - -```bash -npx @openuidev/cli@latest generate --spec ./src/library.tsx --out ./src/generated/library.spec.json -``` - -Send the spec through the server helper. OpenUI Cloud uses it to assemble the prompt and validate the streamed output against your components. - -```ts -import { generateSystemPrompt } from "@openuidev/thesys-server"; -import library from "./generated/library.spec.json"; - -const response = await client.responses.create({ - model: "openai/gpt-5", - input: "Show revenue by region as an interactive dashboard.", - instructions: generateSystemPrompt({ - library, - promptOptions: { - additionalRules: ["Prefer compact layouts and concise labels."], - }, - }), - stream: true, -}); -``` - -Render the response with the same component library used to generate the spec. +To use the built-in library on the client or bring your own components, see [Component Library](/docs/openui-cloud/build/component-library). ## Stream and render responses diff --git a/docs/content/docs/openui-cloud/build/component-library.mdx b/docs/content/docs/openui-cloud/build/component-library.mdx new file mode 100644 index 000000000..b8302c0cc --- /dev/null +++ b/docs/content/docs/openui-cloud/build/component-library.mdx @@ -0,0 +1,168 @@ +--- +title: Component Library +description: Use OpenUI Cloud with its built-in chat library, or bring your own components. +--- + +## Using the built-in library + +Out of the box, OpenUI Cloud ships a general-purpose chat library with text, headers, tables, charts, forms, tabs, buttons, and more. + +Use it with `AgentInterface` on the client: + +```tsx +import { chatLibrary } from "@openuidev/thesys"; + +; +``` + +On the backend, `generateSystemPrompt()` uses the built-in library by default. The placement of the generated instructions depends on the API: + + + + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const response = await client.responses.create({ + model: "openai/gpt-5", + input: "Show revenue by region as an interactive dashboard.", + instructions: generateSystemPrompt({ + instructions: "Optional instructions for the model.", + }), +}); +``` + + + + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + instructions: "Optional instructions for the model.", + }), + }, + { role: "user", content: "Show revenue by region as an interactive dashboard." }, + ], +}); +``` + + + + +OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library. + +## Using your own library + +Use your own library when the domain calls for components the generic set cannot express or when the application follows its own design system. + +**Define the library.** Create one [`defineComponent`](/docs/openui-lang/defining-components) per component in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag. + +```tsx title="src/lib/chat-library.tsx" +import { Metric, Panel } from "@/components"; +import { createLibrary, defineComponent } from "@openuidev/react-lang"; +import { z } from "zod/v4"; + +const MetricDef = defineComponent({ + name: "Metric", + description: "A single KPI stat with an optional trend arrow.", + props: z.object({ + label: z.string(), + value: z.string(), + trend: z.enum(["up", "down"]).optional(), + }), + component: ({ props }) => , +}); + +const PanelDef = defineComponent({ + name: "Panel", + description: "Top-level container. Children stack vertically.", + props: z.object({ children: z.array(MetricDef.ref) }), + component: ({ props, renderNode }) => {renderNode(props.children)}, +}); + +export const myLibrary = createLibrary({ + id: "acme-chat@1", + root: "Panel", + components: [PanelDef, MetricDef], +}); +``` + +**Generate the spec handover file.** [`openui generate`](/docs/api-reference/cli#openui-generate) turns the library module into a self-contained JSON file for the backend: + +```bash tab="pnpm" tab-group="pkg" +pnpx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +```bash tab="bun" tab-group="pkg" +bunx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +```bash tab="yarn" tab-group="pkg" +yarn dlx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +```bash tab="npm" tab-group="pkg" +npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +**Declare it in the backend call.** Import the generated JSON and pass it as `library`. + + + + +```diff ++ import librarySpec from "./generated/library-spec.json"; + + const response = await client.responses.create({ + model: "openai/gpt-5", + input, + instructions: generateSystemPrompt({ + instructions: "Optional instructions for the model.", ++ library: librarySpec, ++ promptOptions: { preamble: "You build dashboards for Acme operators." }, + }), + }); +``` + + + + +```diff ++ import librarySpec from "./generated/library-spec.json"; + + const completion = await client.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + instructions: "Optional instructions for the model.", ++ library: librarySpec, ++ promptOptions: { preamble: "You build dashboards for Acme operators." }, + }), + }, + ...messages, + ], + }); +``` + + + + +`promptOptions` is valid only alongside `library`. Use `preamble`, `additionalRules`, and `examples` to tune the generated prompt. + +**Swap the client library:** + +```diff +- import { chatLibrary } from "@openuidev/thesys"; ++ import { myLibrary } from "@/lib/chat-library"; + +- ; ++ ; +``` diff --git a/docs/content/docs/openui-cloud/meta.json b/docs/content/docs/openui-cloud/meta.json index c1d55af1b..2ff4515b1 100644 --- a/docs/content/docs/openui-cloud/meta.json +++ b/docs/content/docs/openui-cloud/meta.json @@ -10,6 +10,7 @@ "api/chat-completions", "models-and-byok", "---Features---", + "build/component-library", "build/chat", "build/slides", "build/reports", From 2564775bbbe97f0b334269ec96a5ab5e2b59ea57 Mon Sep 17 00:00:00 2001 From: Visharad Kashyap <154831195+vishxrad@users.noreply.github.com> Date: Mon, 17 Aug 2026 16:27:29 +0530 Subject: [PATCH 4/4] docs: split OpenUI Cloud API reference --- .../docs/openui-cloud/api/artifacts.mdx | 76 +++++++++ .../openui-cloud/api/chat-completions.mdx | 148 +++--------------- .../docs/openui-cloud/api/conversations.mdx | 93 +++++++++++ .../docs/openui-cloud/api/overview.mdx | 71 +++++++++ .../docs/openui-cloud/api/responses.mdx | 88 ++--------- .../openui-cloud/build/component-library.mdx | 10 +- .../docs/openui-cloud/how-it-works.mdx | 41 ++--- docs/content/docs/openui-cloud/index.mdx | 10 +- docs/content/docs/openui-cloud/meta.json | 3 + .../docs/openui-cloud/models-and-byok.mdx | 2 +- 10 files changed, 316 insertions(+), 226 deletions(-) create mode 100644 docs/content/docs/openui-cloud/api/artifacts.mdx create mode 100644 docs/content/docs/openui-cloud/api/conversations.mdx create mode 100644 docs/content/docs/openui-cloud/api/overview.mdx diff --git a/docs/content/docs/openui-cloud/api/artifacts.mdx b/docs/content/docs/openui-cloud/api/artifacts.mdx new file mode 100644 index 000000000..29e61b031 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/artifacts.mdx @@ -0,0 +1,76 @@ +--- +title: Chat Completions (Artifacts) +description: "Generate and edit standalone OpenUI Cloud presentations and reports with a Chat Completions-compatible endpoint." +--- + +The Artifact Chat Completions API generates a standalone slide deck or report as an OpenUI Lang program. Use it when the artifact lifecycle is separate from an agent's Responses stream. + +**Endpoint:** `POST https://api.thesys.dev/v1/artifact/chat/completions` + +Use the `artifactClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration. + +## Generate an artifact + +Every request includes `metadata.thesys` as a JSON string with your artifact `id` and a `c1_artifact_type` of `"slides"` or `"report"`. + +```ts +const artifact = await artifactClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [{ role: "user", content: "Create a three-slide deck on Q4 results." }], + metadata: { + thesys: JSON.stringify({ + id: "art_1", + c1_artifact_type: "slides", + }), + }, +}); + +const program = artifact.choices[0].message.content; +``` + +The response content is a raw OpenUI Lang program rooted at `SlideShow` or `ReportView`. OpenUI Cloud validates and repairs it before returning it. Set `stream: true` to receive the program progressively. + +## Render an artifact + +Render the returned program with the matching managed viewer: + +```tsx +import { Presentation, Report } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; + +export function Artifact({ kind, program }: { kind: "slides" | "report"; program: string }) { + return kind === "slides" ? ( + + ) : ( + + ); +} +``` + +Pass `isStreaming` while accumulating a streamed program. + +## Edit an artifact + +Send the current OpenUI Lang program as an assistant message, describe the change in the next user message, and set `is_edit: true`. + +```ts +const edited = await artifactClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "assistant", content: previousProgram }, + { role: "user", content: "Make slide 2 about European revenue." }, + ], + metadata: { + thesys: JSON.stringify({ + id: "art_1", + c1_artifact_type: "slides", + is_edit: true, + }), + }, + stream: true, +}); +``` + +The response is a patch-mode OpenUI Lang program merged against the assistant-message base. + +Use the [Responses API](/docs/openui-cloud/api/responses#generate-slides-and-reports) instead when artifacts should be stored, opened, and edited as part of a persistent agent conversation. diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdx index 695dc5365..82648e619 100644 --- a/docs/content/docs/openui-cloud/api/chat-completions.mdx +++ b/docs/content/docs/openui-cloud/api/chat-completions.mdx @@ -1,37 +1,22 @@ --- -title: Chat Completions API -description: "Use the OpenAI-compatible Chat Completions and artifact endpoints for text, OpenUI Lang, tools, slides, and reports." +title: Chat Completions (Embed) +description: "Use the OpenAI-compatible embed endpoint for text, managed or self-hosted generative UI, and function tools." --- -The Chat Completions API is a drop-in OpenAI-compatible endpoint for applications that already use `chat.completions.create()`. It supports plain text, self-hosted generative UI, and managed generative UI without changing the application's message format. +The Embed Chat Completions API is a drop-in endpoint for applications that already use `chat.completions.create()`. It preserves the standard message format and supports text or OpenUI Lang responses. **Endpoint:** `POST https://api.thesys.dev/v1/embed/chat/completions` -It uses the stock OpenAI SDK. Keep the Thesys API key and the request on your server. +Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration. -## Configure the client - -Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and point the OpenAI client at the OpenUI Cloud base URL. - -```ts title="server.ts" -import OpenAI from "openai"; - -const client = new OpenAI({ - apiKey: process.env.THESYS_API_KEY, - baseURL: "https://api.thesys.dev/v1/embed", -}); -``` - -Both streaming and non-streaming requests are supported. - -## Make a request +## Make a managed UI request Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library. ```ts title="server.ts" import { generateSystemPrompt } from "@openuidev/thesys-server"; -const completion = await client.chat.completions.create({ +const completion = await embedClient.chat.completions.create({ model: "openai/gpt-5", messages: [ { role: "system", content: generateSystemPrompt() }, @@ -42,9 +27,7 @@ const completion = await client.chat.completions.create({ console.log(completion.choices[0].message.content); ``` -The returned message content is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. - -To use the built-in library on the client or bring your own components, see [Component Library](/docs/openui-cloud/build/component-library). +The returned message content is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow. ## Stream and render responses @@ -72,13 +55,13 @@ Use `openAIAdapter()` when your route preserves the raw `data:` SSE response. If ## Manage conversation history -Chat Completions requests are message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn. +Chat Completions is message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn. -Use the [Responses API](/docs/openui-cloud/api/responses#manage-conversation-history) if you want to reference `previous_response_id` or a persistent Cloud conversation instead. +The [Conversations API](/docs/openui-cloud/api/conversations) integrates with Responses, not Embed Chat Completions. Choose Responses when you want Cloud-managed persistent history. -## Use tools +## Use function tools -Chat Completions accepts `function` tools only. The endpoint does not execute them. Run the standard loop in your application: +Embed Chat Completions accepts `function` tools only and does not execute them. Run the standard loop in your application: 1. Send the messages and function declarations. 2. Read `tool_calls` from the assistant message. @@ -86,106 +69,16 @@ Chat Completions accepts `function` tools only. The endpoint does not execute th 4. Append the assistant tool-call message and each `role: "tool"` result. 5. Repeat until the model returns a final response. -Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#use-tools), not Chat Completions. - -## Generate slides and reports - -Artifacts have a separate Chat Completions-compatible endpoint: - -**Endpoint:** `POST https://api.thesys.dev/v1/artifact/chat/completions` - -Point another OpenAI client at the artifact base URL. Every request must include `metadata.thesys` as a JSON string with your artifact `id` and a `c1_artifact_type` of `"slides"` or `"report"`. - -```ts -import OpenAI from "openai"; - -const artifactClient = new OpenAI({ - apiKey: process.env.THESYS_API_KEY, - baseURL: "https://api.thesys.dev/v1/artifact", -}); - -const artifact = await artifactClient.chat.completions.create({ - model: "openai/gpt-5", - messages: [{ role: "user", content: "Create a three-slide deck on Q4 results." }], - metadata: { - thesys: JSON.stringify({ - id: "art_1", - c1_artifact_type: "slides", - }), - }, -}); - -const program = artifact.choices[0].message.content; -``` - -Provider models use the same native routing and BYOK behavior as the embed endpoint. The response content is a raw OpenUI Lang program rooted at `SlideShow` or `ReportView`. It is validated and repaired before being returned. Set `stream: true` to receive it progressively. - -### Render an artifact - -Render the returned program with the matching managed viewer: - -```tsx -import { Presentation, Report } from "@openuidev/thesys"; -import "@openuidev/thesys/styles.css"; - -export function Artifact({ kind, program }: { kind: "slides" | "report"; program: string }) { - return kind === "slides" ? ( - - ) : ( - - ); -} -``` - -Pass `isStreaming` while accumulating a streamed program. - -### Edit an artifact - -Send the current OpenUI Lang program as an assistant message, describe the change in the next user message, and set `is_edit: true`. - -```ts -const edited = await artifactClient.chat.completions.create({ - model: "openai/gpt-5", - messages: [ - { role: "assistant", content: previousProgram }, - { role: "user", content: "Make slide 2 about European revenue." }, - ], - metadata: { - thesys: JSON.stringify({ - id: "art_1", - c1_artifact_type: "slides", - is_edit: true, - }), - }, - stream: true, -}); -``` - -The response is a patch-mode OpenUI Lang program merged against the assistant-message base. - -## Bring your own provider key - -Follow [Models and BYOK](/docs/openui-cloud/models-and-byok) to add an OpenAI, Anthropic, or Google key in the [Thesys console](https://console.thesys.dev/byok). When the requested model matches that provider, OpenUI Cloud selects the configured key automatically. The request body does not change. - -For a request-level self-hosted key flow, encrypt the key with `POST /encryption/encrypt`, then include this object in the request body: - -```ts -byok: { - provider, - encryptedApiKey, -} -``` +Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#use-tools). For standalone slides or reports, use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts). ## Use other generation modes -Managed generative UI is the closest match to the Responses API flow. Chat Completions also supports plain passthrough and application-managed prompt assembly. - ### Plain text passthrough -Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt()` sentinel. OpenUI Cloud forwards the messages, including your system prompt, without injecting a generative UI prompt or component schema. +Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt()` sentinel. OpenUI Cloud forwards your messages and system prompt without injecting a generative UI prompt or component schema. ```ts -const completion = await client.chat.completions.create({ +const completion = await embedClient.chat.completions.create({ model: "openai/gpt-5", messages: [ { role: "system", content: "You are a concise product analyst." }, @@ -206,7 +99,7 @@ Compile the complete system prompt in your application from a generated OpenUI l import { generateSystemPrompt } from "@openuidev/lang-core"; import library from "./generated/library.spec.json"; -const completion = await client.chat.completions.create({ +const completion = await embedClient.chat.completions.create({ model: "openai/gpt-5", messages: [ { @@ -224,6 +117,13 @@ const completion = await client.chat.completions.create({ In this mode, prompt assembly, output validation, and rendering are owned by your application. -## When to use Responses +### Request-level provider key -Use the [Responses API](/docs/openui-cloud/api/responses) for new OpenUI Cloud applications, Cloud-managed conversations, hosted search or MCP tools, and artifacts inside the agent stream. Use Chat Completions when an existing application already speaks that protocol, when you want plain model passthrough or self-hosted prompt assembly, or when your application owns its conversation history and function-tool loop. +For a request-level self-hosted key flow, encrypt the provider key with `POST /encryption/encrypt`, then include this object in the request body: + +```ts +byok: { + provider, + encryptedApiKey, +} +``` diff --git a/docs/content/docs/openui-cloud/api/conversations.mdx b/docs/content/docs/openui-cloud/api/conversations.mdx new file mode 100644 index 000000000..ca11c1465 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/conversations.mdx @@ -0,0 +1,93 @@ +--- +title: Conversations API +description: "Create persistent OpenUI Cloud conversations, inspect their items, and connect them to Responses and Agent Interface." +--- + +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](/docs/openui-cloud/api/overview), which covers authentication and the shared OpenAI SDK clients. + + + Conversations integrate with the Responses API. Embed Chat Completions applications own and resend + their own `messages` history. + + +## Create a conversation + +Create the conversation before the first stored response: + +```ts +const conversation = await conversationClient.conversations.create({ + metadata: { workspace: "acme" }, +}); +``` + +Then send only the new turn to Responses and set `store: true`: + +```ts +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: + +```ts +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 + +| Method | Path | Purpose | +| ------------------------- | ----------------------------------------------------- | ------------------------------------------- | +| `GET` / `POST` | `/v1/conversations` | List or create conversations. | +| `GET` / `POST` / `DELETE` | `/v1/conversations/{conversation_id}` | Retrieve, update, or delete a conversation. | +| `GET` / `POST` | `/v1/conversations/{conversation_id}/items` | List or add conversation items. | +| `GET` / `DELETE` | `/v1/conversations/{conversation_id}/items/{item_id}` | Retrieve or delete one item. | + +Server-side requests authenticate with the API key described in the [API overview](/docs/openui-cloud/api/overview#authenticate). + +## 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`. + +```tsx +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 ; +} +``` + +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](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/app/api/frontend-token/route.ts) and [Cloud storage setup](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) as complete references. diff --git a/docs/content/docs/openui-cloud/api/overview.mdx b/docs/content/docs/openui-cloud/api/overview.mdx new file mode 100644 index 000000000..655ee4ae5 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/overview.mdx @@ -0,0 +1,71 @@ +--- +title: API Overview +description: "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](/docs/openui-cloud/api/responses) | `POST /v1/embed/responses` | New agent applications, hosted tools, persistent conversations, and artifacts inside the agent stream. | +| [Chat Completions (Embed)](/docs/openui-cloud/api/chat-completions) | `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)](/docs/openui-cloud/api/artifacts) | `POST /v1/artifact/chat/completions` | Standalone slide or report generation and explicit program-based edits. | +| [Conversations](/docs/openui-cloud/api/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](https://console.thesys.dev/keys) and configure `THESYS_API_KEY` on your server. Server-side requests use: + +```http +Authorization: Bearer $THESYS_API_KEY +``` + +Never expose this key to browser code. Browser access to conversations and artifacts uses a scoped, short-lived frontend token instead; see the [Conversations API](/docs/openui-cloud/api/conversations#connect-agent-interface). + +## 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: + +```ts title="lib/openui-cloud.ts" +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](/docs/openui-cloud/models-and-byok) for supported models and provider credentials. +- Use the built-in chat library or provide your own components. See [Component Library](/docs/openui-cloud/build/component-library). +- Keep generation behind a server route and match the browser adapter to the selected response protocol. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats). +- For the relationship between generation, storage, and rendering, see [How it works](/docs/openui-cloud/how-it-works). diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdx index 3bd477bb7..6cfa9025b 100644 --- a/docs/content/docs/openui-cloud/api/responses.mdx +++ b/docs/content/docs/openui-cloud/api/responses.mdx @@ -1,28 +1,13 @@ --- title: Responses API -description: "Use the OpenAI-compatible Responses API for managed generative UI, persistent conversations, hosted tools, and artifacts." +description: "Generate managed UI with persistent conversations, hosted tools, and artifacts in the agent stream." --- -The Responses API is the recommended OpenUI Cloud endpoint for new agent applications. It combines managed generative UI with persistent conversations, hosted tools, and editable slide and report artifacts. +The Responses API is the recommended generation endpoint for new OpenUI Cloud agent applications. **Endpoint:** `POST https://api.thesys.dev/v1/embed/responses` -It uses the stock OpenAI SDK. Keep the Thesys API key and the request on your server. - -## Configure the client - -Create an API key in the [Thesys console](https://console.thesys.dev/keys), set it as `THESYS_API_KEY`, and point the OpenAI client at the OpenUI Cloud base URL. - -```ts title="server.ts" -import OpenAI from "openai"; - -const client = new OpenAI({ - apiKey: process.env.THESYS_API_KEY, - baseURL: "https://api.thesys.dev/v1/embed", -}); -``` - -Both streaming and non-streaming requests are supported. +Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration. ## Make a request @@ -31,7 +16,7 @@ Use the server helper to have OpenUI Cloud assemble the system prompt for its bu ```ts title="server.ts" import { generateSystemPrompt } from "@openuidev/thesys-server"; -const response = await client.responses.create({ +const response = await embedClient.responses.create({ model: "openai/gpt-5", input: "Compare quarterly revenue by region.", instructions: generateSystemPrompt(), @@ -40,9 +25,7 @@ const response = await client.responses.create({ console.log(response.output_text); ``` -The returned `output_text` is an OpenUI Lang program that can be rendered with the Cloud `chatLibrary`. - -To use the built-in library on the client or bring your own components, see [Component Library](/docs/openui-cloud/build/component-library). +The returned `output_text` is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow. ## Stream and render responses @@ -77,23 +60,23 @@ Your `/api/chat` route should forward the OpenUI Cloud response stream without c The Responses API supports three history patterns: -| Pattern | Use it when | -| -------------------------------- | --------------------------------------------------------------------------------------- | -| Send the full history in `input` | Your application owns all message storage. | -| Set `previous_response_id` | You want to chain turns without creating a named conversation. Use `store: true`. | -| Set `conversation` | You want a persistent thread that can be loaded by `AgentInterface`. Use `store: true`. | +| Pattern | Use it when | +| -------------------------------- | --------------------------------------------------------------------------------- | +| Send the full history in `input` | Your application owns all message storage. | +| Set `previous_response_id` | You want to chain turns without a named conversation. Use `store: true`. | +| Set `conversation` | You want a persistent thread managed by the Conversations API. Use `store: true`. | Chain a follow-up to an earlier response: ```ts -const first = await client.responses.create({ +const first = await embedClient.responses.create({ model: "openai/gpt-5", input: "Compare quarterly revenue by region.", instructions: generateSystemPrompt(), store: true, }); -const followUp = await client.responses.create({ +const followUp = await embedClient.responses.create({ model: "openai/gpt-5", input: "Focus on Europe and explain the change.", instructions: generateSystemPrompt(), @@ -102,18 +85,7 @@ const followUp = await client.responses.create({ }); ``` -For a named Cloud conversation, send only the new turn on each request: - -```ts -const response = await client.responses.create({ - model: "openai/gpt-5", - conversation: threadId, - input: latestMessage, - instructions: generateSystemPrompt(), - store: true, - stream: true, -}); -``` +For persistent named threads, see the [Conversations API](/docs/openui-cloud/api/conversations). ## Use tools @@ -130,7 +102,7 @@ OpenUI Cloud runs hosted tools inside the platform. App-owned function tools sti ```ts import type { Tool } from "openai/resources/responses/responses"; -const response = await client.responses.create({ +const response = await embedClient.responses.create({ model: "openai/gpt-5", input: "Research the market and summarize the most important changes.", instructions: generateSystemPrompt(), @@ -160,7 +132,7 @@ Add `artifactTool()` to generate editable slides or reports inside the agent str import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server"; import type { Tool } from "openai/resources/responses/responses"; -const response = await client.responses.create({ +const response = await embedClient.responses.create({ model: "openai/gpt-5", conversation: threadId, input: "Create a three-slide deck on Q4 results.", @@ -171,32 +143,6 @@ const response = await client.responses.create({ }); ``` -Artifacts are stored separately from the chat messages. Register `presentationArtifactRenderer`, `reportArtifactRenderer`, and `useOpenuiCloudStorage()` with `AgentInterface` to render and persist them. The [OpenUI Cloud scaffold](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) contains the complete client setup. - -### Render an artifact - -`AgentInterface` opens artifacts returned by the tool with the registered presentation or report renderer. The renderer receives the stored artifact state and updates progressively while the response is streaming. - -### Edit an artifact - -Send the requested change in the same stored conversation. OpenUI Cloud associates the follow-up with the existing artifact and applies the edit: - -```ts -const edited = await client.responses.create({ - model: "openai/gpt-5", - conversation: threadId, - input: "Make slide 2 about European revenue.", - instructions: generateSystemPrompt(), - tools: [artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool], - store: true, - stream: true, -}); -``` - -## Bring your own provider key - -Follow [Models and BYOK](/docs/openui-cloud/models-and-byok) to add an OpenAI, Anthropic, or Google key in the [Thesys console](https://console.thesys.dev/byok). When the requested model matches that provider, OpenUI Cloud selects the configured key automatically. The request body does not change. - -## When to use Chat Completions +Artifacts are stored separately from chat messages. Register `presentationArtifactRenderer`, `reportArtifactRenderer`, and `useOpenuiCloudStorage()` with `AgentInterface` to render and persist them. The [OpenUI Cloud scaffold](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) contains the complete client setup. -Use the [Chat Completions API](/docs/openui-cloud/api/chat-completions) when an existing application already speaks that protocol, when you want plain model passthrough or self-hosted prompt assembly, or when your application owns its conversation history and function-tool loop. Use Responses for Cloud-managed conversations, hosted search or MCP tools, and artifacts inside the agent stream. +Follow-up requests in the same stored conversation edit the existing artifact automatically. Use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts) when you need standalone generation or explicitly managed edits outside an agent stream. diff --git a/docs/content/docs/openui-cloud/build/component-library.mdx b/docs/content/docs/openui-cloud/build/component-library.mdx index b8302c0cc..376cfa548 100644 --- a/docs/content/docs/openui-cloud/build/component-library.mdx +++ b/docs/content/docs/openui-cloud/build/component-library.mdx @@ -15,7 +15,7 @@ import { chatLibrary } from "@openuidev/thesys"; ; ``` -On the backend, `generateSystemPrompt()` uses the built-in library by default. The placement of the generated instructions depends on the API: +On the backend, `generateSystemPrompt()` uses the built-in library by default. Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview); the placement of the generated instructions depends on the API: @@ -23,7 +23,7 @@ On the backend, `generateSystemPrompt()` uses the built-in library by default. T ```ts import { generateSystemPrompt } from "@openuidev/thesys-server"; -const response = await client.responses.create({ +const response = await embedClient.responses.create({ model: "openai/gpt-5", input: "Show revenue by region as an interactive dashboard.", instructions: generateSystemPrompt({ @@ -38,7 +38,7 @@ const response = await client.responses.create({ ```ts import { generateSystemPrompt } from "@openuidev/thesys-server"; -const completion = await client.chat.completions.create({ +const completion = await embedClient.chat.completions.create({ model: "openai/gpt-5", messages: [ { @@ -119,7 +119,7 @@ npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./gener ```diff + import librarySpec from "./generated/library-spec.json"; - const response = await client.responses.create({ + const response = await embedClient.responses.create({ model: "openai/gpt-5", input, instructions: generateSystemPrompt({ @@ -136,7 +136,7 @@ npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./gener ```diff + import librarySpec from "./generated/library-spec.json"; - const completion = await client.chat.completions.create({ + const completion = await embedClient.chat.completions.create({ model: "openai/gpt-5", messages: [ { diff --git a/docs/content/docs/openui-cloud/how-it-works.mdx b/docs/content/docs/openui-cloud/how-it-works.mdx index ee875eb23..c874c7149 100644 --- a/docs/content/docs/openui-cloud/how-it-works.mdx +++ b/docs/content/docs/openui-cloud/how-it-works.mdx @@ -7,17 +7,19 @@ description: "Learn how OpenUI Cloud handles model access, automatic fallbacks, Generative UI puts model output directly in front of users, and raw model output is not reliable enough for that. OpenUI Cloud sits between the application and the model. It can act as a compatible model gateway or assemble and validate renderable OpenUI Lang for generative UI. -OpenUI Cloud exposes three API surfaces: +OpenUI Cloud exposes four API surfaces, summarized in the [API overview](/docs/openui-cloud/api/overview): -- **Responses API:** The recommended generation endpoint for new agent applications. It accepts a conversation turn and streams validated UI as **OpenUI Lang**, with persistent conversations, hosted tools, and slide and report generation in the same API. -- **Chat Completions API:** A drop-in endpoint for applications that already use the OpenAI Chat Completions message format. It supports plain text passthrough, self-hosted or managed generative UI, application-run function tools, and a dedicated Chat Completions-compatible artifact endpoint. -- **Persistence API:** Provides read and write access to stored conversations, slides, and reports. The browser calls it directly using short-lived session tokens. +- **[Responses API](/docs/openui-cloud/api/responses):** The recommended generation endpoint for new agent applications. It accepts a conversation turn and streams validated UI as **OpenUI Lang**, with persistent conversations, hosted tools, and slide and report generation in the same API. +- **[Chat Completions (Embed)](/docs/openui-cloud/api/chat-completions):** A drop-in endpoint for applications that already use the OpenAI Chat Completions message format. It supports plain text passthrough, self-hosted or managed generative UI, and application-run function tools. +- **[Chat Completions (Artifacts)](/docs/openui-cloud/api/artifacts):** A standalone endpoint for generating and explicitly editing slide and report programs. +- **[Conversations API](/docs/openui-cloud/api/conversations):** Provides read and write access to stored conversation threads and items. The browser calls it directly using short-lived frontend tokens. -The generation APIs integrate with AgentInterface through their matching stream adapters, while the Persistence API supplies thread history and stored artifacts. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer. +The generation APIs integrate with AgentInterface through their matching stream adapters, while the Conversations API and artifact storage endpoints supply thread history and stored artifacts. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer. Rendering stays in the browser: responses render client-side with the application's component library, exactly as in open-source OpenUI. - A[AgentInterface] @@ -25,9 +27,9 @@ flowchart LR end subgraph Cloud[OpenUI Cloud] R[Responses API] - C[Chat Completions API] - AR[Artifact endpoint] - PA[Persistence API] + C["Chat Completions (Embed)"] + AR["Chat Completions (Artifacts)"] + PA[Conversations API] M["Model routing and fallbacks"] V["Output validation and correction"] G[Artifact generation] @@ -37,7 +39,7 @@ flowchart LR B --> R B --> C B --> AR - A -->|session token| PA + A -->|frontend token| PA R --> M R --> V R --> G @@ -48,7 +50,8 @@ flowchart LR AR --> V AR --> G PA --> S -`} /> +`} +/> The application consists of product code, AgentInterface or a custom UI, and a backend route that holds the API key. OpenUI Cloud runs model routing, managed output validation, artifact generation, and storage. @@ -69,6 +72,7 @@ sequenceDiagram Cloud-->>App: Stream of renderable UI App-->>Browser: Stream relayed, interface renders progressively Note over Cloud: Turn persisted to the conversation + `} /> 1. The user sends a message. AgentInterface posts it to the application backend. @@ -84,7 +88,7 @@ Chat Completions uses the application's existing `messages` array. The applicati Plain passthrough requests receive no injected generative UI prompt. For managed generative UI, a server helper places an OpenUI configuration sentinel in the system message so Cloud can assemble the prompt and validate the generated program. Function tools are returned to the application for execution; hosted search and MCP tools remain on the Responses API. -Slides and reports use `POST /v1/artifact/chat/completions`. The application sends artifact metadata with a prompt and receives a raw OpenUI Lang artifact program. Editing sends the current program back as an assistant message with `is_edit: true`. +Standalone slides and reports use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts). The application sends artifact metadata with a prompt and receives a raw OpenUI Lang artifact program. Editing sends the current program back as an assistant message with `is_edit: true`. ## Output validation @@ -100,7 +104,7 @@ With Chat Completions, the dedicated artifact endpoint returns a raw OpenUI Lang ## Conversation persistence -Responses API conversations can be stored server-side. Each turn's messages, actions, and outputs attach to a conversation thread, and generation calls reference the thread instead of resending its history. The application backend stores no chat history and runs no database. On load, AgentInterface reads threads and artifacts from the Persistence API. +Responses API conversations can be stored server-side. Each turn's messages, actions, and outputs attach to a conversation thread, and generation calls reference the thread instead of resending its history. The application backend stores no chat history and runs no database. On load, AgentInterface reads threads from the Conversations API and artifacts from the storage plane. Chat Completions applications own their message history and resend the relevant messages on each turn. Choose the Responses API when Cloud-managed conversation persistence is required. @@ -108,8 +112,8 @@ Chat Completions applications own their message history and resend the relevant Two credentials with different scopes: -- **API key:** Authorizes generation calls and session-token minting. It is held by the application backend and is never sent to the browser. -- **Session tokens:** Short-lived tokens that the application backend requests from Cloud and returns to the browser. The browser uses them to read conversations and artifacts from the Persistence API without the backend proxying each read. Tokens expire within minutes, and AgentInterface requests a fresh token from the backend before expiry. +- **API key:** Authorizes generation calls and frontend-token minting. It is held by the application backend and is never sent to the browser. +- **Frontend tokens:** Short-lived tokens that the application backend requests from Cloud and returns to the browser. The browser uses them to read conversations and artifacts without the backend proxying each read. Tokens expire within minutes, and AgentInterface requests a fresh token from the backend before expiry. >App: Session token request + Browser->>App: Frontend token request App->>Cloud: Mint request, authorized with the API key - Cloud-->>App: Short-lived session token - App-->>Browser: Session token + Cloud-->>App: Short-lived frontend token + App-->>Browser: Frontend token Browser->>Cloud: Reads conversations and artifacts + `} /> diff --git a/docs/content/docs/openui-cloud/index.mdx b/docs/content/docs/openui-cloud/index.mdx index 880f6fe92..e14d28cc7 100644 --- a/docs/content/docs/openui-cloud/index.mdx +++ b/docs/content/docs/openui-cloud/index.mdx @@ -71,13 +71,9 @@ Requests are automatically routed to a fallback when the selected model or provi ## Choose an API - - The recommended API for new agents, with persistent conversations, hosted tools, managed - generative UI, slides, and reports in one stream. - - - A drop-in endpoint for existing OpenAI Chat Completions applications, with plain text, - self-hosted or managed generative UI, function tools, and a dedicated artifact endpoint. + + Compare the Responses, Embed Chat Completions, Artifact Chat Completions, and Conversations + APIs, then open the focused guide for the surface you need. diff --git a/docs/content/docs/openui-cloud/meta.json b/docs/content/docs/openui-cloud/meta.json index 2ff4515b1..89042e5e9 100644 --- a/docs/content/docs/openui-cloud/meta.json +++ b/docs/content/docs/openui-cloud/meta.json @@ -6,8 +6,11 @@ "get-started", "how-it-works", "---APIs---", + "api/overview", "api/responses", "api/chat-completions", + "api/artifacts", + "api/conversations", "models-and-byok", "---Features---", "build/component-library", diff --git a/docs/content/docs/openui-cloud/models-and-byok.mdx b/docs/content/docs/openui-cloud/models-and-byok.mdx index 96c299240..3db5e981d 100644 --- a/docs/content/docs/openui-cloud/models-and-byok.mdx +++ b/docs/content/docs/openui-cloud/models-and-byok.mdx @@ -1,6 +1,6 @@ --- title: Models and BYOK -description: "Configure provider keys, choose supported models, and call OpenUI Cloud with the Responses API." +description: "Configure provider keys and choose supported models for OpenUI Cloud generation APIs." --- import { CopyableModelId } from "@/components/copyable-model-id";