Edit a queued message

edit_queued_message

Rewrites a message that is still waiting in a site's queue, before the site agent picks it up.

POST /v1/edit_queued_messageScopechat:writeMakes changes

The edit is optimistically concurrent. Read the queue with list_queued_messages first and send the entry's QueueVersion as expectedVersion, and a version that is no longer current is refused rather than quietly overwriting an edit somebody else made in the meantime. On a rejection the tool tells the client to read the queue again, decide whether the change still makes sense against the newer text, and only then retry with the version it just read.

You can only edit a message you queued yourself, and only while it is still queued. Anything you leave out keeps the value the queued message already holds, and content is refused over 500,000 characters. A successful edit raises the entry's QueueVersion and returns the updated entry in item.

Sending content as an empty string removes the entry from the queue instead of rewriting it, and the response then says removed:true. A message that carries files is kept in the queue even then. See Message queue.

Request

Call it with a POST to https://api.modulify.ai/v1/edit_queued_message, sending the inputs below as a JSON object. The token needs the chat:write scope.

It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

curl -X POST https://api.modulify.ai/v1/edit_queued_message \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","itemId":"ITEM_ID","expectedVersion":1}'

Over MCP, the same method is the edit_queued_message tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site id, from `list_sites` or `get_site`.
`itemId`	string	Yes	The `Id` of the queued message, exactly as `list_queued_messages` reported it.
`expectedVersion`	integer	Yes	The `QueueVersion` that `list_queued_messages` reported for this entry. A stale version is refused, so another person's edit is never silently overwritten.
`content`	string	No	The new text of the queued message. An empty string removes the entry from the queue instead of rewriting it.
`mode`	string	No	`build`, where the agent makes the change, or `plan`, where it proposes a plan for you to approve first. Leave it out to keep the current mode.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.