Getting Started

Copy page

Quick Start

Create a project and run your first wood beam calculation.

Prerequisites

• API key from Calcs.com (contact [email protected])

Step 1: Create a Project

All calculations belong to a project. Create one first:

Code
 
curl -X POST "https://api.calcs.com/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Project",
    "buildingStandard": "US"
  }'

Response:

Code
 
{
  "projectId": "e206293f-773b-44ae-96ba-b0df6ddb75f6",
  "name": "My First Project"
}

Save the projectId - you'll need it for calculations.

Step 2: Run a Calculation

Calculate a floor joist using the single-call endpoint:

Code
 
curl -X POST "https://api.calcs.com/v1/timber-beam/calculate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "e206293f-773b-44ae-96ba-b0df6ddb75f6",
    "preset": "floorJoist",
    "name": "Kitchen Floor Joist",
    "attributes": {
      "L_X": 14,
      "member": "2x10 D.Fir-L No. 1",
      "supports": [["Pinned", 0, 1.5], ["Pinned", 14, 1.5]],
      "loadsDist": [["Floor Load", 0, "L", "spacing", "TW_s", {"D": [15], "L": [40]}]]
    }
  }'

Response:

Code
 
{
  "sheetId": "648d7791-e5ea-4809-a69c-6596cb33069c",
  "name": "Kitchen Floor Joist",
  "status": "solved",
  "results": {
    "passed": true,
    "utilizationRatio": 0.67,
    "summaryCheck": {
      "referenceId": "delta_DL+LL_summary",
      "value": 0.67,
      "error": false,
      "failReasons": []
    }
  },
  "inputs": {
    "member": "2x10 D.Fir-L No. 1",
    "length": 14,
    "supports": 2,
    "loads": 1,
    "preset": "floorJoist"
  }
}

Done! The beam passes with 67% utilization.

Understanding the Results

Field	Description
passed	true if all checks pass
utilizationRatio	Demand/capacity ratio (0-1). Lower is better.
summaryCheck.failReasons	Empty array means no failures

Input Parameters Explained

Code
 
{
  "L_X": 14,                                      // Span length in feet
  "member": "2x10 D.Fir-L No. 1",                 // Lumber size and grade
  "supports": [                                   // [type, position, bearingWidth]
    ["Pinned", 0, 1.5],
    ["Pinned", 14, 1.5]
  ],
  "loadsDist": [                                  // Distributed loads
    ["Floor Load", 0, "L", "spacing", "TW_s", {"D": [15], "L": [40]}]
  ]
}

Alternative: Multi-Step Workflow

For complex scenarios, use the step-by-step approach:

Code
 
# 1. Create sheet
curl -X POST "https://api.calcs.com/v1/timber-beam/sheets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "YOUR_PROJECT_ID", "preset": "genericBeam", "name": "My Beam"}'

# 2. Update attributes
curl -X PATCH "https://api.calcs.com/v1/timber-beam/sheets/SHEET_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "Database", "L_X": 12, "member": "2x12 D.Fir-L No. 1", "supports": [["Pinned", 0, 1.5], ["Pinned", 12, 1.5]], "loadsDist": [["Load", 0, "L", 1, "One", {"D": [50], "L": [100]}]]}'

# 3. Solve
curl -X POST "https://api.calcs.com/v1/timber-beam/sheets/SHEET_ID/solve" \
  -H "Authorization: Bearer YOUR_API_KEY"

Presets

13 presets provide sensible defaults for common beam types:

Preset	Use Case	Key Defaults
genericBeam	Custom configuration	Minimal defaults
genericFlitchBeam	Steel-reinforced timber	Flitch plate configuration
floorJoist	Repeating floor joists	16" spacing, top braced
floorGirder	Multi-ply floor beams	3-ply default
ceilingJoist	Ceiling framing	16" spacing, top braced
rafter	Inclined roof members	4:12 slope default
hipValley	Hip/valley rafters	4:12 slope default
roofGirder	Ridge beams	2-ply default
roofHeader	Roof openings	No lateral bracing
floorHeader	Floor openings	No lateral bracing
comboBeam	Combined loading	Floor + roof loads
deckJoist	Deck joists	Wet service, 16" spacing
deckBeam	Deck beams	Wet service, 3-ply default

Next Steps

• Timber Beam Guide - Detailed beam documentation
• Presets Reference - All preset options

Common Issues

"projectId is required" - Create a project first using POST /v1/projects

"Invalid preset" - See the presets table above for valid preset codes

Results show passed: false - Check summaryCheck.failReasons for details

Results show NaN utilization - Check your loadsDist format. The correct format is:

Code
 
["Load Name", start, "L", width, widthType, {loadCases}]

For joists: ["Floor Load", 0, "L", "spacing", "TW_s", {"D": [15], "L": [40]}] For headers/beams: ["Wall Load", 0, "L", 1, "One", {"D": [100], "L": [200]}]