Skip to main content
POST
/
v2
/
bots
/
{id}
/
hc-prompt
Update prompts
curl --request POST \
  --url https://api-prod.usefini.com/v2/bots/{id}/hc-prompt \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "hcPlanningPrompt": [
    {}
  ],
  "hcGuidelinePrompt": [
    {}
  ],
  "hcChannelPrompt": [
    {}
  ]
}
'
Saves a new prompt version for one agent and returns the stored version.
Current controller behavior: the workspace-API-key write route uses POST /v2/bots/{id}/hc-prompt and does not add a /public suffix, even though the read routes do.
This route creates a new saved prompt version. It does not patch a prompt in place.

​
Headers

​
Authorization
string
required
Bearer token containing your Fini workspace API key. Format: Bearer fini_... The key needs write scope.
​
Content-Type
string
required
application/json

​
Path parameters

​
id
string
required
Agent ID whose prompts you want to update. Use List agents to get the botId.

​
Body parameters

​
hcPlanningPrompt
PromptSection[]
required
Full Planning Prompt section array. Send the complete array, not just the section you changed.
​
hcGuidelinePrompt
PromptSection[]
required
Full Main Guidelines section array.
​
hcChannelPrompt
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 saved Prompt version.
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

The body is malformed. All three top-level prompt arrays are required.
The API key is missing, malformed, revoked, or invalid.
The API key does not include the write scope required for this route.
The agent ID does not exist.
Current controller behavior: if the agent belongs to a different workspace, this route returns 406 with an invalid-agent message rather than 403.
Fini failed while saving the prompt version in storage.