# Make a workflow from a template

**POST** `/api/templates/{id}/use`

Makes a new workflow in this workspace from a template.

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

## Parameters

### Path

- `id` · Required · UUID: The template’s ID.

### Headers

- `Idempotency-Key` · Optional · string: Up to 255 characters. The same request with the same key within 24 hours answers the first result again, instead of making a second workflow.

### Body

Optional. Nothing makes a draft named after the template.

- `name` · Optional · string: Up to 255 characters, trimmed. Blank: the template’s name.
- `connections` · Optional · object: A connection of this workspace for each slot: `{"c1": "…"}`. It must be for the slot’s service.
- `values` · Optional · object: Fill-ins, by step name and field: `{"step": {"field": value}}`. A step or field the template lacks is refused.
- `publish` · Optional · boolean: `true` turns the workflow on when it can run, as [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow) does. Needs the **Publish** permission.
- `folderId` · Optional · UUID or null: A folder of this workspace to file it in.

## Connections, by slot

A template needs one connection for each service account its steps use: its slots, `c1`, `c2`… [Preview using it](https://docs.gorunner.io/api/templates/preview-template-use) lists them with the connections that could fill each.

A slot you don’t name keeps the template’s own connection where it exists here. Otherwise its steps arrive without one, and `install.missing` lists the slot.

## When publish is refused

A refused turn-on is not an error. The draft is made, the answer is still 201, and `install.publishRefusal` says why: `CONNECTION_NOT_WORKING` when a chosen connection isn’t working, or what Publish a workflow would answer.

A value tied to the account the template was saved with, such as a choice filled from it, arrives blank outside the workspace it was saved in. An expression never does.

## Responses

- 201 Created

  The new workflow, a draft or live, and `install`: what was done.

- 400 `VALIDATION_ERROR`

  The body isn’t JSON, the name is over 255 characters, `connections` names a slot the template lacks or a connection outside the workspace, `folderId` isn’t a folder here, `values` names a step or field the template lacks, the template holds a condition operator that doesn’t exist or a step name or display name over 255 characters, or `Idempotency-Key` is over 255 characters.

- 403 `FORBIDDEN`

  The token lacks the **Write** permission for workflows, or `publish` is `true` without **Publish**. Nothing is made.

- 403 `FEATURE_OFF`

  A token made inside a partner’s product, with the `publish` or `folders` switch off (`details.switch`).

- 403 `ACCOUNT_SUSPENDED`

  The workspace’s account is suspended. Nothing is made.

- 404 `NOT_FOUND`

  No template with this ID that this workspace may use. An ID that isn’t a UUID answers this too.

- 409 `CONFLICT`

  A request with this `Idempotency-Key` is still in progress, or its answer was too large to keep.

- 409 `ACCOUNT_DELETED`

  The workspace’s account was deleted.

- 422 `VALIDATION_ERROR`

  The template uses an app, or an app version, this installation can’t run.

- 422 `VALIDATION_ERROR`

  This `Idempotency-Key` was already used with a different request.

- 422 `PIECE_NOT_ALLOWED`

  A step uses an app this workspace may not use.

- 422 `CONNECTION_MISMATCH`

  A connection named for a slot is for another service (`details.slot`).

- 500 `INTERNAL_ERROR`

  The template or the workspace’s connections couldn’t be read, or the workflow couldn’t be made.

- 503 `STATE_UNAVAILABLE`

  The account’s state couldn’t be read. Nothing was made.

- 503 `PIECES_UNAVAILABLE`

  GoRunner couldn’t check which apps this workspace may use. Nothing was made.

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 EMBED_NOT_ALLOWED`](https://docs.gorunner.io/errors#EMBED_NOT_ALLOWED) · [`403 EMBED_NOT_AVAILABLE`](https://docs.gorunner.io/errors#EMBED_NOT_AVAILABLE) · [`413 PAYLOAD_TOO_LARGE`](https://docs.gorunner.io/errors#PAYLOAD_TOO_LARGE) · [`415 INVALID_CONTENT_TYPE`](https://docs.gorunner.io/errors#INVALID_CONTENT_TYPE) · [`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 Write for workflows
TEMPLATE_ID="your-template-id"

curl -X POST "$GORUNNER/api/templates/$TEMPLATE_ID/use" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order intake — EU",
    "connections": {
      "c1": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b"
    },
    "publish": true
  }'
