Data Models

Overview

The Mathcad API uses consistent data models for document generation, element management, and file operations. All operations follow an asynchronous job-based workflow.

MathcadJobRequest

Request schema for creating Mathcad document generation jobs.

interface MathcadJobRequest {
  operation: "create_document" | "read_document" | "generate_pdf" | "add_elements";
  document_name?: string;           // Document title (for create operations)
  elements?: MathcadElement[];      // Array of document elements
  metadata?: DocumentMetadata;      // Document metadata (author, project, etc.)
  options?: JobOptions;             // Optional job configuration
  source_file?: string;             // For read/pdf operations (base64 encoded .mcdx)
}

Field Details

operation

string

required

Type of operation to performValid values:

"create_document" - Generate new .mcdx file
"read_document" - Parse existing .mcdx file
"generate_pdf" - Convert .mcdx to PDF
"add_elements" - Add content to existing document

"operation": "create_document"

document_name

string

Title/name for the document (used for create operations)

"document_name": "Beam Design Calculation"

elements

array

Array of document elements to addSee MathcadElement schema below

"elements": [
  {"type": "text", "content": "# Introduction"},
  {"type": "variable", "name": "L", "value": 20}
]

metadata

object

Document metadataSee DocumentMetadata schema below

"metadata": {
  "author": "John Doe",
  "project": "Building A",
  "date": "2025-10-17"
}

options

object

Optional job configurationSee JobOptions schema below

"options": {
  "ai_formatting": true,
  "page_orientation": "portrait"
}

source_file

string

Base64-encoded .mcdx file (for read/pdf operations)

"source_file": "UEsDBBQAAAAIAOiG..."

MathcadElement

Individual document element (text, variable, formula, or image).

type MathcadElement = TextElement | VariableElement | FormulaElement | ImageElement;

TextElement

Text blocks for headers, descriptions, and documentation.

interface TextElement {
  type: "text";
  content: string;              // Markdown-formatted text
  style?: "normal" | "heading1" | "heading2" | "heading3";
}

Example:

{
  "type": "text",
  "content": "# Beam Design\n\nThis calculation determines the required reinforcement for a simply supported beam.",
  "style": "normal"
}

VariableElement

Variable definitions with values and units.

interface VariableElement {
  type: "variable";
  name: string;                 // Variable name (e.g., "L", "fc_prime")
  value: number;                // Numeric value
  unit?: string;                // Unit (e.g., "ft", "psi", "kN")
  description?: string;         // Optional description
}

Example:

{
  "type": "variable",
  "name": "L",
  "value": 20,
  "unit": "ft",
  "description": "Beam span length"
}

FormulaElement

Calculations and equations.

interface FormulaElement {
  type: "formula";
  expression: string;           // Mathematical expression
  description?: string;         // Optional description
  result_unit?: string;         // Unit for the result
}

Example:

{
  "type": "formula",
  "expression": "M = w * L^2 / 8",
  "description": "Maximum moment at midspan",
  "result_unit": "kip-ft"
}

Supported Operators:

Arithmetic: +, -, *, /, ^ (power)
Functions: sqrt(), sin(), cos(), tan(), log(), exp()
Comparison: >, <, >=, <=, ==

ImageElement

Embedded images and diagrams.

interface ImageElement {
  type: "image";
  url: string;                  // Image URL or base64 data URI
  caption?: string;             // Optional caption
  width?: number;               // Width in pixels
  height?: number;              // Height in pixels
}

Example:

{
  "type": "image",
  "url": "https://example.com/beam-diagram.png",
  "caption": "Figure 1: Beam loading diagram",
  "width": 600
}

DocumentMetadata

Metadata for Mathcad documents.

interface DocumentMetadata {
  author?: string;              // Document author
  project?: string;             // Project name
  date?: string;                // Date (ISO 8601 format)
  company?: string;             // Company name
  revision?: string;            // Revision number
  custom?: Record<string, any>; // Custom metadata fields
}

Example:

