> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/tools/techniques-and-actions.md).

# Technique and action tools

Reference for the FLORA MCP tools that find and run saved Techniques, and run prebuilt or custom actions headless or on a canvas.

These [FLORA MCP](https://flora.ai/mcp) tools run saved [Techniques](https://docs.flora.ai/nodes/techniques.md) (your team's multi-step workflows) and [actions](https://docs.flora.ai/nodes/action-node.md) (deterministic transforms such as crop, stitch and color grading). Techniques spend money on every run; actions are free but need a workspace plan that includes them. Actions run headless with inputs you pass ([`flora_run_action`](#flora_run_action)) or as a node on the canvas ([`flora_add_action`](#flora_add_action), then [`flora_run_canvas_action`](#flora_run_canvas_action)).

For a worked example, see [Run your team's Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md).

{% hint style="info" %}
**Polling rule.** Save every `run_id`. Wait at least 15 seconds between polls, or 2 seconds per run for bigger batches (40 seconds for 20 runs). Then read every `run_id` in one `flora_list_generations` call (up to 20 per call). For example: `flora_list_generations({"run_ids": ["run_a", "run_b"]})`. For Technique runs, also pass `"technique_id"`. Polling faster returns `429` or cooldown errors with `retry_after_seconds`.
{% endhint %}

| Tool                                                                  | What it does                                                                                                                        | Labels                                   |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [`flora_list_techniques`](#flora_list_techniques)                     | List saved Techniques with their declared inputs, outputs and run cost.                                                             | read-only                                |
| [`flora_get_technique`](#flora_get_technique)                         | Read one Technique's declared inputs and outputs.                                                                                   | read-only                                |
| [`flora_run_technique`](#flora_run_technique)                         | Run a saved Technique on your inputs.                                                                                               | writes, destructive, spends money, async |
| [`flora_list_technique_runs`](#flora_list_technique_runs)             | List past Technique runs with their status, cost and outputs.                                                                       | read-only                                |
| [`flora_search_actions`](#flora_search_actions)                       | Search the prebuilt action registry (crop, stitch, split, color grade and more) and read each action's inputs and params.           | read-only                                |
| [`flora_get_action`](#flora_get_action)                               | Read one prebuilt action's definition: its inputs, outputs and the params it accepts, with their types and defaults.                | read-only                                |
| [`flora_run_action`](#flora_run_action)                               | Run a prebuilt action headless on inputs you pass by URL or text. Nothing appears on the canvas.                                    | writes, destructive, async               |
| [`flora_add_action`](#flora_add_action)                               | Place a prebuilt action node on a canvas. It runs nothing until [`flora_run_canvas_action`](#flora_run_canvas_action) runs it.      | writes                                   |
| [`flora_open_action_studio`](#flora_open_action_studio)               | Open FLORA's action studio on a prebuilt action and the inputs you pass, without running it, so the user can tune its params first. | read-only                                |
| [`flora_create_custom_action`](#flora_create_custom_action)           | Add a custom action node to a canvas from Python or JavaScript code you write. The code is stored on the node, not run.             | writes                                   |
| [`flora_update_canvas_action`](#flora_update_canvas_action)           | Change an action node on a canvas in place: its label and params, and for a custom action its code, language and runtime.           | writes, destructive                      |
| [`flora_open_canvas_action_studio`](#flora_open_canvas_action_studio) | Open FLORA's action studio on an action node already on a canvas, without running it, so the user can tune its params first.        | read-only                                |
| [`flora_run_canvas_action`](#flora_run_canvas_action)                 | Run an action node that's already on a canvas, using the nodes wired into it as inputs.                                             | writes, destructive, async               |

## flora\_list\_techniques <a href="#flora_list_techniques" id="flora_list_techniques"></a>

List saved Techniques with their declared inputs, outputs and run cost.

**Labels:** read-only

**Shown in clients as:** List techniques

**Use when:** The user names a Technique or asks what workflows their team has saved.

**Don't use when:** You already have the `technique_id`: use [`flora_get_technique`](#flora_get_technique) for its inputs.

**Arguments**

| Argument       | Type   | Required | Notes                                                       |
| -------------- | ------ | -------- | ----------------------------------------------------------- |
| `workspace_id` | string | no       | Filter by workspace (ws\_…).                                |
| `query`        | string | no       | Filter by technique name.                                   |
| `limit`        | number | no       | Max items to return (default 20).                           |
| `cursor`       | string | no       | Pagination cursor from a previous call's meta.next\_cursor. |

**Returns:** A page of Techniques with their IDs (`tech_…`), inputs, outputs and `run_cost` in US dollars, and `meta.next_cursor`.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](https://docs.flora.ai/mcp/tools/workspaces-and-projects.md#flora_list_workspaces)

**Usually comes before:** [`flora_get_technique`](#flora_get_technique)

**Example prompt:** "What Techniques does my team have in FLORA?"

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "query": "background swap"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List saved techniques (reusable multi-step workflows) with their declared inputs, outputs, and run cost.
```

{% endcode %}

</details>

## flora\_get\_technique <a href="#flora_get_technique" id="flora_get_technique"></a>

Read one Technique's declared inputs and outputs.

**Labels:** read-only

**Shown in clients as:** Get technique

**Use when:** Right before [`flora_run_technique`](#flora_run_technique): the input IDs it returns are the keys `inputs` expects.

**Don't use when:** You don't have the ID yet: find it with [`flora_list_techniques`](#flora_list_techniques) or [`flora_list_technique_runs`](#flora_list_technique_runs).

**Arguments**

| Argument       | Type   | Required | Notes                            |
| -------------- | ------ | -------- | -------------------------------- |
| `technique_id` | string | yes      | Technique to describe (tech\_…). |

**Returns:** The Technique's `technique_id`, `name`, `description`, `run_cost` (US dollars per run), and its declared inputs (IDs and types) and outputs.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_techniques`](#flora_list_techniques)

**Usually comes before:** [`flora_run_technique`](#flora_run_technique)

**Example prompt:** "What inputs does our Background swap Technique need?"

**Example call:**

```json
{
  "technique_id": "tech_123"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Get one technique's declared inputs and outputs. Call this before flora_run_technique: the input ids it returns are the keys that tool's inputs map expects.
```

{% endcode %}

</details>

## flora\_run\_technique <a href="#flora_run_technique" id="flora_run_technique"></a>

Run a saved Technique on your inputs.

**Labels:** writes · destructive · spends money · async

**Shown in clients as:** Run technique

**Use when:** The user wants their team's saved workflow, such as a background swap, relight or upscale, applied to their images or text.

**Don't use when:** You don't know the input IDs: call [`flora_get_technique`](#flora_get_technique) first. For a one-off prompt without a saved workflow, use [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations).

{% hint style="info" %}
Media inputs must be public `https` URLs, or the call fails with `input_validation_error` (HTTP 400). During the run FLORA downloads media only from its own hosts (`media.flora.ai`, `ik.imagekit.io`) and a short storage allowlist, so a URL on another host is accepted and then fails partway: upload other files with [`flora_create_asset`](https://docs.flora.ai/mcp/tools/assets.md#flora_create_asset) and pass the `url` it returns. There's no `workspace_id` argument: the run bills the connection's workspace, and its outputs land in a private project FLORA keeps for that Technique.
{% endhint %}

**Arguments**

| Argument       | Type    | Required | Notes                                                                                                                                                                                                              |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `technique_id` | string  | yes      | Technique to run (tech\_…).                                                                                                                                                                                        |
| `inputs`       | object  | yes      | Input values keyed by the technique's input ids.                                                                                                                                                                   |
| `open_only`    | boolean | no       | Open the FLORA action studio on these inputs without running or billing: the user's Apply runs the technique once (each Apply bills run\_cost). Hosts without MCP Apps cannot show the studio; leave it out there. |

**Returns:** Starts the run right away and returns its `run_id`. Poll it with [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations), passing the same `technique_id`. In clients that show FLORA's in-chat views (MCP Apps hosts such as Claude and ChatGPT), the action studio also opens on that run and waits for it, so don't poll there; Apply runs it again. With `open_only: true` nothing runs until the user clicks Apply, and `run_id` is null.

**Cost:** Spends the Technique's `run_cost` on every run (returned by [`flora_get_technique`](#flora_get_technique) and [`flora_list_techniques`](#flora_list_techniques)). Tell the user the cost in US dollars first: without `open_only`, the call itself starts and bills a run, and each Apply in the studio bills again. With `open_only: true` nothing is billed until the user clicks Apply.

**Usually comes after:** [`flora_get_technique`](#flora_get_technique), [`flora_create_asset`](https://docs.flora.ai/mcp/tools/assets.md#flora_create_asset)

**Usually comes before:** [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations)

**Example prompt:** "Run our Background swap Technique on this product photo with a beach backdrop."

**Example call:**

```json
{
  "technique_id": "tech_123",
  "inputs": {
    "input_image": "https://media.flora.ai/example/product.png",
    "backdrop": "Sunny beach at noon"
  }
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Run a saved technique. SPENDS USAGE. inputs is a map keyed by the input ids from flora_get_technique, valued with text or asset URLs; each value is sent as the type the technique declares for that input. URL-typed (media) inputs must use FLORA-hosted or allowlisted media URLs. Upload external media first with flora_create_asset and pass its returned url. Returns a run_id — poll it with flora_list_generations, passing this same technique_id. In MCP Apps hosts the call opens the FLORA action studio, where the user edits the technique's inputs and clicks Apply to run it (each Apply bills run_cost); pass open_only: true to open it without running anything. The studio waits for the run and hands you its run id, status, outputs and final inputs.
```

{% endcode %}

</details>

## flora\_list\_technique\_runs <a href="#flora_list_technique_runs" id="flora_list_technique_runs"></a>

List past Technique runs with their status, cost and outputs.

**Labels:** read-only

**Shown in clients as:** List technique runs

**Use when:** The user asks what a Technique produced before, or you need a `technique_id` from work already done in a workspace.

**Don't use when:** You're polling runs you just started: use [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations) with `run_ids` and `technique_id`.

**Arguments**

| Argument       | Type   | Required | Notes                                                                                                                                                                    |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workspace_id` | string | no       | Filter by workspace (ws\_…).                                                                                                                                             |
| `project_id`   | string | no       | Filter by project (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>. |
| `technique_id` | string | no       | Filter by technique (tech\_…).                                                                                                                                           |
| `status`       | string | no       | Filter by run status. One of `pending`, `running`, `completed`, `failed`.                                                                                                |
| `limit`        | number | no       | Max items to return (default 20).                                                                                                                                        |
| `cursor`       | string | no       | Pagination cursor from a previous call's meta.next\_cursor.                                                                                                              |

**Returns:** A page of runs with status, cost and outputs, and `meta.next_cursor`.

**Cost:** Free. This tool doesn't spend money.

**Usually comes before:** [`flora_get_technique`](#flora_get_technique)

**Example prompt:** "Show me the last five runs of our Background swap Technique."

**Example call:**

```json
{
  "technique_id": "tech_123",
  "limit": 5
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List past technique runs with their status, cost, and outputs. Also the way to find technique ids from work already done in a workspace.
```

{% endcode %}

</details>

## flora\_search\_actions <a href="#flora_search_actions" id="flora_search_actions"></a>

Search the prebuilt action registry (crop, stitch, split, color grade and more) and read each action's inputs and params.

**Labels:** read-only

**Shown in clients as:** Search actions

**Use when:** The user wants a deterministic edit, such as cropping, stitching or splitting media, rather than a new generation.

**Don't use when:** You want generated output: use [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations) or [`flora_run_technique`](#flora_run_technique).

**Arguments**

| Argument | Type   | Required | Notes                                           |
| -------- | ------ | -------- | ----------------------------------------------- |
| `query`  | string | no       | Match against action name, id, and description. |
| `limit`  | number | no       | Max items to return (default 10).               |

**Returns:** Matching actions, each with its `action_id`, declared inputs and params (with defaults and options), and `charged_cost`, plus `total_matched`.

**Cost:** Free. Running an action is free too, but the workspace plan must include actions.

**Usually comes before:** [`flora_run_action`](#flora_run_action), [`flora_add_action`](#flora_add_action)

**Example prompt:** "Is there a FLORA action that crops an image to a set aspect ratio?"

**Example call:**

```json
{
  "query": "crop",
  "limit": 5
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Search FLORA's prebuilt action catalog by name, id or description. Read-only: it runs nothing. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them. Each result declares the inputs, outputs and params the action accepts; read them before running or placing an action rather than guessing parameter names.
```

{% endcode %}

</details>

## flora\_get\_action <a href="#flora_get_action" id="flora_get_action"></a>

Read one prebuilt action's definition: its inputs, outputs and the params it accepts, with their types and defaults.

**Labels:** read-only

**Shown in clients as:** Get action

**Use when:** You know the `action_id` and need its exact inputs and param keys before [`flora_run_action`](#flora_run_action), [`flora_add_action`](#flora_add_action) or [`flora_open_action_studio`](#flora_open_action_studio).

**Don't use when:** You don't know which action fits: search with [`flora_search_actions`](#flora_search_actions). For a custom action on a canvas, read its node with [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas).

**Arguments**

| Argument    | Type   | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action_id` | string | yes      | The prebuilt catalog action. One of `color-grade-image-browser`, `overlay-image-browser`, `draw-image-browser`, `pixel-remover-image-browser`, `magic-eraser-image-browser`, `crop-image-browser`, `scene-3d-image-browser`, `blur-image-browser`, `change-image-ar-browser`, `rotate-image-browser`, `color-filter-image-browser`, `color-tint-image-browser`, `filter-color-image-browser`, `duplicate-image-browser`, `side-by-side-composite-browser`, `add-shape-to-image-browser`, `add-text-to-image-browser`, `qr-code-generator-browser`, `resize-image-browser`, `shader-effect-browser`, `split-text-browser`, `find-and-replace-text-browser`, `concat-text-browser`, `ken-burns-video`, `stitch-videos`, `split-video`, `extract-video-frames`, `color-grade-video`, `video-to-frame-grid`, `boomerang-video`, `reverse-video`, `video-to-long-exposure`, `video-effect`, `color-filter-video`, `speed-up-video`, `slow-down-video`, `duplicate-video`, `greenscreen-video`, `resize-video`, `change-video-ar`, `split-audio-from-video`, `merge-audio-into-video`. |

**Returns:** The action's name, description, declared inputs and outputs, and params with their types and defaults. It runs nothing.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_search_actions`](#flora_search_actions)

**Usually comes before:** [`flora_run_action`](#flora_run_action), [`flora_open_action_studio`](#flora_open_action_studio)

**Example prompt:** "What settings does FLORA's color grade action take?"

**Example call:**

```json
{
  "action_id": "color-grade-image-browser"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Read one prebuilt catalog action's definition: its name, description, declared inputs and outputs, and the params it accepts with their types and defaults. Read-only: it runs nothing. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them.
```

{% endcode %}

</details>

## flora\_run\_action <a href="#flora_run_action" id="flora_run_action"></a>

Run a prebuilt action headless on inputs you pass by URL or text. Nothing appears on the canvas.

**Labels:** writes · destructive · async

**Shown in clients as:** Run action

**Use when:** You need an action's output, such as a crop or a stitched video, without adding nodes to the canvas.

**Don't use when:** The user wants the result on the canvas: use [`flora_add_action`](#flora_add_action), then [`flora_run_canvas_action`](#flora_run_canvas_action). Don't pass canvas node IDs or generation IDs as inputs; pass URLs.

**Arguments**

| Argument            | Type            | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`      | string          | yes      | Workspace (ws\_…).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `project_id`        | string          | yes      | Project canvas to run in (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `action_id`         | string          | yes      | The prebuilt catalog action, from flora\_search\_actions or flora\_get\_action. One of `color-grade-image-browser`, `overlay-image-browser`, `draw-image-browser`, `pixel-remover-image-browser`, `magic-eraser-image-browser`, `crop-image-browser`, `scene-3d-image-browser`, `blur-image-browser`, `change-image-ar-browser`, `rotate-image-browser`, `color-filter-image-browser`, `color-tint-image-browser`, `filter-color-image-browser`, `duplicate-image-browser`, `side-by-side-composite-browser`, `add-shape-to-image-browser`, `add-text-to-image-browser`, `qr-code-generator-browser`, `resize-image-browser`, `shader-effect-browser`, `split-text-browser`, `find-and-replace-text-browser`, `concat-text-browser`, `ken-burns-video`, `stitch-videos`, `split-video`, `extract-video-frames`, `color-grade-video`, `video-to-frame-grid`, `boomerang-video`, `reverse-video`, `video-to-long-exposure`, `video-effect`, `color-filter-video`, `speed-up-video`, `slow-down-video`, `duplicate-video`, `greenscreen-video`, `resize-video`, `change-video-ar`, `split-audio-from-video`, `merge-audio-into-video`. |
| `inputs`            | array of object | yes      | Inputs in the order the action expects. Media inputs are passed by URL, never by canvas node id or generation id: image, video and audio each need `url` (a public HTTPS URL, e.g. an asset's url from flora\_create\_asset/flora\_complete\_asset or a generation output url from flora\_list\_generations). text takes `text` or `url`. model3d takes `url` or `asset_id`. To run an action on a canvas node instead, use flora\_run\_canvas\_action.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `inputs[].type`     | string          | yes      | Input kind. One of `image`, `video`, `audio`, `text`, `model3d`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `inputs[].url`      | string          | no       | Public HTTPS URL. Required for image, video and audio; accepted for text and model3d.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `inputs[].text`     | string          | no       | Inline text value for text inputs; alternatively provide url.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `inputs[].asset_id` | string          | no       | Asset ID (asset\_…). Only for model3d inputs, as an alternative to url.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `inputs[].name`     | string          | no       | Optional input name when the action names its inputs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `params`            | object          | no       | Values for the action's declared params, keyed as flora\_get\_action (or flora\_search\_actions) lists them. The API rejects any key the action does not declare.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `state`             | object          | no       | Interaction state the FLORA action studio's live preview committed (JSON, at most 256 KiB), replayed by the run. Only the studio sets this; leave it out when calling by hand.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

**Returns:** The run, with a `canvas_url` to give the user; its outputs come back from [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations). In clients that show FLORA's action studio, the studio opens, waits for the run itself and hands back its ID, status and outputs, so don't poll.

**Cost:** Free, but the workspace plan must include actions. A `403` means the plan lacks actions or the credential can't write to that workspace; don't retry either way.

**Usually comes after:** [`flora_search_actions`](#flora_search_actions)

**Usually comes before:** [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations)

**Example prompt:** "Crop this product photo to a square."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "project_id": "prj_abc",
  "action_id": "change-image-ar-browser",
  "inputs": [
    {
      "type": "image",
      "url": "https://example.com/product.jpg"
    }
  ],
  "params": {
    "aspect_ratio": "1:1",
    "fit": "crop"
  }
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Run one prebuilt catalog action headlessly on inputs you supply inline, as a single API operation that starts one run. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them. Read the action's declared inputs and params first (flora_get_action or flora_search_actions) and pass only those; undeclared parameter names are rejected. A 403 means either the credential cannot write to that workspace (check workspace_id against flora_list_workspaces) or the plan lacks actions (tell the user to upgrade) — do not retry either way. This does NOT touch the canvas — nothing appears in the project, and outputs come back from flora_list_generations. project_id only scopes authorization and generation history. To produce a canvas node, use flora_add_action then flora_run_canvas_action. To let the user tune the settings before anything runs, use flora_open_action_studio instead. Returns canvas_url; give the user that link rather than building one from an id. In MCP Apps hosts the result opens the FLORA action studio view, where the user adjusts the action's parameters (previewed live in the browser for browser-runtime actions). To build the view, the call reads the action's definition: the catalog action, or the canvas node's action (its catalog action on an API without that read). Once the run has started, the view reads its status with flora_list_generations automatically, without a click, until it finishes. The view's only other calls are on the user's click: Apply calls this tool once more with the chosen parameters, and Save to canvas adds the outputs with flora_add_to_canvas. The studio waits for the run itself, so do not poll flora_list_generations for it or ask the user to send a message to check. When the run finishes the studio hands you its run id, status, outputs and final params. For writing or fixing custom action code, the flora-action-studio skill (flora_discover_skills with name="flora-action-studio") carries tested templates.
```

{% endcode %}

</details>

## flora\_add\_action <a href="#flora_add_action" id="flora_add_action"></a>

Place a prebuilt action node on a canvas. It runs nothing until [`flora_run_canvas_action`](#flora_run_canvas_action) runs it.

**Labels:** writes

**Shown in clients as:** Add action

**Use when:** The user wants a prebuilt action as a node on the canvas, wired to other nodes.

**Don't use when:** The node already exists: run it with [`flora_run_canvas_action`](#flora_run_canvas_action), or change it with [`flora_update_canvas_action`](#flora_update_canvas_action) instead of adding a second node. For a custom action from code, use [`flora_create_custom_action`](#flora_create_custom_action). For a one-off result off the canvas, use [`flora_run_action`](#flora_run_action).

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | yes      | Project canvas to add to (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `action_id`  | string | yes      | The prebuilt catalog action, from flora\_search\_actions or flora\_get\_action. One of `color-grade-image-browser`, `overlay-image-browser`, `draw-image-browser`, `pixel-remover-image-browser`, `magic-eraser-image-browser`, `crop-image-browser`, `scene-3d-image-browser`, `blur-image-browser`, `change-image-ar-browser`, `rotate-image-browser`, `color-filter-image-browser`, `color-tint-image-browser`, `filter-color-image-browser`, `duplicate-image-browser`, `side-by-side-composite-browser`, `add-shape-to-image-browser`, `add-text-to-image-browser`, `qr-code-generator-browser`, `resize-image-browser`, `shader-effect-browser`, `split-text-browser`, `find-and-replace-text-browser`, `concat-text-browser`, `ken-burns-video`, `stitch-videos`, `split-video`, `extract-video-frames`, `color-grade-video`, `video-to-frame-grid`, `boomerang-video`, `reverse-video`, `video-to-long-exposure`, `video-effect`, `color-filter-video`, `speed-up-video`, `slow-down-video`, `duplicate-video`, `greenscreen-video`, `resize-video`, `change-video-ar`, `split-audio-from-video`, `merge-audio-into-video`. |
| `params`     | object | no       | Starting values for the action's declared params, keyed as flora\_get\_action lists them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `label`      | string | no       | Node label on the canvas. Defaults to the action's name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

**Returns:** The action node, including the UUID that [`flora_run_canvas_action`](#flora_run_canvas_action) accepts. The node does nothing until it runs.

**Cost:** Free, but the workspace plan must include actions.

**Usually comes after:** [`flora_search_actions`](#flora_search_actions)

**Usually comes before:** [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas), [`flora_run_canvas_action`](#flora_run_canvas_action)

**Example prompt:** "Add a crop-to-4:5 action to my canvas."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "action_id": "change-image-ar-browser",
  "params": {
    "aspect_ratio": "4:5",
    "fit": "crop"
  },
  "label": "Crop to 4:5"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Place one prebuilt catalog action node on a project canvas, as a single API operation; it runs nothing and spends nothing. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them. The node is inert until flora_run_canvas_action runs it; use flora_run_action instead to run an action headlessly with inline inputs. For a custom action from code, use flora_create_custom_action. The workspace plan must include actions. A 403 can mean the plan lacks actions or the credential cannot write to the project's workspace; do not retry the unchanged request.
```

{% endcode %}

</details>

## flora\_open\_action\_studio <a href="#flora_open_action_studio" id="flora_open_action_studio"></a>

Open FLORA's action studio on a prebuilt action and the inputs you pass, without running it, so the user can tune its params first.

**Labels:** read-only

**Shown in clients as:** Open action studio

**Use when:** The user wants to see or adjust an action's settings before it runs, in a client that shows MCP Apps.

**Don't use when:** Your client can't show MCP Apps, or the user just wants the result: run it with [`flora_run_action`](#flora_run_action). For an action node already on a canvas, use [`flora_open_canvas_action_studio`](#flora_open_canvas_action_studio).

**Arguments**

| Argument            | Type            | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`      | string          | yes      | Workspace (ws\_…).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `project_id`        | string          | yes      | Project canvas to run in (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `action_id`         | string          | yes      | The prebuilt catalog action, from flora\_search\_actions or flora\_get\_action. One of `color-grade-image-browser`, `overlay-image-browser`, `draw-image-browser`, `pixel-remover-image-browser`, `magic-eraser-image-browser`, `crop-image-browser`, `scene-3d-image-browser`, `blur-image-browser`, `change-image-ar-browser`, `rotate-image-browser`, `color-filter-image-browser`, `color-tint-image-browser`, `filter-color-image-browser`, `duplicate-image-browser`, `side-by-side-composite-browser`, `add-shape-to-image-browser`, `add-text-to-image-browser`, `qr-code-generator-browser`, `resize-image-browser`, `shader-effect-browser`, `split-text-browser`, `find-and-replace-text-browser`, `concat-text-browser`, `ken-burns-video`, `stitch-videos`, `split-video`, `extract-video-frames`, `color-grade-video`, `video-to-frame-grid`, `boomerang-video`, `reverse-video`, `video-to-long-exposure`, `video-effect`, `color-filter-video`, `speed-up-video`, `slow-down-video`, `duplicate-video`, `greenscreen-video`, `resize-video`, `change-video-ar`, `split-audio-from-video`, `merge-audio-into-video`. |
| `inputs`            | array of object | yes      | Inputs in the order the action expects. Media inputs are passed by URL, never by canvas node id or generation id: image, video and audio each need `url` (a public HTTPS URL, e.g. an asset's url from flora\_create\_asset/flora\_complete\_asset or a generation output url from flora\_list\_generations). text takes `text` or `url`. model3d takes `url` or `asset_id`. To run an action on a canvas node instead, use flora\_run\_canvas\_action.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `inputs[].type`     | string          | yes      | Input kind. One of `image`, `video`, `audio`, `text`, `model3d`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `inputs[].url`      | string          | no       | Public HTTPS URL. Required for image, video and audio; accepted for text and model3d.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `inputs[].text`     | string          | no       | Inline text value for text inputs; alternatively provide url.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `inputs[].asset_id` | string          | no       | Asset ID (asset\_…). Only for model3d inputs, as an alternative to url.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `inputs[].name`     | string          | no       | Optional input name when the action names its inputs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `params`            | object          | no       | Values for the action's declared params, keyed as flora\_get\_action (or flora\_search\_actions) lists them. The API rejects any key the action does not declare.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

**Returns:** The studio view. It starts no run and writes nothing. When the user clicks Apply, the studio calls [`flora_run_action`](#flora_run_action) once with the chosen params, waits for the run and hands you its run ID, status, outputs and final params, so don't start a run or poll yourself.

**Cost:** Free. Applying runs the action, which is free too, but the workspace plan must include actions.

**Usually comes after:** [`flora_search_actions`](#flora_search_actions), [`flora_get_action`](#flora_get_action)

**Usually comes before:** [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas)

**Example prompt:** "Let me tweak the color grade on this photo before you apply it."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "project_id": "prj_abc",
  "action_id": "color-grade-image-browser",
  "inputs": [
    {
      "type": "image",
      "url": "https://example.com/product.jpg"
    }
  ]
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Open the FLORA action studio on one prebuilt catalog action and the inline inputs you supply, without running it, so the user can tune its parameters first. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them. Read-only: it starts no run, writes nothing and spends nothing. To build the view it reads the action's definition. The user adjusts the parameters there and clicks Apply, which calls flora_run_action once with the chosen settings; once that run starts the view reads its status with flora_list_generations until it finishes, and Save to canvas adds the outputs with flora_add_to_canvas. Do not start a run yourself and do not poll: when the applied run finishes, the studio hands you its run id, status, outputs and final params. Hosts without MCP Apps cannot show the studio; run the action with flora_run_action there instead.
```

{% endcode %}

</details>

## flora\_create\_custom\_action <a href="#flora_create_custom_action" id="flora_create_custom_action"></a>

Add a custom action node to a canvas from Python or JavaScript code you write. The code is stored on the node, not run.

**Labels:** writes

**Shown in clients as:** Create custom action

**Use when:** No prebuilt action does what the user wants, and they want a custom transform as a node on the canvas.

**Don't use when:** A prebuilt action fits: place it with [`flora_add_action`](#flora_add_action). The node already exists: change its code with [`flora_update_canvas_action`](#flora_update_canvas_action) instead of adding a second node.

{% hint style="info" %}
Before writing the code, the agent loads the `flora-action-studio` skill with [`flora_discover_skills`](https://docs.flora.ai/mcp/tools/skills-and-discovery.md#flora_discover_skills). It has a tested template for each runtime and the `@flora-*` annotations the code declares its inputs, outputs and params with.
{% endhint %}

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                                                                                                       |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | yes      | Project canvas to add to (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                             |
| `code`       | string | yes      | Source of the custom action, with its @flora-\* annotations.                                                                                                                                                                                                |
| `language`   | string | yes      | Language of code. One of `javascript`, `python`.                                                                                                                                                                                                            |
| `runtime`    | string | no       | Where custom code runs: python for Python; node (harness helpers) or browser (ES module with a live preview) for JavaScript. Defaults to browser when the JavaScript exports execute, otherwise the language's sandbox. One of `node`, `python`, `browser`. |
| `label`      | string | no       | Node label on the canvas. Defaults to the action's declared name.                                                                                                                                                                                           |
| `params`     | object | no       | Starting values for the params the code declares, keyed as declared.                                                                                                                                                                                        |

**Returns:** The new action node, including the UUID that [`flora_run_canvas_action`](#flora_run_canvas_action) accepts. The node does nothing until it runs.

**Cost:** Free, but the workspace plan must include custom actions.

**Usually comes after:** [`flora_discover_skills`](https://docs.flora.ai/mcp/tools/skills-and-discovery.md#flora_discover_skills), [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas)

**Usually comes before:** [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas), [`flora_run_canvas_action`](#flora_run_canvas_action)

**Example prompt:** "Write a pixelate action for my canvas with an adjustable block size."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "language": "python",
  "runtime": "python",
  "code": "# @flora-name: \"Pixelate\"\n# @flora-description: \"Blocky pixels\"\n# @flora-inputs: [{\"name\": \"source\", \"type\": \"image\"}]\n# @flora-outputs: [{\"name\": \"out\", \"type\": \"image\"}]\n# @flora-params: [{\"key\": \"size\", \"label\": \"Block size\", \"type\": \"number\", \"default\": 8, \"min\": 2, \"max\": 64}]\nimport io\nfrom PIL import Image\nsource = Image.open(get_input(0)[\"path\"]).convert(\"RGB\")\nsize = int(get_param(\"size\", 8))\nsmall = source.resize((max(1, source.width // size), max(1, source.height // size)), Image.NEAREST)\nbuffer = io.BytesIO()\nsmall.resize(source.size, Image.NEAREST).save(buffer, format=\"PNG\")\nwrite_output(\"out.png\", buffer.getvalue())\n"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Add one custom action node to a project canvas from source code you write, as a single API operation. The code is stored on the node, not run: it runs only when flora_run_canvas_action runs the node, in FLORA's sandbox (python, node) or the user's browser (browser). To place a prebuilt catalog action instead, use flora_add_action; to change an existing node's code, use flora_update_canvas_action rather than adding a second node. Declare the contract in comment lines at the top, one `# @flora-x: value` per line (`//` in JavaScript; a space instead of the colon also works): @flora-name: "Pixelate"; @flora-description: "Blocky pixels"; @flora-inputs: [{"name": "source", "type": "image"}]; @flora-outputs: [{"name": "out", "type": "image"}] (required; types image, video, audio, text, model3d; when you wire a source into the action with flora_add_to_canvas, the in of each connect is the declared input name, e.g. "source", never a type such as "image"); @flora-params: [{"key": "size", "label": "Block size", "type": "number", "default": 8, "min": 2, "max": 64}] (every entry needs key, label, type AND a default of the right type; types number, boolean, color, select with options [{label, value}], text, point2d, point3d, interval; visibleIf: [{key, equals}]). Runtime contract, Python: get_input(i) returns a dict {index, type, name, path} (a text input carries text instead of path); open media with Image.open(get_input(0)["path"]); read tunables with get_param("size", 8) using the declared camelCase keys; write each declared output with write_output("0-out.png", bytes_or_str) (outputs fill the declared slots in filename order, so prefix names to sort in declared order); Pillow, numpy, cv2, moviepy and ffmpeg are available; raise FloraUserError("message") for a user-facing error. JavaScript on the node runtime: getInput(i) gives {path|text}, getParam(key, default), writeOutput("out.png", buffer); sharp and canvas are available. JavaScript written as an ES module runs in the browser and, when it exports preview, previews live in the studio: export async function execute({ inputs, params, state }) returning {type: "image", dataUrl}, and export const preview = { mode: "wysiwyg", mount({ el, inputs, params, state, onState }) { return { update({ params, state }) {}, dispose() {} } } }; inputs are {type, dataUrl|text}; browser APIs only (Canvas2D/WebGL), no fetch. The flora-action-studio skill carries a complete tested template for each runtime. The workspace plan must include custom actions. flora_get_canvas lists the params of a custom node under their declared keys; the action reads and runs use their snake_case form; writes accept either.
```

{% endcode %}

</details>

## flora\_update\_canvas\_action <a href="#flora_update_canvas_action" id="flora_update_canvas_action"></a>

Change an action node on a canvas in place: its label and params, and for a custom action its code, language and runtime.

**Labels:** writes · destructive

**Shown in clients as:** Update canvas action

**Use when:** The user wants different settings saved on an action node, or a custom action's code fixed or rewritten.

**Don't use when:** You want the node to run: this runs nothing, so call [`flora_run_canvas_action`](#flora_run_canvas_action) afterwards. Never add a second node to fix a broken action.

{% hint style="warning" %}
New `code` replaces the node's previous code completely. Pass the whole source, not a patch.
{% endhint %}

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                                                                                                       |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | yes      | Project holding the node (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                             |
| `node_id`    | string | yes      | The action node to change: its persisted short id (n7) from flora\_get\_canvas or its UUID. Never predict an id.                                                                                                                                            |
| `label`      | string | no       | New node label.                                                                                                                                                                                                                                             |
| `params`     | object | no       | Param values to store on the node, merged key by key (omitted keys keep their values). Keys as flora\_get\_canvas lists them for the node.                                                                                                                  |
| `code`       | string | no       | Custom nodes only: the complete new source, with its @flora-\* annotations.                                                                                                                                                                                 |
| `language`   | string | no       | Language of code. One of `javascript`, `python`.                                                                                                                                                                                                            |
| `runtime`    | string | no       | Where custom code runs: python for Python; node (harness helpers) or browser (ES module with a live preview) for JavaScript. Defaults to browser when the JavaScript exports execute, otherwise the language's sandbox. One of `node`, `python`, `browser`. |

**Returns:** The updated node. It keeps its ID and wiring, and param values the new code still declares survive.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas)

**Usually comes before:** [`flora_run_canvas_action`](#flora_run_canvas_action)

**Example prompt:** "Set the crop action on my canvas to 4:5."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "node_id": "n7",
  "params": {
    "aspect_ratio": "4:5"
  }
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Change one existing action node in place, as a single API operation; only the fields given change. Any action node takes label and params. A custom node also takes code, language and runtime, and new code overwrites the previous code, which is why the tool is marked destructive. The node keeps its id and wiring, and param values the new code still declares survive. Nothing runs: run it afterwards with flora_run_canvas_action. Fix a broken custom action this way, never by adding a second node. New code follows the same @flora-* contract and runtime helpers as flora_create_custom_action. For writing or fixing custom action code, the flora-action-studio skill (flora_discover_skills with name="flora-action-studio") carries tested templates.
```

{% endcode %}

</details>

## flora\_open\_canvas\_action\_studio <a href="#flora_open_canvas_action_studio" id="flora_open_canvas_action_studio"></a>

Open FLORA's action studio on an action node already on a canvas, without running it, so the user can tune its params first.

**Labels:** read-only

**Shown in clients as:** Open canvas action studio

**Use when:** The user wants to see or adjust a canvas action node's settings before it runs, in a client that shows MCP Apps.

**Don't use when:** Your client can't show MCP Apps, or the user just wants the node run: use [`flora_run_canvas_action`](#flora_run_canvas_action). For an action that isn't on the canvas, use [`flora_open_action_studio`](#flora_open_action_studio).

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                                                                 |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | yes      | Project holding the node (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                       |
| `node_id`    | string | yes      | Action node to open: the persisted short id (n7) from flora\_get\_canvas or the UUID flora\_add\_action or flora\_create\_custom\_action returned. Use the UUID if the short id is ambiguous.                         |
| `params`     | object | no       | Suggested starting values the studio shows over the node's stored ones, keyed as flora\_get\_canvas lists them. Nothing is saved: the node keeps its values until the user's Apply runs it with the values on screen. |

**Returns:** The studio view, showing the node's stored params and wired inputs. It starts no run and saves nothing. When the user clicks Apply, the studio calls [`flora_run_canvas_action`](#flora_run_canvas_action) once with the values on screen, waits for the run and hands you its run ID, status, outputs and final params, so don't start a run or poll yourself.

**Cost:** Free. Applying runs the action, which is free too, but the workspace plan must include actions.

**Usually comes after:** [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas)

**Usually comes before:** [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations)

**Example prompt:** "Open the crop action on my canvas so I can adjust it."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "node_id": "n7"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Open the FLORA action studio on one action node that already sits on a project canvas, prebuilt or custom, without running it, so the user can tune its parameters first. The studio shows the node's stored parameter values and wired inputs. Read-only: it starts no run, writes nothing and spends nothing. To build the view it reads the action's definition. The user adjusts the parameters there and clicks Apply, which calls flora_run_canvas_action once with the chosen settings; once that run starts the view reads its status with flora_list_generations until it finishes, and Save to canvas adds the outputs with flora_add_to_canvas. Do not start a run yourself and do not poll: when the applied run finishes, the studio hands you its run id, status, outputs and final params. Hosts without MCP Apps cannot show the studio; run the action with flora_run_canvas_action there instead.
```

{% endcode %}

</details>

## flora\_run\_canvas\_action <a href="#flora_run_canvas_action" id="flora_run_canvas_action"></a>

Run an action node that's already on a canvas, using the nodes wired into it as inputs.

**Labels:** writes · destructive · async

**Shown in clients as:** Run canvas action

**Use when:** An action node exists with its inputs connected, and the user wants its result on the canvas.

**Don't use when:** The node doesn't exist yet (add it with [`flora_add_action`](#flora_add_action)), or you want a result without touching the canvas (use [`flora_run_action`](#flora_run_action)). Never add a duplicate node to rerun an action.

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                                                                                         |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | yes      | Project holding the node (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                               |
| `node_id`    | string | yes      | Action node to run: the persisted short id (n7) from flora\_get\_canvas or the UUID flora\_add\_action or flora\_create\_custom\_action returned. Use the UUID if the short id is ambiguous.                                                  |
| `params`     | object | no       | Parameter values to store on the node before running, merged key by key into what it holds (a named key is overwritten, omitted keys survive). Keys as flora\_get\_canvas lists them for the node.                                            |
| `state`      | object | no       | Interaction state the FLORA action studio's live preview committed (JSON, at most 256 KiB). It is saved on the node, replacing the state the node held, and the run replays it. Only the studio sets this; leave it out when calling by hand. |

**Returns:** The run, with a `canvas_url` to give the user. Params you pass are saved on the node first, and the outputs replace what its result nodes show. In clients that show FLORA's action studio, the studio waits for the run itself, so don't poll.

**Cost:** Free, but the workspace plan must include actions.

**Usually comes after:** [`flora_add_action`](#flora_add_action), [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas)

**Usually comes before:** [`flora_list_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_list_generations), [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas)

**Example prompt:** "Run the crop action on my canvas again at 4:5."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "node_id": "n14",
  "params": {
    "aspect_ratio": "4:5"
  }
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Run one action node that already sits on a project canvas — a prebuilt action, or a custom action whose user-authored code runs in FLORA's sandbox — taking its inputs from the nodes wired into it. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them. One call is one API operation that starts one run, with these writes: params and preview state given are first saved on the node, overwriting the values they name, and its outputs replace what the node's result nodes show. A 403 means the plan lacks actions or the credential cannot write to the project's workspace, so check the workspace before telling the user to upgrade. For an existing action node, use its persisted short id or UUID from flora_get_canvas; do not add a duplicate. Only add a node (flora_add_action, or flora_create_custom_action for code) when it does not exist. Connect the action's inputs — an action with required inputs and no incoming edges fails. Returns canvas_url; give the user that link rather than building one from an id. Actions cannot connect directly to other actions. Run the source action first and wait for its outputs with flora_list_generations. A browser materializes its RESULT nodes; a headless run may finish without creating canvas result nodes. Read flora_get_canvas and connect a result node only if it exists. If absent, run the next action headlessly with flora_run_action using those output URLs/text as inline inputs. To continue a media chain on the canvas, add image/video/audio output URLs with flora_add_to_canvas using type and content_url, then connect the created node to the next action and run it. In MCP Apps hosts the result opens the FLORA action studio view, where the user adjusts the action's parameters (previewed live in the browser for browser-runtime actions). To build the view, the call reads the action's definition: the catalog action, or the canvas node's action (its catalog action on an API without that read). Once the run has started, the view reads its status with flora_list_generations automatically, without a click, until it finishes. The view's only other calls are on the user's click: Apply calls this tool once more with the chosen parameters, and Save to canvas adds the outputs with flora_add_to_canvas. The studio waits for the run itself, so do not poll flora_list_generations for it or ask the user to send a message to check. When the run finishes the studio hands you its run id, status, outputs and final params. For writing or fixing custom action code, the flora-action-studio skill (flora_discover_skills with name="flora-action-studio") carries tested templates.
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/tools/techniques-and-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
