Update form definition

POST

/wp-json/wp2tutor-forms/form/v1/updateDefinition

curl --request POST \
  --url https://example.com/wp-json/wp2tutor-forms/form/v1/updateDefinition \
  --header 'Content-Type: application/json' \
  --header 'X-WP-Nonce: <X-WP-Nonce>' \
  --data '{ "id": 42, "definition": "{\"name\":\"Form #42\",\"language\":\"ru_RU\",\"clusters\":[]}", "token": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "name": "Form", "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "stencil": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "actionables": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }'

Saves the Tripetto form definition JSON into post_content of a wp2tutor_form CPT post, and optionally name, fingerprint, stencil, and actionables. This is not a runner switch and not a styles write: definition (plus related meta) only. id, definition, and token are required (otherwise WordPress REST rest_missing_callback_param). definition is a JSON string; a failed json_decode returns 400 invalid_json. token is the optimistic lock: PHP compares it with the form snapshot md5 (generate_token). Empty or "0" is 400 empty_token; mismatch is 400 invalid_token. After success PHP recomputes the md5 and returns a new token. name is optional (sanitize_text_field): post title and definition.name. fingerprint, stencil, and actionables are optional SHA-256 (exactly 64 hex); otherwise rest_invalid_param. They are not part of the token md5. Requires edit_post on that post. Cookie + X-WP-Nonce or Application Password.

Authorizations

• cookie
• applicationPassword

Request Body^required

Media typeapplication/json

object

id

required

ID of the wp2tutor_form CPT post. Required. PHP casts to int. Missing post is 404 post_not_found; other post type is 400 invalid_post_type.

integer

definition

required

Tripetto definition as a JSON string. Required. PHP requires a successful json_decode (invalid_json) and writes post_content. Not a JSON object in the REST body: a string.

string

token

required

Current form snapshot md5 (generate_token). Required. Empty or "0" is 400 empty_token. Mismatch with the server snapshot is 400 invalid_token (message includes generated vs expected).

string

name

Form title. Optional, sanitize_text_field. PHP sets post_title and definition.name.

string

fingerprint

SHA-256 definition fingerprint (64 hex). Optional. If sent, Helpers::is_valid_sha_256, otherwise rest_invalid_param. Stored as meta fingerprint; not part of the token md5.

string

stencil

SHA-256 form stencil (64 hex). Optional. Same validation as fingerprint. Meta stencil; not part of the token md5.

string

actionables

SHA-256 runner actionables hash (64 hex). Optional. Same validation. Meta actionables; not part of the token md5.

string

Example

{
  "id": 42,
  "definition": "{\"name\":\"Form #42\",\"language\":\"ru_RU\",\"clusters\":[]}",
  "token": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Form",
  "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "stencil": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "actionables": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Responses

200

Definition saved. Body is the new token (generate_token after write).

Media typeapplication/json

object

token

required

New optimistic-lock token after a successful write. PHP: md5(definition_json + runner + json(styles) + json(l10n) + json(hooks) + json(trackers) + json(shortcode)). The client sends it on the next update*. Not a magic-link secret and not an Application Password.

string

Example

{
  "token": "0f5a3c9e1b7d2468ace0f13579bdf246"
}

400

Invalid_post_type — post is not CPT wp2tutor_form; invalid_id — same check in the id arg; invalid_json — definition is not JSON; empty_token — token is empty or "0"; invalid_token — token does not match the snapshot md5; rest_invalid_param — fingerprint/stencil/actionables are not SHA-256; rest_missing_callback_param — a required field is missing.

Media typeapplication/json

object

code

WP_Error code for this API (invalid_token, empty_token, invalid_json, invalid_runner, invalid_permissions, post_not_found, and so on).

string

message

Human-readable text from PHP (Invalid token: generated "…", expected "…", Token cannot be empty., Invalid JSON., etc.).

string

data

Usually { status: HTTP code } on WP_Error from these controllers.

object

Example^generated

{
  "code": "example",
  "message": "example",
  "data": {}
}

401

Not authenticated. WordPress REST: rest_not_logged_in / rest_forbidden. Use cookie + X-WP-Nonce or Application Password.

Media typeapplication/json

object

code

WP_Error code for this API (invalid_token, empty_token, invalid_json, invalid_runner, invalid_permissions, post_not_found, and so on).

string

message

Human-readable text from PHP (Invalid token: generated "…", expected "…", Token cannot be empty., Invalid JSON., etc.).

string

data

Usually { status: HTTP code } on WP_Error from these controllers.

object

Example^generated

{
  "code": "example",
  "message": "example",
  "data": {}
}

403

Invalid_permissions — no edit_post capability on the form post. WordPress REST: rest_forbidden / rest_cookie_invalid_nonce.

Media typeapplication/json

object

code

WP_Error code for this API (invalid_token, empty_token, invalid_json, invalid_runner, invalid_permissions, post_not_found, and so on).

string

message

Human-readable text from PHP (Invalid token: generated "…", expected "…", Token cannot be empty., Invalid JSON., etc.).

string

data

Usually { status: HTTP code } on WP_Error from these controllers.

object

Example^generated

{
  "code": "example",
  "message": "example",
  "data": {}
}

404

Post_not_found — no post with that id (permission_callback); entity_not_found — FormPost did not find the post in the service.

Media typeapplication/json

object

code

WP_Error code for this API (invalid_token, empty_token, invalid_json, invalid_runner, invalid_permissions, post_not_found, and so on).

string

message

Human-readable text from PHP (Invalid token: generated "…", expected "…", Token cannot be empty., Invalid JSON., etc.).

string

data

Usually { status: HTTP code } on WP_Error from these controllers.

object

Example^generated

{
  "code": "example",
  "message": "example",
  "data": {}
}