Prompts
Create prompt draft version
Create a draft prompt version for one agent without publishing it.
POST
Creates a draft prompt version for one agent and returns the stored draft version. Unlike Update prompts, this route stores a version with
status: "DRAFT".
Use this route when you want to stage prompt changes for review before they become the active prompt.
Headers
string
required
Bearer token containing your Fini workspace API key. Format:
Bearer fini_... The key needs write scope.string
required
application/jsonPath parameters
string
required
Agent ID whose prompt version you want to draft. Use List agents to get the
botId.Body parameters
PromptSection[]
required
Full Planning Prompt section array. Send the complete array, not just the section you changed.
PromptSection[]
required
Full Main Guidelines section array.
PromptSection[]
required
Full Channel Prompt section array.
The body uses the same section shape as Update prompts. The returned object is a prompt-version row with draft metadata, not the merged template view returned by Get prompts.
Response
Returns the created draft prompt version.string
Draft prompt version ID.
string
Prompt record ID this version belongs to.
string
Agent ID the draft version belongs to.
number
Version number assigned to the draft.
string
Version status. This route returns
DRAFT.string | null
Parent version used for stale-draft detection.
datetime | null
Publication timestamp. Draft versions return
null.PromptSection[]
Planning Prompt sections stored on the draft.
PromptSection[]
Main Guidelines sections stored on the draft.
PromptSection[]
Channel Prompt sections stored on the draft.
Errors
400 Bad Request
400 Bad Request
The body is malformed, the agent ID is invalid, or the current prompt is missing the prompt ID needed to create a draft version.
403 Forbidden
403 Forbidden
The API key does not include the
write scope required for this route.406 Not Acceptable
406 Not Acceptable
The agent belongs to a different workspace.
500 Internal Server Error
500 Internal Server Error
Fini failed while creating the draft prompt version.

