API Reference

Complete reference for the SimFusion REST API. Base URL: https://api.simfusion.io/v1

Authentication

All API requests require authentication using an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.simfusion.io/v1/projects

Obtaining an API Key

Go to Settings → API Keys in the dashboard
Click "Generate New Key"
Copy and store securely (keys are only shown once)

Projects

List Projects

GET /projects

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 20, max: 100)
`offset`	integer	Pagination offset
`visibility`	string	`public`, `private`, or `all`

Response:

{
  "projects": [
    {
      "id": "proj_123456",
      "name": "Signal Analysis",
      "visibility": "private",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z",
      "owner": "user_789"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Create Project

POST /projects

Request Body:

{
  "name": "My New Project",
  "visibility": "private",
  "template": "blank"
}

Get Project

GET /projects/{project_id}

Update Project

PATCH /projects/{project_id}

Delete Project

DELETE /projects/{project_id}

Models

Export Model

GET /projects/{project_id}/models/{model_id}/export

Query Parameters:

Parameter	Description
`format`	`json`, `python`, `cpp`
`include_data`	Include embedded data files

Response:

{
  "format": "python",
  "code": "import numpy as np...",
  "filename": "model_export.py"
}

Run Simulation

POST /projects/{project_id}/simulate

Request Body:

{
  "duration": 10.0,
  "sample_rate": 1000,
  "parameters": {
    "frequency": 100
  }
}

Blocks

List Available Blocks

GET /blocks

Query Parameters:

Parameter	Description
`category`	Filter by category
`source`	`builtin`, `custom`

Get Block Details

GET /blocks/{block_id}

Response:

{
  "id": "block_sine_wave",
  "name": "Sine Wave",
  "category": "Sources",
  "inputs": [],
  "outputs": [
    {
      "name": "signal",
      "type": "data",
      "description": "Generated sine wave"
    }
  ],
  "parameters": [
    {
      "name": "frequency",
      "type": "float",
      "default": 1.0,
      "min": 0.0,
      "max": 100000.0,
      "unit": "Hz"
    }
  ]
}

Data

Upload Data File

POST /data/upload
Content-Type: multipart/form-data

Form Fields:

Field	Description
`file`	Binary file data
`project_id`	Associated project
`name`	Display name

Query Data

POST /data/query

Request Body:

{
  "data_id": "data_123456",
  "start": 0,
  "end": 1000,
  "fields": ["time", "value"]
}

Workspaces (coming soon)

Collaborative workspaces are part of SimFusion's upcoming real-time collaboration release. The endpoints below are a preview and are not yet generally available.

Create Workspace

POST /workspaces

A workspace is a collaborative editing session.

Request Body:

{
  "project_id": "proj_123456",
  "name": "Team Workspace",
  "participants": ["user_111", "user_222"]
}

Get Workspace Token

GET /workspaces/{workspace_id}/token

Returns a WebSocket token for real-time collaboration.

Error Handling

Status Codes

Code	Meaning
200	Success
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "Frequency must be positive",
    "field": "frequency"
  }
}

Rate Limits

Tier	Requests/Minute	Burst
Explorer	60	10
Professional	600	100
Enterprise	6000	1000

SDKs

Official SDKs available:

Python: pip install simfusion

Changelog

v1.2.0 (2024-03-01)

Added batch simulation endpoints
Improved error messages
Added WebSocket support for workspaces

v1.1.0 (2024-02-15)

Added data query API
New block metadata endpoints
Rate limiting improvements

v1.0.0 (2024-01-01)

Initial stable release

API Reference

Help us improve