> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Section hub for reading prompt configuration and saving prompt versions through Fini's public API.

Prompts are the instruction layers behind [Configuration → Prompts](/en/configuration/prompts): planning, main guidelines, and channel-specific overrides. Use these public routes to read one agent's current prompt configuration, inspect saved prompt history, save a new prompt version, or stage a draft prompt version for review.

<Info>
  The wire-format paths still use `/hc-prompt` because that is the current controller contract. In this reference, we call them **prompts** because they manage the agent instructions you configure in the product.
</Info>

<Note>
  The read routes return a merged view: Fini overlays the agent's saved prompt version on top of the workspace template prompt. That is why read responses include helper fields like `defaultPrompt` and `custom`. The write route stores a raw version payload and does not perform that merge in its response.
</Note>

## Reference pages

<CardGroup cols={2}>
  <Card title="Get prompts" icon="eye" href="/en/api-reference/get-prompts">
    `GET /v2/bots/{id}/hc-prompt/public` - fetch the agent's current merged prompt configuration.
  </Card>

  <Card title="Get prompt history" icon="clock-rotate-left" href="/en/api-reference/get-prompt-history">
    `GET /v2/bots/{id}/hc-prompt/history/public` - list metadata for saved prompt versions.
  </Card>

  <Card title="Get prompt version" icon="code-commit" href="/en/api-reference/get-prompt-version">
    `GET /v2/bots/{id}/hc-prompt/{promptId}/public` - fetch one saved prompt version as a merged prompt object.
  </Card>

  <Card title="Update prompts" icon="pen" href="/en/api-reference/update-prompts">
    `POST /v2/bots/{id}/hc-prompt/public` - save a new prompt version for one agent.
  </Card>

  <Card title="Create prompt draft version" icon="file-pen" href="/en/api-reference/create-prompt-draft-version">
    `POST /v2/bots/{id}/hc-prompt/versions/public` - create a draft prompt version without publishing it.
  </Card>

  <Card title="Get prompt draft version" icon="file-magnifying-glass" href="/en/api-reference/get-prompt-draft-version">
    `GET /v2/bots/{id}/hc-prompt/versions/{versionId}/public` - fetch one exact stored draft version for review.
  </Card>

  <Card title="Publish prompt draft version" icon="paper-plane" href="/en/api-reference/publish-prompt-draft-version">
    `POST /v2/bots/{id}/hc-prompt/versions/{versionId}/publish/public` - publish one reviewed draft version.
  </Card>
</CardGroup>

## Endpoint map

| Method | Path                                                        | Scope   | Purpose                                                         |
| ------ | ----------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `GET`  | `/v2/bots/:id/hc-prompt/public`                             | `read`  | Fetch the current merged prompts for one agent.                 |
| `GET`  | `/v2/bots/:id/hc-prompt/history/public`                     | `read`  | List saved prompt-version metadata for one agent, newest first. |
| `GET`  | `/v2/bots/:id/hc-prompt/:promptId/public`                   | `read`  | Fetch one saved prompt version as a merged prompt object.       |
| `POST` | `/v2/bots/:id/hc-prompt/public`                             | `write` | Save a new prompt version for one agent.                        |
| `POST` | `/v2/bots/:id/hc-prompt/versions/public`                    | `write` | Create a draft prompt version for one agent.                    |
| `GET`  | `/v2/bots/:id/hc-prompt/versions/:versionId/public`         | `read`  | Fetch one exact stored draft version for review.                |
| `POST` | `/v2/bots/:id/hc-prompt/versions/:versionId/publish/public` | `write` | Publish one reviewed, non-stale draft version.                  |

## Prompt object

<ResponseField name="id" type="string">
  Prompt version ID. On read routes, this is the saved version ID when one exists, otherwise the template prompt ID.
</ResponseField>

<ResponseField name="botId" type="string">
  Agent ID the prompt is scoped to.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp for when this prompt version was created.
</ResponseField>

<ResponseField name="createdBy" type="string">
  Creator identifier recorded for the saved version.
</ResponseField>

<ResponseField name="hcPlanningPrompt" type="PromptSection[]">
  Planning Prompt sections.
</ResponseField>

<ResponseField name="hcGuidelinePrompt" type="PromptSection[]">
  Main Guidelines sections.
</ResponseField>

<ResponseField name="hcChannelPrompt" type="PromptSection[]">
  Channel Prompt sections.
</ResponseField>

## PromptSection object

<ResponseField name="id" type="string">
  Section ID.
</ResponseField>

<ResponseField name="name" type="string">
  Section name shown in the dashboard.
</ResponseField>

<ResponseField name="description" type="string">
  Section description.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether the section is enabled.
</ResponseField>

<ResponseField name="custom" type="boolean">
  Present on merged read responses. `true` means this section does not come from the default template.
</ResponseField>

<ResponseField name="subsections" type="PromptSubsection[]">
  Subsections inside the section.
</ResponseField>

## PromptSubsection object

<ResponseField name="id" type="string">
  Subsection ID.
</ResponseField>

<ResponseField name="name" type="string">
  Subsection name shown in the dashboard.
</ResponseField>

<ResponseField name="prompt" type="string">
  The saved custom prompt text for this subsection. On merged read responses, this can be an empty string when `useDefault` is `true`.
</ResponseField>

<ResponseField name="defaultPrompt" type="string">
  Present on merged read responses. The default template text Fini would use if `useDefault` is `true`.
</ResponseField>

<ResponseField name="useDefault" type="boolean">
  Whether this subsection should use the template prompt text instead of the custom `prompt` value.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether the subsection is enabled.
</ResponseField>

<ResponseField name="custom" type="boolean">
  Present on merged read responses. `true` means this subsection does not come from the default template.
</ResponseField>

<Note>
  If you want to edit prompts safely through the API, the simplest workflow is: call [Get prompts](/en/api-reference/get-prompts), modify the returned arrays, then send those arrays back to [Update prompts](/en/api-reference/update-prompts). That preserves section IDs and ordering.
</Note>