curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/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/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/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
Update prompts
Save a new prompt version for one agent.
POST
/
v2
/
bots
/
{id}
/
hc-prompt
/
public
curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/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/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/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
}
]
}
]
}
Saves a new prompt version for one agent and returns the stored version.
This route creates a new saved prompt version. It does not patch a prompt in place.
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 prompts you want to update. 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.
For write payloads, subsection helper fields from merged reads such as
defaultPrompt and custom are not required. A safe round-trip pattern is to start from Get prompts, edit the arrays in place, and send them back.Response
Returns the savedPrompt version.
curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/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/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/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
}
]
}
]
}
Current controller behavior: this response is the stored version row, not the merged template view. If you need the merged read shape with
defaultPrompt and custom, call Get prompts after writing.Errors
400 Bad Request
400 Bad Request
The body is malformed. All three top-level prompt arrays are required.
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.404 Not Found
404 Not Found
The agent ID does not exist.
406 Not Acceptable
406 Not Acceptable
Current controller behavior: if the agent belongs to a different workspace, this route returns
406 with an invalid-agent message rather than 403.500 Internal Server Error
500 Internal Server Error
Fini failed while saving the prompt version in storage.
Was this page helpful?
⌘I

