{"openapi":"3.1.0","info":{"title":"Simien Central API","description":"\nRun SIMIEN building-energy simulations and edit simulatable building parameters over HTTP.\n\nFor detailed usage instructions, see the [API Guide](/) ([Markdown version](/guide.md) for tools and LLMs).\n\n## For LLM agents and code generators\n\n- [`/llms.txt`](/llms.txt): index of machine-readable resources\n- [`/guide.md`](/guide.md): the full guide, including rules for agents\n- [`/schemas/simulatable-parameters.schema.json`](/schemas/simulatable-parameters.schema.json):\n  JSON Schema for the `simulatable_parameters` document (also in this spec as `SimulatableParametersDocument`)\n\n## Authentication\n\nAll authenticated endpoints require a Bearer token:\n\n```\nAuthorization: Bearer sk_live_<identifier>_<secret>\n```\n\nClick the 🔓 **Authorize** button to enter your API key.\n\n## Getting an API Key\n\nTo request an API key, use our contact form:\n[https://simien.no/kontakt-oss/](https://simien.no/kontakt-oss/)\n\n## Terms\n\n- [License user terms](https://simien.no/wp-content/uploads/Bruksvilkar-Simien-2026.pdf)\n- [Privacy policy](https://simien.no/personvernerklaering/)\n\n## Rate limits\n\nLimits are per client IP. Rate-limited endpoints return `X-RateLimit-Limit`, `X-RateLimit-Remaining`\nand `X-RateLimit-Reset` (Unix time) on every response; a `429` carries `Retry-After` in seconds.\n\n## Errors\n\nEvery error is `{\"error\": {\"code\", \"message\", \"request_id\"}}`. Branch on `code`:\n\n| Code | Meaning |\n|---|---|\n| `MISSING_API_KEY` | No Authorization: Bearer header was sent (401) |\n| `INVALID_API_KEY` | The API key is not valid (401) |\n| `API_KEY_EXPIRED` | The API key has expired (401) |\n| `CUSTOMER_SUSPENDED` | The account is suspended (403) |\n| `VALIDATION_ERROR` | A required field is missing or has the wrong type; see details (422) |\n| `RATE_LIMIT_EXCEEDED` | Too many requests; wait Retry-After seconds (429) |\n| `INVALID_REQUEST` | The simulation service rejected the request, e.g. a bad version or file (400) |\n| `SIMX_DECRYPT_FAILED` | The .simx file could not be decrypted (400) |\n| `SIMX_KEYS_UNAVAILABLE` | The .simx decryption keys could not be loaded; retry later (502) |\n| `FILE_UNREADABLE` | The building file could not be read (400) |\n| `PARAMETERS_INVALID` | The simulatable-parameters document is not valid JSON or has no source.sha256 (400) |\n| `PARAMETERS_WRONG_BUILDING` | The simulatable-parameters document was made from a different building (400) |\n| `PARAMETERS_REJECTED` | One or more changes cannot be applied; see message.problems (400) |\n| `SIMULATION_REJECTED` | The simulation engine rejected the file or settings, e.g. an unknown location (400) |\n| `SXO_UNREADABLE` | The uploaded file could not be read as a SIMIEN .sxo result (400) |\n| `FILE_TOO_LARGE` | The uploaded file is larger than the size limit (413) |\n| `ALL_SIMULATIONS_FAILED` | Every simulation in simulate-all failed (502) |\n| `SIMULATION_TIMEOUT` | The simulation engine did not respond in time; retry later (504) |\n| `SIMULATION_SERVICE_UNAVAILABLE` | The simulation engine is unavailable; retry later (502) |\n| `UPSTREAM_UNAVAILABLE` | The simulation service could not be reached; retry later (502) |\n| `UPSTREAM_ERROR` | The simulation service failed; retry later (502) |\n| `UPSTREAM_AUTH_FAILED` | The gateway could not authenticate with the simulation service; contact us (502) |\n| `INTERNAL_ERROR` | Unexpected error; contact us with the request_id (500) |\n    ","termsOfService":"https://simien.no/wp-content/uploads/Bruksvilkar-Simien-2026.pdf","version":"1.0.0"},"paths":{"/healthz":{"get":{"tags":["health"],"summary":"Healthz","description":"Comprehensive health check endpoint for Azure App Service.\n\nReturns service status, configuration, and performance metrics.\nUsed by Azure for health monitoring and load balancing.","operationId":"healthz","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/sim/simulate":{"post":{"tags":["sim"],"summary":"Run one simulation","description":"Run a SIMIEN simulation and get the results.\n\nAccepts a .simx building file (a plaintext .sxi also works) and returns the result as a download.\n\nParameters:\n- file: Your .simx building file (a plaintext .sxi also works)\n- params: The simulation id to run, e.g. 'aarsim#23'. Exactly one - use /simulate-all to run every simulation in the file.\n- simien_version: SIMIEN core version - underscores or dots both work, e.g. '8_1_2_6' or '8.1.2.6'. SIMIEN 7 is not supported.\n- location: Climate location name (optional) - e.g. 'Oslo'. If provided, replaces the climate in your file. See GET /api/v1/sim/locations.\n- format: Output format (optional) - 'sxo' (default), 'catalog' (JSON catalog), or 'zip' (SXO + parsed exports)\n- simulatable_parameters: Optional. The document from POST /api/v1/sim/simulatable-parameters with your edits - change a u-value and re-run without the desktop tool.\n\nReturns:\nThe result as a download, named {file}_{version}_{sim}_{climate}_{timestamp}.\n\nResponse Headers:\n- X-Job-ID: Unique job identifier\n- X-Simien-Version: The SIMIEN version that was run\n- X-Climate: The climate the result used, when known\n- X-Simulatable-Parameters-Changed: How many values your edits changed, when simulatable_parameters was sent\n\nEditing simulatable parameters:\n1. POST /api/v1/sim/simulatable-parameters with your file\n2. Change numbers inside values, series or profile - nothing else\n3. Send the same file and the edited document back here as simulatable_parameters\n\nYou can send the whole document back, or only what you changed. A node is found by its id,\nso the shortest valid document is:\n\n    {\n      \"source\": {\"sha256\": \"7d7d041e...\"},\n      \"parameters\": [{\"id\": \"facade#1\", \"values\": {\"uvalue\": 0.10}}]\n    }\n\nOnly list what you change. source.sha256 ties the document to the exact file it was\nmade from, so submitting it with a different building is rejected with a 400\n(code PARAMETERS_WRONG_BUILDING). The document's JSON Schema is SimulatableParametersDocument,\nalso at /schemas/simulatable-parameters.schema.json.\n\nApplied changes: with format=catalog the result has a top-level applied_changes object; with\nformat=zip it contains _applied_changes.json. Both list every change as\n{address, attribute, old, new, label, active} (plus position for arrays, and replaced_by_measure when\nan accepted measure's copy of the object is simulated instead, so the edit has no effect on year/winter\nsimulations). A repairs list appears when the file was fixed before simulating (e.g. a repeated\nattribute removed). format=sxo only carries the X-Simulatable-Parameters-Changed count.\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: 1-5 s for format=sxo, 2-15 s for catalog, 5-40 s for zip; use a client timeout of at least 120 s","operationId":"simulate","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_simulate"}}},"required":true},"responses":{"200":{"description":"The result as a download, named {file}_{version}_{sim}_{climate}_{timestamp}. The content type follows `format`.","headers":{"X-Job-ID":{"description":"Id of this job in the simulation service; quote it to support","schema":{"type":"string"}},"X-Simien-Version":{"description":"SIMIEN version that was run","schema":{"type":"string"}},"X-Climate":{"description":"Climate the result used, when known","schema":{"type":"string"}},"X-Simulatable-Parameters-Changed":{"description":"How many values the simulatable_parameters document changed (only when it was sent)","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"(format=sxo) raw .sxo result XML"},"application/json":{"schema":{"properties":{"metadata":{"type":"object"},"variables":{"items":{"type":"object"},"type":"array"},"applied_changes":{"properties":{"changed":{"type":"integer","description":"Number of values changed"},"applied":{"items":{"properties":{"address":{"type":"string","description":"Object id, e.g. facade#5"},"attribute":{"type":"string","description":"Attribute (or profile slot) that changed"},"old":{"type":"number"},"new":{"type":"number"},"position":{"description":"Series index name or profile slot, for array edits"},"label":{"type":"string","description":"The object's label, e.g. \"Facade 'South'\""},"active":{"type":"boolean","description":"false when the object is marked inactive: applied, but no effect"},"replaced_by_measure":{"properties":{"measure":{"type":"string"},"measure_name":{"type":"string"},"replacement":{"type":"string"}},"type":"object","description":"Present when an accepted measure's copy of the object is simulated instead (year/winter simulations): the edit has no effect there; edit the replacement"}},"type":"object","required":["address","attribute","old","new"]},"type":"array"},"repairs":{"items":{"type":"string"},"type":"array","description":"File repairs made before simulating, e.g. a repeated attribute removed or a wrong encoding declaration corrected; not your changes"}},"type":"object","description":"Present only when simulatable_parameters was sent"}},"type":"object","description":"Variable catalog of the simulation result (format=catalog)"}},"application/zip":{"schema":{"type":"string","format":"binary"},"example":"(format=zip) {file}_{version}_{sim}_{climate}_{timestamp}_export.zip: .sxo + parsed exports, plus _applied_changes.json when simulatable_parameters was sent"}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/locations":{"get":{"tags":["sim"],"summary":"List climate locations","description":"Get list of available climate locations.\n\nNo parameters - the list is the same for every SIMIEN version.\n\nReturns:\n- locations: List of available location names (sorted alphabetically), including\n  Norwegian names with ø/æ/å. Pass one as the location field of /simulate or /simulate-all.\n- count: Total number of locations\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Typical time: under 1 s","operationId":"list_locations","responses":{"200":{"description":"Successful Response","headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsResponse"}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/versions":{"get":{"tags":["sim"],"summary":"List the SIMIEN versions that can be run","description":"Get the SIMIEN core versions that can be run.\n\nNo parameters.\n\nReturns:\n- versions: Newest first. Each entry has:\n  - version: the value to pass as simien_version to /simulate (the dotted core_version works too)\n  - core_version: the same build in dotted form\n  - platform (x86, linux) and build_type (release, debug)\n- count: Number of versions\n\nSIMIEN 7 is not supported.\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Typical time: under 1 s","operationId":"list_versions","responses":{"200":{"description":"Successful Response","headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionsResponse"}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/simulate-all":{"post":{"tags":["sim"],"summary":"Run every simulation in the file (ZIP)","description":"Batch simulation endpoint - Runs every simulation found in the file and returns the results as a ZIP.\n\nThis endpoint:\n1. Finds every simulation in the uploaded file (yearsim, wintersim, evalsim, ...). Evaluations such as\n   energy label (energymark26) and profitability (profitsim) are not run here; run them one at a time\n   with /simulate.\n2. Uses the SIMIEN version you pass, or the one recorded in the file\n3. Runs the simulations concurrently\n4. Returns a ZIP with one file per simulation, plus a _results.json manifest\n\nParameters:\n- file: Your .simx building file (a plaintext .sxi also works)\n- location: Climate location name (optional) - e.g. 'Oslo'. If provided, replaces the climate in your file. See GET /api/v1/sim/locations.\n- simien_version: SIMIEN core version (optional) - e.g. '8_1_2_6' or '8.1.2.6'. If not provided, auto-detected from the file. An invalid version returns 400.\n- format: 'catalog' (default) for a JSON catalog per simulation, or 'sxo' for the raw .sxo per simulation. The response is always a ZIP.\n- simulatable_parameters: Optional. The document from POST /api/v1/sim/simulatable-parameters with your edits, applied before every simulation runs. See /simulate for the format.\n\nReturns:\napplication/zip named {file}_simulations.zip, containing one file per successful simulation\nand _results.json recording the status of each:\n\n    {\n      \"job_id\": \"...\",\n      \"sxi_file\": \"building.simx\",\n      \"simien_version\": \"8_1_2_6\",\n      \"climate\": \"Oslo\",\n      \"format\": \"catalog\",\n      \"applied_changes\": {\"changed\": 1, \"applied\": [...]},\n      \"simulation_count\": 4,\n      \"succeeded\": 4,\n      \"failed\": 0,\n      \"simulations\": [\n        {\"type\": \"yearsim\", \"id\": \"aarsim#23\", \"status\": \"success\", \"file\": \"...\", \"variable_count\": 200}\n      ]\n    }\n\nResponse Headers:\n- X-Job-ID: Unique job identifier\n- X-Simulation-Count: Number of simulations that succeeded\n- X-Failed-Count: Number of failed simulations\n- X-Simulatable-Parameters-Changed: How many values your edits changed, when simulatable_parameters was sent\n\nNotes:\n- A failed simulation does not sink the others; it is recorded in _results.json. The request only fails if every simulation failed.\n- Results are no longer merged into one catalog - each simulation keeps its own file.\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 20 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: a few seconds per simulation (they run in parallel)","operationId":"simulate_all","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_simulate_all"}}},"required":true},"responses":{"200":{"description":"{file}_simulations.zip: one file per successful simulation (catalog JSON or .sxo, per `format`) plus _results.json with each simulation's status and, when simulatable_parameters was sent, the applied changes under `applied_changes`. Evaluations (energy label, profitability) are not run here; use /simulate.","headers":{"X-Job-ID":{"description":"Id of this job in the simulation service; quote it to support","schema":{"type":"string"}},"X-Simulation-Count":{"description":"Number of simulations that succeeded","schema":{"type":"integer"}},"X-Failed-Count":{"description":"Number of simulations that failed","schema":{"type":"integer"}},"X-Simulatable-Parameters-Changed":{"description":"How many values the simulatable_parameters document changed (only when it was sent)","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/simulatable-parameters":{"post":{"tags":["sim"],"summary":"List the editable numbers in a building","description":"Get the simulatable parameters (every editable number) of a .simx building file (a plaintext .sxi also works).\n\nThis is the first half of a parametric workflow: edit a number in the returned document,\nthen send it back with the same file to POST /api/v1/sim/simulate (or /simulate-all) as\nsimulatable_parameters. This is how a .simx is changed: it is decrypted only inside the service, never on your side.\n\nParameters:\n- file: Your .simx building file (a plaintext .sxi also works)\n- download: true to get the document as a .json file attachment (default: inline JSON)\n\nReturns:\n    {\n      \"source\": {\n        \"filename\": \"building.simx\",\n        \"sha256\": \"4bc4a1...\",         // hash of the file, ties the document to this building\n        \"simien_version\": \"8.1.0.29\",\n        \"schema_version\": \"8.1.2.16\",\n        \"schema_exact\": false,\n        \"job_id\": \"...\"\n      },\n      \"simulations\": [{\"id\": \"aarsim#12\", \"type\": \"yearsim\", \"name\": \"...\"}],\n      \"limits\": {\"facades\": {\"uvalue\": {\"min\": 0.05, \"max\": 6.0, \"unit\": \"W/m²K\"}}},\n      \"parameters\": {\n        \"facades\": [\n          {\"id\": \"fasade#3\", \"label\": \"Facade in zone 'a'\",\n           \"values\": {\"uvalue\": 0.18, \"thermal_cap\": 10.0}}\n        ],\n        \"usage_profiles\": [\n          {\"id\": \"internlaster#8/usage_person\", \"kind\": \"person\",\n           \"interval_minutes\": 15, \"unit\": \"percent\", \"profile\": [100.0, ...]}\n        ]\n      },\n      \"excluded\": {\"by_rule\": {\"geometry\": 42, \"date\": 4}, \"numeric_not_in_registry\": 310}\n    }\n\nNotes:\n- simulations lists every id you can pass as params to /simulate, including evaluations\n  (energy label, profitability).\n- An object an accepted measure replaces carries \"replaced_by_measure\": {\"measure\", \"measure_name\",\n  \"replacement\"}. Year and winter simulations use the replacement, so edit that object instead.\n- Only numbers inside values (series / profile for arrays) are editable. id and label are context.\n- Geometry (areas, orientations, inclinations) is deliberately not editable; see /simx-metadata.\n- excluded reports what was left out and why.\n\nResponse Headers:\n- X-Job-ID: Unique job identifier\n- X-Simulatable-Parameter-Objects: Number of editable objects in the document\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: under 1 s","operationId":"get_simulatable_parameters","parameters":[{"name":"download","in":"query","required":false,"schema":{"type":"boolean","description":"Return the simulatable parameters as a .json file download instead of an inline response","default":false,"title":"Download"},"description":"Return the simulatable parameters as a .json file download instead of an inline response"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_get_simulatable_parameters"}}}},"responses":{"200":{"description":"Every editable number in the building. Inline JSON, or a {name}_simulatable_parameters.json attachment with download=true. Edit it (or build a minimal document, see SimulatableParametersDocument) and send it to /simulate as simulatable_parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","properties":{"filename":{"type":"string"},"sha256":{"type":"string","description":"Identity of this building; copy it unchanged"},"simien_version":{"type":"string","description":"Version recorded in the file"},"schema_version":{"type":"string"},"schema_exact":{"type":"boolean"},"generated_at":{"type":"string"},"job_id":{"type":"string"}}},"warnings":{"type":"array","items":{"type":"string"}},"simulations":{"type":"array","description":"Every id you can pass as `params` to /simulate, including evaluations (energy label, profitability)","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"}}}},"limits":{"type":"object","description":"limits[collection][attribute] = {min, max, unit}"},"parameters":{"type":"object","description":"The editable tree: zones, measures, central_heating_systems, global_variables, ... Objects may carry `active: false` (ignored by the simulation) or `replaced_by_measure` (an accepted measure's copy is simulated instead)."},"excluded":{"type":"object"},"derivation":{"type":"object"}}}}},"headers":{"X-Job-ID":{"description":"Id of this job in the simulation service; quote it to support","schema":{"type":"string"}},"X-Simulatable-Parameter-Objects":{"description":"Number of editable objects in the document","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","content":{"application/json":{"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","content":{"application/json":{"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","content":{"application/json":{"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","content":{"application/json":{"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","content":{"application/json":{"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","content":{"application/json":{"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","content":{"application/json":{"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","content":{"application/json":{"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/simx-metadata":{"post":{"tags":["sim"],"summary":"Describe a building (.simx)","description":"Decrypt a .simx file and return metadata extracted from the decrypted .sxi.\n\nParameters:\n- file: The encrypted .simx file\n\nReturns the metadata as a downloadable JSON file.\n\nResponse Headers:\n- X-Job-ID: Unique job identifier\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: under 1 s","operationId":"get_simx_metadata","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_get_simx_metadata"}}},"required":true},"responses":{"200":{"description":"{name}_metadata.json: zones, areas, systems and the simulation ids in the building","headers":{"X-Job-ID":{"description":"Id of this job in the simulation service; quote it to support","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"filename":{"type":"string"},"project":{"type":"object"},"climate_name":{"type":"string"},"detected_simien_version":{"type":"string"},"simulation_count":{"type":"integer"},"simulations":{"items":{"type":"object"},"type":"array"},"zone_count":{"type":"integer"},"total_area":{"type":"number"},"zones":{"items":{"type":"object"},"type":"array"}},"type":"object"}}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/sxo/parse":{"post":{"tags":["sim"],"summary":"Parse a result (.sxo) into JSON and CSV (ZIP)","description":"Parse a .sxo result and export everything in it.\n\nParameters:\n- file: A .sxo result file\n\nReturns:\nA ZIP with JSON files of the parsed data, CSV files of its tables, graphs, bar charts\nand hourly values, and the variable catalog. The same exports /simulate gives with format=zip.\n\nResponse Headers:\n- X-Export-Type: full\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: 5-40 s for a 10 MB result","operationId":"sxo_parse","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_sxo_parse"}}},"required":true},"responses":{"200":{"description":"A ZIP of the parsed result: JSON, CSV (tables, graphs, bar charts, hourly values) and the variable catalog","headers":{"X-Export-Type":{"description":"full, catalog or info","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/sxo/catalog":{"post":{"tags":["sim"],"summary":"Variable catalog of a result (.sxo)","description":"Build the variable catalog of a .sxo result.\n\nParameters:\n- file: A .sxo result file\n\nReturns:\nThe catalog as a JSON download: every variable in the result with its metadata\n(name, type, source, zone, ...). The same catalog /simulate gives with format=catalog.\n\nResponse Headers:\n- X-Export-Type: catalog\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: 1-5 s for a 10 MB result","operationId":"sxo_catalog","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_sxo_catalog"}}},"required":true},"responses":{"200":{"description":"The variable catalog of the result, as a JSON download","headers":{"X-Export-Type":{"description":"full, catalog or info","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"metadata":{"type":"object"},"variables":{"items":{"type":"object"},"type":"array"}},"type":"object"}}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/sxo/info":{"post":{"tags":["sim"],"summary":"Structure and contents of a result (.sxo)","description":"Describe what a .sxo result contains.\n\nParameters:\n- file: A .sxo result file\n\nReturns:\nA JSON download with the file's metadata (project, version, simulation type, ...),\nits zones with element counts, the lists of tables, graphs and charts, and error and\nwarning counts.\n\nResponse Headers:\n- X-Export-Type: info\n\nRequires valid API key authentication.\n\n**Limits**\n\n- Rate limit: 120 requests per minute per client IP\n- Files up to 50 MB (larger: 413 FILE_TOO_LARGE)\n- Typical time: 1-5 s for a 10 MB result","operationId":"sxo_info","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_sxo_info"}}},"required":true},"responses":{"200":{"description":"Metadata, zones and element lists of the result, as a JSON download","headers":{"X-Export-Type":{"description":"full, catalog or info","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}},"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request needs fixing. Codes: INVALID_REQUEST, SIMX_DECRYPT_FAILED, FILE_UNREADABLE, PARAMETERS_INVALID, PARAMETERS_WRONG_BUILDING, PARAMETERS_REJECTED, SIMULATION_REJECTED, SXO_UNREADABLE. `message` may be an object with `problems` and `hint`.","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PARAMETERS_REJECTED","message":{"code":"PARAMETERS_REJECTED","message":"The parameters file contains changes that cannot be applied","job_id":"09b8c1e0-...","problems":["facade#5.uvalue: 20.0 is outside the allowed range 0.01..10.0"],"problem_count":1},"request_id":"3f2a9c0e8b7d4f1a"}}}}},"413":{"description":"The uploaded file is larger than the limit (50 MB by default). Code: FILE_TOO_LARGE","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"FILE_TOO_LARGE","message":"The file is larger than the 50 MB limit","request_id":"3f2a9c0e8b7d4f1a"}}}}},"401":{"description":"Missing, invalid or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, API_KEY_EXPIRED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_API_KEY","message":"Invalid API key","request_id":"3f2a9c0e8b7d4f1a"}}}}},"403":{"description":"Account suspended. Code: CUSTOMER_SUSPENDED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"CUSTOMER_SUSPENDED","message":"Customer suspended","request_id":"3f2a9c0e8b7d4f1a"}}}}},"422":{"description":"A required field is missing or has the wrong type. Code: VALIDATION_ERROR; see `details`","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","request_id":"3f2a9c0e8b7d4f1a"}}}}},"429":{"description":"Rate limit exceeded. Code: RATE_LIMIT_EXCEEDED; wait `Retry-After` seconds","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests (limit: 20 per 1 minute). Please try again later.","request_id":"3f2a9c0e8b7d4f1a"}}}}},"502":{"description":"The simulation service or engine is unavailable or failed; retry later. Codes: UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, SIMULATION_SERVICE_UNAVAILABLE, ALL_SIMULATIONS_FAILED","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Simulation service unavailable","request_id":"3f2a9c0e8b7d4f1a"}}}}},"504":{"description":"The simulation engine did not respond in time; retry later. Code: SIMULATION_TIMEOUT","headers":{"X-Request-Id":{"description":"Id of this request; quote it to support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SIMULATION_TIMEOUT","message":"SCRA did not respond within 600s.","request_id":"3f2a9c0e8b7d4f1a"}}}}}},"security":[{"BearerAuth":[]}]}},"/api/v1/sim/health":{"get":{"tags":["sim"],"summary":"Simulation service health and SIMIEN versions","description":"Get SIMIEN API health status and available versions.\n\nNo authentication required.","operationId":"get_sim_health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_decrypt_simx":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"The encrypted .simx file"}},"type":"object","required":["file"],"title":"Body_decrypt_simx"},"Body_get_simulatable_parameters":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Your .simx building file (encrypted). A plaintext .sxi also works."}},"type":"object","required":["file"],"title":"Body_get_simulatable_parameters"},"Body_get_simx_metadata":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"The encrypted .simx file to extract metadata from"}},"type":"object","required":["file"],"title":"Body_get_simx_metadata"},"Body_simulate":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Your building file: a .simx (encrypted, decrypted only inside the service). A plaintext .sxi also works."},"params":{"type":"string","title":"Params","description":"Simulation id to run, e.g. 'aarsim#23' (exactly one)","default":"aarsim#23"},"simien_version":{"type":"string","title":"Simien Version","description":"SIMIEN core version - underscores or dots both work, e.g. '8_1_2_6' or '8.1.2.6'"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Climate location name (optional) - e.g., 'Oslo'. If omitted, the climate in the file is used."},"format":{"type":"string","title":"Format","description":"Output format (optional) - 'sxo' (default), 'catalog' (JSON catalog), or 'zip' (SXO + parsed exports)","default":"sxo"},"simulatable_parameters":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"Simulatable Parameters","description":"Optional edited simulatable-parameters document from POST /api/v1/sim/simulatable-parameters"}},"type":"object","required":["file","simien_version"],"title":"Body_simulate"},"Body_simulate_all":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Your building file: a .simx (encrypted, decrypted only inside the service). A plaintext .sxi also works."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Climate location name (optional) - e.g., 'Oslo'. If omitted, the climate in the file is used."},"simien_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Simien Version","description":"SIMIEN core version (optional) - e.g. '8_1_2_6' or '8.1.2.6'. Auto-detected from the file if omitted."},"format":{"type":"string","title":"Format","description":"What goes inside the ZIP - 'catalog' (default, a JSON catalog per simulation) or 'sxo' (the raw .sxo per simulation)","default":"catalog"},"simulatable_parameters":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"Simulatable Parameters","description":"Optional edited simulatable-parameters document from POST /api/v1/sim/simulatable-parameters"}},"type":"object","required":["file"],"title":"Body_simulate_all"},"Body_sxo_catalog":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"A .sxo result file, e.g. from /simulate with format=sxo"}},"type":"object","required":["file"],"title":"Body_sxo_catalog"},"Body_sxo_info":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"A .sxo result file, e.g. from /simulate with format=sxo"}},"type":"object","required":["file"],"title":"Body_sxo_info"},"Body_sxo_parse":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"A .sxo result file, e.g. from /simulate with format=sxo"}},"type":"object","required":["file"],"title":"Body_sxo_parse"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine-readable error code","examples":["PARAMETERS_REJECTED"]},"message":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}],"title":"Message","description":"Human-readable message. For input problems reported by the simulation service this is an object, e.g. {\"code\", \"message\", \"problems\", \"hint\"}."},"request_id":{"type":"string","title":"Request Id","description":"Same as the X-Request-Id header; quote it to support"},"doc_url":{"type":"string","title":"Doc Url","description":"Link to this code's explanation in the guide","examples":["https://simien-central-api.azurewebsites.net/#err-PARAMETERS_REJECTED"]},"details":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Details","description":"Field errors, only for VALIDATION_ERROR"},"retry_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After","description":"Seconds to wait, only for RATE_LIMIT_EXCEEDED"}},"type":"object","required":["code","message","request_id","doc_url"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"LocationsResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of locations","examples":[359]},"locations":{"items":{"type":"string"},"type":"array","title":"Locations","description":"Location names, sorted; pass one as `location`","examples":[["Bergen","Bodø","Oslo","Trondheim"]]}},"type":"object","required":["count","locations"],"title":"LocationsResponse"},"VersionEntry":{"properties":{"version":{"type":"string","title":"Version","description":"Pass this as `simien_version`","examples":["8_1_2_16"]},"core_version":{"type":"string","title":"Core Version","description":"The same build in dotted form (also accepted)","examples":["8.1.2.16"]},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","examples":["x86"]},"build_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Build Type","examples":["release"]}},"type":"object","required":["version","core_version"],"title":"VersionEntry"},"VersionsResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of versions","examples":[86]},"versions":{"items":{"$ref":"#/components/schemas/VersionEntry"},"type":"array","title":"Versions","description":"Newest first"}},"type":"object","required":["count","versions"],"title":"VersionsResponse"},"SimulatableParametersDocument":{"title":"Simulatable parameters document","description":"The document sent as the `simulatable_parameters` file on POST /api/v1/sim/simulate and /simulate-all. Either the full document returned by POST /api/v1/sim/simulatable-parameters with numbers edited, or a minimal document listing only the changes. Must be sent together with the same building file it was made from. Passing this schema does not guarantee acceptance: ids must exist in the building, attribute names must be editable on that object, and values must be inside `limits` — the server checks those and answers 400 with every problem listed.","type":"object","required":["source","parameters"],"properties":{"source":{"type":"object","description":"Only `sha256` is read; other keys from the full document are ignored.","required":["sha256"],"properties":{"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Copy exactly from `source.sha256` of the simulatable-parameters response for this building."}}},"parameters":{"description":"The edits. Minimal form: a flat array of objects, one per object you change. Full form: the `parameters` tree from the simulatable-parameters response. Objects are matched by `id` wherever they appear, so any nesting works; if an id appears twice, the last one wins.","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/SimulatableParametersDocument/$defs/object"}},{"type":"object","description":"The full tree (zones, measures, central_heating_systems, global_variables, ...)."}]}},"$defs":{"number_or_null":{"type":["number","null"],"description":"null leaves that position unchanged."},"object":{"type":"object","description":"One object in the building. Only `values`, `profile` and `series` are read as edits; `label`, `comment`, `kind`, `unit`, `interval_minutes`, `active`, `index` and `replaced_by_measure` are ignored. Any other key (e.g. `windows`) is read as nested objects.","properties":{"id":{"type":"string","minLength":1,"description":"Copied exactly from the full document, e.g. `facade#5`, `window#1`, `cav#58/usage_ventilation`."},"values":{"type":"object","description":"Attribute -> new number. Attribute names exactly as in this object's `values` in the full document.","additionalProperties":{"type":"number"},"examples":[{"uvalue":0.18}]},"profile":{"description":"A daily profile: the full 96 quarter-hour values (null = unchanged), or an object naming only the slots to change, by number (\"0\"-\"95\") or by name (\"percentage_0730-0745\").","oneOf":[{"type":"array","minItems":96,"maxItems":96,"items":{"$ref":"#/components/schemas/SimulatableParametersDocument/$defs/number_or_null"}},{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SimulatableParametersDocument/$defs/number_or_null"},"examples":[{"percentage_0730-0745":80}]}]},"series":{"type":"object","description":"Series name -> the full array (same length as in the full document; null = unchanged), or an object naming only the positions to change, by index name (\"mar\") or number.","additionalProperties":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/SimulatableParametersDocument/$defs/number_or_null"}},{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SimulatableParametersDocument/$defs/number_or_null"}}]},"examples":[{"import_price":{"mar":3.4}}]}},"dependentRequired":{"values":["id"],"profile":["id"],"series":["id"]}}},"examples":[{"source":{"sha256":"4bc4a1a431436a6fd82c19d3a9ee0a51b1c3a2f0e9d8c7b6a5f4e3d2c1b0a998"},"parameters":[{"id":"facade#5","values":{"uvalue":0.18}},{"id":"window#1","values":{"uvalue":0.8,"const_solar_factor":0.35}},{"id":"cav#58/usage_ventilation","profile":{"percentage_0730-0745":80}},{"id":"project#79062/monthly_el_price","series":{"import_price":{"mar":3.4}}}]}]}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Enter your API key (e.g., sk_live_abc123...)"}}}}