Introduction
The Factry Historian API gives developers direct programmatic access to data stored in Factry Historian. With it, you can query, retrieve, and interact with time-series data, events, the asset tree,... in a secure and structured way.
We provide a OpenAPI (Swagger) specification, making it easy to explore available endpoints, understand request/response formats, and integrate Historian data into your own applications, dashboards, or analytics workflows.
Have a look at the Python examples to interact with the Factry Historian API using Python.
OpenAPI validation layer
In Historian v8.2 we introduced a validation layer on top of the API that automatically validates all requests against our OpenAPI specification. This ensures all interactions with the API are as described in the spec. For this we rewrote large portions of the OpenAPI spec, making it more strict in certain places than before. This can cause certain legacy integrations to stop functioning if they depend on the more loose input validation performed before this update.
If you are encountering problems with the new validation layer, it can be disabled using the environment variable OPENAPI_VALIDATION_ENABLED. Setting this to false will disable the API validation layer, allowing the more loose legacy integrations. Do note that this opens up the Historian API to faulty data inputs which may result in unexpected behavior.
Request rules from version 8.3
From version 8.3, the API checks requests more strictly. Integrations that worked with v8.2 can get errors after the upgrade:
- Case-sensitive JSON keys. Keys in a JSON request body only match a field with exactly the same name. A key in another case (name instead of Name) is ignored like any unknown key: a required field then gets a 400, an optional one is silently dropped. Set HTTP_JSON_CASE_SENSITIVE to false to restore the old behavior. Query parameter names are not affected.
- Stricter validation. Write endpoints reject an empty body. Names must not be empty, UUIDs must be valid, limit and offset must not be negative and page starts at 1.
- Body size limit. A request body is limited to 64 MB by default. A larger body gets a 413. Change the limit with HTTP_MAX_BODY_SIZE (for example 128MB).
- Error format. A request that does not match the specification gets a 400 with content type application/problem+json. Its errors list has one entry per violation. The body also keeps the error and info members of the older error format.
Setting OPENAPI_VALIDATION_ENABLED to false bypasses most of the stricter validation, but not these rules:
- A time series query (POST /api/timeseries/query) needs Start and at least one of MeasurementUUIDs, AssetPropertyUUIDs, Measurements or Filter.
- POST /api/logs/query takes Limit and Page as JSON numbers, not strings.
- POST /api/timeseries/export needs CompressionCodec, CompressionLevel and Interval (at least 1s).
- The asset or event type of an event configuration, and the event configuration or property of a property configuration, cannot be changed.
Other breaking changes in version 8.3:
- GET /api/collectors/{collectorUUID}/measurements is removed. Use GET /api/measurements?CollectorUUID={collectorUUID} to list the measurements of a collector.
- GET /api/product-updates/{uuid} is removed. Use GET /api/product-updates to list the product updates.
- Writing to a manual entry form property that is not editable returns a 403.