Create a canvas action

POST

/projects/{projectId}/actions

import { FloraClient } from '@flora-ai/flora';

const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });

const action = await client.projects.actions.create({
  projectId: '<projectId>',
  action_id: 'color-grade-image-browser',
  code: '<code>',
  language: 'javascript',
  runtime: 'node',
  label: '<label>',
  params: {},
});
console.log(action);

Creates an action node on a project canvas: a prebuilt action by slug (action_id), or a custom action from source (code + language). A custom action’s inputs, outputs and parameters come from the annotations in its code; read them back with GET /projects/{projectId}/actions/{nodeId}.

Error responses use the standard error body.

Authorizations

• bearerAuth

Parameters

Path Parameters

projectId

required

Project identifier

string

/^prj_\S+$/

Project identifier

Request Body

Media type application/json

object

action_id

Prebuilt action identifier. Required unless code is given.

string

Allowed values: 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

code

Source of a custom action, in place of action_id. Declare its contract in comment annotations the way prebuilt actions do: @flora-name, @flora-description, @flora-inputs (JSON array of {name, type}), @flora-outputs (required, same shape) and @flora-params (JSON array of {key, label, type, default, min, max, step, options, visibleIf}). Read a prebuilt action’s code conventions from GET /actions/{actionId}. Requires the workspace plan to include custom actions. Limits: at most 1048576 bytes of UTF-8 source; each @flora-inputs, @flora-outputs and @flora-params JSON array at most 131072 bytes, with up to 64 inputs, 64 outputs, 128 params and 256 options per select. A multiple bounds object takes nonnegative integer min and max with min (1 when absent) at most max, and each declared default must be a value its param accepts.

string

>= 1 characters

language

Language of code. Required with code; ignored with action_id.

string

Allowed values: javascript python

runtime

Where custom code runs. python code runs on python; javascript runs on node (the harness with getInput/getParam/writeOutput) or browser (an ES module exporting execute and optionally preview, which hosts can mount live). Defaults to browser for JavaScript that exports execute, otherwise the language’s sandbox. Ignored with action_id.

string

Allowed values: node python browser

label

Node label on the canvas. Defaults to the action’s declared name.

string

>= 1 characters <= 120 characters

params

Action parameters (snake_case keys). For a prebuilt action the accepted keys depend on action_id; see GET /actions/{actionId} or POST /runs/action for the per-action schema. For a custom action they are the keys its @flora-params annotation declares, as GET /projects/{projectId}/actions/{nodeId} lists them, in at most 262144 bytes of JSON.

object

key

additional properties

any

Responses

201

Canvas action created.

Media type application/json

object

project_id

required

Project identifier

string

/^prj_\S+$/

node_id

required

Canvas action node identifier

string

>= 1 characters

action_id

required

Any of:

string

Action identifier

string

Allowed values: 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

null

null

canvas_url

required

Project canvas URL

string format: uri

Example

{
  "project_id": "prj_abc123",
  "node_id": "node_abc123",
  "action_id": "color-grade-image-browser"
}