Start a build through a deploy hook

trigger_deploy_hook

Calls one deploy hook now, exactly as its URL would be called, which starts a real publish of the site.

POST /v1/trigger_deploy_hookScopepublish:writeMakes changes

The latest saved version goes live on the site's public address, like pressing Publish. The tool tells the client to run it only when you ask. The response carries status, deploymentId and callId, the row the call wrote to the hook's call log.

Only one build runs per site at a time. When a build is already running, the call succeeds with status already-building and that build's deploymentId, and nothing new is started or queued, which counts as success. A started build comes back with status started once it is claimed, not when it finishes, so follow it with get_publish_status.

A hook that is turned off is refused and starts nothing, and a publish the site cannot make is refused with the reason. A hook called more than 10 times in a minute is refused for the rest of that minute, and retryAfter gives the seconds to wait.

Every call, refused or not, is logged in the hook's call log with the source mcp, or api when the tool is called through the HTTP API. Only the first call refused by the rate limit in a minute is logged. See Deploy hooks.

Request

Call it with a POST to https://api.modulify.ai/v1/trigger_deploy_hook, sending the inputs below as a JSON object. The token needs the publish: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/trigger_deploy_hook \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","hookId":"HOOK_ID"}'

Over MCP, the same method is the trigger_deploy_hook tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site id.
`hookId`	string	Yes	The hook id from `list_deploy_hooks`.

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.