formio-api

name

formio-api

description

Comprehensive Form.io API reference — every endpoint in the Form.io API Postman collection across platform admin, project admin, runtime/end-user, and PDF scopes. Use when the user asks to call, script, inspect, or document any Form.io REST endpoint: platform/project auth; projects, stages, tenants, teams; forms, resources, and revisions (create, list, update, import, export); actions; roles; end-user registration and login; submissions (submit, query, patch, delete); aggregation reports; PDF template uploads and submission downloads; health/status. Also for x-jwt-token auth questions and the base URL vs project URL distinction. Not for: building a whole application around Form.io (see formio-application); planning a data model (see formio-resource-planner); authoring Form.io JSON schemas (see formio-schema); calling the JavaScript SDK — `Formio.*` statics, `new Formio(...)` instances, `Utils.*` helpers (see formio-sdk).

Form.io API Skills

Single entry point for the full Form.io REST API surface. Detailed endpoint references live under ./references/ — one file per capability group.

Terminology

Two distinct endpoints exist. These references NEVER conflate them:

• baseUrl / base_url → platform deployment endpoint → FORMIO_BASE_URL (the Postman {{baseUrl}} variable when used bare, without {{projectName}})
• projectUrl / {{baseUrl}}/{{projectName}} → project endpoint → FORMIO_PROJECT_URL (a separate environment variable — not a computed sub-path)

Authentication

All endpoints (except Server API health/status) require an x-jwt-token header populated by the MCP server's browser-based portal-login flow. The MCP server attaches this header automatically via formioFetch. See references/runtime-auth.md or references/platform-auth.md for details.

MCP Tool Preference

Prefer first-party MCP tools (form_create, form_get, form_list, form_update, role_create, role_list, role_update, project_export, project_import) over raw HTTP when both paths exist. Each reference doc surfaces the preferred tool alongside its HTTP fallback in a mapping table. Authentication is implicit — any authenticated tool call triggers the portal-login flow on first use.

Scope map

Platform scope — ${FORMIO_BASE_URL}/

• platform-auth — platform-admin login, portal users, identity providers
• platform-projects — project CRUD, export, import
• platform-teams — teams, membership, project access
• platform-staging — stages, version tagging, cross-stage deploys
• platform-tenants — multi-tenant projects and tenant admins
• server-status — liveness, health, version diagnostics

Project scope — ${FORMIO_PROJECT_URL}/

• project-auth — project-admin login, admin resource
• project-roles — role CRUD
• project-forms — form/resource CRUD, import, export
• project-form-revisions — revision enablement, drafts, publish
• project-actions — form action CRUD (email, webhook, role-assignment, etc.)

Runtime scope — ${FORMIO_PROJECT_URL}/

• runtime-auth — end-user registration and login on the built-in user resource
• runtime-custom-users — custom user resources, custom roles, Login/Role-Assignment actions
• runtime-access-control — "own" submission access, group permissions
• runtime-reports — aggregation pipelines across submissions
• runtime-submissions — submission CRUD, validate, patch, revisions

PDF scope — ${FORMIO_PROJECT_URL}/pdf-proxy/

• pdf-api — PDF template upload, PDF-backed forms, submission-to-PDF download

How to use this skill

When the user asks an API-oriented question, identify the scope (platform / project / runtime / PDF) and open the matching reference file under ./references/. Each reference documents:

• Endpoints (method + path relative to the scope's root URL)
• Request / response shapes
• Related reference docs
• MCP-tool mapping (where a first-party tool covers the operation)

Do not merge content across scopes — each reference names its own base URL and endpoint set.