Forms

Forms are the structural primitive Appilot uses to author multi-field workflows. This page is a brief technical slice for integrators. The admin authoring guide is Managing Forms.

Schema

Field	Type	Notes
id	UUID	API-generated.
app_id	int	Mandatory.
domain_id	int | null	Optional per-domain scoping.
semantic_id	string	Unique per app. Lowercase + hyphens.
label	string	Default-locale name.
label_i18n, description_i18n	record<locale, string> | null	Locale overrides.
view_paths	string[]	Ordered. Non-empty.
required_field_ids	string[]	UUIDs of fields in this form.
submit_control_id, entry_control_id	string | null	UUIDs of controls.
visibility_rules	array	DSL: { when: {control, op, value?}, show: [semantic_ids] }.
field_defaults	record<semantic_id, value> | null	'none' | 'lorem' | 'sample_url' | 'sample_email' | { literal: string }.

Controls gain two columns:

• form_id: UUID | null. The form this control belongs to.
• form_order: int | null. Position inside the form's fill order. Both set together or both NULL (DB CHECK).

REST API

All endpoints require a JWT and are org-scoped via requireSameOrg.

List forms

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.appilot.space/domain/forms?app_id=42&resolveFields=true"

resolveFields=true populates each form's fields[] projection (joining controls.form_id).

Get a single form

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.appilot.space/domain/forms/$FORM_ID"

Always returns the form with fields[] resolved.

Create

curl -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  "https://api.appilot.space/domain/forms" \
  -d '{
    "app_id": 42,
    "semantic_id": "online-service-form",
    "label": "Online service form",
    "view_paths": ["app/online-services/form/general", "app/online-services/form/params"],
    "required_field_ids": [],
    "submit_control_id": null,
    "entry_control_id": null
  }'

Update / Delete

PUT /domain/forms/:id and DELETE /domain/forms/:id. Delete returns 409 with dependents when knowledge entries reference the form.

Validation

The backend validator (formsValidator.ts) enforces:

1. view_paths non-empty.
2. submit_control_id / entry_control_id reference controls in the same app.
3. entry_control_id is NOT itself a field of this form.
4. Every required_field_id is a field of this form.
5. visibility_rules.when.control exists in the app; show[] references fields of this form.
6. field_defaults keys are semantic_ids of fields in this form.

Failures return HTTP 400 with a violations: [{ code, message, field }] array.

Agent integration

• The turn loads the app's forms with their fields resolved.
• The model references forms through Narrative Step markers such as [Complete the form]({{form:online-service-form}}).
• Before an action plan reaches the user, the server validates the submitted values, applies visibility rules and defaults, inlines prerequisites, and emits the trusted plan the guided UI runs.

Authors reference forms, controls and tools from knowledge markdown with {{form:semantic_id}}, {{control:semantic_id}} and {{tool:semantic_id}}. The references are indexed when the article is saved, so deleting an entity can name what still points at it.