Skip to main content
PATCH
Set an Agent Prompt
PATCH /workflows/:id/prompt Reemplaza el prompt base (global) de un agente — qué dice, a quién califica y hacia qué objetivo trabaja. Es el prompt editable que aparece en el editor de agentes del dashboard. Para un override por canal encima de este prompt base, ver Configurar Prompts por Canal.

Parámetros de Ruta

Cuerpo de la Solicitud

Evitar sobrescribir un prompt más nuevo

global_prompt reemplaza el prompt completo. Si alguien edita el prompt entre tu lectura y tu escritura, una escritura simple borra su cambio. Para evitarlo:
  1. Lee el agente con Consultar agente y guarda workflow.prompt_sha256.
  2. Envía ese valor como expected_prompt_sha256 junto con el nuevo prompt.
  3. Si recibes 409 PROMPT_CHANGED, vuelve a leer el agente, aplica tu cambio sobre el prompt actual y reintenta.
prompt_sha256 es el SHA-256 de los bytes UTF-8 del prompt, en hex en minúsculas, sin normalizar. Un agente sin prompt usa el hash del texto vacío. Cada escritura exitosa devuelve el nuevo prompt_sha256, así puedes encadenar escrituras sin volver a leer.

Respuestas

200 — Prompt actualizado

400 — Error de validación

También se devuelve si global_prompt supera los 50,000 caracteres, o si expected_prompt_sha256 no es un SHA-256 hexadecimal de 64 caracteres.

401 — Error de autenticación

Ver Autenticación.

404 — No encontrado

409 — El prompt cambió

Solo se devuelve cuando envías expected_prompt_sha256. El prompt guardado queda como estaba. Un 409 con PROMPT_NOT_SAVED significa que el almacenamiento no conservó el prompt enviado; lee el agente antes de reintentar.

500 — Error interno del servidor

Authorizations

X-API-Key
string
header
required

API key for authentication. Keys are prefixed with nxr_live_.

Path Parameters

id
string<uuid>
required

Workflow identifier.

Body

application/json
global_prompt
string
required
Required string length: 1 - 50000
expected_prompt_sha256
string | null

Optional version check. SHA-256 (lowercase hex) of the UTF-8 bytes of the prompt you last read, exactly as returned in workflow.prompt_sha256 or in a previous write's prompt_sha256. An agent with no prompt hashes as the empty string. When it no longer matches the stored prompt, the request answers 409 PROMPT_CHANGED and saves nothing. Omit it or send null to write without the check.

Pattern: ^[0-9a-fA-F]{64}$

Response

Successful response.

success
enum<boolean>
required
Available options:
true
workflow_id
string<uuid>
required
prompt_length
integer
required
persisted
enum<boolean>
required
Available options:
true
prompt_sha256
string
required

SHA-256 (lowercase hex) of the prompt now stored. Send it as expected_prompt_sha256 on the next write.

Pattern: ^[0-9a-f]{64}$
Last modified on October 13, 2026