S3D Agent Skill

You are an agent that builds, analyses, and queries SkyCiv Structural 3D (S3D) structural models via the SkyCiv API. This skill covers the full s3d_model JSON schema and every function in the S3D.model, S3D.results, S3D.file, and S3D.SB namespaces.

Prerequisite: Always begin a session with S3D.session.start as the first function. See the skyciv-core skill for auth, options, and the request/response envelope.

The `s3d_model` Object#

The s3d_model is the JSON representation of a structural model. It is passed to S3D.model.set.

{
  "settings": { ... },
  "nodes": { ... },
  "members": { ... },
  "plates": { ... },
  "meshed_plates": { ... },
  "sections": { ... },
  "materials": { ... },
  "supports": { ... },
  "settlements": { ... },
  "point_loads": { ... },
  "moments": { ... },
  "distributed_loads": { ... },
  "pressures": { ... },
  "area_loads": { ... },
  "self_weight": { ... },
  "load_combinations": { ... },
  "groups": { ... }
}

All objects use integer-keyed dictionaries (e.g. "1": { ... }, "2": { ... }).

Tip: To inspect a model as JSON, open it in SkyCiv S3D and use File → Export → SkyCiv File (JSON for API). To test JSON, use File → Import → SkyCiv File (JSON for API).

`settings`#

Key	Type	Accepts	Default
`units`	`string` or `object`	`"imperial"`, `"metric"`, or detailed object	varies
`vertical_axis`	`string`	`"Y"`, `"Z"`	`"Y"`
`precision`	`string`	`"fixed"`, `"exponential"`	`"fixed"`
`precision_values`	`integer`	1–15	—
`evaluation_points`	`integer`	3–50	—
`solver_timeout`	`integer`	seconds	—
`non_linear_tolerance`	`string`	e.g. `"1"` (= 1%)	—
`non_linear_theory`	`string`	`"small"`, `"finite"`	`"small"`
`auto_stabilize_model`	`boolean`	—	`false`
`member_offsets_axis`	`string`	`"global"`, `"local"`	`"local"`
`dynamic_modes`	`integer`	positive integer	5

Detailed units object:

{
  "units": {
    "length": "m",
    "section_length": "mm",
    "material_strength": "mpa",
    "density": "kg/m3",
    "force": "kn",
    "moment": "kn-m",
    "pressure": "kpa",
    "mass": "kg",
    "translation": "mm",
    "stress": "mpa"
  }
}

Imperial defaults: ft, in, ksi, lb/ft3, kip, kip-ft, ksf, kip, in, ksi.

`nodes`#

{
  "nodes": {
    "1": { "x": 0, "y": 0, "z": 0 },
    "2": { "x": 5, "y": 0, "z": 0 }
  }
}

`members`#

Key	Type	Description
`type`	`string`	`"normal"` (default), `"normal_continuous"`, `"cable"`
`node_A`	`integer`	Start node ID
`node_B`	`integer`	End node ID
`section_id`	`integer`	Section ID
`rotation_angle`	`float`	Rotation about member axis in degrees (−180 to 180)
`fixity_A` / `fixity_B`	`string`	6-character restraint code
`offset_Ax/Ay/Az`	`float`	Local offsets at node A
`offset_Bx/By/Bz`	`float`	Local offsets at node B
`local_axis_y`	`[float]`	Global vector `[X,Y,Z]` for local y-axis
`local_axis_z`	`[float]`	Global vector `[X,Y,Z]` for local z-axis

{
  "members": {
    "1": {
      "node_A": 1,
      "node_B": 2,
      "section_id": 1,
      "rotation_angle": 0,
      "fixity_A": "FFFFFF",
      "fixity_B": "FFFFFF",
      "offset_Ax": "0", "offset_Ay": "0", "offset_Az": "0",
      "offset_Bx": "0", "offset_By": "0", "offset_Bz": "0"
    }
  }
}

`plates`#

Key	Type	Description
`nodes`	`[integer]`	Node IDs forming the plate (min 3, sequential order)
`thickness`	`float`	Plate thickness (section_length units)
`material_id`	`integer`	Material ID
`rotZ`	`float`	Rotation about local Z in degrees (default `0`)
`type`	`string`	`"auto"` — considers shear deformation automatically
`diaphragm`	`string`	`"no"` or `"rigid"`
`state`	`string`	`"stress"` or `"strain"`

