ErgoPlanner

Appearance

API Reference Overview ​

Technical documentation for developers

Introduction ​

ErgoPlanner provides APIs for integration with external systems, automation, and custom development. This section documents available interfaces.

API Types ​

REST API ​

For server-side integration:

  • Project management
  • Simulation execution
  • Results retrieval
  • User authentication

JavaScript SDK ​

For browser-based extensions:

  • Canvas manipulation
  • Custom components
  • Event handling
  • UI extensions

Authentication ​

API Keys ​

Generate API keys in Account Settings > API Keys:

javascript
// Include in request headers
Authorization: Bearer YOUR_API_KEY

OAuth 2.0 ​

For third-party applications:

  • Authorization code flow
  • Token refresh
  • Scope-based permissions

REST API Endpoints ​

Projects ​

MethodEndpointDescription
GET/api/projectsList projects
POST/api/projectsCreate project
GET/api/projects/:idGet project
PUT/api/projects/:idUpdate project
DELETE/api/projects/:idDelete project

Simulations ​

MethodEndpointDescription
POST/api/projects/:id/simulateRun simulation
GET/api/projects/:id/resultsGet results
GET/api/projects/:id/streamsGet stream data

Units ​

MethodEndpointDescription
GET/api/unitsList unit types
GET/api/units/:typeGet unit schema

JavaScript SDK ​

Installation ​

html
<!-- Via CDN -->
&lt;script src="https://cdn.ergoplanner.com/sdk.js"&gt;&lt;/script&gt;
bash
# Via npm
npm install @ergoplanner/sdk

Basic Usage ​

javascript
import { ErgoPlanner } from '@ergoplanner/sdk';

// Initialize
const ep = new ErgoPlanner({
  apiKey: 'YOUR_API_KEY'
});

// Load project
const project = await ep.projects.get('project-id');

// Run simulation
const results = await project.simulate({
  type: 'steady-state'
});

// Access results
console.log(results.effluent.TSS);

Event Handling ​

javascript
// Listen for simulation complete
project.on('simulation:complete', (results) => {
  console.log('Simulation finished:', results);
});

// Listen for unit selection
project.on('unit:selected', (unit) => {
  console.log('Selected:', unit.id);
});

Data Formats ​

Project JSON ​

json
{
  "id": "project-123",
  "name": "Sample Plant",
  "units": [
    {
      "id": "unit-1",
      "type": "CSTR",
      "properties": {
        "volume": 5000,
        "MLSS": 3500
      }
    }
  ],
  "connections": [
    {
      "from": "unit-1",
      "to": "unit-2",
      "type": "liquid"
    }
  ]
}

Results JSON ​

json
{
  "status": "converged",
  "iterations": 45,
  "streams": {
    "effluent": {
      "flow": 10000,
      "TSS": 12,
      "COD": 35,
      "NH4": 1.5
    }
  },
  "massBalance": {
    "COD": {
      "in": 5000,
      "out": 350,
      "removed": 4650
    }
  }
}

Rate Limits ​

PlanRequests/hour
Free100
Professional1,000
Enterprise10,000

Error Handling ​

HTTP Status Codes ​

CodeMeaning
200Success
400Bad request
401Unauthorized
403Forbidden
404Not found
429Rate limited
500Server error

Error Response ​

json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Volume must be positive",
    "field": "units[0].properties.volume"
  }
}

Webhooks ​

Configure webhooks for event notifications:

Supported Events ​

EventTrigger
simulation.completeSimulation finishes
project.updatedProject saved
export.readyExport file ready

Webhook Payload ​

json
{
  "event": "simulation.complete",
  "timestamp": "2024-01-15T10:30:00Z",
  "project_id": "project-123",
  "data": {
    "status": "converged",
    "duration_ms": 1250
  }
}

SDK Examples ​

Custom Unit Type ​

javascript
// Register custom unit
ep.units.register({
  type: 'MyCustomUnit',
  schema: {
    properties: {
      efficiency: { type: 'number', min: 0, max: 1 }
    }
  },
  calculate: (inputs, params) => {
    return {
      COD: inputs.COD * (1 - params.efficiency)
    };
  }
});

Batch Simulations ​

javascript
// Run multiple scenarios
const scenarios = [
  { influent: { COD: 400 } },
  { influent: { COD: 500 } },
  { influent: { COD: 600 } }
];

const results = await Promise.all(
  scenarios.map(s => project.simulate(s))
);

// Compare results
results.forEach((r, i) => {
  console.log(`Scenario ${i}: Effluent COD = ${r.effluent.COD}`);
});

Support ​

Resources ​

Contact ​