> ## 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.

# Marketplace skills

> Marketplace skill routes — list and publish a skill, edit and transfer the listing, search the catalog, and install, update, and uninstall on an agent

Marketplace skills are single [skills](/concepts/skills-and-tools) listed for other agents to install. These routes list a skill on the marketplace, publish and unpublish its versions, edit and transfer the listing, search and read the catalog, and install, update, uninstall, and list marketplace skills on an agent. For a whole agent, use [agent templates](/reference/rest/agent-templates). The CLI twin is [`lua marketplace skill`](/reference/cli/marketplace).

*Verified against lua-cli 3.33.0.*

## Base URL and authentication

Listing checks `automations:write` on the skill's agent; publishing, unpublishing, unlisting, and editing check `automations:write` as the creator; installs, updates, and uninstalls check `automations:write` on the agent, and reading an agent's or an organization's installs checks `automations:read` on it. Ownership transfers check `org:manage`. Catalog reads need only an authenticated key and are visibility-filtered: a private skill is visible only to its creator organization. The host, the bearer header, the error envelope, and the catalog rate limits are on the [REST API overview](/reference/rest/overview).

## Marketplace skill object

A skill object carries `id, name, displayName, description, longDescription?, category?, tags, creatorId, creatorOrgId?, ownershipStatus: "active" | "quarantined", sourceSkillId, listed, visibility, verified, featured, published, installCount, activeInstallCount, iconUrl?, screenshots?, repositoryUrl?, documentationUrl?, listedAt?, createdAt, updatedAt, versions[], versionsCount, pendingVersionsCount, approvedVersionsCount`. A version carries `id, marketplaceSkillId, version, description, changelog?, context?, tools?, envVarsMetadata?, approvalStatus, published, approvalNotes?, approvedBy?, approvedAt?, createdBy, createdAt`.

## Endpoints

### POST /marketplace/skills/list

Lists a skill on the marketplace. Scope `automations:write` on the skill's agent. Equivalent: `lua marketplace skill list`.

<ParamField body="skillId" type="string" required>The skill to list.</ParamField>
<ParamField body="displayName" type="string" required>Display name.</ParamField>
<ParamField body="category" type="string">Category.</ParamField>
<ParamField body="tags" type="string[]">Tags.</ParamField>
<ParamField body="longDescription" type="string">Detailed description.</ParamField>
<ParamField body="iconUrl" type="string">Icon URL.</ParamField>
<ParamField body="screenshots" type="string[]">Screenshot URLs.</ParamField>
<ParamField body="repositoryUrl" type="string">Repository URL.</ParamField>
<ParamField body="documentationUrl" type="string">Documentation URL.</ParamField>
<ParamField body="visibility" type="string">`public` or `private`.</ParamField>

**Response**

