Skip to main content
POST
Create a step library entry
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/workflows/createStep adds a step to the step library and returns it with 201.

Authentication

External App credential or platform API key, or a Personal key. Requires permission workflows:manage (an elevated permission) held at the platform scope; a key or app granted only at some org units receives 403. Forge agents can never hold workflows:manage. Because the success returns what was written, the credential’s scopes must include workflows:read as well; otherwise 403 naming workflows:read, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it. The body is the step: name, displayName, description, category, tags, command, and optionally role, timeout (seconds), onFailure, inputs, outputs, successCriteria and isPublic (default true). The step’s author is always the caller; a createdBy field is refused. Send an Idempotency-Key to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds workflows:read and workflows:manage at the platform scope; otherwise 409 idempotency_result_unavailable, and the write never runs twice (see Idempotency). Without a key, a repeat creates a second entry, so send an Idempotency-Key.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json
name
string
required

The step's key.

Minimum string length: 1
displayName
string
required
Minimum string length: 1
description
string
required
category
string
required
Minimum string length: 1
tags
string[]
required
Minimum string length: 1
command
string
required

The command the step runs.

Minimum string length: 1
role
string
Minimum string length: 1
timeout
integer

Seconds.

onFailure
string
Minimum string length: 1
inputs
object
outputs
object
successCriteria
string[]
Minimum string length: 1
isPublic
boolean

Default true.

Response

Success

data
object
required
meta
object
required