{
  "author": "John Doe, PE",
  "project": "Building A - Foundation Design",
  "date": "2025-10-17",
  "company": "ABC Engineering",
  "revision": "Rev 2",
  "custom": {
    "client": "XYZ Developers",
    "job_number": "2025-042"
  }
}

JobOptions

Optional configuration for document generation jobs.

interface JobOptions {
  ai_formatting?: boolean;              // Enable AI layout optimization
  page_orientation?: "portrait" | "landscape";
  include_toc?: boolean;                // Include table of contents
  output_format?: "mcdx" | "pdf";       // Output file format
}

Example:

{
  "ai_formatting": true,
  "page_orientation": "portrait",
  "include_toc": true,
  "output_format": "mcdx"
}

MathcadJobResponse

Response when a job completes successfully.

interface MathcadJobResponse {
  job_id: string;
  status: "completed";
  created_at: string;
  completed_at: string;
  results: MathcadResults;
}

MathcadResults

Results for different operation types.

interface MathcadResults {
  file_url?: string;            // Download URL (for create/pdf operations)
  file_type?: "mcdx" | "pdf";   // File type
  expires_at?: string;          // URL expiration (ISO 8601)
  document_structure?: DocumentStructure;  // Parsed structure (for read operations)
}

Example (Create Document):

{
  "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"
  }
}

Example (Read Document):

{
  "job_id": "job_mcd_xyz789",
  "status": "completed",
  "created_at": "2025-10-17T10:35:00Z",
  "completed_at": "2025-10-17T10:35:05.123Z",
  "results": {
    "document_structure": {
      "name": "Beam Design Calculation",
      "elements": [
        {"type": "text", "content": "# Introduction"},
        {"type": "variable", "name": "L", "value": 20, "unit": "ft"}
      ],
      "metadata": {
        "author": "John Doe",
        "project": "Building A"
      }
    }
  }
}

DocumentStructure

Parsed structure of a Mathcad document (returned by read operations).

interface DocumentStructure {
  name: string;
  elements: MathcadElement[];
  metadata: DocumentMetadata;
  page_count: number;
}

Example:

{
  "name": "Beam Design Calculation",
  "elements": [
    {"type": "text", "content": "# Beam Design"},
    {"type": "variable", "name": "L", "value": 20, "unit": "ft"},
    {"type": "formula", "expression": "M = w * L^2 / 8"}
  ],
  "metadata": {
    "author": "John Doe",
    "project": "Building A"
  },
  "page_count": 3
}

ConversionRequest

Request to convert legacy .xmcd files to .mcdx format.

interface ConversionRequest {
  source_file: string;          // Base64-encoded .xmcd file
  options?: ConversionOptions;
}

ConversionOptions

interface ConversionOptions {
  preserve_formatting?: boolean;    // Attempt to preserve original layout
  output_format?: "mcdx" | "pdf";   // Output format (default: mcdx)
}

Example:

{
  "source_file": "UEsDBBQAAAAIAOiG...",
  "options": {
    "preserve_formatting": true,
    "output_format": "mcdx"
  }
}

ConversionResponse

Response from conversion jobs.

interface ConversionResponse {
  job_id: string;
  status: "completed";
  results: {
    file_url: string;
    file_type: "mcdx" | "pdf";
    expires_at: string;
    conversion_notes?: string[];    // Warnings or issues encountered
  }
}

Example:

{
  "job_id": "job_conv_abc123",
  "status": "completed",
  "results": {
    "file_url": "https://storage.stru.ai/temp/converted.mcdx?signature=...",
    "file_type": "mcdx",
    "expires_at": "2025-10-18T10:30:00Z",
    "conversion_notes": [
      "Some complex formatting simplified",
      "Custom font replaced with default"
    ]
  }
}

Error Responses

Standard error format for failed jobs.

interface MathcadError {
  code: string;
  message: string;
  details?: any;
}

Common Error Codes

Code	Description
`INVALID_ELEMENT`	Invalid element type or structure
`FORMULA_PARSE_ERROR`	Unable to parse mathematical expression
`FILE_TOO_LARGE`	Source file exceeds size limit
`UNSUPPORTED_FORMAT`	File format not supported
`GENERATION_FAILED`	Document generation encountered an error
`CONVERSION_FAILED`	Legacy file conversion failed

