# Recipes

Base URL `https://pfcloud.pfctek.com/api/v1`. Every call needs `Authorization: Bearer mf_…`. Changes accept an `Idempotency-Key` header. Ids are public ids (UUIDs).

## GET /servers/{server}/recipe-runs

**List recipe runs on a server**

Scope: `servers:read`

Needs the manage-servers permission.

| Parameter | In | Description |
| --- | --- | --- |
| `server` | path | Public id from the dashboard address (required) |

## GET /recipes

**List recipes**

Scope: `servers:read`

The team’s recipes with their scripts. Needs the manage-servers permission.

## POST /recipes

**Create a recipe**

Scope: `servers:write`

Needs the manage-servers permission; not for tokens limited to some servers.

| Body field | Type | Description |
| --- | --- | --- |
| `name` | string |  |
| `run_as` | string | root, myforge or a site’s user |
| `script` | string |  |

## GET /recipes/{recipe}

**Get a recipe**

Scope: `servers:read`

| Parameter | In | Description |
| --- | --- | --- |
| `recipe` | path | Public id of the recipe (required) |

## PUT /recipes/{recipe}

**Change a recipe**

Scope: `servers:write`

| Parameter | In | Description |
| --- | --- | --- |
| `recipe` | path | Public id of the recipe (required) |

| Body field | Type | Description |
| --- | --- | --- |
| `name` | string |  |
| `run_as` | string |  |
| `script` | string |  |

## DELETE /recipes/{recipe}

**Delete a recipe**

Scope: `servers:write`

Its past runs stay in the servers’ logs.

| Parameter | In | Description |
| --- | --- | --- |
| `recipe` | path | Public id of the recipe (required) |

## GET /recipes/{recipe}/runs

**List a recipe’s runs**

Scope: `servers:read`

Only runs on servers this token can reach.

| Parameter | In | Description |
| --- | --- | --- |
| `recipe` | path | Public id of the recipe (required) |

## POST /recipes/{recipe}/runs

**Run a recipe on servers**

Scope: `servers:write`

Sends the script as it is now; one run per server, logged on each server.

| Parameter | In | Description |
| --- | --- | --- |
| `recipe` | path | Public id of the recipe (required) |

| Body field | Type | Description |
| --- | --- | --- |
| `servers` | array | Public ids of connected servers |