```

**JavaScript**

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

const res = await fetch(
  `${GORUNNER}/api/templates/${TEMPLATE_ID}/use`,
  {
    method: "POST",
    headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
    body: JSON.stringify({
        name: "Order intake — EU",
        connections: {
          c1: "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
        },
        publish: true,
      }),
  },
);
const { data } = await res.json();
```

**Python**

```python
import os, uuid, requests

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

res = requests.post(
    f"{GORUNNER}/api/templates/{TEMPLATE_ID}/use",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "name": "Order intake — EU",
      "connections": {
        "c1": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
      },
      "publish": True,
    },
)
data = res.json()["data"]
```

Response · 201 Created, shortened

```json
{
  "data": {
    "id": "6e9a1c3f-8b2d-4a57-9e0c-3f7b5d1a8c42",
    "name": "Order intake — EU",
    "status": "active",
    "triggerType": "webhook",
    "webhookToken": "2f4c8e1a-6b3d-4f7e-9a05-c1d2e3f4a5b6",
    "install": {
      "published": true,
      "publishRefusal": null,
      "missing": []
    }
  }
}
```

**Every field**

### Body

- `name` · Optional · string: Optional name for the new workflow; trimmed. Blank or absent uses the template’s name. Max 255 characters.
- `connections` · Optional · object: Slot key → a connection of this workspace made for the slot’s service.
  - `{key}` · UUID: Each key’s value.
- `publish` · Optional · boolean: Turn the new workflow on when it can run. Needs `workflow:publish`. A refused turn-on keeps the draft and is reported in `install.publishRefusal`. Default `false`.
- `folderId` · Optional · UUID or null: A folder of this workspace to file the new workflow in.
- `values` · Optional · object: The person’s fill-ins: step name → input key → value, written over the template’s values. A blank value (`""`, null, `[]`) leaves the field blank. A step or input the template does not have is refused 400 (`details.field: values`, `details.step`, `details.input`).
  - `{key}` · object: Each key’s value.

### Response · 201 Created

- `data` · object: The workflow created from a template — the same shape the workflows API returns — and what the install did.
  - `id` · UUID
  - `name` · string
  - `description` · string: Copied from the template.
  - `definition` · object: The template’s snapshot with its connection slots filled (steps of a slot left empty, and any other connection this workspace cannot resolve, carry no connection), and previously-unpinned steps on the fleet’s current app versions. A workflow definition: its fields are in [Workflow definition](https://docs.gorunner.io/api/workflow-definition).
  - `status` · string: `draft`, or `active` when `publish` turned it on. One of `draft`, `active`, `paused`.
  - `triggerType` · string: Copied from the template.
  - `webhookToken` · string: Present for a webhook workflow that `publish` turned on: the secret segment of the public webhook URL. Treat it as a credential.
  - `folderId` · UUID: The folder it was filed in, when `folderId` was sent.
  - `tags` · array of strings
  - `hasUnpublishedChanges` · boolean
  - `workspaceId` · UUID
  - `orgId` · UUID
  - `createdBy` · UUID
  - `createdAt` · time
  - `updatedAt` · time
  - `install` · object: What using the template did, beside the workflow it made.
    - `published` · boolean: The new workflow was turned on.
    - `publishRefusal` · object or null: Why `publish` did not publish it: `CONNECTION_NOT_WORKING` when a chosen connection is `error`, `expired` or `pending` (the workflow is made as a draft), else the `{code, message}` `POST /api/workflows/{id}/publish` answers (`VALIDATION_ERROR`, `PIECE_NOT_ALLOWED`, `PIECES_UNAVAILABLE`). null when it did, or was not asked.
      - `code` · string
      - `message` · string
    - `missing` · array of objects: Slots left without a connection.
      - `key` · string: The slot’s name in this template (`c1`, `c2`, … in the order the steps first use it).
      - `pieceId` · string: The service a connection for this slot must be for.
      - `steps` · array of strings: The steps that use it; `trigger` for the trigger.
  - `latestVersionId` · UUID or null: Present when `publish` turned it on: the published version.
  - `definitionRev` · integer: Present when `publish` turned it on.
  - `testPayloads` · object or null: Present, null, when `publish` turned it on.

Related: [Preview using a template](https://docs.gorunner.io/api/templates/preview-template-use) · [List templates](https://docs.gorunner.io/api/templates/list-templates) · [Templates for customers](https://docs.gorunner.io/embed/templates)

Source: https://docs.gorunner.io/api/templates/use-template