# List plugin agents

> The subagents installed plugins brought, as templates to hire an agent from: each with its ref (plugin:agent), plugin, marketplace, name, description, the system prompt as prompt, and its model, skills and tools.

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

Members only.

Each is a subagent file (`agents/&lt;name>.md`) from an installed, switched-on plugin: its front matter as fields and its body as `prompt`. They are listed under Agents → Templates, From plugins, to hire an agent from.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`customize`](/reference/mcp/#customize) with `action` `list_plugin_agents`, 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. |

## Example request

```sh
curl https://api.g1t.sh/workspaces/flagon-io/customize/agents \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
[
  {
    "ref": "release-notes:release-writer",
    "plugin": "release-notes",
    "marketplace": "flagon-tools",
    "name": "release-writer",
    "description": "Drafts a release's notes and asks a maintainer to check them.",
    "prompt": "You write release notes…",
    "model": null,
    "skills": [
      "release-notes"
    ],
    "tools": [
      "Read",
      "Grep"
    ]
  }
]
```

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