Components (plugins, themes, modules)

Previewcapability-gated

The components resource is the differentiating surface of the managed.dev API — the dynamic application layer that generic PaaS deliberately won’t touch and other WP hosts expose only bluntly. It models plugins, themes, and (on other runtimes) modules as one typed resource: you install, activate, update, and remove them per environment, each call returns a job, and every action is gated by both a scope and a runtime capability.

Developer preview

The managed.dev public API is in active development. Endpoints, scopes, and payloads described here reflect the current design and may change before general availability. The components endpoints are capability-gated and ship in a later API tier — see runtimes & capabilities.

the resource

A component is a unit of the application layer addressed by kind and slug:

{
  "id": "comp_01J9...",
  "kind": "plugin",          // plugin | theme | module
  "slug": "wordpress-seo",
  "name": "Yoast SEO",
  "version": "23.4",
  "status": "active",        // active | inactive
  "update_available": "23.5",
  "site_id": "site_01J7...",
  "env_id": "env_01J8..."
}

Components are environment-scoped by default: a plugin can be active on staging but not production, so calls live under /v1/sites/{siteID}/environments/{envID}/components. A site-level alias resolves to the production environment as a convenience.

the two gates

Every components call is checked twice. First the scope on your key — for example wp.plugins:write to install a plugin. Then the runtime capability the route requires — components.plugins. A key can hold a scope it can never use, because the capability simply isn’t present on a runtime that has no plugins.

404 vs 409 — two ways to say no

The split is deliberate. If a runtime structurally cannot hold the capability (a static site has no plugin model at all), the route returns 404 not_found — existence hiding, the capability isn’t there to address. If the route exists but this runtime can’t perform it, you get 409 capability.unsupported with param: "kind". Always discover capabilities before you branch on runtime — never hard-code if runtime == "wordpress".

endpoints

list components

GET …/{envID}/components  

wp.plugins:read

Note

Requires the components.plugins (or .themes / .modules) capability on the site’s runtime.

Parameter	Type	Required	Description
kind	string	no	Filter by plugin, theme, or module. Omit to list all kinds.
status	string	no	Filter by active or inactive.
limit	integer	no	Page size. See pagination.
cursor	string	no	Opaque cursor from a prior next_cursor.

cURL

List active plugins on staging

curl https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../components?kind=plugin&status=active \
  -H "Authorization: Bearer mfk_live_9aF2..." \
  -H "Forge-Version: 2026-06-23"

Go

List active plugins

comps, err := mf.Components.List(ctx, forge.ComponentListParams{
    SiteID: "site_01J7...",
    EnvID:  "env_01J8...",
    Kind:   forge.Plugin,
    Status: forge.Active,
})

TypeScript

List active plugins

const comps = await mf.components.list({
  siteId: "site_01J7...",
  envId: "env_01J8...",
  kind: "plugin",
  status: "active",
});

mf CLI

List active plugins

mf components list --env env_01J8... --kind plugin --status active

200 response

{
  "data": [
    { "id": "comp_01J9...", "kind": "plugin", "slug": "woocommerce",
      "version": "9.1.2", "status": "active", "update_available": null },
    { "id": "comp_01J9...", "kind": "plugin", "slug": "wordpress-seo",
      "version": "23.4", "status": "active", "update_available": "23.5" }
  ],
  "pagination": { "next_cursor": "eyJ0...", "has_more": false },
  "request_id": "req_01J9..."
}

install a component

POST …/{envID}/components  

wp.plugins:write

Returns 202 Accepted with a job — installs are asynchronous. Send an Idempotency-Key so a retried request never installs twice.

Parameter	Type	Required	Description
kind	string	yes	plugin, theme, or module.
slug	string	yes	The component slug, e.g. wordpress-seo.
source	string	no	registry (default), or a signed artifact reference.
version	string	no	A pinned version, or latest (default).
activate	boolean	no	Activate immediately after install. Defaults to false.

