Voiceflow bearer token
Prompts
Manage reusable prompts for your agent.
See Authentication for credentials and permissions.
Reads several prompts by ID in one call. An ID that matches no prompt in the environment is reported instead of failing the request.
Authentication
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Prompt IDs to read. Duplicates are ignored; at most 50 distinct IDs.
Response
Returns the prompts found, in request order, and missing, the requested IDs that match no prompt in this environment.
Requested IDs that match no prompt in this environment, in request order.
Returns one prompt by ID. A prompt is the system text and model settings a workflow step in prompt mode sends to the model.
Authentication
Voiceflow bearer token
Path parameters
The ID of the prompt to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
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.
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.
Authentication
Voiceflow bearer token
Path parameters
The ID of the prompt to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Response
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.
A human-readable message confirming the update.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
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.
Authentication
Voiceflow bearer token
Path parameters
The ID of the prompt to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
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.
A human-readable message confirming the deletion.
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Defaults to "Untitled prompt", as the editor names one.
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.
Response
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.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
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.
Authentication
Voiceflow bearer token
Path parameters
The ID of the prompt to operate on.
Query parameters
The ID of the project to operate on.
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.
Response
Confirms the prompt settings were updated. The body is a message only, so refetch the prompt to see its settings as they now stand.
A human-readable message confirming the update.