> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keebai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PUT /v1/agents/{id}/prompts/{section}
> Write one section of an agent's prompt, leaving the rest alone.
Replaces the text of **that one section** and creates it if it was not there. The rest of the agent is untouched, which is the difference between this and sending `prompts` to [the update endpoint](/dev/endpoints/agents-update) — that one replaces them all.
Every save that changes the text leaves [a version](/dev/endpoints/agents-prompt-versions-list) behind, so an integration that writes sections gets an audit trail and an undo for free.
## Endpoint
```
PUT https://api.keebai.com/v1/agents/{id}/prompts/{section}
```
## Required scope
`agents:write`
## Path parameters
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `id` | `string` | `ObjectId` of the agent. |
| `section` | `string` | Section type from [the catalogue](/dev/endpoints/prompt-types-list), for example `business_context`. |
## Body
| Field | Type | Required | Description |
| ---------- | -------- | -------- | ---------------------------------------------------------------------- |
| `markdown` | `string` | Yes | The complete section text, plain markdown, up to 20 000 characters. |
| `label` | `string` | No | A title of your own for this section. Omit it to keep the current one. |
## Example request
```bash curl theme={"system"}
curl -X PUT https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0/prompts/agent_limits \
-H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"markdown": "Los precios los das del catálogo. Si no está, ofreces confirmarlo con el equipo.\n\nNo prometes horarios de entrega: dices el rango que aparece en el pedido."
}'
```
```js JavaScript theme={"system"}
await fetch(
"https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0/prompts/agent_limits",
{
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ markdown: limitsText }),
},
);
```
```python Python theme={"system"}
import os, requests
requests.put(
"https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0/prompts/agent_limits",
headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
json={"markdown": limits_text},
timeout=10,
).raise_for_status()
```
## Response
### 200 OK
Returns the whole agent, so you can see the section in place without a second read.
```json theme={"system"}
{
"agent": {
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Camila",
"model": "gpt-5",
"prompts": [
{ "section": "business_context", "label": null, "markdown": "..." },
{ "section": "agent_limits", "label": null, "markdown": "Los precios los das del catálogo..." }
]
}
}
```
### 401 Unauthorized
Missing, invalid, revoked, or expired token.
### 403 Forbidden
The token does not have the `agents:write` scope.
### 404 Not Found
`ASSISTANT_NOT_FOUND` when no agent has that id in the token's company and project, or `PROMPT_SECTION_NOT_FOUND` when the section is not in the catalogue. The error lists the valid sections.
### 502 Bad Gateway
The agent service is unreachable.
## Operational notes
* **Send the whole section, not the new paragraph.** The text is replaced. Appending is your job before the call.
* **An unknown section is rejected, on purpose.** Storing it would return `200` and change nothing: the agent only reads sections the catalogue declares.
* **Two writes to different sections of the same agent can lose one.** The section is written by reading the agent, replacing that entry and saving it back, so simultaneous writes race. Serialise your writes per agent.
* **Saving identical text does not create a version.** The history records changes, not calls.
* **This does not restart anything.** The agent picks the new text up on its next turn; conversations already in flight finish on what they had.
## OpenAPI
````yaml PUT /v1/agents/{id}/prompts/{section}
openapi: 3.0.0
info:
title: Keebai Public API
description: Superficie pública REST autenticada con Personal Access Tokens (PAT).
version: 1.0.0
contact: {}
servers:
- url: https://api.keebai.com
description: Production
security: []
tags: []
paths:
/v1/agents/{id}/prompts/{section}:
put:
tags:
- agents
summary: Escribir una seccion del prompt
description: >-
Reemplaza el texto de ESA seccion y deja el resto como estaba. La crea
si no existia. Cada guardado deja una version nueva en el historial. Una
seccion que no este en el catalogo devuelve 404
PROMPT_SECTION_NOT_FOUND: guardarla igual seria un 200 sin ningun efecto
en el agente.
operationId: PublicAgentsController_setPrompt
parameters:
- name: id
required: true
in: path
schema:
type: string
- name: section
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPromptWriteDto'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAgentEnvelopeDto'
security:
- PAT: []
components:
schemas:
PublicPromptWriteDto:
type: object
properties:
label:
type: string
maxLength: 150
markdown:
type: string
description: El texto completo de la seccion, en markdown.
required:
- markdown
PublicAgentEnvelopeDto:
type: object
properties:
agent:
$ref: '#/components/schemas/PublicAgentDto'
required:
- agent
PublicAgentDto:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
avatar_url:
type: string
model:
type: string
voice_response_enabled:
type: boolean
description: Indica si la respuesta de voz está habilitada.
created_at:
type: string
required:
- id
- name
- model
- voice_response_enabled
securitySchemes:
PAT:
scheme: bearer
bearerFormat: kbai_pk_
type: http
description: >-
Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal
con permiso `developer.manage_tokens`.
````