# Quickstart

> Create an API key, make your first request, then create a board and put a kanban on it.

Source: https://mockflow.com/developers/quickstart

The MockFlow Boards API is a REST API for the visual boards you build in MockFlow: spaces, boards, the items on them such as kanbans, mind maps, flowcharts and wireframes, sharing, and Mida, the AI assistant. This quickstart takes you from no key to a board with a kanban on it, using `curl` from a terminal.

## Before you start

You need a MockFlow account. An API key acts as the person who creates it, so the API reaches the same boards that account can open in the app, with the same role.

Every plan can use the API. The plan sets the [rate limit](/developers/concepts/rate-limits) (60 requests a minute on Basic, 300 on Plus, 600 on Max) and the same limits as the app, such as three boards on Basic. Generating with Mida needs the Plus plan or above.

## Create an API key

1. Open the [developer console](/developers/console/) and sign in to MockFlow.
2. On the **API keys** tab, click **Create key**.
3. Enter a name, for example `Quickstart`.
4. Under **Scopes**, tick **user:read**, **boards:read** and **boards:write**.
5. Leave **Mode** on **Live**, choose when the key **Expires**, and click **Create key**.
6. Copy the key. It is shown once: MockFlow stores only a hash of it.

Keep the key in an environment variable rather than in your code, and never in code that runs in a browser:

```bash
export MOCKFLOW_API_KEY="paste your key here"
```

A key carries only the [scopes](/developers/concepts/scopes) you tick. The three above read your account and create boards and items. Add **ai:generate** to generate with Mida, and **members:write** to share spaces.

## Make your first request

Every request goes to `https://api.mockflow.com/v1` with the key in an `Authorization: Bearer` header. Start with `GET /me`, which describes the person behind the key:

```bash
curl https://api.mockflow.com/v1/me \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY"
```

The response names the person and their workspace, including its plan (`basic`, `plus` or `max`) and how many boards and spaces it has. A `401` with the code `unauthorized` means the header is missing or the key was mistyped, revoked or has expired. A `403` with `forbidden` means the key lacks a scope, and the message names the one it needs. Every error has the same shape, described in [Errors](/developers/concepts/errors).

## Create a board

`POST /boards` creates a board. Without a `spaceId` it goes in the default space.

```bash
curl https://api.mockflow.com/v1/boards \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "API quickstart" }'
```

The `201` response carries the board's `id`, which starts with `brd_`, and its `url`, which opens it in the editor. Keep the `id` for the next step:

```bash
export BOARD_ID="brd_..."
```

## Add a kanban to the board

`POST /boards/{boardId}/items` adds one item. The `type` says what it is and `data` holds its content. This adds a kanban with three columns:

```bash
curl https://api.mockflow.com/v1/boards/$BOARD_ID/items \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kanban",
    "data": {
      "columns": [
        { "id": "col_1", "title": "Research", "color": "#2196f3",
          "cards": [{ "id": "card_1", "title": "Interview five customers" }] },
        { "id": "col_2", "title": "Design", "color": "#9c27b0",
          "cards": [{ "id": "card_2", "title": "Sketch the onboarding flow" }] },
        { "id": "col_3", "title": "Launch", "color": "#4caf50",
          "cards": [{ "id": "card_3", "title": "Write the release notes" }] }
      ],
      "settings": { "boardTitle": "Product launch" }
    }
  }'
```

Items are drawn on the board by the same renderer as the editor. When the drawing finishes quickly, the answer is `201` with the new item. Otherwise it is `202` with a job, and `GET /jobs/{jobId}` reports its `status` until it is `succeeded`, with the new item's id in `result.itemIds`:

```bash
curl https://api.mockflow.com/v1/jobs/job_... \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY"
```

Open the board's `url` to see the kanban in MockFlow.

## What you can create on a board

The kanban is one of many item types. The simple ones are the items you place from the editor's toolbar, such as text, shapes, connectors, sections and comments. The rich ones are full components such as mind maps, flowcharts, wireframes, charts, tables, timelines and database diagrams, and the list grows with the product.

`GET /item-types` lists every type the API accepts, with no key needed, and `GET /item-types/{type}` returns the schema for its `data` and an example payload. To check a payload before drawing it, send it to `POST /item-types/{type}:validate`. Each type also has its own page under [Item types](/developers/reference/item-types).

## Let Mida build a board

On Plus and Max, a board can start from a description. Add a `prompt` when you create it and Mida fills the board in the background, using AI credits:

```bash
curl https://api.mockflow.com/v1/boards \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product launch",
    "prompt": "Plan a product launch with a timeline, a kanban of tasks and a mind map of risks."
  }'
```

The board is created at once and the response includes a `job`. Poll `GET /jobs/{jobId}` until it succeeds, then open the board. To be told when a job finishes instead of polling, add a `callbackUrl` to the request, as described in [Webhooks](/developers/concepts/webhooks).

## Next steps

- Read the rules every call shares: [errors](/developers/concepts/errors), [pagination](/developers/concepts/pagination), [rate limits](/developers/concepts/rate-limits), [idempotency](/developers/concepts/idempotency) and [versioning](/developers/concepts/versioning).
- Build an app that other people connect to their own MockFlow account with [OAuth apps](/developers/concepts/oauth-apps).
- Browse every endpoint in the [API reference](/developers/reference), or send requests from the browser in the [Try it console](/developers/console/try.jsp).