APEX Entity Actions & Payloads Reference

Detailed API payload contracts and interfaces for mutating Scene Objects, Effects, Operators, Datasets, and Options.
Published: 7/10/2026

Action Contracts & Union Typings

The APEX protocol groups mutations under the ApexAction discriminated union. To provide a lightweight, highly readable workspace reference, the schema is divided by domain payloads as shown below:

Dataset & Row Action Reference#

Detailed payload structure and decoupling contracts for configuring schemas and modifying granular data rows.

Dataset & Row Mutations Reference

Maintains a decoupled architecture where dataset metadata changes are separate from granular row operations to keep payload trees flat. For SDK usage details, see Datasets.

For basic examples of constructing atomic mutations for options or rows, see Basic APEX Transaction Examples. For details on structural schemas returned during inspection, see APEX Domain Structure Schemas.

typescript
export interface DatasetApexAction extends BaseApexAction {
    domain: ApexDomain.DATASET;
    payload: {
        schema?: Record<string, any>;
        name?: string;
    };
}

export interface DatasetRowApexAction extends BaseApexAction {
    domain: ApexDomain.DATASET_ROW;
    payload: {
        /** The ID of the dataset this row belongs to */
        datasetId: string;
        /** The actual row data */
        values: Record<string, any>;
    };
}

Color Conversion Schema Type

When defining the dataset schema, developers are encouraged to use "COLOR" as the schema type for fields containing color values. This automatically handles the conversion of any user-input color format (such as hex strings or RGB values) into the engine's internal [number, number, number, number] RGBA representation.

Universal Delete Action Reference#

The universal deletion schema and rules in the APEX protocol requiring no payload fields.

Universal Deletion Payload

Deletion operates uniformly across all domains. Because deleting an entity permanently purges it from the active Aircada database, it requires no payload parameters beyond the specific target identifier:

typescript
/** Delete acts universally across all domains, requiring no payload */
export interface DeleteAction extends BaseApexAction {
    operation: ApexOperation.DELETE;
    payload?: never;
}

Effect Action Reference#

Detailed payload structure and types for binding stickers, animations, shaders, or visual effects to parent entities.

Effect Mutations Reference

Manages visual effects, stickers, shaders, and animations bound to specific parent scene elements. For SDK usage details, see Visual Effects.

typescript
export interface EffectApexAction extends BaseApexAction {
    domain: ApexDomain.EFFECT;
    payload: {
        /** The parent node this effect belongs to */
        parentId: string;
        type: string; // e.g., "ASE_TEXTURE_STICKER_MATERIALFX"
        name?: string;
        properties?: Record<string, any>;
    };
}

Operator Action Reference#

Detailed payload structure and types for registering and configuring scriptable behaviors and automation blocks.

Operator Mutations Reference

Configures scriptable behaviors, triggers, calculators, and system automation blocks. For SDK usage details, see Operators.

typescript
export interface OperatorApexAction extends BaseApexAction {
    domain: ApexDomain.OPERATOR;
    payload: {
        type?: string; // e.g., "TIMER"
        name?: string;
        properties?: Record<string, any>;
    };
}

Option Model & Set Action Reference#

Detailed payload structure and types for option models and sets connecting 3D meshes to customizable datasets.

Option Model & Set Mutations Reference

Binds customizable options (e.g., color ranges, shoe materials) to scene configurators. For SDK usage details, see Options.

typescript
export interface OptionModelApexAction extends BaseApexAction {
    domain: ApexDomain.OPTION_MODEL;
    payload: {
        name?: string;
    };
}

export interface OptionSetApexAction extends BaseApexAction {
    domain: ApexDomain.OPTION_SET;
    payload: {
        /** The ID of the option model this set belongs to */
        optionModelId: string;
        name?: string;
        datasetId?: string;
    };
}

Scene Object Action Reference#

Detailed payload structure and types for spawning and editing 3D models, cameras, lights, shapes, or UI layouts.

Scene Object Mutations Reference

Used for spawning and editing 3D models, shapes, cameras, lights, or flat UI layouts. For SDK usage details, see 3D Scene and Scene Objects Reference. Specific spatial transform operations are defined in 3D Transforms Reference, and surface texturing rules can be found in 3D Materials Reference.

typescript
export interface SceneObjectApexAction extends BaseApexAction {
    domain: ApexDomain.SCENE_OBJECT;
    payload?: {
        type: "Model" | "Shape" | "Camera" | "Light" | "UI";
        name?: string;
        mediaItemId?: string;
        transform?: TransformPartial;
        material?: Partial<IAircadaMaterial>;
        properties?: Record<string, any>;
    };
}

"### Helper Structural Types", "These utilities are used inside transformations and 3D positioning payloads:",

typescript
export interface Vector3Partial { x?: number; y?: number; z?: number; }
export interface Vector4Partial { x?: number; y?: number; z?: number; w?: number; }

export interface TransformPartial {
    position?: Vector3Partial;
    rotation?: Vector4Partial;
    scale?: Vector3Partial;
}