# Simien Central API

> HTTP API for running SIMIEN building-energy simulations and for changing a building's numbers (u-values, profiles, prices) and re-simulating it, without the SIMIEN desktop software.

Base URL: https://dev-central-api.simien.no. All endpoints are under `/api/v1/sim/` and need `Authorization: Bearer <api-key>` (except the health endpoints). The building is a `.simx` (SIMIEN's encrypted file; a plaintext `.sxi` also works), uploaded as `multipart/form-data` in a field named `file`. A `.simx` can't be edited directly: change it through simulatable parameters. Errors are `{"error": {"code", "message", "request_id"}}`; branch on `code`. Rate-limited responses carry `X-RateLimit-Remaining`; a 429 carries `Retry-After`.

Other endpoints: `POST /api/v1/sim/sxo/catalog`, `/sxo/info` and `/sxo/parse` (read a .sxo result you already have, sent in `file`).

Typical flow: `POST /api/v1/sim/simulatable-parameters` (file=building.simx) → take `source.sha256`, `source.simien_version`, `simulations[].id` → baseline `POST /api/v1/sim/simulate` → edit numbers → `POST /api/v1/sim/simulate` (same .simx + `simulatable_parameters` JSON file) → compare with the baseline.

## Docs

- [Guide (Markdown)](https://dev-central-api.simien.no/guide.md): every endpoint, the simulatable-parameters workflow, the minimal document, error codes, and rules for agents. Read this first.
- [OpenAPI spec](https://dev-central-api.simien.no/openapi.json): machine-readable reference with request fields, response types, headers and error codes.
- [Simulatable parameters JSON Schema](https://dev-central-api.simien.no/schemas/simulatable-parameters.schema.json): validate a `simulatable_parameters` document before sending it.

## Optional

- [Guide (HTML)](https://dev-central-api.simien.no/): the same guide for people.
- [Swagger UI](https://dev-central-api.simien.no/docs): interactive reference.
- [Postman collection](https://dev-central-api.simien.no/postman.json): every endpoint ready to import into Postman; set the `apiKey` variable.
- [Get an API key](https://simien.no/kontakt-oss/)
- [License user terms](https://simien.no/wp-content/uploads/Bruksvilkar-Simien-2026.pdf)
- [Privacy policy](https://simien.no/personvernerklaering/)