OpenUI

Manage dashboards from your server

List, read, rename, pin, share, and delete saved dashboards on your server with openui.artifacts.

openui.artifacts reads, changes, and shares saved dashboards with your API key. Use it where there's no browser, such as a server route, a background job, or an admin tool. For an agent's tool, use dashboards.get(), which always reads as the signed-in user.

app/api/dashboards/route.ts
import { openui } from "@/lib/openui";
import { getSession } from "@/lib/auth"; // your session lookup

export async function GET(request: Request) {
  const session = await getSession(request);
  if (!session) return new Response("Unauthorized", { status: 401 });

  const page = await openui.artifacts.list({
    userId: session.user.id,
    kind: "dashboard",
    signal: request.signal,
  });
  return Response.json(page.data.map(({ id, name, updatedAt }) => ({ id, name, updatedAt })));
}

Act as a user or as your org

Every call takes an optional userId:

userIdThe call acts asIt can
OmittedYour orgRead, update, share, and delete every user's dashboards. It has no pins.
A user's idThat userDo what their frontend token can, on their own and shared dashboards.

With a userId, also pass the user's groupIds, the same as on their frontend token, so dashboards shared with their groups count. The client also sends its appId, so the call stays in that user's app, as their frontend token does.

Take userId from your session, as for the user id. Never pass on a user id from the browser's query string or request body, or anyone could read another user's dashboards. User ids can appear in request URLs and logs, so use opaque ids, not emails.

Methods

MethodDescription
list(params?)One page of dashboards, newest first.
get(id, options?)One dashboard, with its program.
update(id, { name?, content? }, options?)Renames it, saves an edited program as a new version, or both.
delete(id, options?)Deletes it. A deleted dashboard can't be restored.
pin(id, { userId })Pins it for that user.
unpin(id, { userId })Unpins it for that user.
share(id, { type, id, access }, options?)Shares it, or changes the access of an existing share.
unshare(id, { type, id }, options?)Removes a share.

options takes userId, groupIds, and a signal that cancels the call. pin and unpin always need a userId, because pins belong to a user.

List

ParamDescription
kindOnly these kinds, such as "dashboard".
nameMatch on the name.
pinnedtrue for the user's pinned dashboards only, false for the rest. Needs userId.
isOwnertrue for the user's own dashboards, false for those shared with them. Needs userId.
conversationIdOnly the dashboards made in this conversation.
limitPage size, from 1 to 100. Default: 100.
after, beforeThe page after lastId, or before firstId.
order"desc" (newest first, the default) or "asc".

list returns { data, hasMore, firstId, lastId }. To load every page, pass lastId back as after:

let after: string | undefined;
do {
  const page = await openui.artifacts.list({ userId, kind: "dashboard", after });
  for (const dashboard of page.data) console.log(dashboard.name);
  after = page.hasMore ? page.lastId : undefined;
} while (after);

Share

Share with one user, or with a group the user is in, to view or edit. See Share dashboards for who can do what.

const asUser = { userId: session.user.id, groupIds: session.user.teamIds };

await openui.artifacts.share(id, { type: "group", id: "team:sales", access: "view" }, asUser);
await openui.artifacts.unshare(id, { type: "group", id: "team:sales" }, asUser);

As a user, only the owner and edit shares can share. Without a userId, your org can share any dashboard.

The dashboard

FieldDescription
idart_…. Pass it to LiveArtifactRenderer or dashboards.edit.
kind"dashboard", "slides", or "report".
nameThe title.
contentThe openui-lang program. Data scripts stay in OpenUI Cloud and aren't included.
versionChanges with every edit.
pinnedWhether the user pinned it. Always false for your org.
isOwnerWhether the user made it. Always false for your org.
isEditableWhether the caller can edit, rename, and share it. Always true for your org.
sharesWho it's shared with: type, id, access, createdBy, and createdAt in ms. Only when isEditable.
userId, appIdThe user it was made for, and their app.
conversationIdThe conversation it was made in, if any.
createdAt, updatedAtUnix milliseconds.

Errors

A failed call throws OpenUIApiError, with a code and the HTTP status.

StatuscodeWhen
404http_errorThe dashboard doesn't exist, or the user can't see it.
403insufficient_accessThe user can see it, but their access doesn't allow this.
400needs_userisOwner without a userId.
400invalid_inputA bad userId, groupIds, or share target.

On this page