Simien Central API — Guide

1. Quick start: five calls

This is the whole workflow on a real building (a 16-zone house). Each step uses a value from the step before.

API=https://central-api.simien.no/api/v1/sim
AUTH="Authorization: Bearer $API_KEY"

# 1. What can I change, and what can I run?
curl -s -X POST "$API/simulatable-parameters" -H "$AUTH" -F "file=@building.simx" -o parameters.json

import os, json, requests

API = "https://central-api.simien.no/api/v1/sim"
AUTH = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

# 1. What can I change, and what can I run?
with open("building.simx", "rb") as f:
    r = requests.post(f"{API}/simulatable-parameters", headers=AUTH, files={"file": f})
r.raise_for_status()
parameters = r.json()

import { readFile } from "node:fs/promises";

const API = "https://central-api.simien.no/api/v1/sim";
const AUTH = { Authorization: `Bearer ${process.env.API_KEY}` };
const building = new Blob([await readFile("building.simx")]);

// 1. What can I change, and what can I run?
const form = new FormData();
form.append("file", building, "building.simx");
const parameters = await (await fetch(`${API}/simulatable-parameters`,
  { method: "POST", headers: AUTH, body: form })).json();

$Api  = "https://central-api.simien.no/api/v1/sim"
$Auth = @{ Authorization = "Bearer $env:API_KEY" }

# 1. What can I change, and what can I run?
Invoke-RestMethod -Method Post "$Api/simulatable-parameters" -Headers $Auth `
  -Form @{ file = Get-Item building.simx } -OutFile parameters.json

From parameters.json take three things:

{
  "source": {
    "sha256": "29b6901aa58674bb…",      // → identifies this building; needed in step 3
    "simien_version": "8.1.1.15"        // → use as simien_version
  },
  "simulations": [
    {"id": "winter-simulation#159", "type": "wintersim", "name": "Winter Simulation 1"},
    {"id": "year-simulation#158",   "type": "yearsim",   "name": "Year Simulation 1"},   // → use as params
    {"id": "profit-evaluation#230", "type": "profitsim", "name": "Profit Evaluation 1"}
  ],
  "parameters": { … {"id": "facade#178", "label": "Facade 'living_room_and_kitchen_89bc1d78..Face2_ExteriorWall'",
                     "values": {"uvalue": 0.18, "thermal_cap": 2.4, "ext_absorption_coeff": 0.8}} … }
}

# 2. Run the simulation as it is (the baseline)
curl -s -X POST "$API/simulate" -H "$AUTH" -F "file=@building.simx" \
  -F "params=year-simulation#158" -F "simien_version=8.1.1.15" -F "format=catalog" -o baseline.json

# 3. Write the change you want: facade#178 gets a better wall (use the full sha256)
cat > edit.json <<'EOF'
{"source": {"sha256": "29b6901aa58674bb…"},
 "parameters": [{"id": "facade#178", "values": {"uvalue": 0.10}}]}
EOF

# 4. Run it again with the change (the same .simx + the edit)
curl -s -X POST "$API/simulate" -H "$AUTH" -F "file=@building.simx" \
  -F "simulatable_parameters=@edit.json;type=application/json" \
  -F "params=year-simulation#158" -F "simien_version=8.1.1.15" -F "format=catalog" \
  -D headers.txt -o edited.json

# 5. Confirm the change was applied, then compare baseline.json with edited.json (§6.3)
grep -i x-simulatable-parameters-changed headers.txt      # → 1

building = open("building.simx", "rb").read()
form = {"params": "year-simulation#158", "simien_version": "8.1.1.15", "format": "catalog"}

# 2. Run the simulation as it is (the baseline)
r = requests.post(f"{API}/simulate", headers=AUTH, data=form, timeout=300,
                  files={"file": ("building.simx", building)})
baseline = r.json()

# 3. Write the change you want: facade#178 gets a better wall
edit = {"source": {"sha256": parameters["source"]["sha256"]},
        "parameters": [{"id": "facade#178", "values": {"uvalue": 0.10}}]}

# 4. Run it again with the change (the same .simx + the edit)
r = requests.post(f"{API}/simulate", headers=AUTH, data=form, timeout=300,
                  files={"file": ("building.simx", building),
                         "simulatable_parameters": ("edit.json", json.dumps(edit), "application/json")})
edited = r.json()

# 5. Confirm the change was applied, then compare baseline with edited (§6.3)
print(r.headers["X-Simulatable-Parameters-Changed"])   # → 1

const simulate = (edit) => {
  const form = new FormData();
  form.append("file", building, "building.simx");
  form.append("params", "year-simulation#158");
  form.append("simien_version", "8.1.1.15");
  form.append("format", "catalog");
  if (edit) form.append("simulatable_parameters",
    new Blob([JSON.stringify(edit)], { type: "application/json" }), "edit.json");
  return fetch(`${API}/simulate`, { method: "POST", headers: AUTH, body: form });
};

// 2. Run the simulation as it is (the baseline)
const baseline = await (await simulate()).json();

// 3. Write the change you want: facade#178 gets a better wall
const edit = { source: { sha256: parameters.source.sha256 },
               parameters: [{ id: "facade#178", values: { uvalue: 0.10 } }] };

// 4. Run it again with the change (the same .simx + the edit)
const response = await simulate(edit);
const edited = await response.json();

// 5. Confirm the change was applied, then compare baseline with edited (§6.3)
console.log(response.headers.get("X-Simulatable-Parameters-Changed"));   // → 1

$Run = @{ params = "year-simulation#158"; simien_version = "8.1.1.15"; format = "catalog" }

# 2. Run the simulation as it is (the baseline)
Invoke-RestMethod -Method Post "$Api/simulate" -Headers $Auth `
  -Form ($Run + @{ file = Get-Item building.simx }) -OutFile baseline.json

