Skip to main content
POST
/
v1
/
mathcad
/
jobs
Create Document
curl --request POST \
  --url https://api.stru.ai/v1/mathcad/jobs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "operation": "<string>",
  "document_name": "<string>",
  "elements": [
    {}
  ],
  "metadata": {},
  "options": {},
  "type": "<string>",
  "content": "<string>",
  "style": "<string>",
  "name": "<string>",
  "value": 123,
  "unit": "<string>",
  "description": "<string>",
  "expression": "<string>",
  "result_unit": "<string>",
  "url": "<string>",
  "caption": "<string>",
  "width": 123,
  "height": 123
}'
{
  "400": {},
  "422": {},
  "job_id": "<string>",
  "status": "<string>",
  "created_at": "<string>"
}

​
Overview

Create a new Mathcad Prime (.mcdx) document by defining its structure as a JSON request. Build complete calculation documents element by element without opening Mathcad.
Asynchronous Operation: Returns immediately with a job ID. Poll Get Job Status for the download URL.

​
Authentication

​
Authorization
string
required
Bearer token (API key from app.stru.ai)
Authorization: Bearer sk_live_abc123...

​
Request Body

​
operation
string
required
Must be "create_document"
"operation": "create_document"
​
document_name
string
required
Document title (1-200 characters)
"document_name": "Beam Design Calculation"
​
elements
array
required
Array of document elements (text, variables, formulas, images)See Element Types below for details
"elements": [
  {"type": "text", "content": "# Introduction"},
  {"type": "variable", "name": "L", "value": 20, "unit": "ft"}
]
​
metadata
object
Document metadata (optional)
"metadata": {
  "author": "John Doe, PE",
  "project": "Building A",
  "date": "2025-10-17"
}
​
options
object
Job configuration options (optional)
"options": {
  "ai_formatting": true,
  "page_orientation": "portrait"
}

​
Element Types

​
Text Elements

Add headers, descriptions, and documentation. 
{
  "type": "text",
  "content": "# Beam Design\n\nThis calculation determines the required reinforcement.",
  "style": "normal"
}
​
type
string
required
Must be "text"
​
content
string
required
Markdown-formatted text content
​
style
string
Text style: "normal", "heading1", "heading2", "heading3"

​
Variable Elements

Define input values with units. 
{
  "type": "variable",
  "name": "L",
  "value": 20,
  "unit": "ft",
  "description": "Beam span length"
}
​
type
string
required
Must be "variable"
​
name
string
required
Variable name (letters, numbers, underscores)
​
value
number
required
Numeric value
​
unit
string
Unit (e.g., "ft", "psi", "kN")
​
description
string
Optional description/comment

​
Formula Elements

Add calculations and equations. 
{
  "type": "formula",
  "expression": "M = w * L^2 / 8",
  "description": "Maximum moment at midspan",
  "result_unit": "kip-ft"
}
​
type
string
required
Must be "formula"
​
expression
string
required
Mathematical expression (Mathcad syntax)
​
description
string
Optional description
​
result_unit
string
Unit for the result
Supported Operators: +, -, *, /, ^, sqrt(), sin(), cos(), tan(), log(), exp()

​
Image Elements

Embed diagrams and photos. 
{
  "type": "image",
  "url": "https://example.com/diagram.png",
  "caption": "Figure 1: Beam loading diagram",
  "width": 600
}
​
type
string
required
Must be "image"
​
url
string
required
Image URL or base64 data URI
​
caption
string
Optional image caption
​
width
number
Width in pixels
​
height
number
Height in pixels

​
Response

Returns a job object with status “pending”.
​
job_id
string
Unique job identifier
"job_mcd_abc123"
​
status
string
Job status: "pending"
"pending"
​
created_at
string
ISO 8601 creation timestamp
"2025-10-17T10:30:00Z"

​
Example Requests

# Create simple document with text and variable
curl -X POST https://api.stru.ai/v1/mathcad/jobs \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create_document",
    "document_name": "Simple Calculation",
    "elements": [
      {
        "type": "text",
        "content": "# Beam Span"
      },
      {
        "type": "variable",
        "name": "L",
        "value": 20,
        "unit": "ft"
      }
    ]
  }'

​
Example Response (Pending)

{
  "job_id": "job_mcd_abc123",
  "status": "pending",
  "created_at": "2025-10-17T10:30:00Z"
}
Status Code: 202 Accepted

​
Example Response (Completed)

After polling, when job completes: 
{
  "job_id": "job_mcd_abc123",
  "status": "completed",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": "2025-10-17T10:30:12.456Z",
  "results": {
    "file_url": "https://storage.stru.ai/temp/beam-calc.mcdx?signature=xyz...",
    "file_type": "mcdx",
    "expires_at": "2025-10-18T10:30:12.456Z"
  }
}

​
Error Responses

​
400
Bad Request
Invalid request structure
{
  "error": {
    "code": "INVALID_ELEMENT",
    "message": "Element at index 3: type must be one of: text, variable, formula, image"
  }
}
​
422
Validation Error
Formula parsing error
{
  "error": {
    "code": "FORMULA_PARSE_ERROR",
    "message": "Unable to parse expression: 'M = w * L^2 /'",
    "details": {
      "element_index": 5,
      "expression": "M = w * L^2 /"
    }
  }
}

​
Best Practices

Structure documents logically - Use text headers to organize sections (Inputs, Calculations, Results)
Define variables before formulas - Ensure all variables used in formulas are defined earlier in the element array
Use descriptive variable names - beam_length is clearer than l
Add descriptions - Include description fields to document what each element represents
Enable AI formatting - For documents with 10+ elements, use ai_formatting: true for professional layout
Download files immediately: Generated .mcdx files expire after 24 hours. Download and store them promptly.
Formula dependencies: Variables must be defined before they’re used in formulas. The API validates this during generation.

​
Next Steps

1

Poll for Completion

Use Get Job Status to check when the document is ready
GET /v1/jobs/{job_id}
2

Download the File

When complete, use the signed URL to download your .mcdx file
curl -o calculation.mcdx "{file_url}"
3

Open in Mathcad

Open the downloaded .mcdx file in Mathcad Prime for review or editing