`meshed_plates`#

Manually defined mesh elements (usually auto-generated by S3D.model.mesh).

Key	Description
`node_A/B/C/D`	Corner node IDs. `node_D: null` for triangular elements
`parent_plate`	ID of the parent plate

`sections`#

Sections can be defined four ways:

1. Library section (recommended for standard shapes):

{
  "sections": {
    "1": {
      "load_section": ["American", "AISC", "W shapes", "W14x22"],
      "material_id": 1
    }
  }
}

2. Custom section from My Sections:

{ "1": { "load_custom": ["Folder1", "my-section-name"] } }

3. Numeric properties only (no design/stress support):

{
  "1": {
    "name": "MySection",
    "area": 6500,
    "Iy": 16000000,
    "Iz": 50000000,
    "J": 250000,
    "material_id": 1,
    "shear_area_z": 500,
    "shear_area_y": 800
  }
}

4. Template shape:

{
  "1": {
    "material_id": 1,
    "info": {
      "shape": "ibeam",
      "dimensions": { "h": 200, "b": 100, "tf": 10, "tw": 6 }
    }
  }
}

Available template shapes: rectangle, hollow rectangle, circle, hollow circle, ibeam/i, tbeam/tee/t, lbeam/angle/l, channel/c, lipped channel, zshape/z, lipped zshape, lipped angle, lipped channel box.

`materials`#

Key	Type	Description
`name`	`string`	Material name
`density`	`float`	Density
`elasticity_modulus`	`float`	Young's modulus
`poissons_ratio`	`float`	Poisson's ratio
`yield_strength`	`float`	Yield strength
`ultimate_strength`	`float`	Ultimate strength
`class`	`string`	`"steel"`, `"aluminium"`, `"concrete"`, `"wood"`, `"masonry"`, `"other"`

`supports`#

Key	Description
`node`	Node ID
`restraint_code`	6-char restraint code
`tx/ty/tz/rx/ry/rz`	Spring stiffness values (used when restraint char = `S`)

`point_loads`#

Key	Description
`type`	`"n"` (nodal) or `"m"` (member)
`node`	Node ID (when `type = "n"`)
`member`	Member ID (when `type = "m"`)
`position`	Position along member as % (0–100, when `type = "m"`)
`x_mag/y_mag/z_mag`	Load magnitudes
`load_group`	Load group name (string)

`moments`#

Same structure as point_loads — x_mag/y_mag/z_mag represent moment magnitudes about each axis.

`distributed_loads`#

Key	Description
`member`	Member ID
`x/y/z_mag_A`	Load magnitude at start (position A)
`x/y/z_mag_B`	Load magnitude at end (position B)
`position_A/B`	Start/end positions as percentage (0–100)
`load_group`	Load group name
`axes`	`"global"`, `"global_projected"`, or `"local"`

`pressures`#

Applied to plates.

Key	Description
`plate_id`	Plate ID
`x/y/z_mag`	Pressure magnitude
`axes`	`"global"`, `"global_projected"`, `"local"`
`load_group`	Load group name

`area_loads`#

Key	Description
`type`	`"one_way"`, `"two_way"`, `"column_wind_load"`, `"open_structure"`, `"non_rectangular"`
`nodes`	Node IDs defining the area (3 or 4)
`mag`	Load magnitude
`direction`	`"X"`, `"Y"`, `"Z"`, or projected variants
`LG`	Load group

`self_weight`#

{
  "self_weight": {
    "enabled": true,
    "x": 0,
    "y": -1,
    "z": 0
  }
}

`load_combinations`#

{
  "load_combinations": {
    "1": {
      "name": "1.2D + 1.6L",
      "criteria": "strength",
      "Dead": 1.2,
      "Live": 1.6,
      "SW1": 1.2
    }
  }
}

criteria is optional: "strength", "serviceability", or "other". Load group names used as keys (e.g. "Dead", "SW1") — values are load factors.

`groups`#

{
  "groups": {
    "1": {
      "name": "Columns",
      "ids": [1, 2, 3],
      "type": "elements"
    }
  }
}

type accepts: "elements", "nodes", "supports", "plates", "groups".

Restraint Codes#

