---
title: "Configure a plugin on a slide"
method: POST
path: "/projects/{slug}/slides/{slideId}/plugins"
tags: ["Plugins"]
---

# Configure a plugin on a slide

`POST /projects/{slug}/slides/{slideId}/plugins`

Configure a plugin instance on a slide. The config is validated against the plugin's schema and written to the slide's face.plugins.json. Other plugin instances on the slide are preserved. By default this refuses to overwrite an existing instance with the same localName (returns 409) — pass overwrite: true to replace its config, or use a fresh localName to add another instance. After setup, wire the plugin into the slide's face.tsx via its hook (see getPluginDocs).

## Path parameters

- `slug` string, required
- `slideId` string, required

## Request body

- object
  - `pluginId` string, required — The plugin ID from listPlugins.
  - `localName` string, required — Identifier for this instance, referenced in code as useFormPlugin/usePresenterPlugin(localName). camelCase or snake_case, starting with a letter.
  - `config` object, required — Config object matching the plugin's config schema (see getPluginDocs).
  - `overwrite` boolean — Set true to replace an existing instance with the same localName. Defaults to false.

## Response `200`

Plugin configured

- object
  - `slideId` string, required
  - `versionId` string, required — The new project version ID.
  - `instanceId` string, required — The configured instance id, formatted as `${slideId}.${localName}`.
  - `pluginId` string, required
  - `created` boolean, required — True if a new instance was created, false if an existing one was overwritten.
  - `warning` string — Present when the config was saved but a post-save side effect (e.g. presenter avatar provisioning) failed. The instance is configured; address the warning and call setupPlugin again with overwrite: true to retry.

## Other responses

- `400` — Invalid config, or the slide's existing face.plugins.json is corrupt
- `404` — Project or slide not found
- `409` — An instance with this localName already exists and overwrite was not set

---

[API](https://skmtc.dev/faces/apis/faces-api.md) · [All operations](https://skmtc.dev/faces/apis/faces-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/faces/faces-api/revisions/83197d741969/schema)