---
product: "AG Studio"
title: "Studio API Reference"
description: "To access the API, see ."
framework: angular
version: "3.1.0"
related:
    - title: "Overview"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-interface/"
    - title: "Properties Reference"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-properties/"
    - title: "Events Reference"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-events/"
    - title: "Theme Reference"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-theme/"
    - title: "State Reference"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-state/"
    - title: "Studio Lifecycle"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-lifecycle/"
    - title: "Registry Type"
      url: "https://www.ag-grid.com/studio/archive/3.1.0/angular/registry-type/"
llms: "https://www.ag-grid.com/studio/archive/3.1.0/llms.txt"
---

# Studio API Reference

To access the API, see [Studio API](https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-interface/#studio-api).

## AI

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `getAiContext` | `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. See [Agent Context](https://www.ag-grid.com/studio/archive/3.1.0/angular/ai-context/). |
| `getAiTools` | `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, ...)`). See [Tools Overview](https://www.ag-grid.com/studio/archive/3.1.0/angular/ai-tools/). |
| `defineAiTool` | `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. See [Custom Tools](https://www.ag-grid.com/studio/archive/3.1.0/angular/ai-custom-tools/). |
| `defineAiCommand` | `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. See [Commands](https://www.ag-grid.com/studio/archive/3.1.0/angular/ai-tools/#commands-the-layer-below). |

## Data

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `reload` | `Function` |  | Reload all data from the data sources. See [Reloading Data](https://www.ag-grid.com/studio/archive/3.1.0/angular/loading-data/#reloading-async-data). |
| `getDataEngine` | `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. See [Sharing and Caching Data](https://www.ag-grid.com/studio/archive/3.1.0/angular/sharing-caching-data/#retrieving-the-engine). |

## Lifecycle

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `destroy` | `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. |
| `getStudioId` | `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

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `translate` | `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. See [Localisation](https://www.ag-grid.com/studio/archive/3.1.0/angular/localisation/). |

## Popups

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `createPopup` | `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. See [Popups](https://www.ag-grid.com/studio/archive/3.1.0/angular/popups/). |

## Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `getProperty` | `Function` |  | Returns the Studio properties value for a provided key. See [Studio Properties](https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-properties/). |
| `setProperty` | `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. See [Studio Properties](https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-properties/). |
| `updateProperties` | `Function` |  | Updates the provided subset of Studio properties with the provided values. (Cannot be used on `Initial` properties.) See [Studio Properties](https://www.ag-grid.com/studio/archive/3.1.0/angular/studio-properties/). |

## State

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `getState` | `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. See [Saving and Restoring State](https://www.ag-grid.com/studio/archive/3.1.0/angular/state/). |
| `setState` | `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`. See [Saving and Restoring State](https://www.ag-grid.com/studio/archive/3.1.0/angular/state/). |
| `undo` | `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. See [Undo & Redo](https://www.ag-grid.com/studio/archive/3.1.0/angular/undo-redo/). |
| `redo` | `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. See [Undo & Redo](https://www.ag-grid.com/studio/archive/3.1.0/angular/undo-redo/). |
| `getHistory` | `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. See [Undo & Redo](https://www.ag-grid.com/studio/archive/3.1.0/angular/undo-redo/). |
| `clearHistory` | `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. See [Undo & Redo](https://www.ag-grid.com/studio/archive/3.1.0/angular/undo-redo/). |

## Widgets

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `performWidgetAction` | `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. See [Widget Toolbar Actions](https://www.ag-grid.com/studio/archive/3.1.0/angular/widget-configuration/#toolbar-actions). |
