JavaScript Embedded AnalyticsStudio API Reference

Version 3.1.1

To access the API, see Studio API.

AI

getAiContextCopy Link
Function
Returns a plain typed namespace exposing AI-relevant information about this Studio instance. Synchronous surfaces (schema, catalogue, vocabulary, fragments) are cheap reads — schema and catalogue re-evaluate current state on every call. Async surfaces (health) perform data-engine round-trips.
getAiToolsCopy Link
Function
Returns the built Studio AI tools, bound to this Studio instance and ready for an agent to run. They read live dashboard state at execute time, so pull the toolkit once and close over it when declaring an agent's tools (e.g. inside ai: ({ api }) => createAiHarness(api, ...)).
defineAiToolCopy Link
Function
Build a tool an agent can list, bound to this Studio instance. Pass one of:
  • { name, description, command, result } - a tool whose action is an AgAiCommand.
  • The command's own input shape is the tool's schema; result turns what the command returned into the response the LLM sees.
  • { name, description, params, execute } - a tool that runs its own execute, for anything
  • that is not a single command. Build the result with ctx.success / ctx.error.
  • { kind: 'server', name, description, params } - declared here, executed by the agent's own
  • harness. Studio advertises the schema and never runs it.
  • { kind: 'provided', name, description, provider } - hosted and run by the LLM provider;
  • provider is passed through to the adapter untouched. The returned tool reads live state when it executes, so build it once and list it from an agent's tools callback.
    defineAiCommandCopy Link
    Function
    Resolve an AI command bound to this Studio instance. The argument is either:
  • a factory callback (builder, lenses) => { input, execute } for a
  • custom command; the returned AgAiCommand exposes toJSONSchema(), parse(), and apply().
  • a built-in command reference { type: 'AgX', params? } to retrieve
  • one of the commands shipped with Studio. The built-in ships the schema + execute; the consuming AI library adds the name, description, status text, and UI. Name, description, status text, and UI belong to the consuming AI library in both cases.

    Data

    reloadCopy Link
    Function
    Reload all data from the data sources.
    getDataEngineCopy Link
    Function
    Returns the data engine this Studio instance is currently using, or undefined if it does not have one. A Studio configured without the data property never has an engine, and one that is still loading does not have it yet - the engine is in place by the time the studioReady event fires. If Studio created the engine, its lifetime is tied to this Studio instance: the engine is released when Studio is destroyed. To keep an engine alive across a Studio instance being destroyed and recreated, or to share one engine between several instances, create it yourself with createDataEngine() and pass it via the data property. Studio then leaves it in your hands, and getDataEngine() returns that same engine.

    Lifecycle

    destroyCopy Link
    Function
    Will destroy the Studio instance and release resources. If you are using a framework you do not need to call this, as Studio links in with the framework lifecycle. However if you are using native JavaScript, you need to call this to avoid a memory leak in your application.
    getStudioIdCopy Link
    Function
    Returns the studioId for the current Studio instance as specified via the Studio property studioId or the auto assigned Studio ID if none was provided.

    Localisation

    translateCopy Link
    Function
    Resolve a locale key to text in the locale now in force, applying localeText and getLocaleText. How a history entry's labelKey becomes something to show: api.translate(entry.labelKey, entry.labelVariableValues). A key Studio does not know is passed to getLocaleText like any other, and falls back to the key itself where nothing resolves it, so your own keys work alongside Studio's.

    Popups

    createPopupCopy Link
    Function
    Open a popup showing a component of your own. The popup is rendered inside Studio, or inside the element given by the popupParent property, and Studio owns it: the popup closes and your component is destroyed when Studio is destroyed. The popup stays open until something closes it: clicking outside it leaves it open, nothing is dimmed, and the rest of the page stays interactive. The Escape key and the close button in its title bar close it. To close it from inside your component, supply compParams as a callback and call the closePopup() function it receives. closedCallback runs once each time the popup closes, whichever of those closed it. The popup is sized as it opens and does not grow to fit its content, so set width and height when your component needs more or less room than the default 600 by 400 pixels. Several popups can be open at once, each staying open until it is closed.

    Properties

    getPropertyCopy Link
    Function
    Returns the Studio properties value for a provided key.
    setPropertyCopy Link
    Function
    Updates a single Studio property to the new value provided. (Cannot be used on Initial properties.) If updating multiple options, it is recommended to instead use api.updateProperties() which batches update logic.
    updatePropertiesCopy Link
    Function
    Updates the provided subset of Studio properties with the provided values. (Cannot be used on Initial properties.)

    State

    getStateCopy Link
    Function
    Get the current state of Studio. Can be used in conjunction with the initialState Studio property or api.setState() to save and restore Studio state. The object returned is Studio's own state rather than a copy. Treat it as read-only and build a new object to pass to api.setState(): mutating this one and handing it back updates nothing on screen.
    setStateCopy Link
    Function
    Set the current state of Studio. Can be used in conjunction with api.getState() or onStateUpdated to save and restore Studio state. The state is expected to be a full state object, not a partial state object. State must be updated immutably as Studio uses reference equality to determine which parts of state have changed. options names the change in the undo history and says who made it; see AgSetStateOptions.
    Function
    Undo the last change to the report state (widgets, layout, filters, schema). View state such as the selected page or selection is left as it is, then brought back into view for the restored change. No-op when there is nothing to undo (getHistory().undo is empty). Pass a getHistory().undo entry's id to undo every change back through that entry in a single step; an unknown id is a no-op.
    Function
    Redo the change most recently undone. No-op when there is nothing to redo (getHistory().redo is empty). Making a fresh change discards the redo branch. Pass a getHistory().redo entry's id to redo every change forward through that entry in a single step; an unknown id is a no-op.
    getHistoryCopy Link
    Function
    The editing history: the live state plus what undo() and redo() would step through, each entry labelled and timestamped. Drives control enablement (an empty undo stack means there is nothing to undo) and a history list. History does not survive loading new state.
    clearHistoryCopy Link
    Function
    Discard the undo and redo history, so getHistory() returns empty stacks and undo()/redo() become no-ops until the next change. The live state is untouched.

    Widgets

    performWidgetActionCopy Link
    Function
    Execute an action for a widget. Action can be one of the default actions ('duplicate' or 'delete'), or an action specific to that widget.