---
title: "Prepare an installation"
method: POST
path: "/api/plugin_installations"
tags: ["Installations"]
---

# Prepare an installation

`POST /api/plugin_installations`

## Request

- Base URL: `https://trmnl.com`
- URL: `https://trmnl.com/api/plugin_installations`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, uuid, required
- `X-TRMNL-Configuration-Capabilities` string

## Request body

- object
  - `kind` 'official' | 'recipe', required
  - `source_id` integer, required
  - `source_revision` string, required
  - `choice_id` string, required
  - `device_id` integer: Device whose playlist gets the plugin once the installation completes

## Response `200`

Retained installation replay

- object
  - `data` PluginInstallation
    - `id` string, uuid, required
    - `state` 'setup_required' | 'ready' | 'completed' | 'cancelled' | 'expired' | 'removed', required
    - `source` object, required
      - `kind` string, required
      - `id` integer, required
      - `revision` string, required
      - `choice_id` string, required
      - `device_id` integer
    - `plugin_setting_id` integer, nullable, required
    - `expires_at` string, date_time, required

## Other responses

- `201`: Created installation
- `409`: Idempotency key conflict

---

[API](https://skmtc.dev/trmnl/apis/trmnl-api.md) · [All operations](https://skmtc.dev/trmnl/apis/trmnl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trmnl/apis/trmnl-api/revisions/66179e6d663b?raw)