form·vee API

Getting started

1. Sign in and open /settings/api-keys.
2. Create a key with only the scopes your client needs.
3. Copy the plaintext key once (fv_<prefix>_<secret>). It is never shown again.
4. Call REST at https://form.vee.kr/api/v1 or connect an MCP client to 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.

Send the key on every request:

Authorization: Bearer fv_<prefix>_<secret>

OpenAPI JSON at /api/v1/openapi.json is the only unauthenticated public machine-readable surface (CORS *). All other /api/v1 and /api/mcp routes require a valid Bearer key.

Scopes

Scopes are granted at key creation time. Missing scope returns 403 forbidden. Response creation is not available over API or MCP; respondents submit through the public form.

• forms:read
• forms:write
• forms:publish
• responses:read
• responses:partial:read
• assets:write
• files:read

• responses:partial:read is required in addition to responses:read to list in-progress partials (REST only).
• assets:write uploads authoring images. files:read downloads respondent uploads.
• MCP never exposes custom script editing or partial response reads.

Errors & rate limits

Authenticated JSON errors use:

{
  "ok": false,
  "error": {
    "code": "conflict",
    "message": "Human-readable summary",
    "details": {}
  }
}

Common codes: unauthorized, forbidden, not_found, invalid, conflict, unprocessable, rate_limited, payload_too_large, unsupported_kind, internal.

Successful authenticated responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-Request-Id. Defaults are 120 requests/minute per key and 600 auth attempts/minute per IP. 429 responses also include Retry-After. Inspect remaining budget with GET /api/v1/usage.

REST quick start

List forms:

curl -sS \
  -H "Authorization: Bearer $FORMVEE_API_KEY" \
  "https://form.vee.kr/api/v1/forms"

Create a classic draft, then publish with the returned revision:

curl -sS -X POST \
  -H "Authorization: Bearer $FORMVEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"classic","title":"NPS survey"}' \
  "https://form.vee.kr/api/v1/forms"

# After editing the draft definition via PATCH, publish:
curl -sS -X POST \
  -H "Authorization: Bearer $FORMVEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedDraftRevision":1}' \
  "https://form.vee.kr/api/v1/forms/<form-id>/publish"

Success bodies are wrapped as { "data": ... } except DELETE (204), CSV streams, file redirects (302), and the raw OpenAPI document.

REST endpoints

Paths below are relative to https://form.vee.kr/api/v1. Required scopes come from the OpenAPI x-scope extension used by the runtime.

Discover workspace capabilities (kinds, render modes, block types, authoring flags) with GET /capabilities before generating definitions.

Optimistic concurrency

• draftRevision guards definition publish/unpublish and definition PATCH.
• settingsSignature (sha256: digest) guards settings PATCH. It does not embed settings JSON or custom scripts.
• On 409 conflict, re-read the form and re-apply the intended change.
• Published form_versions rows are immutable. Republishing creates a new version.

Pagination

List endpoints return { "data": { "items": [...], "nextCursor": "..." | null } }. Pass nextCursor unchanged as cursor for the next page. Limits are capped at 100 (forms/versions default 20, responses default 50).

MCP server

form·vee exposes a stateless Streamable HTTP MCP endpoint at https://form.vee.kr/api/mcp. It uses the same API keys, workspace boundary, scopes, and per-key rate limit as REST. The surface is task-oriented (five tools), not one tool per REST route.

• POST only. Other methods return 405 with Allow: POST after auth.
• No sessions, SSE resume tokens, or top-level JSON-RPC batches.
• Request body limit is 1 MiB.
• Auth profile is static Bearer API keys (no OAuth discovery endpoints).

Client setup

Claude Code:

claude mcp add --transport http formvee https://form.vee.kr/api/mcp \
  --header "Authorization: Bearer fv_xxx_xxx"

Any MCP client that can set a Streamable HTTP URL and Authorization header works. If the client sends Origin, it must exactly match the deployment origin.

Tools

Tools appear in tools/list only when the key holds the required scope.

Typical agent loop:

1. Read formvee://workspace/context for scopes, tools, and capabilities.
2. forms_query search/get to obtain draftRevision and settingsSignature.
3. Mutate with forms_create / forms_update, then forms_publication.
4. Use responses_query for compact lists/reports; request transcript only when needed.

Workspace context resource

URI: formvee://workspace/context

Returns the calling key's scopes, visible tools, evaluated authoring capabilities (kinds, render modes, block types, allowlisted features), and MCP-only constraints. Agents should read this before creating definitions so they avoid disabled features.

Results & privacy

• Tool inputs/outputs use strict schemas (unknown keys rejected).
• Errors prefer structuredContent with { error: { code, message, details? } }.
• responses_query.list is compact only (no classic answer bodies or interview transcripts).
• Interview detail keeps includeTranscript default false.
• Following a classic file downloadUrl still requires files:read on the same key.

Machine-readable contract

Prefer /api/v1/openapi.json for codegen and external API explorers. This HTML page is the human manual for both REST and MCP. The deployment is currently private: v1 path and OpenAPI info.version stay at 1.0.0 while contracts may still change in place.