> ## Documentation Index
> Fetch the complete documentation index at: https://armorsmith-designer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference — Coming soon

> Preview the experimental Armorsmith API 0.3 boundary for avatars, tools, host integrations, and Python dialogs.

**Coming soon.** This reference describes experimental API 0.3. The scripting menu is enabled in test builds, including `Release_Test_Build`, and hidden in normal release builds. Native avatar deformation, tool interaction, and workspace mesh behavior still need application smoke tests before release. Types, limits, and behavior may change.

The public API gives you copied document data, opaque handles, validated commands, and application-owned dialogs. It keeps ForgeCore objects, C++ pointers, scene registries, and undo internals inside Armorsmith.

## Choose your integration surface

| Surface | Current development contract |
| - | - |
| C++ host integration | `Armorsmith::Api::Session` in `ArmorsmithApi.h`. The application creates the session and chooses its permissions. Call it on the host's owning thread. |
| Python script | Copied `data` and `context`, `ops` action builders, and `ui` helpers returning a dialog declaration. Buttons invoke named host actions after Python exits. |
| Independently compiled native plugin | A stable DLL ABI and plugin loader are not available in 0.3. |
| External application | An IPC, HTTP, or remote automation transport is not available in 0.3. |

The C++ header uses C++17 standard library types and virtual interfaces. It is a **source contract**, not a binary compatibility promise. Do not pass its STL types across independently compiled DLL boundaries. The Python module is injected by Armorsmith's script launcher; it is not a separately installable package.

## Read, change, and create UI

| Intent | Use | State rules |
| - | - | - |
| Read document, workspace, part, selection, mesh, avatar, or tool metadata | Snapshot and query methods | Returned values are copies. Changing a copy does not change Armorsmith. |
| Rename a part, stretch a mesh, or edit body measurements | `RenamePart`, `StretchMesh`, `SetAvatarMeasurement`, or `SetAvatarHeight` | The host validates handles, permissions, editability, and the expected document revision. Changes use application commands and history. |
| Select a supported interactive tool | `ActivateTool` | Checks context and availability. Activation adds no undo entry; subsequent user edits follow application commands. |
| Navigate history | `Undo` or `Redo` | These operate on the application's history, including edits made outside your integration. |
| Create or close a floating dialog | `ShowDialog` or `CloseDialog` | Requires a UI permission. Dialog controls and actions are declared as data. |
| Observe changes | `PollChanges` | Coarse invalidation tells you when to refresh. There are no public subscriptions or callbacks yet. |

You cannot bypass a lock by requesting a permission. A granted capability means the service is available to your session; the target object must also be eligible when you use it.

## Version and permissions

`Version` contains `major` and `minor`; its defaults are `0` and `3`. `SessionOptions.required_version` selects the requested source contract. The host accepts major `0` with a minor no greater than `3` and rejects newer versions or a different major with `UnsupportedVersion`. `GetInfo()` reports the actual host version and `experimental = true`.

Acceptance of an earlier version does not guarantee future 0.x compatibility. Check capabilities as well as version. Python declarations accept exactly `0.2` or `0.3`; new controls and avatar/tool actions require `0.3`. `ui.dialog` retains its `0.2` default for existing scripts. Opt in with `version=(0, 3)`.

The host chooses `SessionOptions.permissions`. The default is `ReadDocument`. C++ permissions use a bit mask; combine values with `Grant(Permission::...)` and `|`.

| Permission | Value | Allows |
| - | - | - |
| `ReadDocument` | `1` | Document, part, mesh, and history queries; change polling. |
| `RenameParts` | `2` | Part rename commands, with `ReadDocument`. |
| `History` | `4` | Undo and redo commands, with `ReadDocument`. |
| `FilterMeshes` | `8` | Mesh stretch commands, with `ReadDocument`. |
| `CreateUi` | `16` | Dialog creation and cleanup. Creation also requires `ReadDocument`; embedded actions need their own permissions. |
| `EditAvatar` | `32` | Validated height and measurement commands, with `ReadDocument`. |
| `ActivateTools` | `64` | Supported interactive tool activation, with `ReadDocument`. |

Call `GetInfo()` on the host's owning thread to inspect the session's version and grants:

```cpp theme={null}
Result<ApiInfo> GetInfo();
```

`ApiInfo` contains `Version version`, `bool experimental`, and `std::vector<Capability> capabilities`. Each capability has an `id` string and a `granted` boolean.

| Capability ID | Meaning when granted |
| - | - |
| `documents.snapshot` | Read document and part snapshots. |
| `parts.rename` | Request a part rename. |
| `history.read` | Query undo and redo availability. |
| `history.navigate` | Request undo and redo. |
| `events.poll` | Poll document invalidation. |
| `meshes.info` | Query mesh metadata on a host with mesh support. |
| `meshes.stretch` | Request the built-in stretch filter on a host with mesh support. |
| `ui.dialogs` | Create dialogs on a host with UI support. |
| `avatars.read` | Read avatar metadata on a host with avatar support. |
| `avatars.edit` | Request height and measurement edits. |
| `tools.read` | Read viewport context and the tool catalog. |
| `tools.activate` | Request supported interactive tool activation. |

## Current coverage

0.3 adds avatar snapshots, measurement bounds, undoable body edits, a 20-ID viewport tool catalog, and initial activation adapters. The 0.2 document, part, mesh filter, history, and dialog services remain available. Python adds familiar `data`, `context`, and `ops` entry points; `ops` currently builds button actions rather than applying edits during worker execution.

Dedicated topology, transform, island, pattern, spline, material, import/export, appearance, pose, fitting, custom command registration, menu/tool registration, callback, logging, project/plugin data, and filesystem APIs remain future work. Catalog access does not mean every tool can be executed by a script. Reading `selected` does not provide a command to change selection. A mesh query does not expose geometry buffers.

Start with [handles, revisions, and errors](/api/identity-and-errors). Then use the [document reference](/api/documents-and-parts), [avatars and measurements](/api/avatars-and-measurements), [tools and context](/api/tools-and-context), [mesh commands](/api/mesh-commands), [history and changes](/api/history-and-events), [dialog reference](/api/ui-reference), or [Python scripting guide](/api/python-scripting). If you use Blender, read [For Blender scripters](/api/blender-scripters).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.