> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Runtime API

> Read config, react to activity params, and update file entries from inside a plugin.

These APIs are available on `pluginApi` inside `setup` and inside activity `render` functions.

## `pluginApi.config`

Read and react to config values at runtime.

### `config.get`

Returns the current value of any config option, including custom ones registered by your plugin.

```typescript
const apiKey = pluginApi.config.get('myApiKey');
const pubkey = pluginApi.config.get('pubkey');
```

### `config.subscribe`

Calls a callback immediately with the current value and again whenever that config value changes. Returns an unsubscribe function. Subscriptions created during `setup` are cleaned up automatically when the plugin is unregistered. Subscriptions created inside an activity's `render` function should be unsubscribed in that activity's cleanup function.

```typescript
// Inside setup - cleaned up automatically when the plugin is unregistered
pluginApi.config.subscribe('myApiKey', (value) => {
  console.log('myApiKey changed:', value);
});
```

Inside an activity's `render` function, tie the subscription to that mount and unsubscribe in the returned cleanup function:

```typescript
pluginApi.registry.registerActivity({
  id: 'my-activity',
  render(host) {
    const el = document.createElement('my-activity-element');
    el.apiKey = pluginApi.config.get('myApiKey');

    const unsubscribe = pluginApi.config.subscribe('myApiKey', (value) => {
      el.apiKey = value;
    });

    host.replaceChildren(el);

    return () => {
      unsubscribe();
      host.replaceChildren();
    };
  },
});
```

---

## `pluginApi.activity`

Access the parameters passed to the currently active activity via [`setCurrentActivity`](/docs/file-uploader/api/#set-current-activity).

### `activity.getParams`

Returns the current activity parameters synchronously. Useful for reading params once at setup time or at the start of an activity render.

```typescript
const params = pluginApi.activity.getParams();
// { fileId: 'abc123', ... }
```

### `activity.subscribeToParams`

Subscribes to parameter changes. The callback fires immediately with the current params, then on every subsequent update. Returns an unsubscribe function.

```typescript
pluginApi.activity.subscribeToParams((params) => {
  console.log('Activity params:', params);
});
```

The `render` function receives params as its second argument for the initial mount, but if your activity can be re-activated with new params while already mounted, use `subscribeToParams` inside `render` to react to those updates:

```typescript
pluginApi.registry.registerActivity({
  id: 'my-activity',
  render(host, initialParams) {
    const el = document.createElement('my-activity-element');
    el.fileId = initialParams.fileId;

    // React to subsequent param changes without unmounting
    const unsub = pluginApi.activity.subscribeToParams((params) => {
      el.fileId = params.fileId;
    });

    host.replaceChildren(el);

    return () => {
      unsub();
      host.replaceChildren();
    };
  },
});
```

---

## `pluginApi.files`

Mutate file entries in the upload collection.

### `files.update`

Updates mutable properties of a file entry by its `internalId`.

```typescript
// Client-side edit: replace the file blob
pluginApi.files.update(fileEntry.internalId, {
  file: transformedBlob,
  mimeType: 'image/webp',
});

// Server-side edit: update the CDN URL instead
pluginApi.files.update(fileEntry.internalId, {
  cdnUrl: 'https://{subdomain}.ucarecd.net/uuid/-/preview/800x600/',
});
```

| Property          | Type             | Description                                             |
| ----------------- | ---------------- | ------------------------------------------------------- |
| `file`            | `File \| Blob`   | Replace the file data.                                  |
| `cdnUrl`          | `string \| null` | Override the CDN URL.                                   |
| `cdnUrlModifiers` | `string \| null` | Override CDN URL modifiers (transformation directives). |
| `mimeType`        | `string \| null` | Override the MIME type.                                 |