Create a static build

POST

/wp-json/wp2lms/static-builder/v1/builds

const url = 'https://example.com/wp-json/wp2lms/static-builder/v1/builds?blog_id=1';
const options = {
  method: 'POST',
  headers: {'X-WP-Nonce': '<X-WP-Nonce>', 'Content-Type': 'application/json'},
  body: '{"page_ids":[42,57],"course_name":"Information Security Basics","api_type":"scorm","course_id":"course-infosec-101","version":1,"course_comment":"Package for the LMS","export_mode":"package"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://example.com/wp-json/wp2lms/static-builder/v1/builds?blog_id=1' \
  --header 'Content-Type: application/json' \
  --header 'X-WP-Nonce: <X-WP-Nonce>' \
  --data '{ "page_ids": [ 42, 57 ], "course_name": "Information Security Basics", "api_type": "scorm", "course_id": "course-infosec-101", "version": 1, "course_comment": "Package for the LMS", "export_mode": "package" }'

Creates a draft CPT wp2lms_static_build, writes ACF/flags and pages, publishes the post, and returns full serialize. Package generation does not start: this is not POST …/run. Requires non-empty page_ids or a valid build_course_id (wp2lms_courses CPT). Without either — 400 pages_required. With build_course_id and no page_ids, pages come from course structure; empty course — 400 empty_course. Missing/non-course — 404 course_not_found. When both are sent — link via build_course_id, pages from explicit page_ids. Each page_ids entry must be an existing post_type=page; else 400 invalid_page_ids / page_not_found. First item is the main page. api_type may be omitted — response uses ACF apiType or local. Omitted version → 1. Omitted export_mode → package. Requires manage_network or edit_pages. Cookie + X-WP-Nonce or Application Password.

Authorizations

cookie
applicationPassword

Parameters

Query Parameters

blog_id

integer

>= 1

Multisite site ID to read/write builds on. Optional: PHP uses get_current_blog_id(). ≤ 0 — 400 invalid_blog. Missing or foreign-network site — 404 blog_not_found. Usually omitted on a single site.

Example

Request Body^required

application/json

Requires non-empty page_ids or a valid build_course_id (or both).

object

page_ids

Course page IDs in package order. Optional when build_course_id is set. Non-empty array of positive IDs of existing post_type=page; else 400 invalid_page_ids / page_not_found. First item is the main page. PHP de-duplicates with array_unique.

Array<integer>

build_course_id

WP2LMS course CPT ID. Writes meta ssb_course_id (config.build_course_id). Without page_ids, pages come from course structure. Missing id — 404 course_not_found; empty course — 400 empty_course.

integer

>= 1

course_name

Display course name (ACF courseName). Optional; with build_course_id and no name, course post title is used.

string

api_type

Package type (ACF apiType). Optional. Other values — 400 invalid_api_type. If omitted — response uses apiType or local.

string

Allowed values: local scorm xapi

course_id

LMS/xAPI course id string (ACF), not WP post ID. ACF field key depends on api_type.

string

version

Package version (ACF version), float ≥ 1. Below 1 — 400 invalid_version. If omitted — get_version_number returns 1.

number

>= 1

course_comment

Internal comment (ACF courseComment). Optional.

string

export_mode

Package — ZIP/SCORM package; live — live view. Other — 400 invalid_export_mode. If omitted — get_export_mode returns package.

string

Allowed values: package live

is_primary

Favourite build for the course (meta ssb_is_primary). At most one per build_course_id / ssb_course_id: true clears siblings. Without a course link — 400 primary_requires_course. Same star in the course «Builds» metabox.

boolean

Example

{
  "page_ids": [
    42,
    57
  ],
  "course_name": "Information Security Basics",
  "api_type": "scorm",
  "course_id": "course-infosec-101",
  "version": 1,
  "course_comment": "Package for the LMS",
  "export_mode": "package"
}

Responses

201

Build created and published. Body is full BuildService::serialize (config, pages, status, URLs).

application/json

object

CPT wp2lms_static_build post ID.

integer

status

BuildStatus->value: new, pending, building, completed, error, stopped, rebuild, build, stopping. After create typically new; after async run — pending.

string

terminal

True for completed, error, stopped.

boolean

config

object

course_name

ACF courseName on the saved build.

string

api_type

ACF apiType; empty values become local.

string

course_id

ACF courseID (get_course_id); may be an empty string.

string

build_course_id

Linked wp2lms_courses CPT ID (meta ssb_course_id). 0 if unlinked.

integer

version

Version number from ACF (get_version_number), default 1.

number

course_comment

ACF courseComment.

string

export_mode

Package or live (get_export_mode; other/empty → package).

string

page_ids

Page IDs in package order; first item is the main page.

Array<integer>

main_page_id

Main page ID (get_main_page), usually page_ids[0].

integer

is_primary

Favourite build for the course (meta ssb_is_primary). At most one per linked course; star in the course Builds metabox.

boolean

use_sections_in_menu

True when at least one selected page has a sections-taxonomy term. The site option cannot be set via this REST body.

boolean

disable_auto_addition_data

Site-wide Static Builder setting disableAutoAdditionData (not a REST body field).

boolean

not_include_media_files_build

For package — site setting notIncludeMediaFilesBuild; for live PHP always returns false.

boolean

save_external_files

For package — saveExternalFiles (null → true); for live always false (off-site files are not downloaded).

boolean

revision

Build revision number from meta (get_revision_number).

integer

logs

Step log (get_logs(true) — newest first). Usually [] right after create.

Array<object>

object

time

Unix timestamp of the build-step log (0 if meta has no time).

integer

level

Build log level (info if meta has no level).

string

message

Package generation step text.

string

view_url

View URL (index.html / live). Non-null only when status=completed and a view file exists; otherwise null (including after create).

string

nullable

zip_url

ZIP URL. Non-null only when completed and the archive exists (typically package/scorm/xapi). For live often null.

string

nullable

files_url

Directory URL {uploads}/wp2lms-static/{id}/. Always a string, even if files are not there yet.

string

edit_url

Raw wp-admin link to the build card (get_edit_post_link(..., 'raw')).

string

nullable

blog_id

Site ID that owns the build (get_current_blog_id after switch_to_blog).

integer

Example

{
  "id": 128,
  "status": "new",
  "terminal": false,
  "config": {
    "course_name": "Information Security Basics",
    "api_type": "scorm",
    "course_id": "course-infosec-101",
    "version": 1,
    "course_comment": "Package for the LMS",
    "export_mode": "package"
  },
  "page_ids": [
    42,
    57
  ],
  "main_page_id": 42,
  "use_sections_in_menu": false,
  "disable_auto_addition_data": false,
  "not_include_media_files_build": false,
  "save_external_files": true,
  "revision": 0,
  "logs": [],
  "view_url": null,
  "zip_url": null,
  "files_url": "https://pulse.example.com/wp-content/uploads/wp2lms-static/128/",
  "edit_url": "https://pulse.example.com/wp-admin/post.php?post=128&action=edit",
  "blog_id": 1
}

400

Wp2lms_static_builder_pages_required — missing page_ids; invalid_page_ids — not an array of positive ints; page_not_found — no post_type=page (HTTP 400, not 404); invalid_api_type / invalid_version / invalid_export_mode; invalid_blog.

application/json

object

code

Machine-readable WP_Error code (for example wp2lms_static_builder_busy, rest_forbidden, invalid_nonce).

string

message

Human-readable error message from PHP / WordPress REST.

string

data

Usually { status: <HTTP code> }. If status is missing, core REST often returns 500.

object

key

additional properties

any

Example

{
  "code": "wp2lms_static_builder_busy",
  "message": "Build is currently building and cannot be updated.",
  "data": {
    "status": 409
  }
}

401

Not authenticated. DualRest: rest_forbidden (status 401) when there is no cookie session. Cookie + X-WP-Nonce or Application Password.

application/json

object

code

Machine-readable WP_Error code (for example wp2lms_static_builder_busy, rest_forbidden, invalid_nonce).

string

message

Human-readable error message from PHP / WordPress REST.

string

data

Usually { status: <HTTP code> }. If status is missing, core REST often returns 500.

object

key

additional properties

any

Example

{
  "code": "wp2lms_static_builder_busy",
  "message": "Build is currently building and cannot be updated.",
  "data": {
    "status": 409
  }
}

403

Missing manage_network (multisite) or edit_pages (single site); invalid REST nonce rest_cookie_invalid_nonce.

application/json

object

code

Machine-readable WP_Error code (for example wp2lms_static_builder_busy, rest_forbidden, invalid_nonce).

string

message

Human-readable error message from PHP / WordPress REST.

string

data

Usually { status: <HTTP code> }. If status is missing, core REST often returns 500.

object

key

additional properties

any

Example

{
  "code": "wp2lms_static_builder_busy",
  "message": "Build is currently building and cannot be updated.",
  "data": {
    "status": 409
  }
}

404

Wp2lms_static_builder_blog_not_found — site does not exist or belongs to another network.

application/json

object

code

Machine-readable WP_Error code (for example wp2lms_static_builder_busy, rest_forbidden, invalid_nonce).

string

message

Human-readable error message from PHP / WordPress REST.

string

data

Usually { status: <HTTP code> }. If status is missing, core REST often returns 500.

object

key

additional properties

any

Example

{
  "code": "wp2lms_static_builder_busy",
  "message": "Build is currently building and cannot be updated.",
  "data": {
    "status": 409
  }
}

500

Wp2lms_static_builder_create_failed — wp_insert_post returned WP_Error; configure_failed — exception while writing ACF/pages (the draft is then deleted).

application/json

object

code

Machine-readable WP_Error code (for example wp2lms_static_builder_busy, rest_forbidden, invalid_nonce).

string

message

Human-readable error message from PHP / WordPress REST.

string

data

Usually { status: <HTTP code> }. If status is missing, core REST often returns 500.

object

key

additional properties

any

Example

{
  "code": "wp2lms_static_builder_busy",
  "message": "Build is currently building and cannot be updated.",
  "data": {
    "status": 409
  }
}

Create a static build

Authorizations

Parameters

Query Parameters

Example

Request Bodyrequired

Example

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

500

Example

Request Body^required