Getting started
Use REST for scripts and integrations. Use MCP to give an AI client access to the same workspace. Both support classic forms and interviews, subject to your workspace capabilities.
- Open API keys as a workspace owner or admin.
- Create a key with the scopes your integration needs. Copy it when it is shown; the plaintext key is available only once.
- Read
GET /api/v1/capabilities, or the MCP workspace context resource, before authoring a definition.
REST base URL: https://form.vee.kr/api/v1
MCP URL: https://form.vee.kr/api/mcp
Authentication
Workspace API key. Available scopes: forms:read, forms:write, forms:publish, responses:read, responses:partial:read, assets:write, files:read.
Authorization: Bearer fv_<prefix>_<secret>
Send the key on each request. A key belongs to one workspace and acts as its assigned principal. Its creator must remain an active owner or admin, and its principal must remain an active member. Form access rules still apply.
This guide and OpenAPI JSON are public. The OpenAPI document allows cross-origin reads. Other REST endpoints and MCP require a Bearer key; they do not provide general browser CORS access. Keep keys on your server.
Scopes
| Scope | Access |
|---|---|
forms:read | Find forms and read drafts or published versions. |
forms:write | Create, edit, copy, or delete forms. Copying also needs forms:read. |
forms:publish | Publish a draft or stop public access. |
responses:read | Read completed responses, reports, and CSV exports. |
responses:partial:read | Read partial responses through REST, together with responses:read. |
assets:write | Upload images used in form definitions and settings through REST. |
files:read | Download respondent uploads through REST. |
GET /capabilities and GET /usage accept any valid key without requiring a particular scope. A missing scope returns 403. Optional workspace features can impose additional limits.
REST and MCP read responses. Neither creates or submits responses; respondents use the public form.
Errors and limits
REST errors use this envelope. details is present only when the server has additional information, such as validation issues or a conflicting revision.
{
"ok": false,
"error": {
"code": "conflict",
"message": "Draft revision conflict",
"details": {
"currentDraftRevision": 3
}
}
}
| Status | Common code | Next step |
|---|---|---|
| 400 | invalid | Check the JSON, query, or cursor against the schema. |
| 401 | unauthorized | Check the key, expiration, and membership. |
| 403 | forbidden | Check scopes and access to the form. |
| 404 | not_found | Check the resource ID and workspace. |
| 405 | method_not_allowed | Use the endpoint's supported method. |
| 409 | conflict, unsupported_kind | Read the latest state, or use an endpoint for the form's kind. |
| 413 | payload_too_large | Reduce the request size. |
| 422 | unprocessable | Fix the definition, settings, or disabled feature. |
| 429 | rate_limited | Wait for the duration in Retry-After. |
| 503 | service_unavailable | Retry after the advertised delay, when present. |
| 500 | internal | Keep the request ID for troubleshooting. |
Defaults are 120 requests per minute per key and 600 authentication attempts per minute per IP. Responses include X-Request-Id; after authentication and the required scope check succeed, they also include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The reset value is seconds until reset, not a Unix timestamp. GET /usage returns the remaining budget and workspace request counts.
JSON request limits are 1.25 MiB for form creation, 1 MiB for draft replacement, 256 KiB for settings, and 64 KiB for slug or publication changes. MCP accepts up to 1.25 MiB per POST. Image uploads have a separate 5 MiB file limit.
REST quick start
Store your key in FORMVEE_API_KEY. These commands use curl and jq. The example creates a complete classic draft and publishes the revision returned by creation.
BASE_URL="https://form.vee.kr/api/v1"
curl --fail-with-body -sS "$BASE_URL/capabilities" \
-H "Authorization: Bearer $FORMVEE_API_KEY"
FORM=$(curl --fail-with-body -sS "$BASE_URL/forms" \
-H "Authorization: Bearer $FORMVEE_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"kind": "classic",
"title": "Contact us",
"definition": {
"schemaVersion": 1,
"blocks": [{
"id": "blk_useremail1",
"type": "email",
"label": "Your email",
"required": true,
"options": {}
}],
"logic": []
}
}')
FORM_ID=$(printf '%s' "$FORM" | jq -er '.data.id')
REVISION=$(printf '%s' "$FORM" | jq -er '.data.draftRevision')
PUBLISH_BODY=$(printf '{"expectedDraftRevision":%s}' "$REVISION")
curl --fail-with-body -sS "$BASE_URL/forms/$FORM_ID/publish" \
-H "Authorization: Bearer $FORMVEE_API_KEY" \
-H "Content-Type: application/json" \
--data "$PUBLISH_BODY"
Creation requires forms:write; publication requires forms:publish. A successful create returns 201 with { "data": { ...form } }. Publication returns:
{
"data": {
"versionId": "550e8400-e29b-41d4-a716-446655440001",
"version": 1,
"publishedAt": "2026-10-10T12:00:00.000Z"
}
}
Most successful REST responses use { "data": ... }. Deletion returns 204 without a body, CSV exports stream CSV, file downloads redirect with 302, and OpenAPI JSON is unwrapped.
REST endpoints
Paths are relative to https://form.vee.kr/api/v1. Expand an endpoint to see its purpose and required scopes. Full request and response schemas are in OpenAPI JSON.
GET /capabilitiesDiscover API authoring capabilities
Returns the calling key's scopes and the workspace-evaluated form kinds, render modes, block types, and allowlisted authoring features. A valid key is sufficient; each mutation still enforces its own scope and optional capabilities.
Required access: Valid key
GET /usageAPI usage for the calling key's workspace
Any valid key (no specific scope). Returns the key's scopes, the current per-minute rate-limit budget (same values as the X-RateLimit-* response headers), and workspace request counts over the last 24h/7d.
Required access: Valid key
GET /formsList forms
Workspace forms returned as `{ items, nextCursor }`, ordered by updatedAt/id descending. Search matches title or slug; kind and status are optional exact filters.
Required access: forms:read
POST /formsCreate a form
`kind` selects classic (default) or interview; `definition` is validated against the matching schema (FormDefinition for classic, InterviewDefinition for interview). `definition`/`settings` are optional; omitting them starts an empty draft of that kind. A classic definition that uses a feature not enabled for the workspace (file_upload/ranking/matrix) is rejected with 422.
Required access: forms:write
GET /forms/{id}Get a form
Single form with its draft definition and settings. Supports both kinds; `draftDefinition` is a FormDefinition (classic) or InterviewDefinition (interview).
Required access: forms:read
PATCH /forms/{id}Update a form draft
Optimistic concurrency. Classic forms use FormDefinition; interview forms use InterviewDefinition. Returns 409 on revision conflict.
Required access: forms:write
DELETE /forms/{id}Delete a form
Soft delete.
Required access: forms:write
GET /forms/{id}/versionsList published form versions
Bounded immutable publication history returned as `{ items, nextCursor }` and ordered by version descending. Definitions are omitted; fetch a version detail by id to read its snapshot.
Required access: forms:read
GET /forms/{id}/versions/{versionId}Get a published form version
Returns the immutable definition used by responses pinned to this formVersionId.
Required access: forms:read
POST /forms/{id}/duplicateDuplicate a form
Requires both forms:write and forms:read. Creates a draft of the same kind after reapplying the canonical schema, current workspace optional capability gates, settings validation, and image-ownership checks. Legacy readable drafts are canonicalized before the new write.
Required access: forms:write + forms:read
POST /forms/{id}/publishPublish a form
Supports both kinds. Empty forms (classic without input blocks, interview without content) return 422.
Required access: forms:publish
POST /forms/{id}/unpublishUnpublish a form
Unpublish a form
Required access: forms:publish
PATCH /forms/{id}/slugChange the public slug
Changes the public slug after canonical validation.
Required access: forms:write
PATCH /forms/{id}/settingsReplace form settings
Replaces theme, completion, submission, and document settings using optimistic concurrency. Pass the settingsSignature returned by GET /forms/{id} or the preceding successful write.
Required access: forms:write
POST /forms/{id}/assetsUpload an authoring image asset
Uploads one image for this form. The server validates PNG, JPEG, GIF, or WebP by magic bytes and caps the file at 5 MiB. The returned key may be used by image blocks, choice images, logos, and document covers.
Required access: assets:write
GET /forms/{id}/responsesList responses
Kind-aware, filtered keyset page returned as `{ items, nextCursor }`. Compact is the default and never includes interview transcript text; use projection=full for answers/files or transcript. status=partial additionally requires `responses:partial:read` and the partial-submissions feature. Partial responses are a live mutable view, so cursor traversal is best-effort rather than snapshot-isolated.
Required access: responses:read
GET /forms/{id}/reportsGet a kind-aware response report
Classic forms return per-question and score summaries plus core analytics aggregates. Interview forms return the current V2 funnel, analysis coverage, and qualitative-code aggregates. Classic text summaries can contain recent answer samples for responses:read clients; interview reports never contain transcript text. The q filter applies to classic question summaries, while analytics remains the selected date cohort.
Required access: responses:read
GET /forms/{id}/responses/summaryResponse summary
Per-question aggregates plus numeric score summaries. Classic forms only; interview forms return 409 (use GET /forms/{id}/reports or /forms/{id}/interview-analytics for Interview V2).
Required access: responses:read
GET /forms/{id}/responses/{responseId}Get a response
Classic forms return a Response; interview forms return an InterviewResponse.
Required access: responses:read
GET /forms/{id}/responses.csvExport responses as CSV
Exports completed responses. Classic forms export stable block-id variables and support label/code values, defined scores add stable numeric score_<id> variables, wide/long layout, and a conservative deidentified projection. File link columns point to the API file download route; following those links requires `files:read`. Interview forms export conversation summary, extracted fields, qualitative themes, and transcript.
Required access: responses:read
GET /forms/{id}/insightsClassic response insight candidates
Aggregates AI-extracted insights from completed classic responses into field-promotion candidates (frequency × confidence). `auto` candidates have crossed the auto-promotion threshold. Classic forms only; interview forms return 409.
Required access: responses:read
GET /forms/{id}/interview-analyticsGet the live Interview V2 response report
Breaking v1 contract: computes the current Interview V2 funnel, analysis coverage, and qualitative-code aggregates from authoritative tables. It does not read the retired legacy aggregate projection, trigger analysis jobs, or return transcripts. Classic forms return 409.
Required access: responses:read
GET /forms/{id}/files/{fileId}Download an uploaded file
Redirects (302) to a short-lived presigned URL.
Required access: files:read
Edit and publish
Read GET /forms/{id} before changing a form. The result includes kind, draftDefinition, draftRevision, settings, settingsSignature, and currentVersionId.
| Request | JSON body | Result inside data |
|---|---|---|
PATCH /forms/{id} | definition, baseRevision, optional title | { draftRevision } |
PATCH /forms/{id}/settings | settings, expectedSettingsSignature | { settings, settingsSignature } |
PATCH /forms/{id}/slug | slug | { slug } |
POST /forms/{id}/publish | expectedDraftRevision | { versionId, version, publishedAt } |
POST /forms/{id}/unpublish | expectedDraftRevision | { status: "draft" } |
Definition and settings writes replace the supplied document. Preserve fields you intend to keep. Pass the latest draftRevision as baseRevision for a draft edit or as expectedDraftRevision for publication changes. Pass the latest settings digest as expectedSettingsSignature.
On 409, read the form again and reconcile your change. A draft edit conflict also returns X-Draft-Revision. Publication conflicts report error.details.currentDraftRevision; settings conflicts report error.details.settingsSignature.
Classic definitions use schemaVersion: 1. Interview definitions use the current V2 schema. Read the capability response and the corresponding OpenAPI definition before generating content. Empty or unrunnable forms cannot be published.
Pagination
{
"data": {
"items": [],
"nextCursor": null
}
}
When nextCursor is a string, pass it unchanged as cursor on the next request. Keep the same filters. Stop when it is null. A cursor is opaque; do not decode it or reuse it for a different query.
REST defaults to 20 forms or versions and 50 responses per page, with a maximum of 100. Form search accepts q, kind, and status. Forms are ordered by update time and ID, newest first; versions are ordered by descending version number.
Responses and reports
GET /forms/{id}/responses defaults to completed responses with projection=compact. Classic compact items include an answer count; interview compact items include summary and analysis metadata without transcript text. Use projection=full for answer bodies and files or interview transcripts, or request one completed response by ID.
REST response payloads expose classic answers and files, or interview, directly on each item. Read its formVersionId and fetch that immutable version when interpreting stored block and option IDs.
fromandtoare inclusive dates inYYYY-MM-DDformat.tzis the UTC offset in minutes, east positive, such as540for Korea. It is clamped to-840through840.qsearches classic answers or interview summaries and extracted fields. It does not search transcripts.status=partialrequires both response scopes and the partial-submissions feature. Partial records change while respondents work, so pagination is a best-effort live view.
GET /forms/{id}/reports returns classic question and score summaries with analytics, or Interview V2 funnel, analysis coverage, and qualitative-code aggregates. Classic reports use date filters; interview reports use days=1|7|30|90, defaulting to 30, and ignore from, to, tz, and q.
Classic segments use segmentBlock and repeated segmentValue parameters with stable stored codes. Reports accept row and banner together for crosstabs. These features require the workspace crosstab capability; REST ignores them when it is disabled. Search filters affect classic summaries while analytics keeps the selected date cohort.
GET /forms/{id}/responses.csv exports completed responses. Classic exports accept values=labels|codes, layout=wide|long, and privacy=full|deidentified. Interview exports include transcripts. File links in CSV still require files:read.
Images and files
Upload authoring images as multipart form data using a file field. PNG, JPEG, GIF, and WebP are accepted after content validation, up to 5 MiB. The returned data.key belongs to that form and can be used in image blocks, choice images, logos, and covers. The response can also include imageWidth and imageHeight.
curl --fail-with-body -sS "$BASE_URL/forms/$FORM_ID/assets" \
-H "Authorization: Bearer $FORMVEE_API_KEY" \
-F "file=@cover.png"
Respondent uploads are separate. Response details expose file metadata and a downloadUrl pointing to /api/v1/forms/{id}/files/{fileId}. Request that URL with a key holding files:read, then follow its 302 redirect to a short-lived signed storage URL. Do not forward the API key to the storage host.
MCP transport
Connect a Streamable HTTP client to https://form.vee.kr/api/mcp with the same Bearer key used for REST. The endpoint is stateless and returns JSON. It has no session ID, resumable event stream, or OAuth discovery flow.
- Send one JSON-RPC message per
POST. Top-level batch arrays return400. - Use
Content-Type: application/jsonandAccept: application/json, text/event-stream. Let your MCP client negotiate the protocol version. - After authentication, methods other than
POSTreturn405withAllow: POST. - If a client sends
Origin, it must match the configured deployment origin exactly. A missing Origin is accepted for command-line and server clients.
Client setup
Configure a remote HTTP server in your MCP client:
{
"url": "https://form.vee.kr/api/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
For Claude Code, register the endpoint with:
claude mcp add --transport http formvee "https://form.vee.kr/api/mcp" \
--header "Authorization: Bearer $FORMVEE_API_KEY"
The client may store the header in its local configuration. Keep that configuration private. Client configuration formats vary; the URL and Authorization header are the required connection values.
Workspace context
Read formvee://workspace/context through resources/read before authoring. Its JSON contains the key's scopes, visible tools, evaluated capabilities, and MCP constraints. Any valid key can read this resource.
Tools
tools/list returns the tools available to your key, including their input and output schemas. Tool arguments use the shapes below; they are not REST request bodies.
| Tool | Scope | Purpose |
|---|---|---|
forms_query | forms:read | Search forms, fetch one draft (with concurrency tokens), or read published version history/snapshots. |
forms_create | forms:write (+ forms:read for copy) | Create a blank classic/interview draft, or copy an existing readable form through the same create gates. |
forms_update | forms:write | Replace a draft definition or settings with a concurrency token, or change the public slug. |
forms_publication | forms:publish | Publish an observed draft or stop public access. Repeating publication of an unchanged draft reuses its version. |
responses_query | responses:read | List completed responses (compact), fetch detail, or load a kind-aware aggregate report. |
Find a form
forms_query accepts request.view of search, get, versions, or version. Search uses query, optional kind and status, and cursor pagination. Lists default to 20 items, up to 100.
{
"request": {
"view": "search",
"query": "Contact",
"kind": "classic",
"limit": 20
}
}
Use { "request": { "view": "get", "formId": "<form-id>" } } to read the draft and concurrency tokens. Version views require formId; a single version also requires versionId.
Create or copy a form
forms_create accepts request.mode: "blank" with optional kind, title, definition, and settings. Kind defaults to classic. Copy mode requires sourceFormId and optionally a title; it also requires forms:read. Both modes apply current workspace capabilities.
{
"request": {
"mode": "blank",
"kind": "classic",
"title": "Contact us"
}
}
The result contains form with its ID and concurrency tokens, plus nextAction. A blank draft needs content before publication.
Update a draft
forms_update requires formId and one operation. Use replace_definition with definition, baseRevision, and an optional title; replace_settings with settings and settingsSignature; or set_slug with slug.
{
"formId": "550e8400-e29b-41d4-a716-446655440000",
"operation": {
"type": "replace_definition",
"baseRevision": 0,
"definition": {
"schemaVersion": 1,
"blocks": [
{
"id": "blk_useremail1",
"type": "email",
"label": "Your email",
"required": true,
"options": {}
}
],
"logic": []
}
}
}
The result identifies the operation and returns its new draftRevision, settingsSignature, or slug. Reuse those values for the next write.
customScript from settings and computes its settings token over that filtered view. Keep REST and MCP settings tokens within the interface that issued them. MCP settings updates preserve an existing custom script.Publish
forms_publication requires the observed draft revision and a desiredState of published or draft. The example revision must be replaced with the value returned by your preceding read or edit.
{
"formId": "550e8400-e29b-41d4-a716-446655440000",
"expectedDraftRevision": 1,
"desiredState": "published"
}
The result contains status, versionId, version, and publishedAt. Version fields are null when the desired state is draft.
Read responses
responses_query requires formId and a request with one of these views:
list: compact completed responses with optionalquery,days,limit, andcursor. The default page has 30 items, with a maximum of 100.detail: one completedresponseId. For interviews, setincludeTranscript: trueonly when needed; it defaults to false.report: a kind-aware aggregate with optionaldays, classicsegment: { blockId, values }, andcrosstab: { rowBlockId, bannerBlockId }. For classic forms, segment and crosstab requests fail when the workspace capability is disabled. Interview reports ignore these options.
{
"formId": "550e8400-e29b-41d4-a716-446655440000",
"request": {
"view": "list",
"days": 30,
"limit": 30
}
}
MCP days accepts 7, 30, or 90. Each response item has kind and a nested data payload, unlike REST response items. Classic reports omit free-text answer samples; interview reports omit transcripts.
Results and limits
Successful tool results return a typed structuredContent object and the same JSON in a text content block. Forms queries, updates, and response queries wrap their result in result; creation returns form and nextAction; publication returns its state directly.
Tool failures set isError: true and include { "error": { "code", "message", "details"? } } in structured content. Authentication failures use the REST error envelope, while transport failures use JSON-RPC errors. Inspect both the HTTP response and the tool result.
Tool command objects reject unknown keys. MCP exposes no deletion, asset upload, CSV export, partial response read, or custom script editing tool. Use REST for supported operations in that list. Neither interface supports response creation. Following a response file link still requires files:read.
Schemas
Use OpenAPI JSON for REST schemas and client generation. FormDefinition, InterviewDefinition, and FormSettings describe authoring documents. Use MCP tools/list for tool input and output schemas; OpenAPI does not describe MCP arguments.
Read workspace capabilities as well as schemas. A valid definition can still require a feature that your workspace has not enabled. Integrations should re-read the contract when upgrading; the current API retains its v1 path and 1.0.0 document version while contracts can change.