Workflow FormsWorkflow Forms
DeveloperDeveloper API and MCP

Developer API and MCP

Copy page

API keys, the REST API and the MCP server: manage forms, fields, branding and submissions from your own code or an AI agent.

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:

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

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.

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.

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.

Next steps