curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"hcPlanningPrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcGuidelinePrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcChannelPrompt": [
"Answer only from approved knowledge and escalate if unsure."
]
}'
const response = await fetch('https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public', {
method: 'POST',
headers: {
Authorization: 'Bearer fini_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
'hcPlanningPrompt': [
'Answer only from approved knowledge and escalate if unsure.'
],
'hcGuidelinePrompt': [
'Answer only from approved knowledge and escalate if unsure.'
],
'hcChannelPrompt': [
'Answer only from approved knowledge and escalate if unsure.'
]
}
)
});
const data = await response.json();
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public",
headers={"Authorization": "Bearer fini_your_api_key", "Content-Type": "application/json"},
json={
"hcPlanningPrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcGuidelinePrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcChannelPrompt": [
"Answer only from approved knowledge and escalate if unsure."
]
},
)
data = response.json()
{
"id": "9c59b2df-5d5f-4c9e-a070-9ac3c2b1b24e",
"botId": "2a1cf0f0-f35d-46ad-8e61-a15c86b2b312",
"createdAt": "2026-07-28T08:55:32.000Z",
"createdBy": "api",
"hcPlanningPrompt": [
{
"id": "planning-main",
"name": "Planning",
"description": "How the agent plans an answer.",
"enabled": true,
"custom": true,
"subsections": [
{
"id": "planning-grounding",
"name": "Grounding",
"prompt": "Use approved knowledge before answering.",
"defaultPrompt": "Use retrieved knowledge before answering.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
],
"hcGuidelinePrompt": [
{
"id": "guidelines-main",
"name": "Main Guidelines",
"description": "Global answer behavior.",
"enabled": true,
"custom": true,
"subsections": [
{
"id": "guidelines-escalation",
"name": "Escalation",
"prompt": "Escalate billing disputes when policy is unclear.",
"defaultPrompt": "Escalate when unsure.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
],
"hcChannelPrompt": [
{
"id": "channel-chat",
"name": "Chat",
"description": "Chat-specific behavior.",
"enabled": true,
"custom": false,
"subsections": [
{
"id": "channel-chat-style",
"name": "Tone",
"prompt": "Keep replies concise and grounded in approved knowledge.",
"defaultPrompt": "Keep replies helpful and concise.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
]
}
Prompts
Create prompt draft version
Create a draft prompt version for one agent without publishing it.
POST
/
v2
/
bots
/
{id}
/
hc-prompt
/
versions
/
public
curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"hcPlanningPrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcGuidelinePrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcChannelPrompt": [
"Answer only from approved knowledge and escalate if unsure."
]
}'
const response = await fetch('https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public', {
method: 'POST',
headers: {
Authorization: 'Bearer fini_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
'hcPlanningPrompt': [
'Answer only from approved knowledge and escalate if unsure.'
],
'hcGuidelinePrompt': [
'Answer only from approved knowledge and escalate if unsure.'
],
'hcChannelPrompt': [
'Answer only from approved knowledge and escalate if unsure.'
]
}
)
});
const data = await response.json();
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public",
headers={"Authorization": "Bearer fini_your_api_key", "Content-Type": "application/json"},
json={
"hcPlanningPrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcGuidelinePrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcChannelPrompt": [
"Answer only from approved knowledge and escalate if unsure."
]
},
)
data = response.json()
{
"id": "9c59b2df-5d5f-4c9e-a070-9ac3c2b1b24e",
"botId": "2a1cf0f0-f35d-46ad-8e61-a15c86b2b312",
"createdAt": "2026-07-28T08:55:32.000Z",
"createdBy": "api",
"hcPlanningPrompt": [
{
"id": "planning-main",
"name": "Planning",
"description": "How the agent plans an answer.",
"enabled": true,
"custom": true,
"subsections": [
{
"id": "planning-grounding",
"name": "Grounding",
"prompt": "Use approved knowledge before answering.",
"defaultPrompt": "Use retrieved knowledge before answering.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
],
"hcGuidelinePrompt": [
{
"id": "guidelines-main",
"name": "Main Guidelines",
"description": "Global answer behavior.",
"enabled": true,
"custom": true,
"subsections": [
{
"id": "guidelines-escalation",
"name": "Escalation",
"prompt": "Escalate billing disputes when policy is unclear.",
"defaultPrompt": "Escalate when unsure.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
],
"hcChannelPrompt": [
{
"id": "channel-chat",
"name": "Chat",
"description": "Chat-specific behavior.",
"enabled": true,
"custom": false,
"subsections": [
{
"id": "channel-chat-style",
"name": "Tone",
"prompt": "Keep replies concise and grounded in approved knowledge.",
"defaultPrompt": "Keep replies helpful and concise.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
]
}
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.
curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"hcPlanningPrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcGuidelinePrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcChannelPrompt": [
"Answer only from approved knowledge and escalate if unsure."
]
}'
const response = await fetch('https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public', {
method: 'POST',
headers: {
Authorization: 'Bearer fini_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
'hcPlanningPrompt': [
'Answer only from approved knowledge and escalate if unsure.'
],
'hcGuidelinePrompt': [
'Answer only from approved knowledge and escalate if unsure.'
],
'hcChannelPrompt': [
'Answer only from approved knowledge and escalate if unsure.'
]
}
)
});
const data = await response.json();
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public",
headers={"Authorization": "Bearer fini_your_api_key", "Content-Type": "application/json"},
json={
"hcPlanningPrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcGuidelinePrompt": [
"Answer only from approved knowledge and escalate if unsure."
],
"hcChannelPrompt": [
"Answer only from approved knowledge and escalate if unsure."
]
},
)
data = response.json()
{
"id": "9c59b2df-5d5f-4c9e-a070-9ac3c2b1b24e",
"botId": "2a1cf0f0-f35d-46ad-8e61-a15c86b2b312",
"createdAt": "2026-07-28T08:55:32.000Z",
"createdBy": "api",
"hcPlanningPrompt": [
{
"id": "planning-main",
"name": "Planning",
"description": "How the agent plans an answer.",
"enabled": true,
"custom": true,
"subsections": [
{
"id": "planning-grounding",
"name": "Grounding",
"prompt": "Use approved knowledge before answering.",
"defaultPrompt": "Use retrieved knowledge before answering.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
],
"hcGuidelinePrompt": [
{
"id": "guidelines-main",
"name": "Main Guidelines",
"description": "Global answer behavior.",
"enabled": true,
"custom": true,
"subsections": [
{
"id": "guidelines-escalation",
"name": "Escalation",
"prompt": "Escalate billing disputes when policy is unclear.",
"defaultPrompt": "Escalate when unsure.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
],
"hcChannelPrompt": [
{
"id": "channel-chat",
"name": "Chat",
"description": "Chat-specific behavior.",
"enabled": true,
"custom": false,
"subsections": [
{
"id": "channel-chat-style",
"name": "Tone",
"prompt": "Keep replies concise and grounded in approved knowledge.",
"defaultPrompt": "Keep replies helpful and concise.",
"useDefault": false,
"enabled": true,
"custom": true
}
]
}
]
}
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.
401 Unauthorized
401 Unauthorized
The API key is missing, malformed, revoked, or invalid.
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.
Was this page helpful?

