CloudCAD API — 2D drawings

Build a CloudCAD drawing as a JSON object (cad_data), send it with cloudcad.model.create, then store it with cloudcad.file.save. This skill covers the cad_data schema and the cloudcad.model / cloudcad.file namespaces.

Prerequisite: auth, options and the { auth, options, functions } envelope are in skyciv-api-v3. No S3D.session.start is needed. cloudcad.model.create opens its own CloudCAD session (verified: without it, create returns "CloudCAD session successfully created." and a following save works). Adding S3D.session.start first does no harm but adds about 6 s.

Units: every coordinate and every length setting is real-world millimetres, whatever settings.canvasLengthUnits says. That setting ("mm", "cm", "m", "ft", "in") only changes how dimension labels are displayed. Verified: a 7315.2 mm line with canvasLengthUnits: "ft" is labelled 24.0 ft.

Workflow

1. Draw at true size, in mm, with y negative going up (see Coordinates). Never scale geometry to fit a page.
2. Pick a plot scale and size the attributeStyles for it. Every length-valued style setting is printed mm × scale, e.g. dimensionTextSize: 378 at 1:100 prints at 3.78 mm (see Sizing).
3. Wrap the drawing in the default page + title block, unless the user asked for bare geometry. Translate the content into the template's safe zone; do not scale it. See references/pages-and-title-blocks.md.
4. Lint, then send cloudcad.model.create + cloudcad.file.save in one request. create accepts anything and returns status: 0, even {} or {"canvases": "nope"}, so a status: 0 proves nothing. Run the linter (Bundled tools) and look at a render (Verifying).
5. Give the user the data URL returned by save.

In Node, scripts/cad_helpers.js does steps 2–4: emptyCanvas, text, hatch, rectCloud/revisionCloud, attributeStyle(plotScale), wrapInTitleBlock({ canvas, plotScale }) and lint(cad_data). Opt-in structural data uses s3dMember, s3dSupport, s3dColumn, s3dPlate and s3dRoot.

cad_data structure

{
  "settings": { "canvasLengthUnits": "mm" },
  "attributeStyles": [ { "id": "as-default", "name": "Default", "settings": { } } ],
  "blockReferences": [ ],
  "pdfExport": { "pdfPages": [ ] },
  "s3d": { },
  "canvases": [ { "name": "Plan", "lines": [ ], "dimensions": [ ], "texts": [ ] } ]
}

Verified minimum: {"canvases":[{"lines":[...]}]} renders. Missing element arrays, version/schema/drawing_type/is_base are all optional. Real platform exports omit drawing_type and is_base. Including every array as [] is still the safe default (emptyCanvas() does this), because the editor expects them.

Field-by-field schema for every element type (settings keys, style keys, lines, polylines, the three dimension types, leaders, text, tables, axes, construction lines, revision clouds, hatches, images, layers, blocks): read references/elements.md before writing an element type you haven't written in this session.

Minimal working example

Verified live: this renders a 6 m × 4 m rectangle with a dimension and a label, then saves it.

{
  "auth": { "username": "user@example.com", "key": "YOUR_KEY" },
  "functions": [
    { "function": "cloudcad.model.create", "arguments": { "cad_data": {
      "settings": { "canvasLengthUnits": "mm" },
      "attributeStyles": [ { "id": "as-default", "name": "Default", "settings": {
        "dimensionTextSize": 378, "linearArrowShape": "arrow", "linearArrowLength": 216, "linearArrowWidth": 216,
        "leaderTextSize": 378, "leaderArrowLength": 216, "leaderArrowWidth": 216,
        "axisTextSize": 324, "axisCircleDiameter": 1080, "axisDashLength": 216, "axisDashGap": 108,
        "textSizeInput": 14, "textSizeOverride": false, "fontFamily": "monospace", "tableFontSize": 400 } } ],
      "canvases": [ {
        "name": "Ground Floor",
        "lines": [
          { "p1": { "x": 0, "y": 0 },        "p2": { "x": 6000, "y": 0 } },
          { "p1": { "x": 6000, "y": 0 },     "p2": { "x": 6000, "y": -4000 } },
          { "p1": { "x": 6000, "y": -4000 }, "p2": { "x": 0, "y": -4000 } },
          { "p1": { "x": 0, "y": -4000 },    "p2": { "x": 0, "y": 0 } }
        ],
        "dimensions": [ { "p1": { "x": 0, "y": 0 }, "p2": { "x": 6000, "y": 0 },
          "offsetPoint": { "x": 3000, "y": 800 }, "projectionType": "horizontal", "attributeStyleId": "as-default" } ],
        "texts": [ { "position": { "x": 3000, "y": -2000 }, "text": "GROUND FLOOR", "size": 20,
          "color": "#ffffff", "alignment": "center", "textPosition": "middle-center", "attributeStyleId": "as-default" } ]
      } ]
    } } },
    { "function": "cloudcad.file.save", "arguments": { "name": "ground-floor", "path": "projects/cad/" } }
  ]
}

