Set an Agent Prompt
This operation lets you set an agent prompt for the authenticated Nexor account. This reference documents verified path, query, and top-level JSON body fields, observed response status codes, and top-level response fields. Provider-owned or deeply nested response shapes may remain open.
/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:
- Read the agent with Get Agent and keep
workflow.prompt_sha256. - Send that value as
expected_prompt_sha256with the new prompt. - 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
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
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
API key for authentication. Keys are prefixed with nxr_live_.
Path Parameters
Workflow identifier.
Body
1 - 50000Optional 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.
^[0-9a-fA-F]{64}$Response
Successful response.
true true SHA-256 (lowercase hex) of the prompt now stored. Send it as expected_prompt_sha256 on the next write.
^[0-9a-f]{64}$