Example:

{
  "job_id": "job_mcd_abc123",
  "status": "failed",
  "error": {
    "code": "FORMULA_PARSE_ERROR",
    "message": "Unable to parse expression: 'M = w * L^2 /' (incomplete expression)",
    "details": {
      "element_index": 5,
      "expression": "M = w * L^2 /"
    }
  }
}

Validation Rules

Document Name Validation

Length: 1-200 characters
Characters: Letters, numbers, spaces, hyphens, underscores
Required for: create_document operations

Variable Name Validation

Format: Must start with a letter
Characters: Letters, numbers, underscores
Reserved: Cannot use Mathcad reserved words (e.g., if, for, while)
Length: 1-50 characters

Formula Expression Validation

Length: 1-1000 characters
Syntax: Must be valid Mathcad expression
Variables: All variables must be defined before use
Functions: Only supported Mathcad functions

Element Limits

Free tier: Maximum 50 elements per document
Pro tier: Maximum 500 elements per document
Enterprise: Unlimited

File Size Limits

Source files: Maximum 25 MB
Images: Maximum 5 MB per image
Total document: Maximum 50 MB

Complete Example

Full request to create a comprehensive Mathcad document:

{
  "operation": "create_document",
  "document_name": "Simply Supported Beam Design",
  "elements": [
    {
      "type": "text",
      "content": "# Simply Supported Beam Design\n\n## 1. Input Parameters",
      "style": "heading1"
    },
    {
      "type": "variable",
      "name": "L",
      "value": 20,
      "unit": "ft",
      "description": "Beam span"
    },
    {
      "type": "variable",
      "name": "w",
      "value": 2,
      "unit": "kip/ft",
      "description": "Uniform dead load"
    },
    {
      "type": "text",
      "content": "## 2. Moment Calculation"
    },
    {
      "type": "formula",
      "expression": "M_max = w * L^2 / 8",
      "description": "Maximum moment at midspan",
      "result_unit": "kip-ft"
    },
    {
      "type": "text",
      "content": "## 3. Beam Diagram"
    },
    {
      "type": "image",
      "url": "https://example.com/beam-diagram.png",
      "caption": "Figure 1: Simply supported beam with uniform load",
      "width": 600
    }
  ],
  "metadata": {
    "author": "John Doe, PE",
    "project": "Building A - Floor Framing",
    "date": "2025-10-17",
    "company": "ABC Engineering",
    "revision": "Rev 1"
  },
  "options": {
    "ai_formatting": true,
    "page_orientation": "portrait",
    "output_format": "mcdx"
  }
}

Overview

Memory API

Blogs API

Search API

Mathcad API

Excel API

Overview

MathcadJobRequest

Field Details

MathcadElement

TextElement

VariableElement

FormulaElement

ImageElement

DocumentMetadata

JobOptions

MathcadJobResponse

MathcadResults

DocumentStructure

ConversionRequest

ConversionOptions

ConversionResponse

Error Responses

Common Error Codes

Validation Rules

Complete Example

Overview

Memory API

Blogs API

Search API

Mathcad API

Excel API

​Overview

​MathcadJobRequest

​Field Details

​MathcadElement

​TextElement

​VariableElement

​FormulaElement

​ImageElement

​DocumentMetadata

​JobOptions

​MathcadJobResponse

​MathcadResults

​DocumentStructure

​ConversionRequest

​ConversionOptions

​ConversionResponse

​Error Responses

​Common Error Codes

​Validation Rules

​Complete Example

Overview

MathcadJobRequest

Field Details

MathcadElement

TextElement

VariableElement

FormulaElement

ImageElement

DocumentMetadata

JobOptions

MathcadJobResponse

MathcadResults

DocumentStructure

ConversionRequest

ConversionOptions

ConversionResponse

Error Responses

Common Error Codes

Validation Rules

Complete Example