> ## Documentation Index > Fetch the complete documentation index at: https://docs.squawkvoice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace guidelines > Replace the guidelines on an agent's draft with new text > [!WARNING] > > **Start from [Get guidelines](https://docs.squawkvoice.ai/api-reference/agents/get-guidelines.md), and send the placeholders back exactly as you received them.** A `{{...}}` placeholder written with a name instead of its ID, such as `{{action.Check availability}}`, doesn't resolve. Change the text around the placeholders and leave each one as it was. * **The whole text is replaced.** Send everything the agent should keep, not only what changed. An empty string clears the guidelines. * **The last write wins.** There is no conflict check, so a replace overwrites whatever was saved before it, including an edit made in Studio. * **It's recorded.** A replace appears in [Audit Logs](https://docs.squawkvoice.ai/manage/audit-logs.md) as an update to the agent, with the key's creator as the **Actor**. ## When the Change Goes Live A replace saves to the agent's draft, exactly like typing in the **Guidelines** editor: * **An agent that has never been published** runs its draft, so its next conversation uses the new guidelines. * **A published agent** keeps using its published guidelines on phone calls, website chats and emails until it is published again, with [Publish an agent](https://docs.squawkvoice.ai/api-reference/agents/publish-agent.md) or **Publish** in Studio. Until then the agent shows **Unpublished edits**, and **Review Changes** lists the new guidelines. **Talk** and the test **Chat** use the draft straight away. `needs_publish` in the response is `true` when the agent has any unpublished change, yours or an edit made in Studio, and `live_version` names the version that is live. See [Publishing Your Agent](https://docs.squawkvoice.ai/build/ai-agents.md#publishing-your-agent). ## OpenAPI ````yaml api-reference/openapi.yaml PUT /api/v1/assistants/{assistantId}/guidelines openapi: 3.1.0 info: title: SquawkVoice API version: '1.0' description: >- Place on-demand campaign calls, and manage and publish an agent's guidelines, from your own systems. Every request is authenticated with an API key sent in the `X-API-Key` header. servers: - url: https://api.squawkvoice.ai security: - apiKey: [] tags: - name: on-demand-calls x-group: On-Demand Calls description: Place a campaign call for one contact, and cancel it before it is dialed. - name: agents x-group: Agents description: >- Read and replace an agent's guidelines, publish the agent, and see which version is live. paths: /api/v1/assistants/{assistantId}/guidelines: put: tags: - agents summary: Replace guidelines description: >- Replaces the guidelines on the agent's draft with the text you send, exactly as a save in Studio does. The response doesn't return the new text; read it back with [Get guidelines](/api-reference/agents/get-guidelines). operationId: replaceGuidelines parameters: - $ref: '#/components/parameters/assistantId' requestBody: required: true content: application/json: schema: type: object required: - guidelines additionalProperties: false properties: guidelines: type: string description: >- The whole new guidelines text, as Markdown. It replaces what's there, so send everything the agent should keep. An empty string clears the guidelines. This is the only field accepted; any other field returns a `400`. example: guidelines: >- ## Role You book appointments for Bodywell Clinic. ## Booking Check availability with {{action.8b2f6d10-4c3e-4a7b-9e15-2d6c0f8a3b91}} before offering a time. Offer at most three times. responses: '200': description: The guidelines were saved to the agent's draft. content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: type: object required: - assistant_id - needs_publish - live_version properties: assistant_id: type: string format: uuid description: The agent's ID. needs_publish: $ref: '#/components/schemas/NeedsPublish' live_version: $ref: '#/components/schemas/LiveVersion' example: success: true data: assistant_id: 3c7e1a52-8d4f-4b9a-a0e6-5f2d9c8b1e74 needs_publish: true live_version: version_id: 5e0b9c41-7a2d-4f6e-b8c3-1d9a0e4f7b62 version_number: 3 name: null published_at: '2026-10-29T14:02:11.000Z' activated_at: null '400': description: >- The body isn't a JSON object holding only `guidelines` as a string, or the text is one Studio would refuse to save. content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Invalid request body details: 'Unknown field(s): instructions. Only "guidelines" can be set.' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AgentForbidden' '404': $ref: '#/components/responses/AgentNotFound' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: assistantId: name: assistantId in: path required: true description: >- The agent's ID. Open the agent in Studio and select **Copy ID** in its header. schema: type: string format: uuid schemas: NeedsPublish: type: boolean description: >- `true` when the agent has been published and has an edit that isn't live yet, anywhere in the agent and not only in its guidelines, so phone calls, website chats and emails get it only after a publish, with **Publish** in Studio or [Publish an agent](/api-reference/agents/publish-agent). It is set by the edit, so it can stay `true` after an edit is changed back: a publish then answers `400` with nothing to publish, which you can treat as nothing to do. Always `false` for an agent that has never been published. LiveVersion: description: >- The version phone calls, website chats and emails use now. `null` when the agent has never been published: its conversations use the draft. oneOf: - type: object required: - version_id - version_number - name - published_at - activated_at properties: version_id: type: string format: uuid description: >- The version's ID. A conversation on a published version records that version's ID in the variable `interaction.AGENT_VERSION_ID`. A conversation on the draft, such as **Talk** or the test **Chat**, records `draft`. version_number: type: integer description: >- The version's number, as **Version History** in Studio shows it (V1, V2, and so on). name: type: - string - 'null' description: The version's name, or `null` when it has none. published_at: type: string format: date-time description: When this version was published. activated_at: type: - string - 'null' format: date-time description: >- When this version was last made live again with **Make this version active** in Studio, or `null` if never. - type: 'null' Error: type: object description: >- Most errors have `success: false` and a readable `error`. Some agent errors and rate-limit errors carry `message` instead. properties: success: type: boolean const: false error: type: string description: What went wrong. details: description: More detail, when there is any. message: type: string description: What went wrong, on errors that don't use `error`. data: type: object description: >- Extra detail on a few errors, such as the live version when there is nothing to publish, or the running publish on a `409`. responses: Unauthorized: description: >- The API key is missing, unknown, revoked or expired. The reply is the same in every case. content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: 'Unauthorized: Invalid credentials' AgentForbidden: description: The agent isn't in your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Forbidden: Workspace does not belong to your account.' AgentNotFound: description: Agent not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Assistant not found. TooManyRequests: description: >- Too many requests. Wait for the number of seconds in the `Retry-After` header, then retry. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: type: object properties: status: type: string const: error message: type: string example: status: error message: Too many requests, please try again later. securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: >- An API key from **Manage → API Keys** in Studio. See [Authentication](/api-reference/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.