# 3. Write the change you want: facade#178 gets a better wall
$sha256 = (Get-Content parameters.json -Raw | ConvertFrom-Json).source.sha256
@{ source = @{ sha256 = $sha256 }; parameters = @(@{ id = "facade#178"; values = @{ uvalue = 0.10 } }) } |
  ConvertTo-Json -Depth 5 | Set-Content edit.json

# 4. Run it again with the change (the same .simx + the edit)
$r = Invoke-WebRequest -Method Post "$Api/simulate" -Headers $Auth -OutFile edited.json -PassThru `
  -Form ($Run + @{ file = Get-Item building.simx; simulatable_parameters = Get-Item edit.json })

# 5. Confirm the change was applied, then compare baseline.json with edited.json (§6.3)
$r.Headers["X-Simulatable-Parameters-Changed"]   # → 1

2. Basics

2.1 Authentication

Authorization: Bearer sk_live_<identifier>_<secret>

Every endpoint needs the key except the health checks (/healthz, /api/v1/sim/health). Keep the key on your server; never ship it in a browser app. A missing key returns 401 MISSING_API_KEY, a wrong one 401 INVALID_API_KEY.

2.2 Uploading files

• Requests with files are multipart/form-data.
• The building always goes in a field named file: your .simx. It is decrypted in memory for that one request and never stored.
• .sxi works too. A plaintext .sxi is accepted everywhere a .simx is, with the same results — except simx-metadata, which takes .simx only.
• The sxo/* endpoints take a result (.sxo) in the same file field, not a building.
• Files are limited to 50 MB; a larger one gets 413 FILE_TOO_LARGE.
• A simulatable-parameters document goes in a second file field named simulatable_parameters, not a text field.

2.3 How long calls take

Measured on a 10-zone office building and a 16-zone house:

Use a client timeout of at least 120 s for simulate and more for simulate-all on large buildings. Results can be large: a year simulation's .sxo is around 10 MB, its catalog around 11 MB.

2.4 Rate limits

Limits are per endpoint and per client IP. Every rate-limited response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). When you exceed a limit you get 429 RATE_LIMIT_EXCEEDED with a Retry-After header and retry_after (seconds) in the body. Other endpoints are unaffected.

2.5 Errors in one paragraph

Every error is {"error": {"code": "…", "message": …, "request_id": "…", "doc_url": "…"}}. Branch on code, not on the text. message is a string, or — when the simulation service explains an input problem — an object with code, message, job_id, and often problems (a list) and hint. Quote request_id (also the X-Request-Id header) and X-Job-ID when you contact support. doc_url links to the code's explanation in this guide. Full list: §11.

3. Endpoints

Which one do I want?

simx-metadata and simulatable-parameters read the same .simx but answer different questions:

4. Choosing the inputs

4.1 Simulation id (params)

Read it from simulations[].id in the simulatable-parameters response — ids differ per file (year-simulation#158, aarsim#23, …) and cannot be guessed. The list contains every id simulate accepts: simulations (year, winter, …) and evaluations such as the energy label (energimerke26#545) and profitability (profit-evaluation#230). Send exactly one id. simulate-all runs all the simulations in one call, but not the evaluations — run those one at a time with simulate.

4.2 Version (simien_version)

The simplest reliable choice is source.simien_version from simulatable-parameters — the version the building was saved with. Any version from GET /api/v1/sim/versions also works (newest first). Both spellings are accepted: 8_1_2_22 and 8.1.2.22. SIMIEN 7 is not supported. simulate-all reads the version from the file if you leave it out.

4.3 Location (location)

Optional. Leave it out to keep the climate stored in the file — the X-Climate response header tells you which climate was used. To override, pass a name exactly as returned by GET /api/v1/sim/locations, including æ/ø/å (Bodø, Tromsø). An unknown name returns 400 SIMULATION_REJECTED ("Unknown location …").

5. Run a simulation — POST /api/v1/sim/simulate

The file name (Content-Disposition) is {file}_{version}_{simulation}_{climate}_{timestamp} plus .sxo, _catalog.json or _export.zip; the .sxo inside the ZIP has the same name as the sxo download. Names with æ/ø/å are sent as an ASCII filename plus a UTF-8 filename*.

6. Reading the results

6.1 The catalog

format=catalog returns:

{
  "metadata": {"project": "…", "sim_type": "year_sim", "total_zones": 10, "total_variables": 610, "generated_at": "…", "sxo_file": "…"},
  "variables": [
    {
      "variable_name": "Energibehov",           // what it is (Norwegian, as in SIMIEN)
      "heading": "Netto energibehov (A)",       // the table/graph it comes from
      "zone": "Alle soner",                     // "Alle soner" = whole building, or a zone name
      "source_type": "table", "source_id": "table#1",
      "data_type": "time_series", "unit": "kWh",
      "labels": ["1a Romoppvarming", "1b Ventilasjonsvarme (varmebatterier)", "2  Varmtvann (tappevann)", …,
                 "Totalt netto energibehov, sum 1-6"],
      "values": [7038, 400, 6504, …, 23207],
      "value": null,                            // used instead of values for single numbers
      "climate": "Oslo", "sim_type": "year_sim", "sxo_file": "…", "column_index": 1
    },
    …
  ],
  "applied_changes": { … }                      // only when you sent simulatable_parameters (§9.5)
}

labels and values are parallel arrays. The net energy demand of the whole building, for example, is the variable with variable_name: "Energibehov" and zone: "Alle soner"; its label "Totalt netto energibehov, sum 1-6" holds the total in kWh/year.

6.2 The ZIP

format=zip contains the .sxo, metadata.json, and one JSON file per graph (graphs/graph_<n>.json) and per zone (zones/zone_<n>_<name>.json), plus _applied_changes.json when you sent edits.

6.2a A result you already have — POST /api/v1/sim/sxo/…

The three sxo endpoints read a .sxo you already have (from format=sxo, simulate-all with format=sxo, or the SIMIEN desktop software) without simulating anything. Send it in the field file; it must end in .sxo.

A file that isn't a SIMIEN result gets 400 SXO_UNREADABLE.

6.3 Comparing two runs

To see the effect of an edit, run the baseline and the edited version with the same inputs and compare the catalogs. Match variables by (variable_name, source_id, zone, heading, column_index) and compare only value / values. Do not compare whole variables: sxo_file and metadata.generated_at differ on every run. Unedited runs are deterministic — two baseline runs give identical numbers.

def key(v):
    return (v["variable_name"], v.get("source_id"), v.get("zone"), v.get("heading"), v.get("column_index"))

def numbers(catalog):
    return {key(v): (v.get("value"), v.get("values")) for v in catalog["variables"]}

base, edited = numbers(baseline), numbers(edited_catalog)
changed = [k for k in base if k in edited and base[k] != edited[k]]
added, removed = edited.keys() - base.keys(), base.keys() - edited.keys()

def total(catalog):
    v = next(v for v in catalog["variables"] if v["variable_name"] == "Energibehov" and v.get("zone") == "Alle soner")
    return dict(zip(v["labels"], v["values"]))["Totalt netto energibehov, sum 1-6"]

7. Run every simulation — POST /api/v1/sim/simulate-all

Same as simulate without params: it finds every simulation in the file (year, winter, …) and runs them in parallel. Evaluations (energy label, profitability) are not run here; use simulate for those.

The response is always {file}_simulations.zip: one file per successful simulation plus _results.json:

{
  "job_id": "…", "sxi_file": "building.simx", "simien_version": "8.1.1.15", "climate": "Oslo", "format": "catalog",
  "simulation_count": 2, "succeeded": 2, "failed": 0,
  "applied_changes": {"changed": 1, "applied": ["…"]},
  "simulations": [
    {"type": "wintersim", "id": "winter-simulation#159", "status": "success", "file": "….json", "variable_count": 404, "seconds": …},
    {"type": "yearsim",   "id": "year-simulation#158",   "status": "success", "file": "….json", "variable_count": 610, "seconds": …}
  ]
}

A failing simulation does not stop the others; it is listed with "status": "failed" and an error. The request only fails (502 ALL_SIMULATIONS_FAILED) if every simulation fails. Headers: X-Job-ID, X-Simulation-Count (succeeded), X-Failed-Count, X-Simulatable-Parameters-Changed.

8. Describe a building — POST /api/v1/sim/simx-metadata

Send a .simx, get a JSON file ({name}_metadata.json) for display. Nothing is simulated.

{
  "filename": "building.simx",
  "project": {"name": "…", "company": "…", "version": "8.1.1.15"},
  "climate_name": "Oslo",
  "detected_simien_version": "8_1_1_15",
  "simulation_count": 3,
  "simulations": [{"type": "yearsim", "id": "year-simulation#158", "name": "Year Simulation 1"}, …],
  "zone_count": 16, "total_area": 518.8,
  "zones": [
    {"id": "zone#6", "name": "living room and kitchen", "building_type": "Småhus", "area": 66.08, "volume": 190.31,
     "surfaces": [{"id": "roof#40", "name": "living_room_and_kitchen_89bc1d78..Face13_Roof", "uvalue": 0.1, "windows": [], "doors": []}, …],
     "ventilation_systems": […], "heating_systems": […], "cooling_systems": []}
  ],
  "central_heating_systems": […], "central_cooling_systems": […], "measures": […],
  "solar_panels": […], "wind_generators": […]
}

Areas are given once, on the zone; total_area is their sum.

9. Simulatable parameters: change numbers and re-simulate

This is how you change a .simx: you never edit the file itself. Two calls, and the same file goes in both:

POST /api/v1/sim/simulatable-parameters   file=building.simx
    → every editable number, the simulation ids, the version and source.sha256

POST /api/v1/sim/simulate                 file=building.simx  simulatable_parameters=edit.json
    → the result, with the edits applied, and X-Simulatable-Parameters-Changed: <n>

The building is never stored or modified on the server; edits are applied in memory for that one request.

9.1 The document — POST /api/v1/sim/simulatable-parameters

{
  "source": {
    "filename": "building.simx",
    "sha256": "29b6901aa58674bb…",          // identity of this building — copy it into your edits
    "simien_version": "8.1.1.15",
    "schema_version": "8.1.2.22", "schema_exact": false, "generated_at": "…", "job_id": "…"
  },
  "warnings": [],                            // parse problems in the file — read these (§11.2)
  "simulations": [{"id": "year-simulation#158", "type": "yearsim", "name": "Year Simulation 1"}, …],
  "limits": {"facades": {"uvalue": {"min": 0.01, "max": 10.0, "unit": "W/m2K"}, …}, …},
  "parameters": {
    "zones": [ { "id": "zone#6", "label": "Zone 'living room and kitchen'",
                 "facades": [ { "id": "facade#41", "label": "Facade 'living_room_and_kitchen_89bc1d78..Face2_ExteriorWall'",
                                "values": {"uvalue": 0.45, "thermal_cap": 2.4, "ext_absorption_coeff": 0.8},
                                "replaced_by_measure": {"measure": "measure#160", "measure_name": "TEK 17 upgrade",
                                                        "replacement": "facade#178"} }, … ],
                 "ventilation_systems": [ … ], "internal_gains": [ … ], … } ],
    "measures": [ { "id": "measure#160", "label": "Measure 'TEK 17 upgrade'",
                    "values": {"investment": 10000.0, "maintenance": 0.0, "lifespan": 15.0},
                    "facades": [ { "id": "facade#178", "values": {"uvalue": 0.18, …} }, … ],
                    "zones": [ … ], "windows": [ … ], … } ],
    "central_heating_systems": [ … ], "global_variables": [ … ]
  },
  "excluded": {"by_rule": {"geometry": 1050, "schema_says_string": 3004, …}}
}

The tree follows the building (zones[] → facades[] → windows[], ventilation_systems[], internal_gains[], …; plus measures[], central_heating_systems[], global_variables[]). A measure holds its own copies of the objects it changes (measures[] → facades[], windows[], zones[], …). Each object has an id, a label, a comment, and one or more of:

Only numbers inside values, profile and series can be changed. Geometry, names, ids, dates and the simulation/climate settings are not in the document, and objects cannot be added or removed.

9.2 The minimal document

Send only what you change. It has two top-level keys:

{
  "source": {"sha256": "<source.sha256 from simulatable-parameters>"},
  "parameters": [
    {"id": "<object id>", "values":  {"<attribute>": <number>}},
    {"id": "<object id>", "profile": {"<slot>": <number>}},
    {"id": "<object id>", "series":  {"<series name>": {"<position>": <number>}}}
  ]
}

A real multi-edit on the house, applied as 8 changes:

{
  "source": {"sha256": "29b6901aa58674bb704f76729ac4593255aa8defe5f0e37e10d392ce9214d446"},
  "parameters": [
    {"id": "facade#178", "values": {"uvalue": 0.10}},
    {"id": "facade#179", "values": {"uvalue": 0.10, "thermal_cap": 3.0}},
    {"id": "window#183", "values": {"uvalue": 0.6}},
    {"id": "cav#222/usage_ventilation", "profile": {"percentage_0730-0745": 80}},
    {"id": "project#29680/power_steps", "values": {"hours": 4.0}, "series": {"cost": {"2": 400.0}}},
    {"id": "facade#41", "values": {"uvalue": 0.10}}
  ]
}

It moved 200 of 610 result variables (room heating 7,038 → 6,743 kWh). The last entry, facade#41, was applied but had no effect, because an accepted measure replaces it with facade#178 (§9.6).

Windows, doors, heaters and profiles are objects with their own id: list them as their own entries, not inside their parent. Validate your document against /schemas/simulatable-parameters.schema.json before sending — it catches strings instead of numbers, missing ids and short profiles; the server additionally checks that each id exists, the attribute is editable, and the value is inside limits.

9.3 Send it back

curl -X POST "$API/simulate" -H "$AUTH" \
  -F "file=@building.simx" \
  -F "simulatable_parameters=@edit.json;type=application/json" \
  -F "params=year-simulation#158" -F "simien_version=8.1.1.15" -F "format=catalog" -o edited.json

The same field works on simulate-all. Sending the full document back unchanged is valid and changes nothing (changed = 0); sending it with one number edited is the same as sending a minimal document with that number.

9.4 Profiles and series

{"id": "cav#222/usage_ventilation", "profile": {"percentage_0730-0745": 80}}   // by slot name
{"id": "cav#222/usage_ventilation", "profile": {"30": 80}}                     // by slot number (30 = 07:30–07:45)
{"id": "cav#222/usage_ventilation", "profile": [null, null, …, 80, …, null]}   // all 96, null = unchanged
{"id": "project#29680/power_steps", "series": {"cost": {"2": 400.0}}}          // by position
{"id": "project#…/monthly_el_price", "series": {"import_price": {"mar": 3.4}}} // by index name, where the file has monthly prices

A short array (e.g. 95 values) is rejected rather than guessed at.

9.5 Check what was changed

• X-Simulatable-Parameters-Changed counts changed values: one attribute = 1, one profile slot = 1, so setting a whole profile counts 96. 0 means your numbers equalled the file (a wrong id would have been a 400).
• The list of changes comes with the result:

{
  "changed": 3,
  "applied": [
    {"address": "facade#178", "attribute": "uvalue", "old": 0.18, "new": 0.1,
     "label": "Facade 'living_room_and_kitchen_89bc1d78..Face2_ExteriorWall'", "active": true},
    {"address": "cav#222/usage_ventilation", "attribute": "percentage_0730-0745", "old": 100.0, "new": 80.0,
     "position": 30, "label": "Ventilation system 'CAV - Constant Air Volume 1', ventilation profile", "active": true},
    {"address": "facade#41", "attribute": "uvalue", "old": 0.45, "new": 0.1,
     "label": "Facade 'living_room_and_kitchen_89bc1d78..Face2_ExteriorWall'", "active": true,
     "replaced_by_measure": {"measure": "measure#160", "measure_name": "TEK 17 upgrade", "replacement": "facade#178"}}
  ]
}

Each entry names the object (label) and says whether it can move the result: active: false or a replaced_by_measure means the edit was written but the simulation doesn't use that object (§9.6). A repairs list is added only when the file had to be fixed before simulating — an attribute repeated on one tag (e.g. "line 539: removed duplicate attribute language"), or a wrong encoding declaration. Repairs are not your changes.

9.6 Check the effect

"Applied" means the number was written into the file; it does not guarantee the result moves. Compare against a baseline run (§6.3). Real examples:

9.7 What gets rejected

All of these return 400 before anything is simulated, with every problem listed at once in error.message.problems. A file that isn't a SIMIEN project at all returns 400 FILE_UNREADABLE instead.

9.8 Complete example (Python)

import json, requests

API  = "https://central-api.simien.no/api/v1/sim"
AUTH = {"Authorization": "Bearer " + API_KEY}
DATA = open("building.simx", "rb").read()

def upload():                                   # the same bytes every time
    return {"file": ("building.simx", DATA, "application/octet-stream")}

def post(path, **kw):
    r = requests.post(f"{API}{path}", headers=AUTH, timeout=300, **kw)
    if r.status_code >= 400:
        err = r.json()["error"]
        raise RuntimeError(f"{err['code']}: {err['message']} (request {err['request_id']})")
    return r

# 1. what can I change, and what can I run?
doc = post("/simulatable-parameters", files=upload()).json()
sha, version = doc["source"]["sha256"], doc["source"]["simien_version"]
sim = next(s["id"] for s in doc["simulations"] if s["type"] == "yearsim")

# 2. every facade the simulation actually uses (skip inactive ones and ones a measure replaces)
def walk(node):
    if isinstance(node, dict):
        yield node
        for v in node.values():
            yield from walk(v)
    elif isinstance(node, list):
        for v in node:
            yield from walk(v)

facades = [n for n in walk(doc["parameters"])
           if str(n.get("id", "")).startswith("facade#") and "uvalue" in n.get("values", {})
           and n.get("active") is not False and not n.get("replaced_by_measure")]

# 3. baseline and edited run
form = {"params": sim, "simien_version": version, "format": "catalog"}
baseline = post("/simulate", files=upload(), data=form).json()

edit = {"source": {"sha256": sha},
        "parameters": [{"id": f["id"], "values": {"uvalue": 0.10}} for f in facades]}
r = post("/simulate", data=form,
         files={**upload(), "simulatable_parameters": ("edit.json", json.dumps(edit), "application/json")})
edited = r.json()
print(r.headers["X-Simulatable-Parameters-Changed"], "values changed")

# 4. the effect on net energy demand
def energy(catalog):
    v = next(v for v in catalog["variables"] if v["variable_name"] == "Energibehov" and v.get("zone") == "Alle soner")
    return dict(zip(v["labels"], v["values"]))

before, after = energy(baseline), energy(edited)
for label in before:
    if before[label] != after[label]:
        print(f"{label}: {before[label]} → {after[label]} kWh")

10. Versions and locations

• GET /api/v1/sim/versions (no parameters) → {"count": 92, "versions": [{"version": "8_1_2_22", "core_version": "8.1.2.22", "platform": "x86", "build_type": "release"}, …]}, newest first. Pass version or core_version as simien_version.
• GET /api/v1/sim/locations (no parameters) → {"count": 359, "locations": ["Bergen", "Bodø", …, "Oslo", …]}. Pass a name exactly as listed.

11. Errors and troubleshooting

11.1 Error codes

11.2 Common problems

12. Rules for automated clients and LLM agents

Follow these exactly; they cover every mistake seen in testing.

1. Base path https://central-api.simien.no/api/v1/sim/; send Authorization: Bearer <key> on every call.
2. The building is normally a .simx (encrypted). Send it as it is; don't decrypt it first. Change it only through simulatable parameters, never by editing XML. A plaintext .sxi works the same way.
3. Start with POST /simulatable-parameters on the building. Take source.sha256, source.simien_version and simulations[].id from it — never invent ids or versions.
4. File requests are multipart/form-data: the building in field file; edits as a second file field simulatable_parameters (JSON), never a text field.
5. params is exactly one simulation id; use simulate-all for all of them.
6. Use a timeout of at least 120 s for simulate (more for simulate-all); results can be 10+ MB.
7. Prefer format=catalog when you need numbers and the list of applied changes.
8. Edits: a minimal document {"source": {"sha256": …}, "parameters": [{"id": …, "values": {…}}]}. Only change numbers inside values, profile, series; keep ids exactly; stay inside limits; skip objects with "active": false; for objects with replaced_by_measure, edit the replacement id instead. Validate against /schemas/simulatable-parameters.schema.json first.
9. Send the edits with the same building file they were made from.
10. After an edited run, check X-Simulatable-Parameters-Changed and applied_changes; then compare numbers with a baseline run (match variables by name, source, zone, heading, column; ignore sxo_file) to confirm an effect.
11. "Applied" is not "effective": never report an edit's effect without comparing against a baseline run. If an applied edit moves nothing, tell the user which of the causes in §9.6 applies instead of retrying.
12. On an error, branch on error.code. For PARAMETERS_REJECTED fix every entry in error.message.problems in one go. Don't retry a 400 unchanged.
13. On 429 wait retry_after seconds; on 502/504 retry with backoff.
14. If simulatable-parameters returns warnings, the simulation may still work (repeated attributes are repaired automatically and listed under repairs); if it fails with "not well-formed XML", report the warning to the user instead of retrying.