# Get a plugin

> One plugin's page by ref (name@marketplace, URL-encoded in a path: @ as %40), installed or not: its marketplace listing, its install if any, its components and readme read from its source, its manifest, its subagents in full (agents) for hiring from, problems, and the marketplace it is listed in (source).

<div class="g1t-endpoint"><span class="g1t-method" data-method="get">GET</span><code>/workspaces/{workspace}/customize/plugins/{ref}</code></div>

Reads the plugin's files, so it takes a moment. Members only.

In the path, `ref` is URL-encoded: `release-notes%40flagon-tools`. `install` is null until the workspace installs it. `components`, `readme`, `manifest` and `agents` are read from the plugin's source at the commit the listing names, so this takes a moment; for an `unavailable` plugin they are null or empty and `problems` says why.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`customize`](/reference/mcp/#customize) with `action` `get_plugin`, and the same inputs
- **Scope:** An access token needs [`workspace:read`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | Yes | The workspace's slug. |
| `ref` | string | Yes | The plugin as name@marketplace, such as commit-commands@claude-plugins-official. |

## Example request

```sh
curl https://api.g1t.sh/workspaces/flagon-io/customize/plugins/release-notes%2540flagon-tools \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "listing": {
    "ref": "release-notes@flagon-tools",
    "name": "release-notes",
    "marketplace": "flagon-tools",
    "display_name": "Release notes",
    "description": "Writes release notes from merged pull requests.",
    "version": "0.3.1",
    "author": "Flagon",
    "homepage": "https://g1t.sh/flagon-io/plugins",
    "category": "docs",
    "tags": [],
    "keywords": [
      "releases"
    ],
    "fetch": {
      "kind": "g1t",
      "repo": "flagon-io/plugins",
      "ref": null,
      "path": "plugins/release-notes"
    },
    "availability": {
      "kind": "available"
    },
    "skills": [
      "release-notes"
    ]
  },
  "install": null,
  "components": {
    "skills": [
      {
        "name": "release-notes",
        "description": "Write release notes from the pull requests merged since the last tag.",
        "path": "skills/release-notes/SKILL.md"
      }
    ],
    "agents": [
      {
        "name": "release-writer",
        "description": "Drafts a release's notes and asks a maintainer to check them.",
        "path": "agents/release-writer.md"
      }
    ],
    "commands": [],
    "mcp_servers": [
      {
        "name": "linear",
        "type": "http",
        "url": "https://mcp.linear.app/mcp",
        "remote": true
      }
    ],
    "hooks": false,
    "lsp": false,
    "bin": false,
    "output_styles": false
  },
  "readme": "# Release notes\n\nWrites release notes from merged pull requests…",
  "manifest": {
    "name": "release-notes",
    "version": "0.3.1",
    "license": "MIT",
    "repository": "https://g1t.sh/flagon-io/plugins"
  },
  "agents": [
    {
      "name": "release-writer",
      "description": "Drafts a release's notes and asks a maintainer to check them.",
      "tools": [
        "Read",
        "Grep"
      ],
      "model": null,
      "skills": [
        "release-notes"
      ],
      "prompt": "You write release notes…"
    }
  ],
  "problems": [],
  "source": {
    "marketplace": "flagon-tools",
    "owner": "Flagon"
  }
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |