React SDK

@aiql.io/react embeds AiQL Observatory and Studio tools (Canvas, Dashboard, Chat, Knowledge Graph, Common Knowledge, Source Preview, and Presentation) in your product via iframe. Your API key stays on the server. The browser only receives a short-lived workspace-scoped embed token.

How it works

Your backend mints a token with @aiql.io/react/server (one-line Next.js or Express handler).
useToken() fetches that token from /api/aiql and refreshes it before expiry.
AiqlProvider shares the token (and theme) with the subtree.
Canvas, Dashboard, Chat, KnowledgeGraph, CommonKnowledge, Preview, or Presentation builds the embed URL and renders the iframe.

Install

React 18+ is required as a peer dependency.

npm install @aiql.io/react

pnpm add @aiql.io/react

yarn add @aiql.io/react

Quick start

1. Create the token endpoint

Set AIQL_API_KEY and AIQL_WORKSPACE_ID on your server. Next.js App Router — app/api/aiql/route.ts:

import { createNextHandler } from "@aiql.io/react/server";

export const GET = createNextHandler();

Express:

import { createExpressHandler } from "@aiql.io/react/server";

app.get("/api/aiql", createExpressHandler());

See Server handlers for options and other frameworks.

2. Fetch the token and render

import { AiqlProvider, Canvas, useToken } from "@aiql.io/react";

function App() {
  const { token, status, error, reload } = useToken();

  if (status === "loading" || status === "idle") {
    return <p>Loading…</p>;
  }

  if (status === "error" || !token) {
    return (
      <div>
        <p>{error ?? "Failed to load token"}</p>
        <button type="button" onClick={reload}>
          Retry
        </button>
      </div>
    );
  }

  return (
    <AiqlProvider token={token} theme="auto">
      <Canvas canvasId="your-canvas-id" title="My canvas" />
    </AiqlProvider>
  );
}

You can mint the token some other way and pass it to AiqlProvider without using useToken.

Explore the API

Components

AiqlProvider, Canvas, Dashboard, Chat, KnowledgeGraph, CommonKnowledge, Preview, Presentation, and Frame.

Hooks

useToken, useAiql, and useEmbedNavigator for tokens, context, and embed events.

Server

One-line handlers that mint embed tokens on your backend.

Send a message

Chat, Canvas, and Dashboard can start a conversation from your app. Wait for onReady, then call sendMessage on the component ref. onReady fires when the embed posts EMBED_READY, which is later than the iframe load event. The embed keeps the text until its chat can send, then starts the run. On Canvas and Dashboard, that also opens the assistant. A send while a response is already streaming is ignored.

import { useRef } from "react";
import { Chat, type EmbedChatHandle } from "@aiql.io/react";

const ref = useRef<EmbedChatHandle>(null);

<Chat
  ref={ref}
  inquiryId={inquiryId}
  onReady={() => ref.current?.sendMessage("Summarize the latest quarter")}
/>

Canvas and Dashboard use the same ref. See Chat, Canvas, and Dashboard. The useEmbedNavigator page documents the SEND_MESSAGE postMessage.

Artifact open events

When chat (or another embed) shows an artifact card and the user clicks it, the iframe posts ARTIFACT_OPEN to the host instead of navigating away. Handle it with onArtifactOpen on AiqlProvider so your app can route to its own pages (for example /brainstorm/{id}, /analyze/{id}, /present/{id}). See useEmbedNavigator for the full postMessage protocol.

Environment variables

Variable	Where	Description
`AIQL_API_KEY`	Server	API key used to mint embed tokens
`AIQL_WORKSPACE_ID`	Server	Workspace the token is scoped to

Generate an API key in the Dashboard.

Embed tokens are workspace-scoped. /embed/* routes allow framing from any origin (frame-ancestors *). Access is still gated by the embed JWT.

React Components

React Hooks

React Server

How it works

Install

Quick start

1. Create the token endpoint

2. Fetch the token and render

Explore the API

Components

Hooks

Server

Send a message

Artifact open events

Environment variables

​How it works

​Install

​Quick start

​1. Create the token endpoint

​2. Fetch the token and render

​Explore the API

Components

Hooks

Server

​Send a message

​Artifact open events

​Environment variables

How it works

Install

Quick start

1. Create the token endpoint

2. Fetch the token and render

Explore the API

Send a message

Artifact open events

Environment variables