Skip to main content
@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

  1. Your backend mints a token with @aiql.io/react/server (one-line Next.js or Express handler).
  2. useToken() fetches that token from /api/aiql and refreshes it before expiry.
  3. AiqlProvider shares the token (and theme) with the subtree.
  4. 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.

Quick start

1. Create the token endpoint

Set AIQL_API_KEY and AIQL_WORKSPACE_ID on your server. Next.js App Routerapp/api/aiql/route.ts:
Express:
See Server handlers for options and other frameworks.

2. Fetch the token and render

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.

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

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.