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 (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 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:

export MOCKFLOW_API_KEY="paste your key here"

A key carries only the 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:

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.

Create a board

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

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:

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:

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:

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.

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:

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.

Next steps

• Read the rules every call shares: errors, pagination, rate limits, idempotency and versioning.

• Build an app that other people connect to their own MockFlow account with OAuth apps.

• Browse every endpoint in the API reference, or send requests from the browser in the Try it console.