A 6-character string. First 3 = translational DOF (local X, Y, Z). Last 3 = rotational DOF (local X, Y, Z).

Character	Meaning
`F`	Fixed
`R`	Released (free)
`S`	Spring

Examples:

"FFFFFF" — fully fixed (pin/fixed support)
"FFFRRR" — pinned (fixed translation, free rotation)
"FFFFFR" — fixed except rotation about local Z

S3D.model Functions#

`S3D.model.set`#

Sets the structural model for the session.

{
  "function": "S3D.model.set",
  "arguments": { "s3d_model": { /* model object */ } }
}

`S3D.model.get`#

Returns the current s3d_model object. Requires S3D.model.set earlier in session.

{ "function": "S3D.model.get" }

`S3D.model.repair`#

Fixes common model issues before solving. Requires S3D.model.set.

Check	Description
`unused_nodes`	Remove floating/disconnected nodes
`large_structure`	Detect unit-system issues (extreme slenderness)
`merge_nodes`	Merge near-coincident nodes
`zero_members`	Remove zero-length members
`continuous_to_normal_members`	Split members with intermediate nodes
`intersect_members`	Connect crossing members
`default_section`	Add a default section to members with none
`force_plate_mesh`	Allow analysis without pre-meshed plates

{
  "function": "S3D.model.repair",
  "arguments": {
    "checks": ["unused_nodes", "merge_nodes", "intersect_members"]
  }
}

Omit checks to run all repairs.

`S3D.model.solve`#

Runs structural analysis. Requires S3D.model.set.

Key	Type	Default	Description
`analysis_type`	`string`	`"linear"`	`"linear"`, `"nonlinear"`, `"buckling"`, `"dynamic"`, `"response_spectrum"`
`repair_model`	`boolean`	`false`	Run repair before solving
`return_data`	`boolean`	`true`	Include solve data in response
`format`	`string`	`"json"`	`"json"`, `"csv"`, `"summary"`, `"s3d"`
`lc_filter`	`[string]`	all	`"envelope"`, `"envelope_abs_max"`, `"load_case"`, `"load_group"`, `"load_combo"`, or specific LC names like `"LC1"`
`result_filter`	`[string]`	all	`"reactions"`, `"member_forces"`, `"member_stresses"`, `"member_peak_results"`, `"member_discontinuities"`, `"member_displacements"`, `"plate_forces"`, `"plate_stresses"`, `"plate_element_forces"`, `"plate_element_stresses"`, `"plate_peak_results"`, `"buckling"`, `"dynamic_frequency"`
`include_nodal_displacements`	`boolean`	`false`	Include nodal displacements per load combo

{
  "function": "S3D.model.solve",
  "arguments": {
    "analysis_type": "linear",
    "repair_model": true,
    "lc_filter": ["envelope_abs_max"],
    "result_filter": ["member_peak_results", "reactions"]
  }
}

Tip: Always use result_filter and lc_filter to minimise response size.

Results are returned as a dictionary keyed by load combination index.

`S3D.model.mesh`#

Meshes plates. Requires S3D.model.set.

Key	Type	Default	Description
`method`	`string`	`"frontal_quads"`	`"frontal_quads"`, `"frontal"`, `"adapt"`, `"packing_parallelograms"`, `"delaunay"`
`granularity`	`integer`	`1`	1 (coarse) to 5 (fine)
`plate_ids`	`[integer]`	all plates	Specific plates to mesh

`S3D.model.takeScreenshot`#

Returns base64 PNG screenshots.

Key	Type	Description
`views`	`[string]`	`"iso"`, `"front"`, `"side"`, `"top"`, `"custom"`
`is_renderer`	`boolean`	Use 3D renderer (`true`) or wireframe (`false`)
`wireframe_settings`	`object`	`show_nodes`, `show_loads`, `show_plates`, `projection`
`zoom_factor`	`float`	−50 to 50
`scale`	`float`	0 to 5

`S3D.model.surfaceSpringSupports`#

Simulates surface spring supports on a plate.

{
  "function": "S3D.model.surfaceSpringSupports",
  "arguments": {
    "subgrade_modulus": 3,
    "spring_type": "linear",
    "plate_ids": [1]
  }
}

spring_type: "linear", "compression", "tension".

`S3D.model.script`#

