> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Template fleet

> Agent template fleet routes — apply a version to installed agents, poll apply runs, read the installs ledger and health rollup, outcomes, and evals

These routes are the creator's view of every agent that has an [agent template](/concepts/agent-templates) installed: push a version to installed agents and poll the run, read the installs ledger and the health rollup, retry a failed install, read outcome counters, and manage the eval set and its runs. Creating, publishing, installing, and deploying are on [Agent templates](/reference/rest/agent-templates). The CLI twin is [`lua marketplace template`](/reference/cli/marketplace).

*Verified against lua-cli 3.33.0.*

## Base URL and authentication

Every route is creator-organization only: reads check `marketplace:read` and writes check `automations:write`, both resolved against the template's creator organization. The host, the bearer header, and the error envelope are on the [REST API overview](/reference/rest/overview).

## Endpoints

### POST /marketplace/templates/:templateId/apply

Pushes a version to an explicit list of installed agents asynchronously. Scope `automations:write`, creator organization. Equivalent: `lua marketplace template apply`. Unknown body fields are stripped; `migrateRuns` answers `403` `NOT_VERSION_OWNER` on this route and belongs on install from the installing organization.

<ParamField body="version" type="number">Template version to apply.</ParamField>
<ParamField body="targets" type="string[]" required>Agent IDs to apply to. At most 500.</ParamField>

**Response**

`201` with `{ runId }`.

### GET /marketplace/templates/:templateId/apply-runs/:runId

Returns an apply run. Scope `marketplace:read`, creator organization. `lua marketplace template apply` polls it unless `--no-wait` is given. A publish that fans out to consenting installs also creates a run; its ID is `autoApplyRunId` on the publish response.

**Response**

`200` with `{ id, templateId, templateVersion, initiatedBy, targets: [{ agentId, status: "pending" | "applied" | "already_current" | "failed", localAgentVersion?, error? }], status, startedAt, finishedAt?, trigger?: "manual" | "auto-publish" | "auto-publish-chunk", leadRunId?, approvedBy? }`.

### GET /marketplace/templates/:templateId/installs

The installs ledger: one row per agent the template is installed on. Scope `marketplace:read`, creator organization. Equivalent: `lua marketplace template status`.

<ParamField query="page" type="number">Page number.</ParamField>
<ParamField query="limit" type="number">Page size.</ParamField>

**Response**

`200` with an array of [install results](/reference/rest/agent-templates#install-result).

### GET /marketplace/templates/:templateId/installs/health

The health rollup per install and per installed workflow. Scope `marketplace:read`, creator organization. Equivalent: `lua marketplace template health`.

<ParamField query="windowDays" type="number">Reporting window in days.</ParamField>
<ParamField query="cursor" type="string">`nextCursor` from the previous page.</ParamField>
<ParamField query="limit" type="number">Page size. At most 100.</ParamField>

**Response**

`200` with `{ templateId, windowDays, installs: [{ templateInstallId, agentId, orgId, installedVersion, workflows: [{ key, displayName, workflowId, active, capabilityInert, scheduleStatus: "active" | "paused" | "failed" | "none", runs: { inFlight, gated, suspended, terminals: { completed, failed, timedOut, cancelled, abandoned }, last?, lastFailure? }, autoDisabledAt? }] }], nextCursor? }`.

### POST /templates/:templateId/installs/:agentId/retry

Re-runs an `apply_failed` install without forging installer consent. Scope `automations:write`, creator organization.

**Response**

`201` with the [install result](/reference/rest/agent-templates#install-result).

### GET /marketplace/templates/:templateId/outcomes

Outcome counters per unit. Scope `marketplace:read`, creator organization. The counters are separate populations, never summed; only `verified` is badge-grade.

<ParamField query="from" type="string">Start of the window.</ParamField>
<ParamField query="to" type="string">End of the window.</ParamField>

**Response**

`200` with `{ templateId, from?, to?, units: [{ key, title, unitLabel?, recorded, settled, verified, reversed, inertCapabilities? }] }`.

### PUT /marketplace/templates/:templateId/eval-set

Replaces the whole eval set and bumps `revision`. Scope `automations:write`, creator organization.

<ParamField body="jsonl" type="string" required>The eval set as JSONL.</ParamField>

**Response**

`200` with the eval set, in the shape the read route returns.

### GET /marketplace/templates/:templateId/eval-set

Returns the eval set. Scope `marketplace:read`, creator organization.

**Response**

`200` with `{ templateId, revision, minPassRate, caseCount, monitorCount, cases, monitors, updatedAt }`.

### POST /marketplace/templates/:templateId/eval-runs

Starts an eval run. Scope `automations:write`, creator organization.

<ParamField body="agentId" type="string">Agent to run the set against. Defaults to the source agent; must belong to the creator organization.</ParamField>

**Response**

`201` with `{ runId }`.

### GET /marketplace/templates/:templateId/eval-runs

Lists eval runs. Scope `marketplace:read`, creator organization.

<ParamField query="page" type="number">Page number.</ParamField>
<ParamField query="limit" type="number">Page size.</ParamField>

**Response**

`200` with eval runs, each `{ id, templateId, agentId, evalSetRevision, sourceAgentVersion?, status, cases, passRate?, passed?, initiatedBy, startedAt, finishedAt? }`.

### GET /marketplace/templates/:templateId/eval-runs/:runId

Returns one eval run, in the same shape as a list entry. Scope `marketplace:read`, creator organization.

## Errors

Apply and the creator retry share the install error envelope and codes on [Agent templates](/reference/rest/agent-templates#errors). Specific to these routes:

| Status | Code or message      | Meaning                                                                                           | Fix                                                  |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `403`  | `INSUFFICIENT_SCOPE` | The key lacks the scope the route declares on the creator organization; `requiredScope` names it. | Grant the scope.                                     |
| `403`  | `NOT_VERSION_OWNER`  | `migrateRuns` sent on the apply route.                                                            | Send it on install from the installing organization. |

## See also

* [Agent templates](/reference/rest/agent-templates) — publish, install, deploy, the install and deploy results
* [Marketplace skills](/reference/rest/marketplace-skills) — single skills listed on the marketplace
* [Install and apply a template](/marketplace/install-and-apply) — rolling a version out from the CLI
* [Check fleet health](/marketplace/fleet-health) — reading the health rollup
* [`lua marketplace`](/reference/cli/marketplace) — the CLI twin