Import sessions API

The dashboard's Import / Export screen imports bundles through a durable session: the upload is parsed once, you make decisions on a plan, and the import runs in small batches that can be resumed, retried and rolled back. The same endpoints are available if you're building your own import tooling. For most scripted imports, wp vx-framework config import is simpler.

All endpoints are under https://example.com/wp-json/vx-framework/v1/config-sync and need an administrator's credentials.

The flow

1. Upload the bundle: POST /import-sessions with the file. You get back a session and its first plan.
2. Decide: PATCH /import-sessions/{id}/plan with your choices for each item: create, update an existing object, use an existing object only for references, or skip. Choose which parts of a fieldset to import, and rename clashing field keys.
3. Execute: POST /import-sessions/{id}/execute freezes and re-checks the plan.
4. Advance: call POST /import-sessions/{id}/advance repeatedly. Each call applies a small batch, and repeating a call is safe.
5. Retry failed items with POST /import-sessions/{id}/retry, or roll back with repeated POST /import-sessions/{id}/rollback calls, which undo successful changes in reverse order.

GET /import-sessions lists your sessions, GET /import-sessions/active returns the latest unfinished one, and DELETE /import-sessions/{id} discards an idle session. Draft sessions expire after 24 hours, and finished receipts after 30 days.

Technical details for LLMs

• Plan PATCH body: { expected_revision, changes: [ { source_id, entity_mapping: { action: "create"|"update"|"map_only"|"skip", target_key? }, sections?: ["fields","locations","settings","active"], key_resolutions?: { <key>: { action: "rename", to } }, reference_resolutions?: { "<group>:<key>": "<target_key>" } } ] }. Optimistic: a stale expected_revision is refused.
• Rollback: send the latest expected_rollback_cursor to reject duplicate concurrent requests.
• Storage: {prefix}vxframework_config_import_sessions, {prefix}vxframework_config_import_session_items. TTL filters vxframework/config/import_session_ttl, vxframework/config/import_receipt_ttl; batch sizes vxframework/config/import_batch_size, vxframework/config/import_rollback_batch_size.
• Single-envelope dry-run for one object's Source tab: POST vx-framework/v1/config-sync/bundle/import-plan with { envelope, sections?, key_resolutions? }, re-verified on apply.
• Every session operation is refused under VXFRAMEWORK_CONFIG_LOCKED.