# List templates

**GET** `/api/templates`

Lists the templates this workspace may use.

Needs [an API token](https://docs.gorunner.io/api/authentication#scopes) with the **Read** permission for workflows (`workflow:read`).

## Parameters

### Query

- `view` · Optional · string: `summary` leaves out each row’s `definition` and `createdBy`. Any other value is refused.

## Whose templates

In an organization, every template saved in any of its workspaces: `scope: org`.

In a partner’s customer account, only those saved in this workspace (`workspace`) and, while the license includes Embed, those the installation shares with its customers (`installation`), newest first. See [Templates for customers](https://docs.gorunner.io/embed/templates).

## What is left out or marked

A template with a step on an app this workspace may not use is left out. One on an app this installation doesn’t run is listed with `available: false` and `unavailable`, the reason. One that can’t be read is left out, or, with `view=summary`, shown with `readable: false` to someone who may delete it.

`slots` lists the connections a workflow made from it needs. `toFill` counts the values using it would ask for. `uses`, for its author and admins, counts the workflows made from it.

## Responses

- 200 OK

  The templates; the installation’s shared ones first. None answers `[]`.

- 400 `VALIDATION_ERROR`

  `view` isn’t `summary`.

- 403 `FORBIDDEN`

  The token lacks the **Read** permission for workflows.

- 500 `INTERNAL_ERROR`

  The list couldn’t be read. Try again.

- 503 `PIECES_UNAVAILABLE`

  GoRunner couldn’t check which apps this workspace may use. Try again.

Any call can also answer: [`401 UNAUTHORIZED`](https://docs.gorunner.io/errors#UNAUTHORIZED) · [`401 TOKEN_ENDED`](https://docs.gorunner.io/errors#TOKEN_ENDED) · [`403 TOKEN_SURFACE_OFF`](https://docs.gorunner.io/errors#TOKEN_SURFACE_OFF) · [`403 FEATURE_OFF`](https://docs.gorunner.io/errors#FEATURE_OFF) · [`403 EMBED_NOT_ALLOWED`](https://docs.gorunner.io/errors#EMBED_NOT_ALLOWED) · [`403 EMBED_NOT_AVAILABLE`](https://docs.gorunner.io/errors#EMBED_NOT_AVAILABLE) · [`403 ACCOUNT_SUSPENDED`](https://docs.gorunner.io/errors#ACCOUNT_SUSPENDED) · [`429 RATE_LIMITED`](https://docs.gorunner.io/errors#RATE_LIMITED) · [`503 BUSY`](https://docs.gorunner.io/errors#BUSY) · [`503 PAUSED`](https://docs.gorunner.io/errors#PAUSED) · [`503 SERVICE_UNAVAILABLE`](https://docs.gorunner.io/errors#SERVICE_UNAVAILABLE). See [Errors](https://docs.gorunner.io/api/errors#by-status).

Request

**curl**

```bash
GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for workflows

curl "$GORUNNER/api/templates?view=summary" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"
```

**JavaScript**

```js
const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;

const res = await fetch(
  `${GORUNNER}/api/templates?view=summary`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();
```

**Python**

```python
import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]

res = requests.get(
    f"{GORUNNER}/api/templates",
    params={"view": "summary"},
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]
```

Response · 200 OK, shortened

```json
{
  "data": [
    {
      "id": "9c4e2a17-3d5b-4f86-b0e2-8a1c7d3f5e29",
      "scope": "org",
      "name": "Order intake",
      "description": "Webhook to fulfilment, with a VIP branch.",
      "category": "Sales",
      "triggerType": "webhook",
      "createdAt": "2026-10-20T08:00:00Z",
      "author": {
        "name": "Ada Lovelace",
        "left": false
      },
      "savedHere": true,
      "trigger": {
        "displayName": "Order received",
        "pieceId": "webhook",
        "actionId": "catch_webhook"
      },
      "marks": [
        "webhook",
        "http"
      ],
      "slots": [],
      "toFill": 0,
      "available": true,
      "canManage": true
    }
  ]
}
```

**Every field**

It takes no body.

### Response · 200 OK

- `data` · array of objects
  - `id` · UUID
  - `scope` · string: Who sees it: `org` — an organization’s, every workspace of it; `workspace` — a customer account’s, the workspace it was saved in only; `installation` — shared by the installation with its customer accounts (listed only in a customer account, and only while the license has embedding), read-only here. One of `org`, `workspace`, `installation`.
  - `key` · string: An installation template’s stable handle. Absent on every other template.
  - `name` · string
  - `description` · string: What it does, as saved. May be empty: `whenLine` then describes it.
  - `category` · string: Free-text grouping label; empty when none.
  - `triggerType` · string
  - `createdAt` · time
  - `updatedAt` · time
  - `publishedAt` · time: When an installation template was first offered. Absent on every other template.
  - `readable` · boolean: false: its definition cannot be read. Such a row is listed only to someone who may delete it (`canManage`), with everything derived from the definition empty.
  - `author` · object or null: Who saved it; null for an installation template.
    - `id` · UUID or null
    - `name` · string or null: Their name, else their email; null once the account is deleted.
    - `left` · boolean: They are no longer a member of this organization.
  - `source` · object or null: An installation template’s origin; null otherwise.
    - `organization` · string: The organization it was shared from; empty once that organization is gone.
  - `savedHere` · boolean: It was saved in this workspace. Otherwise its bound values arrive blank (see `TemplateFillField`).
  - `savedIn` · string or null: The workspace it was saved in (an installation template: the organization it was shared from); null when not recorded.
  - `sourceWorkflow` · object or null: The workflow it was saved (or last updated) from, while that workflow exists and is in this workspace.
    - `id` · UUID
    - `name` · string
  - `trigger` · object or null
    - `name` · string
    - `displayName` · string
    - `pieceId` · string
    - `actionId` · string
  - `marks` · array of strings: App ids in run order: the trigger’s, then one per step (branch steps `branch`, loops `loop`, a Code step `code`), never de-duplicated.
  - `steps` · array of objects: Every step, in the order of `marks` after the trigger.
    - `name` · string
    - `displayName` · string
    - `pieceId` · string
    - `actionId` · string
    - `type` · string: One of `PIECE`, `CODE`, `BRANCH`, `LOOP`.
    - `depth` · integer: 0 at the top level; one more inside a branch arm, a loop body or an error path.
  - `whenLine` · string: A generated line for a template without a description: how it starts, then its first three steps’ names.
  - `slots` · array of objects: The connections a workflow made from it needs, one per service account.
    - `key` · string
    - `pieceId` · string: The connection’s app (what `GET /api/connections` rows carry).
    - `pieceName` · string
    - `steps` · array of strings
    - `stepLabels` · array of strings
    - `connectionId` · string or null: The connection the template’s own steps name; null for an installation template or none.
  - `toFill` · integer: How many values using it here will ask for: required fields left blank and bound values blanked here.
  - `available` · boolean
  - `unavailable` · object or null: Why it cannot be used on this installation.
    - `code` · string: One of `PIECE_UNAVAILABLE`, `STEP_INCOMPLETE`, `ACTION_UNAVAILABLE`, `UNREADABLE`.
    - `message` · string
    - `step` · string: The step it is about, by name.
  - `uses` · object or null: Workflows of this organization made from it, and how many are live. Sent only to its author, an organization admin or a platform admin.
    - `workflows` · integer
    - `live` · integer
  - `canManage` · boolean: The caller may rename, update the steps of and delete it: its creator, an organization admin, or for a `workspace` template that workspace’s admin.
  - `createdBy` · UUID: Who saved it (`author` names them). Absent on an installation template, when the account is gone, and with `view=summary`.
  - `definition` · object: A workflow definition — the same document the workflow API uses (`schemaVersion` is 2). It is a TREE, not a list: `trigger` is the root and each node chains onward through `nextAction`; `branches[].firstAction` and `firstLoopAction` hold nested sub-chains, and `onErrorAction` holds a step’s error arm. A step’s settings live in `config`, never `settings`. The trigger names its trigger in a field called `actionId`, and trigger `type` is lowercase while action `type` is UPPERCASE (`PIECE`, `BRANCH`, `LOOP`, `CODE`). A step that uses credentials carries `connectionId` — a bare connection id, workspace-scoped, which is why it may be cleared when the template is used in another workspace. A workflow definition: its fields are in [Workflow definition](https://docs.gorunner.io/api/workflow-definition).

Related: [Get a template](https://docs.gorunner.io/api/templates/get-template) · [Make a workflow from a template](https://docs.gorunner.io/api/templates/use-template) · [Use and save templates](https://docs.gorunner.io/build/templates)

Source: https://docs.gorunner.io/api/templates/list-templates