Quick start

Create a token

Open the user menu in the dashboard and choose Tokens. Click Create token, give it a name you will recognise, and keep the scopes that are ticked for you. They include everything this walkthrough needs: workspaces:read, sites:read, chat:write, chat:read and publish:write.

The token is shown once and starts with mdf_mcp_. Copy it now. The examples below write it as YOUR_TOKEN. See Authentication for every field of the form.

Check the token

GET /v1/token reads the token back without running anything:

curl https://api.modulify.ai/v1/token \
  -H "Authorization: Bearer YOUR_TOKEN"

The answer carries its name, its scopes, the workspaces it can reach, when it expires and how much of this minute's call budget is left. A 401 here means the token was not pasted whole.

Find a workspace

list_workspaces takes no arguments, so the body can be left out:

curl -X POST https://api.modulify.ai/v1/list_workspaces \
  -H "Authorization: Bearer YOUR_TOKEN"

Each workspace in data carries an _id. Pick one and use it as WORKSPACE_ID below.

Find a site

curl -X POST https://api.modulify.ai/v1/list_sites \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"workspaceId":"WORKSPACE_ID"}'

Each site carries its _id. That is the projectId every site method takes, written as SITE_ID below. count holds how many sites the workspace has in all.

Send a prompt

send_message hands an instruction to the agent that builds the site, the same agent the editor's chat talks to. It spends AI credits from the workspace.

curl -X POST https://api.modulify.ai/v1/send_message \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"projectId":"SITE_ID","prompt":"Add a short FAQ section above the footer with three questions about opening hours, parking and booking."}'

When the site is free, the answer carries queued: false and a jobId, and the work has started. When the agent is already busy, the message waits in the site's queue instead and the answer carries queued: true. That is a success too, so do not send it again.

Follow the build

Ask get_job how the run is going. Start with cursor 0, and on each later call send back the cursor the last answer gave you, so you only receive new events:

curl -X POST https://api.modulify.ai/v1/get_job \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"projectId":"SITE_ID","jobId":"JOB_ID","cursor":0}'

Call it every few seconds while state is running. The run is over at succeeded, failed or cancelled. See Long-running work for every state.

Publish

curl -X POST https://api.modulify.ai/v1/publish_site \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"projectId":"SITE_ID"}'

The answer comes back once the publish has started, not when it is finished. Call get_publish_status with the same projectId every few seconds until running is false. A status of ready means the new version is live.