BetaThe command API is in beta: command names, parameters and results may still change between editor releases. Pin an editor release with the
versionoption ofinitFPEditorif you depend on it.
The embedded editor's API object can change the plan from your own code: draw rooms, put in doors and windows, place, move and delete furniture, and read what is there. Every change goes through the same rules as when a person makes it in the editor, is drawn straight away, and is one step on the editor's undo stack.
All commands are listed, with their parameters, in the Editor command reference.
Methods
| Method | Description |
|---|---|
api.command(name, payload, options) | Runs one command. Returns its result straight away (it is not a Promise). |
api.transaction(steps, options) | Runs several commands as one change: steps is [{name, payload}, …], at most 100. All or nothing: when one step is refused, nothing changes. One undo step for the whole transaction. |
api.commands(names) | The commands as {name, description, inputSchema, annotations}, where inputSchema is JSON Schema. Without names it returns every command; with a list of names, those in that order. This is the same format MCP and WebMCP tools use. |
options is optional and may contain:
dry_run: true: answers what the command would do, with the samefactsor the same refusal, and changes nothing.expected_rev: therevof an earlier answer. If the plan has changed since then (the user edited it, say), the call is refused withstale: trueand nothing is changed, so you never edit a plan you have not read.agent: {name, version}: names your integration on the undo steps it makes.
Results
A command never throws for a bad name, a bad payload or something it cannot do. It returns:
// accepted
{ok: true, facts: {...}, summary: 'Drew an unnamed room (befde8f8b015) (12 m²).', rev: 7}
// refused: nothing was changed
{ok: false, error: 'no wall with guid nope in this design', rev: 7}factsis what the command did or found, such as the GUIDs it created or the rooms it listed. Each command's facts are its own.summaryis one sentence describing the change, for a log or a chat reply.warnings, when present, lists things the change made true that the user should hear about.erroris a readable sentence saying why the command was refused.revis the plan's revision number. Pass it back asexpected_rev.- When the user has locked part of the plan in the editor's top bar, a write that touches it is refused with
code: 'locked'and alockslist.
GUIDs
Commands refer to walls, rooms, doors, windows and items by their GUID, a short string such as '80c1ed4dc69a'. You get GUIDs from:
- the read-only
list_*commands, such aslist_rooms,list_wallsandlist_items; - the
factsof the command that created something:facts.guids.mintedlists every new GUID by type.
Some edits replace objects. Splitting a wall gives two new walls, and merging two rooms gives one. The old GUIDs are then listed in facts.guids.retired. A GUID you kept from before is refused with an error, so read the plan again with a list_* command.
Coordinates and units
Lengths and coordinates are in centimetres, in plan coordinates: x grows to the east (right) and y to the south (down). Floor areas in facts are in square metres.
Examples
Draw a room of 4 by 3 metres (inside measurements), with its top-left corner at the origin:
const r = api.command('draw_room', {at: {x: 0, y: 0}, width: 400, depth: 300});
// r.facts.room is the new room's GUID; r.facts.guids.minted.walls are its four wallsDraw a room, put a door in its first wall and name it, as one undo step. A string "$N.path" in a payload is the value at path in the facts of step N (counting from 0):
api.transaction([
{name: 'draw_room', payload: {at: {x: 0, y: 0}, width: 400, depth: 300}},
{name: 'add_opening', payload: {wall: '$0.guids.minted.walls.0', kind: 'door', t: 0.5}},
{name: 'update_area', payload: {area: '$0.room', customName: 'Office'}},
]);Check first, then change:
const check = api.command('move_wall', {wall: guid, delta: {x: 50, y: 0}}, {dry_run: true});
if (check.ok) api.command('move_wall', {wall: guid, delta: {x: 50, y: 0}}, {expected_rev: check.rev});Products and materials
A command never loads anything over the network, so a product or material has to be in the editor before a command can use its id. Three functions on the API object load them. They return Promises:
| Method | Description |
|---|---|
api.loadAssets(refids) | Loads products and materials by id. Resolves {ok: true, loaded, notFound}. Call it before add_item, replace_item or a command that sets a material, with ids you already know. |
api.searchProducts(text, {limit, category}) | Searches the furniture catalogue the user sees in the editor's sidebar. Resolves {ok: true, facts: {results: [{refid, name, …}]}}, 5 results by default and 20 at most. Every result is loaded, so its refid can be used straight away. |
api.searchMaterials(text, {limit}) | The same for floor and wall materials. |
Where a parameter's description in the reference says "from search_products" or "from search_materials", use api.searchProducts or api.searchMaterials.
const found = await api.searchProducts('sofa');
const sofa = found.facts.results[0];
api.command('add_item', {refid: sofa.refid, at: {x: 200, y: 150}, rotation: 0});