SimAPI Documentation

Validate simulation results — and simulation setups — before they reach production.

SimAPI checks engineering simulation output against physical laws: it detects impossible values, failed constraints, physics violations, sensor drift, unit errors, and duplicates, then tells you which trials are safe to trust or train on. A pre-flight layer validates the mesh + solver setup before you run and predicts which output checks will fail. Deterministic where physics is exact, AI-assisted where it isn't.

Install the CLI

Pick whichever fits your stack — the command installed is always simapi.

# macOS / Linux
curl -fsSL https://sim-api.vercel.app/install.sh | sh

# Windows (PowerShell)
irm https://sim-api.vercel.app/install.ps1 | iex

# Homebrew
brew install TaxCollector23/tap/simapi

# npm
npm install -g simapi-cli

Quickstart

Validate a batch of simulation trials against the aerodynamics ruleset:

curl -X POST https://sim-api.vercel.app/api/v1/validate \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_type": "aerodynamics",
    "conditions": { "velocity": 15.0 },
    "data": [
      { "cd": 0.312, "cl": 0.847, "re": 415000 },
      { "cd": 999.0, "cl": 0.850, "re": 418000 }
    ]
  }'

The response returns status (passed/warning/failed), the surfaced issues, per-trial exclusions, per-column statistics, and a training_ready verdict.

Authentication

Send your key in the X-API-Key header (preferred) or as a bearer token. The SDKs and CLI read SIMAPI_API_KEY from the environment automatically.

curl https://sim-api.vercel.app/api/v1/validate \
  -H "X-API-Key: sk_live_..."

Base URL

https://sim-api.vercel.app/api

All endpoints are versioned under /v1. The response schema within a version is additive-only.

POST /v1/validate

Runs the deterministic engine on a batch of trials and (when enabled) an AI second pass. Returns only surfaced issues — passed checks are counted, not listed.

Request

Response

POST /v1/validate/setup

Pre-flight validation: judge a mesh + solver + physics configuration before it runs and predict which output checks are likely to fail.

curl -X POST https://sim-api.vercel.app/api/v1/validate/setup \
  -H "Content-Type: application/json" \
  -d '{ "config": {
    "solver": "openfoam",
    "flow_conditions": { "reynolds_number": 1000000 },
    "mesh": { "estimated_yplus": 45, "max_non_orthogonality": 88 },
    "solver_settings": { "turbulence_model": "kOmegaSST" }
  }}'

Returns status (ready/warning/not_ready), estimated_corruption_risk, humanized predicted_failures (each with a why and a fix), and actionable recommendations.

GET /v1/health

curl https://sim-api.vercel.app/api/v1/health

Errors

Errors use a consistent envelope with a stable code and a request_id:

{ "error": { "code": "bad_request", "message": "`data` must be a non-empty array.", "request_id": "3f9c…a12" } }

Python SDK

pip install simapi

import simapi
result = simapi.validate(
    data="cfd_output.csv",
    simulation_type="aerodynamics",
    conditions={"velocity": 15.0, "altitude": 120.0},
)
print(result.status)          # "passed"
print(result.training_ready)  # True

Node / TypeScript SDK

npm install simapi-cli

import { SimAPI } from "simapi-cli";
const client = new SimAPI(process.env.SIMAPI_API_KEY);
const result = await client.validate(rows, { simulationType: "aerodynamics" });
if (result.status === "failed") throw new Error("Simulation rejected");

CLI

simapi login                 # browser sign-in, saves your key
simapi init                  # write a sample simapi.json
simapi validate run.json     # score, status, warnings, violations, time
simapi watch run.json        # re-validate on change
simapi validate run.json --fail-on warning   # non-zero exit for CI
simapi usage                 # requests today/month, quota, avg time
simapi api-key show|rotate|delete

CI/CD

Turn a validation verdict into a build gate with --fail-on:

- name: Validate simulation output
  run: simapi validate results.json --fail-on warning
  env:
    SIMAPI_API_KEY: ${{ secrets.SIMAPI_API_KEY }}