# General API

> Use common commands, events, history, clipboard, UI, WebSocket, enums, and utilities in a PDF application.

- Human documentation: [https://docs.univer.ai/guides/pdfs/features/core/general-api](https://docs.univer.ai/guides/pdfs/features/core/general-api)

- Agent Markdown: [https://docs.univer.ai/guides/pdfs/features/core/general-api.md](https://docs.univer.ai/guides/pdfs/features/core/general-api.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [pdfs/features/core/general-api.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/features/core/general-api.mdx)

---

The root Facade API combines the common Univer runtime with the plugins registered by this PDF application. This page covers cross-product mechanisms without assuming experience with another Univer document type. For PDF units and page entry points, continue with [Univer PDFs API](https://docs.univer.ai/guides/pdfs/features/core/pdfs-api.md).

## Create the API object

Create one `FUniver` wrapper after the Univer instance and required plugins are registered:

```ts
import { FUniver } from '@univerjs/core/facade'

const univerAPI = FUniver.newAPI(univer)
```

Facade entries imported before this call extend the same object with additional methods.

## Commands

`executeCommand()` runs a registered command asynchronously. Use `syncExecuteCommand()` only when that command explicitly supports synchronous execution. Facade methods remain the preferred entry point for common PDF operations.

## Events

```ts
const commandLog = univerAPI.addEvent(
  univerAPI.Event.CommandExecuted,
  ({ id }) => console.log('Executed:', id)
)

// Later, remove the listener.
commandLog.dispose()
```

Use `BeforeCommandExecute` when an application must inspect or cancel a command. `LifeCycleChanged` reports common editor stages such as `Rendered` and `Steady`.

## Undo and redo

Undo and redo act on the currently focused Univer unit and return promises:

```ts
await univerAPI.undo()
await univerAPI.redo()
```

PDF Facade mutations with inverse operations participate in the focused PDF unit's history.

## System clipboard

With `UniverPdfsUIPlugin` registered and PDF editing enabled, the UI Facade's `copy()` and `paste()` methods dispatch clipboard commands to the focused PDF unit:

```ts
import '@univerjs/ui/facade'

await univerAPI.copy()
await univerAPI.paste()
```

For editable PDF objects, the PDF UI plugin keeps the copied payload in the current browser session rather than writing it to the operating-system clipboard. Browser-native text editing continues to use the browser's clipboard behavior.

## UI

The UI Facade can show messages, open dialogs or sidebars, register components, and control built-in UI parts:

```ts
univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.TOOLBAR, true)
```

These methods require `UniverUIPlugin`; PDF editing controls additionally require `UniverPdfsUIPlugin`.

## WebSocket

WebSocket support is optional. Register the Network plugin and import its Facade entry before creating the API object:

```ts
import { UniverNetworkPlugin } from '@univerjs/network'

import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)

const socket = univerAPI.createSocket('wss://example.com/pdfs')
socket.open$.subscribe(() => socket.send('ready'))
```

Message protocols, authentication, reconnection, and collaboration conflict handling remain the host application's responsibility.

## Enums

`univerAPI.Enum` exposes common runtime enums plus those added by the PDF Facade:

```ts
const lifecycle = univerAPI.Enum.LifecycleStages.Steady
const annotationType = univerAPI.Enum.PdfAnnotationType.HIGHLIGHT
```

## Utilities

`univerAPI.Util` exposes shared helpers such as number formatting, rectangle operations, and common tools:

```ts
const payload = univerAPI.Util.tools.deepClone({
  pageId: 'page-1',
  selectedElementIds: ['element-1'],
})
```

See the [Facade reference](https://docs.univer.ai/reference/facade/univer.md) for the complete common API.