> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flows Host App API

> Complete reference for HostAppAPI interaction methods in Flows custom apps, such as navigation, state, sidebar visibility, fullscreen, and AI agents.

Interaction methods available on the `HostAppAPI` instance returned by `connectToHostApp`. Use these to navigate within or outside of Cognite Data Fusion (CDF), persist shareable app state, hide or show the CDF sidebar (the shell), and integrate with the AI agent panel.

For connecting and getting credentials, see [Auth API](/cdf/flows/reference/api/auth).

## Prerequisites

* A Flows custom app created with [`npx @cognite/cli@latest apps create`](/cdf/flows/guides/getting-started)
* A `HostAppAPI` instance from `connectToHostApp`. See [Auth API](/cdf/flows/reference/api/auth).

## Navigation

### navigateInternal

Navigates to a path within CDF.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
await api.navigateInternal({
  path: "/my-other-app",
  queryParams: { tab: "overview" },
});
```

| Parameter      | Type                                | Description                                             |
| -------------- | ----------------------------------- | ------------------------------------------------------- |
| `path`         | `string`                            | CDF-relative path to navigate to                        |
| `queryParams`  | `Record<string, string>` (optional) | Query parameters                                        |
| `hash`         | `string` (optional)                 | URL hash fragment                                       |
| `openInNewTab` | `boolean` (optional)                | Open in a new tab instead of navigating the current tab |

### navigateExternal

Opens an external URL.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
await api.navigateExternal({
  url: "https://docs.cognite.com",
  openInNewTab: true,
});
```

| Parameter      | Type                 | Description               |
| -------------- | -------------------- | ------------------------- |
| `url`          | `string`             | HTTPS URL to navigate to  |
| `openInNewTab` | `boolean` (optional) | Open in a new browser tab |

## State

### syncInternalState

Saves a serialized state string to the `customAppInternalState` URL search param. The saved state is passed back as `initialState` the next time the app mounts. Users can return to the same view after navigating away or refreshing. Because the state lives in the URL, the link is shareable.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
const handled = await api.syncInternalState(
  JSON.stringify({ view: "dashboard", assetId: "12345" })
);
```

| Parameter | Type     | Required | Description                                                                    |
| --------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `state`   | `string` | Yes      | JSON-serialized state. Must be a string. Call `JSON.stringify` before passing. |

| Return type        | Description                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `Promise<boolean>` | `true` if the host saved the state; `false` if the host did not handle the call (for example, in standalone dev mode). |

<Tip>
  See [App state in URLs](/cdf/flows/guides/shareable-app-state-with-urls) for a full guide covering state restoration, what to include in persisted state, and a complete example.
</Tip>

## Layout

### setHideShell

Hides or reveals the CDF sidebar for the current page, maximizing your app on the page.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
await api.setHideShell(true);  // hide the sidebar
await api.setHideShell(false); // show the sidebar again
```

| Parameter | Type      | Required | Description                                           |
| --------- | --------- | -------- | ----------------------------------------------------- |
| `hidden`  | `boolean` | Yes      | `true` to hide the sidebar; `false` to show it again. |

<Note>
  `setHideShell` only takes effect when your app is loaded on a custom apps route (`/custom-apps/…`). Calling it from any other route is a no-op for sidebar visibility. Requires `@cognite/app-sdk` 0.9.0 or later.
</Note>

#### Example: maximize your app on the page

```tsx theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { connectToHostApp } from "@cognite/app-sdk";

const { api } = await connectToHostApp();

// Hide the sidebar to maximize the app on the page
await api.setHideShell(true);

// Show the sidebar again when done
await api.setHideShell(false);
```

## Fullscreen

Flows custom apps run inside a browser iframe that has the `fullscreen` feature policy enabled. This means your app can request the browser's native fullscreen mode using the standard [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API); no additional configuration required.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
// Enter fullscreen
await document.documentElement.requestFullscreen();

// Exit fullscreen
await document.exitFullscreen();
```

<Tip>
  Use `setHideShell` in [Layout](#layout) when you want to hide the CDF sidebar and maximize your app within the page. Use the browser Fullscreen API when you need to take over the entire display (for example, for a media viewer or a 3D scene).
</Tip>

## Agent

Control the CDF AI agent panel and unregister an agent server from your app. For parameters, examples, and the full workflow (registering a server, resources, and actions), see [Integrating AI agents with Flows](/cdf/flows/guides/ai_agent_integration).

### sendAgentLayoutMode

Changes the visibility or layout of the agent panel (`sidebar`, `fullscreen`, or `closed`).

### sendAgentMessage

Injects text into the agent chat. Optionally starts a fresh session. Open the panel with `sendAgentLayoutMode` first so the user sees the message.

### unregisterAgentServer

Unregisters an agent server previously registered with `registerAgentServer` from `@cognite/app-sdk`. Call this when your app unmounts.

## Further reading

* [App state in URLs](/cdf/flows/guides/shareable-app-state-with-urls) — Full guide for `syncInternalState`
* [Integrating AI agents with Flows](/cdf/flows/guides/ai_agent_integration) — Register resources, actions, and agent UI triggers
* [Run your app locally](/cdf/flows/guides/running-locally) — Development setup