{ "components": { "schemas": { "Error": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_REQUEST", "NOT_FOUND", "PHI_BLOCKED", "PLAN_NO_API_ACCESS", "RANGE_TOO_LARGE", "RATE_LIMITED", "READ_ONLY", "REQUEST_REFUSED", "TENANT_INACTIVE", "UNAUTHORIZED", "UNAVAILABLE", "UPSTREAM_ERROR" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "Send an API key with every request: `Authorization: Bearer `. An administrator of your organization creates keys in Settings → API keys. A key reads only its own organization's data. Read-only keys read; read-write keys, on paid plans, can also create work orders and comments. Keep keys secret: anyone with one acts as your organization. API keys aren't available in workspaces that may hold patient data.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Send an API key with every request: `Authorization: Bearer `. An administrator of your organization creates keys in Settings → API keys. A key reads only its own organization's data. Read-only keys read; read-write keys, on paid plans, can also create work orders and comments. Keep keys secret: anyone with one acts as your organization. API keys aren't available in workspaces that may hold patient data.\n\nTimes are Unix milliseconds (`ts`, `from`, `to`) or ISO 8601 strings (`updatedAt`, `createdAt`, dates). One telemetry request covers at most 7 days. Every reading carries its own `unit`, exactly as the sensor reported it: the API converts nothing. Lists come a page at a time: pass back `cursor` (or `nextCursor`) for the next page. A field with no value is left out or null, never a made-up zero.\n\nRate limits: Per organization, per minute: 60 calls on the Free plan, 600 on paid plans. Telemetry reads (`/telemetry` and `/telemetry/latest`) also count against their own 30 a minute. Over a limit the answer is 429 `RATE_LIMITED` with a `Retry-After` header in seconds.", "title": "Powoflow API", "version": "1" }, "openapi": "3.1.0", "paths": { "/v1/alarms/active": { "get": { "description": "Your organization's alarms that are active now, worst first.", "operationId": "get_v1_alarms_active", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "count": 1, "items": [ { "alarmId": "alm-01EXAMPLE00000000000000000", "currentState": "UNACK", "name": "Pump 2 high temperature", "resourceId": "res-01EXAMPLEPUMP0000000000000", "resourceName": "Pump 2", "severity": "high" } ], "truncated": false }, "schema": { "properties": { "count": {}, "items": { "items": { "properties": { "acknowledgedAt": {}, "alarmId": {}, "createdAt": {}, "currentState": {}, "lastStateChange": {}, "name": {}, "resourceClass": {}, "resourceId": {}, "resourceName": {}, "severity": {} }, "type": "object" }, "type": "array" }, "truncated": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "List active alarms", "x-powoflow-example-request": "/v1/alarms/active", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/alarms/summary": { "get": { "description": "Your organization's alarms counted by state and by severity.", "operationId": "get_v1_alarms_summary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "active": 1, "bySeverity": { "high": 1 }, "byState": { "NORM": 11, "UNACK": 1 }, "total": 12 }, "schema": { "properties": { "active": {}, "bySeverity": {}, "byState": {}, "total": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Count alarms", "x-powoflow-example-request": "/v1/alarms/summary", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/alarms/{alarmId}": { "get": { "description": "One alarm rule of your organization, with its current state.", "operationId": "get_v1_alarms__alarmId_", "parameters": [ { "description": "The alarm's id (`alm-…`).", "in": "path", "name": "alarmId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "alarmId": "alm-01EXAMPLE00000000000000000", "createdAt": "2026-10-01T08:00:00.000Z", "currentState": "NORM", "name": "Pump 2 high temperature", "resourceId": "res-01EXAMPLEPUMP0000000000000", "severity": "high" }, "schema": { "properties": { "acknowledgedAt": {}, "alarmId": {}, "createdAt": {}, "currentState": {}, "lastStateChange": {}, "name": {}, "resourceClass": {}, "resourceId": {}, "resourceName": {}, "severity": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Get an alarm", "x-powoflow-example-request": "/v1/alarms/alm-01EXAMPLE00000000000000000", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/resources": { "get": { "description": "Your organization's resources (sites, buildings, devices, sensors and the rest), a page at a time.", "operationId": "get_v1_resources", "parameters": [ { "description": "The most items in one page. The answer's `count` says how many came back.", "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "description": "The `cursor` (or `nextCursor`) from the previous page, to read the next one. Leave it out for the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Only resources of this class, e.g. `SITE` or `PHYSICAL_ASSET`.", "in": "query", "name": "resourceClass", "required": false, "schema": { "type": "string" } }, { "description": "Only resources of this type.", "in": "query", "name": "resourceTypeId", "required": false, "schema": { "type": "string" } }, { "description": "Only the direct children of this resource.", "in": "query", "name": "parentResourceId", "required": false, "schema": { "type": "string" } }, { "description": "Only resources in this status, e.g. `active`.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Only resources changed since this time: Unix milliseconds or an ISO 8601 time.", "in": "query", "name": "updatedSince", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "count": 1, "cursor": null, "items": [ { "resourceClass": "SITE", "resourceId": "res-01EXAMPLESITE0000000000000", "resourceName": "North Yard", "status": "active", "updatedAt": "2026-11-10T09:00:00.000Z" } ] }, "schema": { "properties": { "count": {}, "cursor": {}, "items": { "items": { "properties": { "criticality": {}, "lifecycleStatus": {}, "parentResourceId": {}, "resourceClass": {}, "resourceId": {}, "resourceName": {}, "resourceTypeName": {}, "status": {}, "updatedAt": {} }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "List resources", "x-powoflow-example-request": "/v1/resources?resourceClass=SITE&limit=50", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/resources/{resourceId}": { "get": { "description": "One resource of your organization.", "operationId": "get_v1_resources__resourceId_", "parameters": [ { "description": "The resource's id (`res-…`), from `GET /v1/resources`.", "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "criticality": "high", "parentResourceId": "res-01EXAMPLESITE0000000000000", "resourceClass": "PHYSICAL_ASSET", "resourceId": "res-01EXAMPLEPUMP0000000000000", "resourceName": "Pump 2", "resourceTypeName": "Pump", "status": "active", "updatedAt": "2026-11-10T09:00:00.000Z" }, "schema": { "properties": { "criticality": {}, "lifecycleStatus": {}, "parentResourceId": {}, "resourceClass": {}, "resourceId": {}, "resourceName": {}, "resourceTypeName": {}, "status": {}, "updatedAt": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The resource is not one of your organization's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Get a resource", "x-powoflow-example-request": "/v1/resources/res-01EXAMPLEPUMP0000000000000", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/resources/{resourceId}/alarms": { "get": { "description": "The alarm rules on one resource, with their current state.", "operationId": "get_v1_resources__resourceId__alarms", "parameters": [ { "description": "The resource's id (`res-…`), from `GET /v1/resources`.", "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "count": 1, "items": [ { "alarmId": "alm-01EXAMPLE00000000000000000", "currentState": "NORM", "lastStateChange": "2026-11-09T22:10:00.000Z", "name": "Pump 2 high temperature", "resourceId": "res-01EXAMPLEPUMP0000000000000", "severity": "high" } ] }, "schema": { "properties": { "count": {}, "items": { "items": { "properties": { "acknowledgedAt": {}, "alarmId": {}, "createdAt": {}, "currentState": {}, "lastStateChange": {}, "name": {}, "resourceClass": {}, "resourceId": {}, "resourceName": {}, "severity": {} }, "type": "object" }, "type": "array" }, "truncated": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The resource is not one of your organization's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "List a resource's alarms", "x-powoflow-example-request": "/v1/resources/res-01EXAMPLEPUMP0000000000000/alarms", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/resources/{resourceId}/telemetry": { "get": { "description": "A sensor's readings over a time range, newest first unless `order=asc`, downsampled to about `targetPoints` points when there are more. Each point carries its own `unit`, exactly as recorded.", "operationId": "get_v1_resources__resourceId__telemetry", "parameters": [ { "description": "The sensor's id: a resource whose readings you want.", "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } }, { "description": "The start of the range, in Unix milliseconds.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The end of the range, in Unix milliseconds. Defaults to now.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "The most items in one page. The answer's `count` says how many came back.", "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "description": "`asc` for oldest first. Newest first otherwise.", "in": "query", "name": "order", "required": false, "schema": { "type": "string" } }, { "description": "The `cursor` (or `nextCursor`) from the previous page, to read the next one. Leave it out for the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "About how many points to return over the range: more readings than this are downsampled, each point then carrying its bucket's `min`, `max` and `count`.", "in": "query", "name": "targetPoints", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "count": 1, "downsampled": false, "hasMore": false, "items": [ { "ts": 1762761600000, "unit": "°C", "value": 4.5, "valueType": "AirTemperature" } ], "nextCursor": null }, "schema": { "properties": { "bucketMs": {}, "count": {}, "cursor": {}, "downsampled": {}, "hasMore": {}, "items": { "items": { "properties": { "count": {}, "max": {}, "maxTs": {}, "min": {}, "minTs": {}, "ts": {}, "unit": {}, "value": {}, "valueType": {} }, "type": "object" }, "type": "array" }, "nextCursor": {}, "pointsCapped": {}, "targetPoints": {}, "totalPoints": {}, "truncated": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The resource is not one of your organization's sensors." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Read a sensor's readings", "x-powoflow-example-request": "/v1/resources/res-01EXAMPLETEMP0000000000000/telemetry?from=1762761600000&to=1762765200000&order=asc", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": true } }, "/v1/resources/{resourceId}/telemetry/latest": { "get": { "description": "A sensor's newest reading. `latest` is null when it has none.", "operationId": "get_v1_resources__resourceId__telemetry_latest", "parameters": [ { "description": "The sensor's id.", "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "latest": { "ts": 1762765200000, "unit": "°C", "value": 4.7, "valueType": "AirTemperature" }, "resourceId": "res-01EXAMPLETEMP0000000000000" }, "schema": { "properties": { "latest": {}, "resourceId": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The resource is not one of your organization's sensors." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Read a sensor's latest reading", "x-powoflow-example-request": "/v1/resources/res-01EXAMPLETEMP0000000000000/telemetry/latest", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": true } }, "/v1/work-orders": { "get": { "description": "Your organization's work orders, a page at a time.", "operationId": "get_v1_work_orders", "parameters": [ { "description": "The most items in one page. The answer's `count` says how many came back.", "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "description": "The `cursor` (or `nextCursor`) from the previous page, to read the next one. Leave it out for the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Only work orders in this status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Only work orders of this priority.", "in": "query", "name": "priority", "required": false, "schema": { "type": "string" } }, { "description": "Only work orders changed since this time: Unix milliseconds or an ISO 8601 time.", "in": "query", "name": "updatedSince", "required": false, "schema": { "type": "string" } }, { "description": "Only work orders of this type.", "in": "query", "name": "workOrderType", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "count": 1, "cursor": null, "items": [ { "dueDate": "2026-11-14", "priority": "high", "resourceId": "res-01EXAMPLEPUMP0000000000000", "status": "open", "workOrderId": "wo-01EXAMPLE000000000000000000", "workOrderNumber": "WO-2026-0042", "workOrderTitle": "Replace pump seal" } ] }, "schema": { "properties": { "count": {}, "cursor": {}, "items": { "items": { "properties": { "createdAt": {}, "dueDate": {}, "priority": {}, "resourceId": {}, "resourceName": {}, "status": {}, "updatedAt": {}, "workOrderId": {}, "workOrderNumber": {}, "workOrderStatus": {}, "workOrderTitle": {}, "workOrderType": {} }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "List work orders", "x-powoflow-example-request": "/v1/work-orders?status=open&limit=25", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false }, "post": { "description": "Opens a work order on one of your organization's resources. Needs a read-write key.", "operationId": "post_v1_work_orders", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "dueDate": "2026-11-14", "priority": "high", "resourceId": "res-01EXAMPLEPUMP0000000000000", "workOrderTitle": "Replace pump seal" }, "schema": { "properties": { "category": { "description": "Its category." }, "description": { "description": "More detail." }, "dueDate": { "description": "When it is due (ISO 8601 date)." }, "estimatedHours": { "description": "The estimated hours of work." }, "priority": { "description": "Its priority, e.g. `low`, `medium`, `high`." }, "resourceId": { "description": "The resource it is for: one of your organization's." }, "startDate": { "description": "When work starts (ISO 8601 date)." }, "workOrderTitle": { "description": "What needs doing, in a few words." }, "workOrderType": { "description": "Its type, e.g. `corrective` or `preventive`." } }, "type": "object" } } }, "required": true }, "responses": { "2XX": { "content": { "application/json": { "example": { "workOrderId": "wo-01EXAMPLE000000000000000000", "workOrderNumber": "WO-2026-0042" }, "schema": { "properties": { "workOrderId": {}, "workOrderNumber": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The body's `resourceId` is not one of your organization's resources." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Create a work order", "x-powoflow-example-request": "/v1/work-orders", "x-powoflow-key": "read-write", "x-powoflow-telemetry-limit": false } }, "/v1/work-orders/{woId}": { "get": { "description": "One work order of your organization.", "operationId": "get_v1_work_orders__woId_", "parameters": [ { "description": "The work order's id, `workOrderId` in the list.", "in": "path", "name": "woId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-11-10T07:30:00.000Z", "description": "Seal weeping at the shaft.", "priority": "high", "resourceId": "res-01EXAMPLEPUMP0000000000000", "status": "open", "workOrderId": "wo-01EXAMPLE000000000000000000", "workOrderNumber": "WO-2026-0042", "workOrderTitle": "Replace pump seal" }, "schema": { "properties": { "category": {}, "completedAt": {}, "createdAt": {}, "description": {}, "dueDate": {}, "priority": {}, "resourceId": {}, "resourceName": {}, "startDate": {}, "status": {}, "updatedAt": {}, "workOrderId": {}, "workOrderNumber": {}, "workOrderStatus": {}, "workOrderTitle": {}, "workOrderType": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Get a work order", "x-powoflow-example-request": "/v1/work-orders/wo-01EXAMPLE000000000000000000", "x-powoflow-key": "read", "x-powoflow-telemetry-limit": false } }, "/v1/work-orders/{woId}/comments": { "post": { "description": "Adds a comment to a work order. Needs a read-write key.", "operationId": "post_v1_work_orders__woId__comments", "parameters": [ { "description": "The work order's id.", "in": "path", "name": "woId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "message": "Seal replaced, running normally." }, "schema": { "properties": { "message": { "description": "The comment's text." } }, "type": "object" } } }, "required": true }, "responses": { "2XX": { "content": { "application/json": { "example": { "commentId": "cmt-01EXAMPLE00000000000000000", "createdAt": "2026-11-10T11:05:00.000Z" }, "schema": { "properties": { "commentId": {}, "createdAt": {} }, "type": "object" } } }, "description": "Success." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such item in your organization." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error: see Errors." } }, "summary": "Comment on a work order", "x-powoflow-example-request": "/v1/work-orders/wo-01EXAMPLE000000000000000000/comments", "x-powoflow-key": "read-write", "x-powoflow-telemetry-limit": false } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.powoflow.com" } ], "x-powoflow-errors": [ { "code": "INVALID_REQUEST", "meaning": "A query parameter or body field is not one this route takes, or a value is not valid.", "status": 400 }, { "code": "RANGE_TOO_LARGE", "meaning": "A telemetry request covers more than 7 days. Split a longer range into several requests.", "status": 400 }, { "code": "UNAUTHORIZED", "meaning": "No API key, or one that is not valid, expired or revoked. Every way a key can be wrong gets this same answer.", "status": 401 }, { "code": "READ_ONLY", "meaning": "This key, or the organization's plan, can read but not write.", "status": 403 }, { "code": "PLAN_NO_API_ACCESS", "meaning": "The organization's plan does not include API access.", "status": 403 }, { "code": "TENANT_INACTIVE", "meaning": "The organization is not active.", "status": 403 }, { "code": "PHI_BLOCKED", "meaning": "API keys aren't available in workspaces that may hold patient data.", "status": 403 }, { "code": "REQUEST_REFUSED", "meaning": "The request was refused. The message says why.", "status": 403 }, { "code": "NOT_FOUND", "meaning": "No such route, or no such item in your organization. The two are not told apart.", "status": 404 }, { "code": "RATE_LIMITED", "meaning": "Too many requests this minute. Wait the number of seconds in the Retry-After header.", "status": 429 }, { "code": "UPSTREAM_ERROR", "meaning": "The request could not be completed. It is safe to retry a read.", "status": 502 }, { "code": "UNAVAILABLE", "meaning": "A temporary problem. Retry after the seconds in the Retry-After header.", "status": 503 } ], "x-powoflow-rate-limits": { "freePerMinute": 60, "paidPerMinute": 600, "telemetryPerMinute": 30 } }