formio-api skill
✓ VerifiedProvides a comprehensive reference for Form.io REST API endpoints across platform, project, runtime, and PDF scopes.
- GitHub stars
- 9
- Files
- 18
- Last commit
- Nov 6, 2026
- License
- MIT
- Allowed tools
- —
What does the formio-api skill do?
formio-api provides a comprehensive reference for Form.io REST API endpoints across platform, project, runtime, and PDF scopes.
Summary generated from the skill's SKILL.md.
About the formio-api skill
Developers needing to interact with the Form.io REST API can use this skill to access a complete reference of endpoints across platform, project, runtime, and PDF scopes. It serves as a central documentation hub for inspecting, scripting, or documenting endpoints related to forms, submissions, roles, actions, and teams. When an agent is tasked with calling or documenting a specific Form.io resource, it uses this skill to identify the correct URL structures and authentication requirements, such as the x-jwt-token header.
This skill is intended for API-oriented tasks rather than building applications or designing JSON schemas. It provides guidance on using first-party MCP tools like form_create, role_list, and project_get instead of making manual HTTP requests. By utilizing the project_get tool, agents can resolve the correct Project URL and Base URL for a specific working directory, ensuring that any subsequent tool calls target the intended deployment without requiring the user to manually provide configuration details.
What an agent can do with it
- 1Documenting REST endpointsAn agent can provide detailed documentation for specific Form.io capabilities like project management or user registration.
- 2Resolving project configurationsA developer can ask an agent to determine which Form.io project is currently targeted by the active working directory.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the formio-api skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the formio-api skill in Plugin
/plugin marketplace add formio/ai /plugin install formio-ai@formio
Install the formio-api skill in Claude Code
~/.claude/skills/formio-api/SKILL.md
$ npx degit formio/ai/plugin/skills/formio-api ~/.claude/skills/formio-apiInstall the formio-api skill in Claude Code (project)
.claude/skills/formio-api/SKILL.md
$ npx degit formio/ai/plugin/skills/formio-api .claude/skills/formio-apiInstall the formio-api skill in Codex
~/.agents/skills/formio-api/SKILL.md
$ npx degit formio/ai/plugin/skills/formio-api ~/.agents/skills/formio-apiInstall the formio-api skill in Gemini CLI
~/.gemini/skills/formio-api/SKILL.md
$ npx degit formio/ai/plugin/skills/formio-api ~/.gemini/skills/formio-apiInstall the formio-api skill in Claude.ai
npx degit formio/ai/plugin/skills/formio-api formio-api && zip -r formio-api.zip formio-api # claude.ai → Customize → Skills → + → Create skill → Upload a skill → formio-api.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableformio/ai/plugin/skills/formio-api is public and reachablegithub.com/formio/ai/tree/HEAD/plugin/skills/formio-api ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-06github.com/formio/ai/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/formio/ai/blob/HEAD/plugin/skills/formio-api/SKIL ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/formio/ai/blob/HEAD/plugin/skills/formio-api/SKIL ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 97 linesgithub.com/formio/ai/blob/HEAD/plugin/skills/formio-api/SKIL ↗Pass
SKILL.md
View on GitHubForm.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.
Preflight — the Form.io MCP server
Check this when you reach your first Form.io tool call, not when this skill activates. The check is whether form_list is callable by you, under whatever name this client exposes it. If it is, proceed. If it is not, load the formio-mcp-setup skill and use it to help the user connect the server; that skill is the only remedy you offer, and this skill writes no MCP configuration itself.
A missing server blocks that call, not the turn. Reading this skill, answering a question from it, planning, and writing files to the working directory all need no server. Do everything that needs no server first and in full, then raise the gap when you actually reach the call that needs it. Opening with a blocked-on-setup message — or asking for a Project URL before there is anything to write to it — spends the user's turn on a step that was not due.
Never work around missing tools
Do not work around missing tools by making direct HTTP requests against a Form.io deployment, and do not write a throwaway script that makes them for you. This library documents the whole Form.io REST surface, which makes hand-rolling requests tempting and wrong — it bypasses the guardrails the tools enforce and can write to a live deployment unreviewed. Stop and report what is blocking instead.
That ban is on build-time work — the configuring you do in this session. It says nothing about the application you are building: an app is expected to call the Form.io REST API at runtime, to log its users in and to read and write their submissions, and formio-api's runtime-scope references document those endpoints for exactly that code.
Which project the tools target
Available tools are not a configured project. Every Form.io tool resolves which project it targets per working directory, and with no cwd argument the server takes that directory from the client's workspace root. Before the first call that reads from or writes to a deployment, ask the server what this directory resolves to by calling the project_get tool without cwd, and read the cwdSource it reports. When cwdSource is server or claude-project-dir, the directory is a guess — the MCP server's own, fixed at spawn, or a launch default — and may be mapped to a different project, so pass cwd — the user's current working directory — on a second project_get call and on the Form.io tool calls after it. Otherwise pass cwd only to target another directory, such as one application in a monorepo; and if project_get refuses because the client reports several workspace roots, pass cwd set to the one the user is working in. Do not shell out for this: the connected server answers it directly, with the same resolver every other tool uses, so what it reports is what the next call targets. If project_get is not callable, the connected server predates it — load the formio-mcp-setup skill, which moves the pinned version forward.
What project_get returns IS the configuration. There is one value to think about — the Project URL, the full URL of the Form.io project this work reads and writes. The Base URL (the deployment hosting it) is normally DERIVED from that project URL rather than supplied, so it is not a second thing to ask for. The values may come from a committed formio.json tracked with the application's own source, from this directory's mapping, or from the environment — the report says which. Do not ask the user to confirm or re-supply either one.
Branch on the status it returns. On ok, proceed. On not-configured — nothing is recorded for this directory — relay that message's own instruction to the user, ask for the single value it names, record it with project_set, and call project_get again. On base-url-unresolved the project IS recorded and one named value is still missing — the Base URL, for a project URL that names no deployment of its own: relay that message the same way, ask the user for that one value, and do exactly what that message names — which record the deployment goes in decides what the fix IS, and the report names it rather than leaving you to compose one. For a project this directory's own mapping holds, that is a project_set call, and the report also carries it as a structured remedy. For a project a committed formio.json holds, it is an EDIT to that file — the report names the path and the key, there is no remedy field to act on, and this server never writes a committed file, so composing a project_set call there is refused. Then call project_get again. Do not re-ask the user for the Project URL there; the report already reported it, and the call it names carries it for you. If the call fails outright instead of returning a status, it could not answer at all (an unreadable ~/.formio/projects.json, a formio.json that will not parse, a malformed URL): do NOT interview, because a project_set would fail for the same unreported reason and the loop would repeat with the cause never named — relay the error and stop until it is fixed. Before the first call that WRITES (form_create, form_update, form_publish, form_revert, role_create, role_update, action_create, action_update, action_delete, project_import, project_tag_create), state the resolved Project URL and Base URL in one line, so a wrong target is caught before anything is written to it.
Never invent a Base URL, never reuse one from another project or an earlier session, and never edit ~/.formio/projects.json by any means — its shape, its 0600 mode, and its merge rules belong to the server, and project_set is how you reach it. The server's own messages carry the URL shapes and the remedy for each; this skill does not restate them.
Terminology
Two distinct endpoints exist. These references NEVER conflate them:
baseUrl/base_url→ the platform deployment endpoint, written{baseUrl}as a substitution slot (the Postman{{baseUrl}}variable when used bare, without{{projectName}})projectUrl/project_url→ the project endpoint, written{projectUrl}as a substitution slot (Postman composes it as{{baseUrl}}/{{projectName}}, which is a Postman detail rather than a rule about the URL — see below)
Both are values project_get reports and you substitute into the endpoint. Neither is read from the environment.
The Postman collection composes the project endpoint as {{baseUrl}}/{{projectName}}, but never build a project URL that way yourself — only one of the deployment routings puts the project on a path under the base URL, so composing it that way is wrong for the others. Read both values from the MCP server instead, by calling project_get as the preflight above does, and use exactly what it reports.
Two consequences worth stating, because both look like mistakes and are not: https://api.form.io/examples is not a hosted project URL, and a project host that differs from the base URL's host is normal rather than an error. Never treat a *.form.io host as a base URL.
The routing shapes themselves are not catalogued here. The MCP server carries them in its own guidance and in the message it raises when a URL is missing — one copy, reaching every caller including an agent with no skills installed — so relay what it says rather than reasoning about shapes in this document.
Authentication
Every endpoint except Server API health/status takes a JWT in the x-jwt-token header, and which JWT depends on who is calling. Build-time calls — forms, actions, roles, project settings — carry the JWT from the MCP server's browser-based portal-login flow, which the server attaches automatically via formioFetch. Runtime calls — the runtime-* references, made by the finished application on behalf of its end user — carry that end user's JWT from login, or no token where the Anonymous role holds the permission; application code never receives or sends the portal-login JWT. 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, form_publish, form_revert, form_revision_list, form_revision_get, role_create, role_list, role_update, action_type_list, action_type_get, action_create, action_list, action_get, action_update, action_delete, project_export, project_import, project_tag_list, project_tag_create) over raw HTTP when both paths exist; project_get and project_set resolve and record which project those tools target. 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. The list tools return one page at a time, with total and hasMore beside the items — page with skip while hasMore is true. A failed tool call's text starts with a code in brackets, such as [NOT_FOUND] or [HISTORY_NOT_ACCEPTED]; branch on that code rather than on the wording after it.
Scope map
Platform scope — {baseUrl}/
- 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 — {projectUrl}/
- 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 — {projectUrl}/
- runtime-auth — end-user registration and login on the built-in
userresource - 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 — {projectUrl}/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.
Files in this skill
18formio-api skill questions
How do I install the formio-api skill in Claude Code?
Run npx degit formio/ai/plugin/skills/formio-api ~/.claude/skills/formio-api. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the formio-api skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I authenticate with the Form.io REST API?
Most endpoints require a JWT in the x-jwt-token header. Build-time calls use the MCP server's portal-login flow, while runtime calls use the end-user's JWT.
What is the difference between baseUrl and projectUrl?
The baseUrl refers to the platform deployment endpoint, whereas the projectUrl refers to the specific project endpoint.
Can I make direct HTTP requests instead of using MCP tools?
No, you should not work around missing tools by making direct HTTP requests, as this bypasses guardrails and can write to live deployments unreviewed.