Forms AI

Forms AI backs the “create a form with AI” popup in the coach web app. A coach sends a link, files or pasted text. The API answers at once with a job id, runs the analysis in the background and creates a draft FormTemplate at the end. The client polls the job for progress. Source: backend/apps/core-api/src/modules/forms-ai.

Mount	Middleware
`/v1/web/forms-ai`	`serviceAuth`, `webUserContext(ctx.prisma)`, `webLimiter`

Auth

Web lane. req.auth must carry studioId and userId, otherwise the controller throws UNAUTHORIZED (401). The controller’s callerOf also refuses the TRAINEE role with FORBIDDEN (403, coaches only). OWNER, HEAD_COACH and SUB_COACH are allowed.

How a job runs

analyze() writes the initial state to Redis and schedules runJob with setImmediate. There is no BullMQ queue. The job runs inside the API process that received the request, so a process restart loses a running job and the client only sees the state stop changing until the key expires. State lives in one Redis key, perform:forms-ai:<jobId>, with a 3600 second expiry that is refreshed on every progress write. The stored state includes the owner’s studioId and userId.

Source priority

Link. The first http(s) URL found in text wins, and files are ignored. The page is fetched through ai/safe-fetch.ts with the user agent PerformFormsBot/1.0.
- A page that contains FB_PUBLIC_LOAD_DATA_ is a Google Form. parseGoogleFormHtml reads the embedded data deterministically with no model call.
- Any other page is stripped to text (maximum 20,000 characters) and structured by the model. If the model is unavailable or returns nothing, the deterministic line parser parseFormText is the last resort.
Files. With no URL and at least one file, each file is transcribed by the plan-import OCR (plan-import/ocr.ts). Transcripts are appended to any pasted text.
Text. Otherwise the pasted text is parsed by parseFormText.

For files and text, when the deterministic parse finds fewer than two fields and a structurer is configured, the model re-reads the raw text into the same ParsedForm shape.

Model configuration

The OCR and the structurer are built from ANTHROPIC_API_KEY, AGENT_MODEL and the optional ANTHROPIC_WORKSPACE_ID. According to the wiring in forms-ai.routes.ts, both are null when no key is set. In that case pasted text and Google Forms links still work, file uploads fail with a Hebrew error, and other links fall back to the line parser. The structurer prompt (llm-structurer.ts) tells the model to extract only what is written in the source and never invent fields, options or help text. Any model failure returns null and the caller picks the fallback.

Classification

classifyParsedForm (classifier.ts) maps each parsed field to a production field type with keyword rules and assigns a confidence:

Tier	Value	Meaning
`CONFIDENCE_KEYWORD`	0.95	Exact keyword, or the structured source named the type
`CONFIDENCE_DERIVED`	0.85	Derived, for example options become a dropdown, a scale becomes a rating
`CONFIDENCE_FALLBACK`	0.5	Fallback free text, grid rows, duplicated system fields

Only fields below LOW_CONFIDENCE_THRESHOLD (0.75) are stored, keyed by field id, in logic.aiImport.fieldConfidence. The builder uses them to mark fields the coach should review. Generated fields get ids and keys ai_1, ai_2 and so on. Pages get ids p1, p2. The schema is created with settings.rtl: true.

Template creation

The job calls createTemplate on a forms service built with the repository only. No submit hooks, notifier or summarizer are wired, because the job never submits or sends anything. The template is created with:

type: the requested formType
cadence: "WEEKLY" when the type is CHECK_IN
name: the title found in the source, or the Hebrew type label followed by חדש when there was none
status: "DRAFT" and active: false, which keeps it out of send pickers until the coach publishes it
logic.aiImport: source (link:<host>, files or text), fieldConfidence and createdAt

Stages

Stage	Reported `pct`
`fetch`	3 at creation, 10 when a link fetch starts, 5 to 35 while files are transcribed
`parse`	40 after a link is fetched, 45 for files and text, 60 after a model structuring pass
`classify`	75
`create`	90, then 100 with `done: true`

