Forms

Suggest conditions for a form's fields

POST/forms/{id}/actions/suggest-conditions
forms:writesuggest_conditions_form

Starts a job that asks the AI service which fields should show only on a given answer. Nothing is saved, so nothing needs undoing: result has form_id and, on success, proposals; apply them through field conditions. Draft or published. Fails not_found, upstream_error or upstream_unavailable (120 second call, not retried). Needs perm_can_manage_form_builder (403); an unusable token user is 403 forbidden. 409 invalid_state while a job for the form is queued or running. dry_run: 202, no job.

Path parameters

  • idstring (uuid)Required#

    The form's id, a uuid. An unknown id, or a hidden form, returns 404.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

  • Idempotency-Keystring#

    Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Responses

202

The job that asks the AI service for condition proposals was started. Its result carries the form id and, once it has succeeded, the proposals.

FormSuggestConditionsJobEnvelope
{
  "data": {
    "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "type": "string",
    "status": "queued",
    "progress": {
      "done": 1,
      "total": 1
    },
    "result": {
      "form_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "proposals": []
    },
    "error": {},
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10:00:00+00:00",
    "completed_at": "2026-06-12T10:00:00+00:00"
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
409

The request conflicts with existing state (error.code = conflict), e.g. a compliance flow with the requested name already exists.

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/forms/{id}/actions/suggest-conditions\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"