---
title: "Developer API and MCP - Workflow Forms"
description: "API keys, the REST API and the MCP server: manage forms, fields, branding and submissions from your own code or an AI agent."
canonical: "https://docs.workflow-forms.app/developer-api-and-mcp"
---

# Developer API and MCP

You can manage your forms, fields and submissions from your own code or from an AI agent. Workflow Forms has a **REST API** and an **MCP server**, both on the **Developer** page.

## API keys

On **Developer**, tab **API keys**, select **Create API key**, give it a **Name** and pick the **Access level**:

- **Read only** - list and read forms, fields and submissions.
- **Read & write** - also create, update and delete forms and fields, and manage submissions.

The full key is shown **once**, together with a test command and ready setup commands for AI clients. Store it securely: only a fingerprint of the key is kept, so a lost key is replaced, not recovered. Revoke a key at any time; code or agents using it lose access immediately. You can have up to 20 active keys.

Send the key as a Bearer token on every request:

```text
Authorization: Bearer wfk_your_key_here
```

## REST API

The base URL is shown on the Developer page under **REST API base URL**. It ends in `/api/v1`. The examples below use `https://shopify.workflow-forms.app/api/v1`; use the one your Developer page shows.

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/me`, `/plan` | Check the key; your plan (`FREE`, `STARTER` or `UNLIMITED`), its submissions per 30 days, how many are used and how many remain |
| GET, POST | `/forms` | List forms, or create one |
| GET, PUT, DELETE | `/forms/:id` | Read, replace or delete a form. `PUT` sends the whole form, placements included |
| GET, POST | `/fields` | List the field library, or add a field |
| GET, PUT, DELETE | `/fields/:id` | Read, replace or delete a field. The handle cannot change; default fields cannot be deleted |
| GET, PATCH | `/settings` | The shop branding of every form and the values each setting accepts; `PATCH` changes it |
| GET | `/submissions` | Submissions, newest first, without values. Filter with `?formId=` and `?status=`, page with `?page=` and `?limit=` (up to 100) |
| GET | `/submissions/:id` | One submission with its values |
| POST | `/submissions/:id` | `{ "action": "resend" }` sends it to Shopify Flow again |
| DELETE | `/submissions/:id` | Permanently deletes the submission |

```bash
curl https://shopify.workflow-forms.app/api/v1/me \
  -H "Authorization: Bearer wfk_your_key_here"
```

`GET /api/v1` (no key needed) returns the list of endpoints with the fields each one accepts.

### Forms and fields

A form is created from fields of your library: `placements` is the ordered list of `{ fieldId, required?, label?, conditions? }`. Conditions may only name fields placed on the same form, and circles are refused, exactly as in the editor. Deleting a form keeps its submissions.

### Liquid and HTML in texts

The texts of forms and fields are returned as you wrote them, with their Liquid and HTML; the API does not render them. Texts you write over the API follow the same rules as in the editor: a text with broken Liquid, or with a tag that cannot be used in a form text, is refused. A consent checkbox has no separate link settings: a link is part of its `label`. See [Liquid and HTML in your texts](https://docs.workflow-forms.app/liquid-and-html-in-texts.md).

### Translations

Translations of forms and fields can be written over the API too:

- On a **field**, `translations` holds the field in other languages for every form it is on, for example `{ "de": { "label": "Name" } }`, with placeholder, help text and options by value.
- On a **form**, `translations` holds the languages added to the form (the keys) and the form's texts in each. An empty object adds the language without texts; a missing text falls back to the main language. `defaultLocale` is the main language.
- On a **placement**, `translations` holds the label on this form per language. It wins over the field's translation.

A field's translation is used on a form only when the form has that language. See [Languages](https://docs.workflow-forms.app/languages.md).

### Branding

`GET /settings` returns the shop branding and what each value may be; `PATCH /settings` changes colors, fonts, sizes and the button style, and `null` puts a value back to the theme. A form's own branding is the `branding` of the form. Uploaded custom fonts are read-only over the API; upload them on the Settings page. See [Branding](https://docs.workflow-forms.app/branding.md).

## Submissions are personal data

Submission values are what your visitors sent you. They are stored encrypted and are returned only by `GET /submissions/:id`; the list never contains values. Give a read key only to systems that should be able to read them.

## MCP server

The MCP server lets an AI agent (Claude, Cursor, VS Code, Gemini CLI, OpenAI Codex and others) work with your forms. The **MCP** tab shows the server URL, which ends in `/api/mcp`, and a connect command per client; after you create a key, the same commands come with the key already filled in.

The tools mirror the REST API:

- Read: `list_forms`, `get_form`, `list_fields`, `get_field`, `list_submissions`, `get_submission`, `get_branding`.
- Write (read & write keys only): `create_form`, `update_form`, `delete_form`, `create_field`, `update_field`, `delete_field`, `update_branding`, `resend_submission`, `delete_submission`.

A read-only key only gets the read tools.

## Rate limits

A leaky bucket per key, the same model Shopify uses: bursts of up to 300 requests, refilling 5 per second. Over the limit you get `429` with a retry time - back off and retry, ideally with exponential backoff. Limits are the same on every plan.

The API is versioned in the path (`/api/v1`); a breaking change would ship as `/api/v2` with notice, and `v1` keeps working.

## API use and your plan

Only submissions sent from your storefront count toward your plan. Reading, creating and changing things over the API or MCP does not. See [Plans and pricing](https://docs.workflow-forms.app/plans-and-pricing.md).

## Next steps

- [Fields and the field library](https://docs.workflow-forms.app/fields-and-the-field-library.md) - the field model the API works with.
- [Conditions and multi-step forms](https://docs.workflow-forms.app/conditions-and-multi-step-forms.md) - how conditions are checked.
- [The submissions inbox](https://docs.workflow-forms.app/submissions-inbox.md) - statuses and sending to Flow again.