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

Common Issues

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

"Invalid preset" - See the API Reference 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]}]

Next Steps

• Timber Beam Guide - Detailed beam documentation
• Snow Load Guide - Snow load calculations
• Generic Templates - Use any calculation template
• API Reference - Full interactive endpoint documentation