Endpoint
POST
/v1/stable/prompt/get-many

Reads several prompts by ID in one call. An ID that matches no prompt in the environment is reported instead of failing the request.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

ids
string[]
required

Prompt IDs to read. Duplicates are ignored; at most 50 distinct IDs.

Minimum items: 1

Response

200 - application/json

Returns the prompts found, in request order, and missing, the requested IDs that match no prompt in this environment.

prompts
object[]
required

The prompts found, in request order.

StablePrompt — see its attributes above
missing
string[]
required

Requested IDs that match no prompt in this environment, in request order.

Endpoint
GET
/v1/stable/prompt/{promptID}

Returns one prompt by ID. A prompt is the system text and model settings a workflow step in prompt mode sends to the model.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

promptID
string
required

The ID of the prompt to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Returns the prompt with its name, system text, settings (an empty object means the project defaults), timestamps, and the IDs of the users who created and last changed it.

prompt
object
required
StablePrompt — see its attributes above
Endpoint
PATCH
/v1/stable/prompt/{promptID}

Changes a prompt's name, its system text, or its whole settings object, and edits it in place so the step that uses it keeps pointing at the same ID. The settings value you send replaces the stored one, and an empty object returns it to the project defaults.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

promptID
string
required

The ID of the prompt to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

name
string
Minimum length: 1 · Maximum length: 255
system
object
settings
object

Response

200 - application/json

Confirms the prompt was updated. The body is a message, with unresolvedReferences for any variable or reference in the new system text that did not resolve.

message
string
required

A human-readable message confirming the update.

unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Endpoint
DELETE
/v1/stable/prompt/{promptID}

Deletes a prompt and the messages it holds. The call does not check which workflow step or condition holds the ID, so confirm nothing uses it first. The response carries only a confirmation message, so refetch the prompts to see what is left.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

promptID
string
required

The ID of the prompt to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Confirms the prompt was deleted. The body is a message only, so any step that held the ID still points at a prompt that no longer exists.

message
string
required

A human-readable message confirming the deletion.

Endpoint
POST
/v1/stable/prompt

Creates a prompt, which is a system message plus optional model settings that a workflow step in prompt mode sends to the model. The prompt belongs to nothing until a step holds its ID.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

name
string

Defaults to "Untitled prompt", as the editor names one.

Minimum length: 1 · Maximum length: 255
system
object
required

Plain text; markdown is not interpreted. {variable_name} inserts a variable or entity, {variable_name.path} a field of a variable. Escape a literal { or \ with a backslash. A name matching neither is stored as literal text and reported in unresolvedReferences; secrets are not available here.

VariableReferenceString — see its attributes above
settings
object

Response

201 - application/json

Returns the new prompt with its ID, name, system text, and settings, and unresolvedReferences for any variable or reference in the system text that did not resolve.

prompt
object
required
StablePrompt — see its attributes above
unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Endpoint
PATCH
/v1/stable/prompt/{promptID}/settings

Changes individual model settings of a prompt, such as the model or the temperature, without resending the whole settings object. A key set to null is rejected, so clearing a key goes through the prompt update call.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

promptID
string
required

The ID of the prompt to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

The settings keys to set. Keys you leave out keep their stored value. null is not accepted; to clear a key, send the whole settings object through update.

model
object
maxTokens
number
temperature
number
responseFormat
string
reasoningEffort
object
serviceTier
object
useStructuredOutput
boolean

Response

200 - application/json

Confirms the prompt settings were updated. The body is a message only, so refetch the prompt to see its settings as they now stand.

message
string
required

A human-readable message confirming the update.

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.