update / change state

PATCH …/{envID}/components/{id}  

wp.plugins:write

Patch a component to update its version or flip its status between active and inactive. Returns 202 with a job.

remove a component

DELETE …/{envID}/components/{id}  

wp.plugins:write

Deactivates and removes the component. Returns 202 with a job.

Deletes are destructive

Removing a component drops its files and, for some plugins, its tables and options. Take a snapshot first, and prefer testing the removal on a preview environment before you run it against production.

batch (per-environment bulk)

POST …/{envID}/components:batch  

wp.plugins:write

Apply a set of component actions to one environment in a single call — the typed equivalent of a fleet plugin update. Each item carries its own action; the call returns one job whose result reports per-item outcomes.

Request body

{
  "operations": [
    { "action": "update", "kind": "plugin", "slug": "woocommerce", "version": "latest" },
    { "action": "update", "kind": "plugin", "slug": "wordpress-seo", "version": "latest" },
    { "action": "deactivate", "kind": "plugin", "slug": "hello-dolly" }
  ]
}

worked example — install a plugin on staging

Install Yoast SEO on a staging environment, then watch the job stream to completion.

1. Confirm the capability. Check the site advertises components.plugins before you branch — see capability discovery.

2. Send the install. A scope-pinned key, an idempotency key, and a 202 back.

   cURL

   Install Yoast on staging

   curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../components \
     -H "Authorization: Bearer mfk_live_9aF2..." \
     -H "Forge-Version: 2026-06-23" \
     -H "Idempotency-Key: 6f1c-44a0-9e2b" \
     -H "Content-Type: application/json" \
     -d '{ "kind": "plugin", "slug": "wordpress-seo", "source": "registry", "version": "latest", "activate": true }'

   Go

   Install Yoast on staging

   job, err := mf.Components.Install(ctx, forge.ComponentInstallParams{
       SiteID:         "site_01J7...",
       EnvID:          "env_01J8...",
       Kind:           forge.Plugin,
       Slug:           "wordpress-seo",
       Version:        "latest",
       Activate:       true,
       IdempotencyKey: "6f1c-44a0-9e2b",
   })

   TypeScript

   Install Yoast on staging

   const job = await mf.components.install(
     { siteId: "site_01J7...", envId: "env_01J8..." },
     { kind: "plugin", slug: "wordpress-seo", version: "latest", activate: true },
     { idempotencyKey: "6f1c-44a0-9e2b" },
   );

   mf CLI

   Install Yoast on staging

   mf components install \
     --env env_01J8... \
     --kind plugin --slug wordpress-seo --activate --wait

   202 response

   HTTP/1.1 202 Accepted
   Location: /v1/jobs/job_01J9...
   X-RateLimit-Limit: 100
   X-RateLimit-Remaining: 99
   
   {
     "data": {
       "id": "job_01J9...", "type": "component.install", "status": "queued",
       "created_at": "2026-06-23T18:04:11.412Z",
       "resource": { "type": "component", "kind": "plugin", "slug": "wordpress-seo",
                     "site_id": "site_01J7...", "env_id": "env_01J8..." }
     },
     "request_id": "req_01J9..."
   }

3. Tail the job. Follow it to succeeded over SSE, or ETag long-poll from CI. See async jobs for both paths.

   Live-tail the install

   curl -N https://api.managed.dev/v1/jobs/job_01J9.../stream \
     -H "Authorization: Bearer mfk_live_9aF2..."

The same call against a static site returns 409 capability.unsupported — there are no plugins to install. That’s the capability gate doing its job.

Next steps

Capability discoveryAsk a site what it can do before you call a capability-gated route.

Runtimes & capabilitiesThe full catalog of runtimes and the capabilities each one advertises.

Async jobsHow 202 jobs work, plus SSE streaming and ETag long-poll.

ScopesThe wp.* product scopes that gate the dynamic application layer.