Endpoints

`POST /v1/web/forms-ai/analyze`

Starts an analysis job. Responds with 202. Auth: web lane, any role except TRAINEE. This route has its own 48mb JSON body limit in app.ts, because it can carry up to 10 base64 files.

string

required

INTAKE, CHECK_IN or ONE_TIME. PDF_SIGNATURE is not accepted.

string

Pasted form content or a message containing a link. Maximum 20,000 characters.

object[]

Maximum 10 files.

Show file fields

string

required

1 to 300 characters.

string

required

image/jpeg, image/png, image/webp or application/pdf.

string

required

Base64 content. The decoded size, estimated as 75 percent of the string length, must be at most 8 MB.

At least one of text (non blank after trimming) or files (non empty) is required. Response:

{
  "ok": true,
  "data": { "jobId": "3f1c9a0e-7b52-4c1d-9a44-2f6e8d0b5a17" },
  "requestId": "req_10"
}

Errors:

Code	Status	When
`UNAUTHORIZED`	401	No `studioId` or `userId` on the request
`FORBIDDEN`	403	Caller role is `TRAINEE`
`VALIDATION`	422	Body failed the Zod schema, including `file exceeds 8MB` and `text or at least one file is required`
`BAD_REQUEST`	413	Body larger than 48mb (`payload too large`)

Failures inside the job are not HTTP errors. They surface in the job’s error field.

`GET /v1/web/forms-ai/analyze/:jobId`

Returns the current state of a job. Auth: web lane, any role except TRAINEE. The caller must be the same studioId and userId that started the job.

string

required

The id returned by the analyze call.

Response: the stored state without its owner fields.

string

The job id.

string

fetch, parse, classify or create.

number

Progress from 3 to 100.

boolean

true when the job finished, with either result or error.

string

Present only on failure. A Hebrew message meant to be shown to the coach.

object

Present only on success: formId, name, fieldCount, pageCount.

While running:

{
  "ok": true,
  "data": { "jobId": "3f1c9a0e-7b52-4c1d-9a44-2f6e8d0b5a17", "stage": "classify", "pct": 75, "done": false },
  "requestId": "req_11"
}

Finished:

{
  "ok": true,
  "data": {
    "jobId": "3f1c9a0e-7b52-4c1d-9a44-2f6e8d0b5a17",
    "stage": "create",
    "pct": 100,
    "done": true,
    "result": { "formId": "cmf1x2abc0001xyz", "name": "Onboarding questionnaire", "fieldCount": 14, "pageCount": 2 }
  },
  "requestId": "req_12"
}

result.formId is the new FormTemplate.id. Open it with the template endpoints on the Forms page. fieldCount comes from the forms service and excludes display-only fields. Job failure messages (ERRORS in forms-ai.service.ts):

Key	Shown when
`linkFailed`	The link could not be fetched
`nothingFound`	No fields were found in the source
`filesUnavailable`	Files were sent but no OCR is configured
`generic`	Any other failure, including a failed template creation

Errors:

Code	Status	When
`UNAUTHORIZED`	401	No `studioId` or `userId` on the request
`FORBIDDEN`	403	Caller role is `TRAINEE`
`NOT_FOUND`	404	`analyze job not found`. The key expired, never existed, or belongs to another studio or user
`VALIDATION`	422	Empty `jobId`

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Auth

How a job runs

Source priority

Model configuration

Classification

Template creation

Stages

Endpoints

`POST /v1/web/forms-ai/analyze`

`GET /v1/web/forms-ai/analyze/:jobId`

​Auth

​How a job runs

​Source priority

​Model configuration

​Classification

​Template creation

​Stages

​Endpoints

​POST /v1/web/forms-ai/analyze

​GET /v1/web/forms-ai/analyze/:jobId

Auth

How a job runs

Source priority

Model configuration

Classification

Template creation

Stages

Endpoints

`POST /v1/web/forms-ai/analyze`

`GET /v1/web/forms-ai/analyze/:jobId`