Skip to main content
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/json

Path 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

The body is malformed, the agent ID is invalid, or the current prompt is missing the prompt ID needed to create a draft version.
The API key is missing, malformed, revoked, or invalid.
The API key does not include the write scope required for this route.
The agent belongs to a different workspace.
Fini failed while creating the draft prompt version.