> ## Documentation Index > Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update guidelines > Change an agent's guidelines and response style. Only the fields sent change. `sections` is the whole set of guideline sections, so a request with it needs `If-Match`: a section left out is deleted, a new type is added, and a section sent as it is stays as it is. Answers with the agent's guidelines. Applies from the next call. In the web app, the API key's name shows as who last changed each section. ## OpenAPI ````yaml /api-reference/v1/openapi.json patch /v1/agents/{id}/guidelines openapi: 3.1.0 info: description: >- Authenticate every request with an org API key: `Authorization: Bearer phk_…`. title: Phonely API version: '1' servers: - description: US url: https://api.us.phonely.ai - description: AU url: https://api.au.phonely.ai security: [] paths: /v1/agents/{id}/guidelines: patch: tags: - Agents summary: Update guidelines description: >- Change an agent's guidelines and response style. Only the fields sent change. `sections` is the whole set of guideline sections, so a request with it needs `If-Match`: a section left out is deleted, a new type is added, and a section sent as it is stays as it is. Answers with the agent's guidelines. Applies from the next call. In the web app, the API key's name shows as who last changed each section. operationId: update_agent_guidelines parameters: - description: The agent's ID. in: path name: id required: true schema: description: The agent's ID. title: Id type: string - description: >- The `ETag` from your last read: the change is made only if the resource still has it, otherwise `412`. Optional, except that a change replacing a list needs it (`428` without it). in: header name: If-Match required: false schema: anyOf: - type: string - type: 'null' description: >- The `ETag` from your last read: the change is made only if the resource still has it, otherwise `412`. Optional, except that a change replacing a list needs it (`428` without it). title: If-Match - description: Optional. Must be the key's org. in: header name: Phonely-Organization required: false schema: anyOf: - type: string - type: 'null' description: Optional. Must be the key's org. title: Phonely-Organization requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentGuidelinesUpdate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentGuidelines' description: Successful Response headers: ETag: description: >- The resource's current version. Send it as `If-Match` to change it only if it's unchanged. schema: type: string Phonely-Organization: description: The authorized organization for this request. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request is invalid: a malformed body, a bad or unknown field, or an unknown query parameter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The API key is missing, invalid or revoked. headers: WWW-Authenticate: description: Always `Bearer`. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The key can't do this: a read-only key writing, or `Phonely-Organization` naming another org. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The resource doesn't exist, or belongs to another organization. '412': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- `If-Match` isn't the resource's current `ETag`: it changed since you read it. '428': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The change replaces a list and came without `If-Match`. Read the resource, then send its `ETag`. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limited. Retry after the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds until the request can be retried. schema: type: integer '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error. Contact support with the request ID. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Authentication, authorization or another required service is temporarily unavailable. security: - HTTPBearer: [] components: schemas: AgentGuidelinesUpdate: additionalProperties: false description: >- What to change. Only the fields sent change; `sections` is the whole set, so send `If-Match`. properties: is_speech_humanized: anyOf: - type: boolean - type: 'null' description: >- Whether the agent adds natural speech habits, such as short pauses and filler words. title: Is Speech Humanized personality: anyOf: - description: >- Known values: `casual`, `humorous`, `direct`, `formal`, `persuasive`, `friendly`. More can be added, so handle values you don't recognize. type: string x-extensible-enum: - casual - humorous - direct - formal - persuasive - friendly - type: 'null' description: The tone the agent takes with callers. title: Personality sections: anyOf: - items: $ref: '#/components/schemas/GuidelineSectionUpdate' maxItems: 7 type: array - type: 'null' description: >- All the guideline sections the agent has, in any order. A section left out is deleted, a new type is added, and a section sent as it is stays as it is. title: Sections title: AgentGuidelinesUpdate type: object AgentGuidelines: additionalProperties: false description: >- How an agent behaves in conversation: its guideline sections and response style. properties: agent_id: description: The agent's ID. title: Agent Id type: string is_speech_humanized: description: >- Whether the agent adds natural speech habits, such as short pauses and filler words. title: Is Speech Humanized type: boolean object: const: agent_guidelines default: agent_guidelines description: The type of this object, always `agent_guidelines`. title: Object type: string personality: description: >- The tone the agent takes with callers. Known values: `casual`, `humorous`, `direct`, `formal`, `persuasive`, `friendly`. More can be added, so handle values you don't recognize. title: Personality type: string x-extensible-enum: - casual - humorous - direct - formal - persuasive - friendly sections: description: >- The guideline sections the agent has, in the order the web app shows them. Each type appears at most once. items: $ref: '#/components/schemas/GuidelineSection' title: Sections type: array required: - object - agent_id - personality - is_speech_humanized - sections title: AgentGuidelines type: object ErrorResponse: additionalProperties: false description: The body of every `/v1` error. properties: error: $ref: '#/components/schemas/Error' description: What went wrong. required: - error title: ErrorResponse type: object GuidelineSectionUpdate: additionalProperties: false properties: content: anyOf: - type: string - type: 'null' description: >- The guideline, in Markdown. `null` or blank keeps the section, empty. title: Content name: anyOf: - type: string - type: 'null' description: >- The custom section's name, not blank. Other sections keep the name the web app gives them, so leave it out or send it as it is. title: Name type: description: >- Which section this is. Each type at most once. Known values: `objective`, `response_style`, `never_do`, `general_info`, `rebuttals`, `out_of_scope`, `custom`. More can be added, so handle values you don't recognize. title: Type type: string x-extensible-enum: - objective - response_style - never_do - general_info - rebuttals - out_of_scope - custom required: - type title: GuidelineSectionUpdate type: object GuidelineSection: additionalProperties: false properties: content: anyOf: - type: string - type: 'null' description: The guideline, in Markdown. `null` when the section is empty. title: Content name: description: >- The section's name in the web app. A custom section has the name its owner gave it. title: Name type: string type: description: >- Which section this is. Known values: `objective`, `response_style`, `never_do`, `general_info`, `rebuttals`, `out_of_scope`, `custom`. More can be added, so handle values you don't recognize. title: Type type: string x-extensible-enum: - objective - response_style - never_do - general_info - rebuttals - out_of_scope - custom required: - type - name - content title: GuidelineSection type: object Error: additionalProperties: false properties: code: description: >- What went wrong, stable and machine-readable. Known values: `validation_failed`, `invalid_cursor`, `invalid_api_key`, `invalid_user_token`, `user_unavailable`, `insufficient_access`, `organization_mismatch`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `agent_limit_reached`, `agent_too_large`, `sms_setup_required`, `opportunity_analysis_not_set_up`, `precondition_failed`, `payload_too_large`, `unsupported_media_type`, `precondition_required`, `rate_limited`, `internal_error`, `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`, `gateway_timeout`. More can be added, so handle values you don't recognize. title: Code type: string x-extensible-enum: - validation_failed - invalid_cursor - invalid_api_key - invalid_user_token - user_unavailable - insufficient_access - organization_mismatch - forbidden - not_found - method_not_allowed - conflict - agent_limit_reached - agent_too_large - sms_setup_required - opportunity_analysis_not_set_up - precondition_failed - payload_too_large - unsupported_media_type - precondition_required - rate_limited - internal_error - knowledge_processing_failed - bad_gateway - service_unavailable - gateway_timeout details: description: One entry per problem field. Empty when the error has none. items: $ref: '#/components/schemas/ErrorDetail' title: Details type: array message: description: For people. Wording can change; branch on `code`. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: Also in the `X-Request-Id` header. Quote it to support. title: Request Id required: - code - message - details - request_id title: Error type: object ErrorDetail: additionalProperties: false properties: field: description: >- The field the issue is about, as sent: `agent_id`, `limit`. Empty when none. title: Field type: string issue: description: >- What is wrong with the field. Known values: `required`, `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`, `out_of_range`, `invalid_cursor`, `read_only_field`. More can be added, so handle values you don't recognize. title: Issue type: string x-extensible-enum: - required - unknown_field - invalid_json - invalid_type - invalid_value - out_of_range - invalid_cursor - read_only_field message: description: 'For people: what is wrong with this field.' title: Message type: string required: - field - issue - message title: ErrorDetail type: object securitySchemes: HTTPBearer: description: 'An org API key: `Authorization: Bearer phk_…`' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.