Run custom JavaScript against the S3D model. Useful for complex topology operations.

{
  "function": "S3D.model.script",
  "arguments": {
    "script": "var id = S3D.structure.nodes.add({x:10, y:0, z:0}); API_RETURN_DATA = {new_node: id};"
  }
}

Write to API_RETURN_DATA to return data. Available S3D functions include S3D.structure.nodes.add, S3D.structure.members.add, S3D.structure.supports.add, S3D.structure.members.intersect, S3D.UI.update.

`S3D.model.getLocalAxisVectors`#

Returns local axis vectors {x, y, z} for each member.

S3D.results Functions#

`S3D.results.get`#

Fetches analysis results after solving. Same filter options as S3D.model.solve.

{
  "function": "S3D.results.get",
  "arguments": {
    "result_filter": ["member_peak_results"],
    "lc_filter": ["envelope_abs_max"]
  }
}

`S3D.results.set`#

Set results from an external source for further processing.

{
  "function": "S3D.results.set",
  "arguments": { "analysis_results": { /* results object */ } }
}

`S3D.results.fetchMemberResult`#

Get detailed results for a specific member.

Key	Type	Description
`member_id`	`integer`	Member ID (`null` = all members)
`LC`	`[integer]`	Load combination IDs (empty = all)
`res_key`	`string`	`"bmd_z"`, `"bmd_y"`, `"axial"`, `"sfd_y"`, `"sfd_z"`, `"top_bending_stress_z"`, `"displacement"`, `"displacement_x/y/z"`
`type`	`string`	`"array"`, `"x,y"` (with x positions), `"image"` (base64 plot)

{
  "function": "S3D.results.fetchMemberResult",
  "arguments": {
    "member_id": 1,
    "LC": [1],
    "res_key": "bmd_z",
    "type": "x,y"
  }
}

`S3D.results.getAnalysisReport`#

Generate a PDF or TXT analysis report. Requires S3D.model.set and S3D.model.solve.

{
  "function": "S3D.results.getAnalysisReport",
  "arguments": {
    "job_name": "My Project",
    "file_type": "pdf",
    "load_combinations": [1, 2, "Envelope Absolute Max"],
    "sections": {
      "title_page": true,
      "nodal_reactions": true,
      "member_forces": true,
      "member_displacements": true
    }
  }
}

Returns view_link and download_link URLs.

`S3D.results.getDynamicFreq`#

Returns dynamic/frequency analysis results.

{
  "function": "S3D.results.getDynamicFreq",
  "arguments": {
    "result_filter": ["modes", "mass_participation_percentage"]
  }
}

S3D.file Functions#

`S3D.file.save`#

Save the current model to cloud storage. Requires S3D.model.set.

{
  "function": "S3D.file.save",
  "arguments": {
    "name": "my-model",
    "path": "projects/analysis/",
    "public_share": true
  }
}

Returns a URL to open the file in S3D, and optionally a public_link.

`S3D.file.open`#

Load a model from cloud storage (sets it for the session).

{
  "function": "S3D.file.open",
  "arguments": {
    "name": "my-model",
    "path": "projects/analysis/",
    "load_results": false
  }
}

Use uid instead of name/path if the file UID is known.

`S3D.file.share`#

Share a model file with other SkyCiv users.

{
  "function": "S3D.file.share",
  "arguments": {
    "name": "my-model",
    "path": "projects/",
    "share_with": ["[email protected]"]
  }
}

`S3D.file.getFileDirectory`#

List files/folders in cloud storage.

{
  "function": "S3D.file.getFileDirectory",
  "arguments": {
    "path": "projects/",
    "full_list_flat": true
  }
}

`S3D.file.restoreVersion`#

Roll back to a prior version.

{
  "function": "S3D.file.restoreVersion",
  "arguments": { "rollback_versions": 1 }
}

S3D.SB (Section Builder) Functions#

`S3D.SB.getLibraryTree`#

List available sections in the section library.

{
  "function": "S3D.SB.getLibraryTree",
  "arguments": {
    "section_map": ["American", "AISC", "W shapes"]
  }
}

`S3D.SB.loadLibraryShape`#

Load a specific section from the library into the session.

`S3D.SB.buildCustomShape`#

Build a custom section from points or a line-with-thickness.

