send_message

Every message spends AI credits from the workspace that owns the site, so batch your instructions into one clear prompt rather than many small corrections. Use it for every instruction to the site agent, including answering a question the agent asked and approving or changing a plan. A 402 means the workspace has no AI credits left.

When the site is free, the generation starts at once and the response carries queued:false and a jobId. Poll get_job with that jobId until its state is no longer running.

Only one generation runs per site at a time, and this tool never fails because of that. When a generation is already running, or the last one was stopped, failed or ended part way through, the message is queued instead. The response then carries queued:true, the entry's queueItemId, the reason it was held in queueReason, whether that hold is resumable in queueResumable and its place in line in queuePosition. That is a success, so the tool tells the client not to resend it or retry in a loop.

With queueResumable:false the queue runs in order on its own as soon as the site is free. With queueResumable:true the queue stays parked on purpose, and nothing runs until somebody has looked at what went wrong: read the failure with get_job, then call resume_queue. An answer to the agent's question and a reply to a plan never queue, whatever is already waiting, because the agent is blocked until you reply.

When it is refused

A full queue is refused. A site holds at most 20 waiting messages and at most 8 from any one person, and going over either comes back as a 429 saying which cap was hit. The tool tells the client to remove an entry with remove_queued_message rather than retrying.

The message is also refused rather than queued while the site is locked because the workspace holds more sites than its plan allows. The same goes while the GitHub repository behind the site blocks editing: while its code is being moved into GitHub or back to Modulify, when Modulify has lost access to the repository or it was archived or deleted, and when the code lives in the workspace's own GitHub but the workspace is on the Free plan. See Site chat and Message queue.

Inputs

Input	Type	Required	Description
projectId	string	Yes	The site id, from list_sites or get_site.
prompt	string	Yes	What the site agent should do, as specific as an instruction to a developer. It must not be empty and is refused over 500,000 characters.
mode	string	No	build, where the agent makes the change, or plan, where it proposes a plan for you to approve first. Defaults to build, and any other value is refused.