Formulas API¶

The Formulas API provides endpoints for creating, validating, and applying visual formula configurations using a graph-based builder.

Overview¶

CalcBridge's formula builder supports:

• Graph-Based Design: Visual node-and-edge formula construction
• Validation: Structural and dependency validation before execution
• Preview: Test formulas against real data before applying
• Versioning: Track formula changes with version history
• Dual Mode: Builder (visual) and Advanced (expression) modes

Endpoints¶

Validate Formula Graph¶

Validate a formula graph structure and dependencies.

POST /api/v1/formulas/validate

Request Body¶

Example Request¶

curl -X POST "https://api.calcbridge.io/api/v1/formulas/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "graph": {
      "version": "1.0",
      "template_id": "custom",
      "nodes": [
        {"id": "n1", "type": "column_ref", "params": {"column": "par_value"}},
        {"id": "n2", "type": "column_ref", "params": {"column": "price"}},
        {"id": "n3", "type": "expression", "params": {"formula": "n1 * n2 / 100"}}
      ],
      "edges": [
        {"id": "e1", "source": {"nodeId": "n1", "port": "out"}, "target": {"nodeId": "n3", "port": "in1"}},
        {"id": "e2", "source": {"nodeId": "n2", "port": "out"}, "target": {"nodeId": "n3", "port": "in2"}}
      ]
    }
  }'

Response¶

{
  "is_valid": true,
  "errors": [],
  "warnings": [],
  "dependencies": ["par_value", "price"]
}

Preview Formula¶

Preview formula results against real workbook data.

POST /api/v1/formulas/preview

Request Body¶

Response¶

{
  "sample_results": [
    {"row": 1, "input": {"par_value": 5000000, "price": 98.5}, "output": 4925000.0},
    {"row": 2, "input": {"par_value": 3000000, "price": 101.2}, "output": 3036000.0}
  ],
  "total_rows": 150,
  "preview_size": 25,
  "compiled_formula": "[par_value] * [price] / 100"
}

List Formula Configs¶

List formula configurations for the current tenant.

GET /api/v1/formulas

Query Parameters¶

Create Formula Config¶

Create a new formula configuration.

POST /api/v1/formulas

Request Body¶

Response (201 Created)¶

{
  "id": "fc_abc123",
  "name": "Market Value Calculator",
  "description": "Calculates market value from par and price",
  "template_id": "custom",
  "graph": { "..." },
  "mode": "builder",
  "status": "draft",
  "version_count": 1,
  "current_version": "v1",
  "created_at": "2026-01-25T10:30:00Z"
}

Get Formula Config¶

Get a specific formula configuration with details.

GET /api/v1/formulas/{config_id}

Create Formula Version¶

Create a new version of an existing formula.

PUT /api/v1/formulas/{config_id}/versions

Request Body¶

List Formula Runs¶

List execution history for a formula.

GET /api/v1/formulas/{config_id}/runs

Apply Formula¶

Apply a formula version to a workbook sheet.

POST /api/v1/formulas/{config_id}/apply

Request Body¶

Response¶

{
  "run_id": "run_abc123",
  "config_id": "fc_abc123",
  "version_id": "v1",
  "status": "processing",
  "rows_affected": 0,
  "started_at": "2026-01-25T10:30:00Z"
}

Graph Node Types¶

Related Documentation¶

• Formula Config Models - Data model reference
• Formula Builder - Feature documentation
• Calculations API - Direct formula evaluation