{
  "function": "S3D.SB.buildCustomShape",
  "arguments": {
    "units": "mm",
    "type": "points",
    "points": [
      [0, 0, 0], [100, 0, 0], [100, 200, 0], [0, 200, 0]
    ],
    "run_solve": true,
    "material_id": 1
  }
}

type: "line" takes an open polyline + thickness to create thin-walled sections.

`S3D.SB.solve`#

Calculate section properties for the currently loaded section.

{ "function": "S3D.SB.solve" }

`S3D.SB.submit`#

Submit the current section into the structural model.

{
  "function": "S3D.SB.submit",
  "arguments": { "section_id": 1 }
}

`S3D.SB.runGSD`#

General Section Designer — FEA-based RC section capacity check.

Key	Description
`design_code`	`"ACI"`, `"AS 3600"`, `"BS"`, `"CSA"`, `"EN"`, `"IS 456"`, `"NSCP 2015"`
`concrete_class`	e.g. `"C5000"` (ACI) or `"N32"` (AS)
`steel_grade`	e.g. `"Grade 60"` (ACI)
`reinforcement`	Array of `{z, y, diam}`
`loads`	Array of `{N, M_z, M_y}`

Full Workflow Example#

{
  "auth": { "username": "[email protected]", "key": "YOUR_KEY" },
  "options": { "validate_input": true },
  "functions": [
    { "function": "S3D.session.start", "arguments": { "keep_open": false } },
    {
      "function": "S3D.model.set",
      "arguments": {
        "s3d_model": {
          "settings": { "units": "metric", "vertical_axis": "Y" },
          "nodes": {
            "1": { "x": 0, "y": 0, "z": 0 },
            "2": { "x": 5, "y": 0, "z": 0 }
          },
          "members": {
            "1": {
              "node_A": 1, "node_B": 2, "section_id": 1,
              "rotation_angle": 0,
              "fixity_A": "FFFFFF", "fixity_B": "FFFFFF",
              "offset_Ax": 0, "offset_Ay": 0, "offset_Az": 0,
              "offset_Bx": 0, "offset_By": 0, "offset_Bz": 0
            }
          },
          "sections": {
            "1": { "load_section": ["Australian", "Steel (300 Grade)", "Universal beams", "310 UB 32.0"], "material_id": 1 }
          },
          "materials": {
            "1": { "name": "Steel", "density": 7850, "elasticity_modulus": 200000, "poissons_ratio": 0.27, "yield_strength": 350, "ultimate_strength": 470, "class": "steel" }
          },
          "supports": {
            "1": { "node": 1, "restraint_code": "FFFFFF", "tx": 0, "ty": 0, "tz": 0, "rx": 0, "ry": 0, "rz": 0 },
            "2": { "node": 2, "restraint_code": "FFFFRR", "tx": 0, "ty": 0, "tz": 0, "rx": 0, "ry": 0, "rz": 0 }
          },
          "distributed_loads": {
            "1": { "member": 1, "y_mag_A": -10, "y_mag_B": -10, "x_mag_A": 0, "z_mag_A": 0, "x_mag_B": 0, "z_mag_B": 0, "position_A": 0, "position_B": 100, "load_group": "LL", "axes": "global" }
          },
          "load_combinations": {
            "1": { "name": "LC1", "LL": 1.5 }
          },
          "plates": {}, "meshed_plates": {}, "settlements": {},
          "point_loads": {}, "moments": {}, "pressures": {},
          "area_loads": {}, "self_weight": {}, "groups": {}
        }
      }
    },
    {
      "function": "S3D.model.solve",
      "arguments": {
        "analysis_type": "linear",
        "repair_model": true,
        "result_filter": ["member_peak_results", "reactions"]
      }
    }
  ]
}

The s3d_model Object#

settings#

nodes#

members#

plates#

meshed_plates#

sections#

materials#

supports#

point_loads#

moments#

distributed_loads#

pressures#

area_loads#

self_weight#

load_combinations#

groups#

Restraint Codes#

S3D.model Functions#

S3D.model.set#

S3D.model.get#

S3D.model.repair#

S3D.model.solve#

S3D.model.mesh#

S3D.model.takeScreenshot#

S3D.model.surfaceSpringSupports#

S3D.model.script#

S3D.model.getLocalAxisVectors#