# Quick start

Source: https://modulify.ai/docs/api/quick-start

Create a token, check it, find a site, send it a prompt, follow the build and publish the result.

This walks through a real session with `curl`: the same calls a script makes to change a site and put it live. Every request is a `POST` to `https://api.modulify.ai/v1/` followed by the method name, with the arguments as a JSON object.

## Before you begin

You need a Modulify account with at least one site, and a workspace role that holds the **API access** permission. Workspace owners hold every permission. See [Members and roles](https://modulify.ai/docs/reference/members-and-roles#every-permission).

### 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](https://modulify.ai/docs/api/authentication) for every field of the form.

### Check the token

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

```bash
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:

```bash
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

```bash
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.

```bash
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:

```bash
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](https://modulify.ai/docs/api/long-running-work) for every state.

### Publish

```bash
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.

## What to do next

- [Building with prompts](https://modulify.ai/docs/api/building-with-prompts) covers plans, questions from the agent, the queue and stopping a run.
- [Errors](https://modulify.ai/docs/api/errors) explains every status code you can get back.
- [All methods](https://modulify.ai/docs/api/methods) lists everything else the API can do.