Functions

There is no cloudcad.model.get/set/export function: the API can't read a drawing's JSON back or export a PDF/DXF. Calling one returns "The function '...' could not be found".

Coordinates

• 2D only. y is negative going up the screen/sheet. To draw something upward, subtract from y. Mapping an S3D model (y up) needs y_cad = -y_model.
• No origin boundary; negative coordinates are fine.
• Rotation units differ by element, and every one of these was verified by render:

Sizing: one rule

Pick the plot scale S (100 for 1:100). Every length-valued style setting is printed mm × S:

attributeStyle(S) in the helper builds this. Don't scale textSizeInput, which is not a length. When a generator switches plot scale, it rescales the style (and any page furniture) by the same factor and leaves the geometry at true size.

Plain texts do not use the style for size. size is a unitless factor that renders at roughly 16 mm of character width per unit (monospace), verified across zoom levels: a 17-character string at size: 14 was about 3.9 m wide. So size: 14 suits a building-scale plan at 1:100. For a 1:10 detail, divide it by about 10.

Verifying a drawing (you can't open the viewer)

Undocumented, but useful: when any call in a request fails, the response's top-level response.screenshot holds an 800×600 base64 PNG of the headless CloudCAD editor, showing the model built so far. To see your drawing, append a deliberately unknown call after create, such as {"function": "cloudcad.model.get", "arguments": {}}, then decode response.screenshot. It costs one credit and the view is not always zoomed to your content. This is a debugging aid for checking a new generator's output, not something to leave in production code.

Gotchas

All of these were verified against the live API on 2026-09-22.

• create never validates. Empty, garbage or broken cad_data returns status: 0, and validate_input has no effect on it. Lint the payload and check a render.
• Never scale geometry to fit a page. Dimensions measure the real distance between their points, so scaling corrupts every label: a 24 ft span once read 40000mm. Translate only. If the drawing doesn't fit, change the plot scale or sheet.
• Never pre-convert coordinates for canvasLengthUnits. Dividing coordinates by 304.8 and setting "ft" converts twice (24 ft became 0.08 ft).
• Hatch segments need start/end. Segments with only p1/p2 make create hang until it times out (about 43 s, reproduced twice). Real exports carry both field pairs.
• Revision clouds need a precomputed arcs array. With arcs: [], or no arcs, the cloud is accepted but draws nothing. The platform doesn't generate the scallops. Build them with rectCloud() / revisionCloud().
• Linear dimensions: omit projectionType to get an aligned, true-length dimension (a 3-4-5 diagonal reads 5000.0 mm). "horizontal" / "vertical" give that projection (the same diagonal reads 3000 / 4000). Any other value, including "aligned", is treated as a projection rather than aligned.
• Text needs a light color. The canvas is dark, and a text with no color renders near-black and invisible. Use #ffffff / #e2e8f0 / #94a3b8. PDF output colours are unverified.
• textPosition on every text. Rendering works without it, but the editor is reported to crash when the user selects such a text. alignment anchors the text at position as you'd expect (center centres it on x, right ends it at x), so don't also pre-shift position.
• Missing or unknown attributeStyleId fails silently. The element falls back to the built-in style (grey labels, default sizes).
• Images don't render inside a block definition. Tables, axes, text, linear and radius dimensions do. Put logos on the canvas images array. An image's x/y is its top-left corner and it extends toward +y (down the screen).
• cloudcad.file.open gives no signal. It returns status: 0 for files that don't exist and loads nothing observable, so "open → edit → save" doesn't work. To change a drawing, regenerate the full cad_data, then create + save it with the same name/path.
• Structural (s3d) data is opt-in, and it lives on the elements. Leave it out unless the user explicitly asks for the drawing to carry S3D data. When they do, the root s3d block alone does nothing: a line only becomes a member if it carries s3d: { member: {...} }. The same goes for supports on points and plates on hatches. wrapInTitleBlock drops the root block unless you pass s3d. Per-element s3d survives create + save (verified 2026-09-25). Shapes and helpers are in references/s3d-mapping.md.
• Don't paste the asset JSON into a prompt. assets/title-block-a2.json is about 50 KB and the two example exports are about 125 KB each. Load them in code (fs.readFileSync) and copy the pieces.

Bundled tools and assets

Related skills

• skyciv-api-v3: auth, envelope, options.
• s3d-api: the s3d_model whose nodes/members you'd draw.
• s3d-apps: in-app code, where SKYCIV_UTILS.exportToCad(cad_data) opens a drawing directly.
• schema-agent: reading a floor plan before drawing it.
• renderer: 3D visualisation (not 2D drawings).