`201` with the [skill object](#marketplace-skill-object).

### POST /marketplace/skills/:id/versions/publish

Publishes a version of the listed skill. Scope `automations:write`, creator. Equivalent: `lua marketplace skill publish`.

<ParamField body="versionId" type="string" required>The skill version to publish.</ParamField>
<ParamField body="changelog" type="string">What changed in this version.</ParamField>
<ParamField body="envVars" type="object">Env variables the skill needs, keyed by name; each `{ description, required, example? }`.</ParamField>

**Response**

`201`.

### PUT /marketplace/skills/:id/versions/:versionId/publish

Publishes the version named in the path. Scope `automations:write`, creator.

**Response**

`200`.

### PUT /marketplace/skills/:id/unpublish

Unpublishes a version. Scope `automations:write`, creator. Equivalent: `lua marketplace skill unpublish`.

<ParamField body="versionId" type="string" required>The version to unpublish.</ParamField>

**Response**

`200` with `{ success, message, skillUnlisted, versionId }`.

### PUT /marketplace/skills/:id/unlist

Unlists the skill. Scope `automations:write`, creator. Equivalent: `lua marketplace skill unlist`.

**Response**

`200` with `{ success, message, unlisted, versionsUnpublished }`.

### PATCH /marketplace/skills/:id

Edits the listing. Scope `automations:write`, creator. Equivalent: `lua marketplace skill edit`.

<ParamField body="displayName" type="string">Display name.</ParamField>
<ParamField body="description" type="string">Short description.</ParamField>
<ParamField body="longDescription" type="string">Detailed description.</ParamField>
<ParamField body="category" type="string">Category.</ParamField>
<ParamField body="tags" type="string[]">Tags.</ParamField>
<ParamField body="iconUrl" type="string">Icon URL.</ParamField>
<ParamField body="screenshots" type="string[]">Screenshot URLs.</ParamField>
<ParamField body="repositoryUrl" type="string">Repository URL.</ParamField>
<ParamField body="documentationUrl" type="string">Documentation URL.</ParamField>

**Response**

`200`.

### PUT /marketplace/skills/:id/owner

Transfers the listing to another organization. Scope `org:manage`. Equivalent: `lua marketplace skill transfer`.

<ParamField body="newOrgId" type="string" required>The receiving organization.</ParamField>

**Response**

`200`.

### GET /marketplace/skills

Searches the catalog. Any authenticated key; visibility-filtered. Equivalent: `lua marketplace skill search`.

<ParamField query="listed" type="boolean">Filter by listed state.</ParamField>
<ParamField query="verified" type="boolean">Filter by verified state.</ParamField>
<ParamField query="featured" type="boolean">Filter by featured state.</ParamField>
<ParamField query="category" type="string">Filter by category.</ParamField>
<ParamField query="search" type="string">Free-text search.</ParamField>
<ParamField query="name" type="string">Filter by name.</ParamField>
<ParamField query="creatorId" type="string">Filter by creator.</ParamField>
<ParamField query="publishedVersionsOnly" type="boolean">Return only skills with a published version.</ParamField>
<ParamField query="page" type="number">Page number.</ParamField>
<ParamField query="limit" type="number" default={10}>Page size. At most 100.</ParamField>

**Response**

`200` with `{ data, pagination: { currentPage, totalPages, totalCount, limit, hasNextPage, hasPrevPage, nextPage, prevPage } }`, each `data` entry a [skill object](#marketplace-skill-object).

### GET /marketplace/skills/:id

Returns one skill. Any authenticated key; visibility-filtered. Equivalent: `lua marketplace skill view`.

**Response**

`200` with the [skill object](#marketplace-skill-object).

### GET /marketplace/skills/:id/versions

Lists a skill's versions. Any authenticated key; visibility-filtered.

<ParamField query="includeUnapproved" type="boolean">Include versions that are not yet approved.</ParamField>

**Response**

`200` with version objects.

### GET /marketplace/creator/skills

Lists the caller's own listings. Any authenticated key. Equivalent: `lua marketplace skill mine`.

**Response**

`200` with skill objects.

### GET /marketplace/orgs/:orgId/skills

Lists an organization's listings. Scope `automations:read` on the organization. Equivalent: `lua marketplace skill org`.

**Response**

`200` with skill objects.

### POST /marketplace/install/:id/:agentId

Installs a marketplace skill on an agent. Scope `automations:write` on the agent. Equivalent: `lua marketplace skill install`.

<ParamField body="versionId" type="string">Version to install. Defaults to the active version.</ParamField>
<ParamField body="envVars" type="object">Env values the skill needs, keyed by name.</ParamField>

**Response**

`201` with the resulting skill on the agent.

### PUT /marketplace/install/:id/:agentId

Moves an installed skill to another version or changes its env values; same body as install. Scope `automations:write` on the agent. Equivalent: `lua marketplace skill update`.

**Response**

`200`.

### DELETE /marketplace/install/:id/:agentId

Uninstalls the skill from the agent. Scope `automations:write` on the agent. Equivalent: `lua marketplace skill uninstall`.

**Response**

`200` with the removed skill.

### GET /marketplace/installations/:agentId

Lists the marketplace skills installed on an agent. Scope `automations:read` on the agent. Equivalent: `lua marketplace skill installed`.

**Response**

`200` with the installed skills.

## Errors

| Status | Code or message      | Meaning                                                                                            | Fix              |
| ------ | -------------------- | -------------------------------------------------------------------------------------------------- | ---------------- |
| `403`  | `INSUFFICIENT_SCOPE` | The key lacks the scope the route declares on the agent or organization; `requiredScope` names it. | Grant the scope. |

## See also

* [Agent templates](/reference/rest/agent-templates) — publish, install, and deploy a whole agent
* [Template fleet](/reference/rest/template-fleet) — apply runs, ledger, health, outcomes, evals
* [Publish and install marketplace skills](/marketplace/skills) — the how-to
* [`lua marketplace`](/reference/cli/marketplace) — the CLI twin