---
title: "Install a predefined extension from the catalog"
method: POST
path: "/api/extensions/install"
tags: ["Extensions"]
---

# Install a predefined extension from the catalog

`POST /api/extensions/install`

Installs the named template from `GET /api/extensions/catalog`. Inline bundles (`manifest`/`files`) are rejected with `inline_install_disabled`. Any authenticated agent can install a disabled draft owned by its agent ID. Workers can update only their own bundles; activation remains lead/operator-only.

## Request body

- ExtensionInstallBody
  - `template` string, required — Name of a predefined extension in the catalog (`GET /api/extensions/catalog`).
  - `priority` integer
  - `config` object

## Response `200`

Installed extension

- object
  - `extension` Extension, required
    - `id` string, required
    - `name` string, required
    - `description` string, required
    - `runtime` 'api' | 'worker', required
    - `manifestJson` string, required
    - `contentHash` string, required
    - `version` integer, required
    - `activeVersion` integer, required
    - `enabled` boolean, required
    - `priority` integer, required
    - `configJson` string, required
    - `status` 'disabled' | 'enabled' | 'error' | 'auto-disabled', required
    - `consecutiveFailures` integer, required
    - `lastError` string, nullable, required
    - `agentId` string, nullable, required
    - `createdByAgentId` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
  - `manifest` ExtensionManifest, required
    - `$schema` string
    - `name` string, required
    - `description` string, required
    - `version` string, required
    - `runtime` 'api' | 'worker', required
    - `assets` object, required
      - `hooks` string, required
      - `scripts` object[]
        - `name` string, required — Global script name. Must start with `<extension name>-`.
        - `file` string, required — Bundle path of the script source.
        - `description` string, required
        - `intent` string — Defaults to `description`.
      - `schedules` object[]
        - `name` string, required — Schedule name. Must start with `<extension name>-`.
        - `description` string
        - `script` string, required — Name of a script declared in `assets.scripts`.
        - `cronExpression` string
        - `intervalMs` integer
        - `timezone` string
        - `args` object
      - `workflows` object[]
        - `file` string, required — Bundle path of a YAML or JSON workflow file. Its `name` must start with `<extension name>-`.
      - `skills` object[]
        - `dir` string, required — Bundle directory holding SKILL.md and optional files/**. The SKILL.md frontmatter `name` must start with `<extension name>-`.
    - `homepage` string, uri
    - `author` string
  - `contentDeduped` boolean, required
  - `assets` object, nullable, required — Asset changes made by this install. Null when the installed version is staged, not active.
    - `created` object[], required
      - `kind` 'script' | 'schedule' | 'workflow' | 'skill', required
      - `name` string, required
    - `updated` object[], required
      - `kind` 'script' | 'schedule' | 'workflow' | 'skill', required
      - `name` string, required
    - `skipped` object[], required
      - `kind` 'script' | 'schedule' | 'workflow' | 'skill', required
      - `name` string, required
    - `deleted` object[], required
      - `kind` 'script' | 'schedule' | 'workflow' | 'skill', required
      - `name` string, required
    - `detached` object[], required
      - `kind` 'script' | 'schedule' | 'workflow' | 'skill', required
      - `name` string, required

## Other responses

- `400` — Inline bundle rejected or bundle validation failed
- `403` — Permission denied
- `404` — Template not found in the catalog

## Changes

- **2026-09-24** `ad817d2e687d` — 4 breaking, 2 warning, 13 info
  - added the new required request property `template`
  - the `manifest/assets/schedules/items/` response's property type changed from `string` to `object` for status `200`
  - the `manifest/assets/skills/items/` response's property type changed from `string` to `object` for status `200`
  - the `manifest/assets/workflows/items/` response's property type changed from `string` to `object` for status `200`
  - …15 more
- **2026-09-16** `3f6e56391f84` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/extensions/install/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/01e2386c97da?raw)