Skip to main content
POST
Add a single action to an integration you have already created. Create an Integration accepts actions[] inline, which covers authoring everything in one call. Use this endpoint instead when the integration already exists — to extend it with a new capability, or to add actions one at a time rather than batching them. The body is the same action shape that endpoint accepts inline, so an action you can create one way you can create the other. Use the versionId returned by Create an Integration as {integrationVersionId}. Requires the Integration: Full permission at organization level.
Every call creates a new action. It never updates or replaces an existing one, even if the name matches — call it twice and the integration has two actions.

Headers

string
required
Your API authentication key

Path Parameters

string
required
The integration version to attach the action to. This is versionId from Create an Integration — not the integration’s id.

Body Parameters

The action is nested under an action key.
object
required
The action to create. Fields below.
string
required
Action name, shown in the workflow builder. Maximum 255 characters.
string
required
The external endpoint this action talks to. Metadata only — code is what actually executes. Maximum 2048 characters.
object
required
The action’s input schema, keyed by each field’s variableName. See Field object. Send {} for an action that takes no input.
object
required
The action’s output schema, keyed by each field’s variableName. Same shape as inputs. Send {} for an action that returns nothing.
string
Action description. Maximum 2048 characters.
string
Python source that runs when the action executes. Evaluated in the global scope, not wrapped in a function: read caller values from input_data[...] and the connected secret from credential_value, then assign to result[...]. Maximum 65535 characters.
The field is code. Unrecognised fields are dropped silently rather than rejected, so sending arb_code — the name used by the internal API — returns 201 with an action that has no code at all, and the action does nothing when a workflow runs it.

Field object

Each value inside inputs and outputs. The map key must equal the field’s variableName.
string
required
Positional identifier, 1-indexed as a string — "1", "2", and so on.
string
required
Programmatic key. Referenced from code as input_data[<variableName>] for inputs, or result[<variableName>] for outputs.
string
required
Human-readable label rendered in the workflow builder.
object[]
required
Value types this field accepts. Between 1 and 11 entries. Each has a type — one of int, float, bool, str, object, file, array, date, binary, json_string, node — plus optional typeDefinition and typeDefinitionEnforced.
string
Description shown next to the field in the builder. Maximum 2048 characters.
any
Pre-filled default value. Its type must match one of allowedTypes.
boolean
default:"false"
When true, the workflow may omit this field at execute time.
string[]
Free-form tags the builder uses for grouping and filtering. Maximum 20.
object[]
Enum-style choice list. When non-empty the builder renders a dropdown. Maximum 20.
string[]
Top-level field names the builder locks. Maximum 20.
boolean
default:"true"
When false, the builder hides the “remove field” affordance.
For composite types, typeDefinition describes the shape inside: for array, a single-key map naming the element; for object, a map of its properties. Each value is itself a field definition and may nest further, so a list of records is array → object → properties. Maximum 50 entries per map.

Response

string
required
The created action id.
string
required
The created action version id. Every edit to an action creates a new version, so this identifies the exact revision you just authored.

Errors

Bad Request
Invalid body — a missing required field, a value over its limit, or an integrationVersionId that is not a UUID.
Unauthorized
Missing, invalid, or expired API key.
Forbidden
Your organization is not verified to author integrations, the key owner lacks the Integration: Full permission, or the integration belongs to another organization.
Not Found
The integration version does not exist. Check you are using versionId and not the integration’s id.
Unprocessable Entity
Rejected downstream after passing validation here.