Skip to main content
POST
/
v1
/
mathcad
/
jobs
Read Document
curl --request POST \
  --url https://api.stru.ai/v1/mathcad/jobs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "operation": "<string>",
  "source_file": "<string>"
}'

​
Overview

Parse an existing Mathcad Prime (.mcdx) document to extract its structure, elements, and metadata as JSON. Use this to analyze, validate, or migrate existing calculations.
Asynchronous Operation: Returns immediately with a job ID. Poll for the parsed structure.

​
Authentication

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

​
Request Body

​
operation
string
required
Must be "read_document"
"operation": "read_document"
​
source_file
string
required
Base64-encoded .mcdx file content
"source_file": "UEsDBBQAAAAIAOiG..."

​
Response Structure

When complete, returns the parsed document structure: 
{
  "document_structure": {
    "name": string,
    "elements": MathcadElement[],
    "metadata": DocumentMetadata,
    "page_count": number
  }
}

​
Example Request

# First, encode the file
FILE_B64=$(base64 -i calculation.mcdx)

curl -X POST https://api.stru.ai/v1/mathcad/jobs \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d "{
    \"operation\": \"read_document\",
    \"source_file\": \"$FILE_B64\"
  }"

​
Example Response

{
  "job_id": "job_read_abc123",
  "status": "completed",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": "2025-10-17T10:30:05.123Z",
  "results": {
    "document_structure": {
      "name": "Beam Design Calculation",
      "elements": [
        {
          "type": "text",
          "content": "# Beam Design\n\n## Input Parameters"
        },
        {
          "type": "variable",
          "name": "L",
          "value": 20,
          "unit": "ft",
          "description": "Beam span"
        },
        {
          "type": "variable",
          "name": "w",
          "value": 2,
          "unit": "kip/ft",
          "description": "Uniform load"
        },
        {
          "type": "formula",
          "expression": "M_max = w * L^2 / 8",
          "description": "Maximum moment",
          "result_unit": "kip-ft"
        }
      ],
      "metadata": {
        "author": "John Doe, PE",
        "project": "Building A",
        "date": "2025-10-17"
      },
      "page_count": 3
    }
  }
}

​
Use Cases

Parse existing calculations to verify formulas, check variables, and validate against standards.
structure = read_document('calc.mcdx')

# Check for required variables
variables = {e['name'] for e in structure['elements'] if e['type'] == 'variable'}
required = {'L', 'w', 'fc_prime'}

if not required.issubset(variables):
    print(f"Missing required variables: {required - variables}")
Extract calculations from legacy documents and recreate in a standardized format.
old_structure = read_document('legacy-calc.mcdx')

# Transform and recreate with new template
new_elements = transform_elements(old_structure['elements'])
create_document("Updated Calculation", new_elements)
Parse multiple calculations to extract data for reporting or comparison.
for file in calculation_files:
    structure = read_document(file)

    # Extract key results
    results = [e for e in structure['elements'] if e['type'] == 'formula']
    store_in_database(file, results)
Parse a well-formatted calculation to extract its structure as a reusable template.
template_structure = read_document('standard-beam-calc.mcdx')

# Save structure as template
save_template('beam-calc-template', template_structure['elements'])

​
Best Practices

Validate parsed data - Always check that the parsed structure matches expectations before using it
Handle missing metadata - Not all documents have complete metadata; use defaults when needed
Check element types - Verify element types before accessing type-specific fields
Use the parsed structure to create standardized versions of legacy calculations or to build a searchable database of your calculation library.

​
Limitations

Complex formatting: Some advanced Mathcad formatting (custom regions, complex layouts) may be simplified during parsing.
Embedded objects: Some embedded objects (OLE, custom components) may not be fully extracted.

​
Next Steps

After parsing, you can:
  • Validate the extracted structure
  • Use elements to create new standardized documents
  • Extract data for reporting or analysis
  • Identify which calculations need updates