Skip to main content
PATCH
Set an Agent Prompt
PATCH /workflows/:id/prompt Replace an agent’s base (global) prompt — what it says, who it qualifies, and the goal it works toward. This is the editable prompt surfaced in the dashboard’s agent editor. For a per-channel override on top of this base prompt, see Set Channel Prompts.

Path Parameters

Request Body

Avoid overwriting a newer prompt

global_prompt replaces the whole prompt. If someone edits the prompt between your read and your write, a plain write erases their change. To prevent it:
  1. Read the agent with Get Agent and keep workflow.prompt_sha256.
  2. Send that value as expected_prompt_sha256 with the new prompt.
  3. On 409 PROMPT_CHANGED, read the agent again, apply your change to the current prompt, and retry.
prompt_sha256 is the SHA-256 of the prompt’s UTF-8 bytes, in lowercase hex, with no normalization. An agent with no prompt hashes as the empty string. Each successful write returns the new prompt_sha256, so you can chain writes without reading again.

Responses

200 — Prompt updated

400 — Validation error

Also returned if global_prompt exceeds 50,000 characters, or if expected_prompt_sha256 is not a 64-character hex SHA-256.

401 — Authentication error

See Authentication.

404 — Not found

409 — Prompt changed

Returned only when you send expected_prompt_sha256. The stored prompt is left as it was. A 409 with PROMPT_NOT_SAVED means the store did not keep the prompt that was sent; read the agent before retrying.

500 — Internal server error

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