---
title: "Install a project plugin on a project"
method: POST
path: "/api/v1/plugins/{plugin}/installations"
tags: ["Management"]
---

# Install a project plugin on a project

`POST /api/v1/plugins/{plugin}/installations`

## Request

- Base URL: `https://entire.io` (the document declares no server; this is the origin it was published from)
- URL: `https://entire.io/api/v1/plugins/{plugin}/installations`
- Auth: none declared

Core checks redirect_uri and state, creates and provisions the installation, and returns redirect_to. An install started in Entire sends neither and gets no redirect_to. A project holds one installation of each plugin, so when it has one already this updates it instead, accepting accepted_permissions. Requires project manage or GitHub org owner.

## Path parameters

- `plugin` string, required

## Request body

- object
  - `project_id` string, required
  - `repository_selection` 'all' | 'selected', required: Every repository in the project, including later ones, or only repository_ids.
  - `repository_ids` string[]: Only with a selected repository_selection, where none selects no repositories.
  - `redirect_uri` string
  - `state` string
  - `accepted_permissions` string[], required: The plugin's permissions as resource:access, exactly as the user was shown them. A list that no longer matches the plugin answers 409 with reason permissions_changed.

## Response `200`

Installed

- object
  - `installation_id` string, required
  - `redirect_to` string: Present when a redirect_uri was sent. Send the browser there unchanged.

## Other responses

- `400`: Invalid request
- `401`: Not authenticated
- `403`: Access denied
- `404`: Resource not found
- `409`: The plugin's permissions changed since they were shown (reason permissions_changed)
- `412`: Precondition failed
- `422`: Validation failed
- `429`: Too many requests
- `502`: Entire Core request failed
- `503`: Entire Core is unavailable

## Changes

- **2026-10-27** `b5f5651bc1a0`: 1 breaking, 1 warning, 1 info
  - added the new required request property `accepted_permissions`
  - removed the optional property `type` from the response with the `409` status
  - added the optional property `reason` to the response with the `409` status
- **2026-10-05** `7311ac3485c3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/entire/apis/entire-api/changes/api/v1/plugins/:plugin/installations/post.md)

---

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