QuickFreeze QFM API
Read live status and control your QFM units from your WMS or building-automation system — set cycle times, record what is on the pallet, pause and resume fans.
Your software addresses each unit by its QFM serial number (printed on the unit) plus the rack location you have on file for it. Everything runs through one secured endpoint, scoped to your facility’s own units. The serial is permanent — when a control box is replaced, the API resolves the serial to whichever box is installed at that moment, so a swap needs no change on your side.
Connection
- Endpoint
https://qfreeze.com/wp-json/qf/v1/qfm
the same address for every customer — your key scopes it to your units- Auth header
X-QF-API-Key: {your-api-key}— issued per facility; TLS 1.2+ required- Methods
- HTTP GET (query parameters) or POST (JSON body)
- Responses
- Reads return 200 with the unit’s live state; commands return 202 accepted. Every failure is JSON with a stable
errorcode — a missing or wrong key returns 401. - User-Agent
- Please send an identifying agent, e.g.
YourCompany-WMS/1.0. Our edge blocks a few known automated-client signatures; if you ever receive an HTML 403 instead of JSON, tell us and we will allow your client.
1. Identifying a unit
Every request carries two identifiers, and both must match our records:
| Parameter | Example | Notes |
|---|---|---|
QFM_SERIAL | QFM-12107 | Printed on the unit. Permanent — survives control-box swaps. |
RACK_LOCATION | 2X-001B | The rack position we have recorded for that QFM. |
WAREHOUSE_ID | DC-EAST | Optional. Your own site or warehouse code, echoed back unchanged — a label for multi-site systems, not a permission. |
If the serial exists but the rack does not match, the request is refused and the reply
tells you which rack we have on file (409 rack_mismatch). A stale or mis-keyed mapping in the
WMS can never make us act on the wrong unit. A serial belonging to another customer returns
403, even with a correct rack.
2. Poll a unit (read latest)
COMMAND=poll is the default and may be omitted. Polling is read-only and cannot affect equipment.
curl -H "X-QF-API-Key: {your-api-key}" -H "User-Agent: YourCompany-WMS/1.0" \
"https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=poll"
→ 200 {"ok":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
"controlBox":"F8B3B74E6E7C","ts":1786143610000,"state":"READY",
"airtF":3.4,"airtC":-15.89,"deltap":0.01,
"remaining":172800,"active":true,"SKU":"I1-123456"}
| Field | Meaning |
|---|---|
ok | true on success. Always present. |
RACK_LOCATION | The rack we have on file for the unit. |
controlBox | The control box installed right now. Opaque to you — quote it when reporting an issue. |
ts | Time of the reading, epoch milliseconds UTC. Always check it: an offline unit returns its last known values with an older timestamp. |
state | Current unit state, e.g. READY, RUNNING, COMPLETE, PAUSE, BAD SEAL. |
airtF / airtC | Air temperature in both scales. Units measure in Celsius — read airtF if you work in Fahrenheit; do not assume an unlabelled value is °F. |
deltap | Differential pressure across the unit (seal quality). |
remaining | Seconds remaining in the current cycle; 0 when not running. |
active | Whether the unit is currently running. |
SKU | Item code stamped on the cycle in progress (always a string). Empty when no cycle is running — the unit clears it at cycle end. |
3. Commands
Three commands are available: set_cycle, pause and resume.
Commands are asynchronous: we validate and authorise the request, return
202, then apply it to the unit a moment later. Anything we cannot act on is
rejected up front with a 4xx and an error code — we never return 202 for a
command that would quietly do nothing. To confirm a change reached the unit, poll it afterwards.
Set cycle time and cycle details — set_cycle
| Parameter | Notes |
|---|---|
INCUBATION | Run time in hours, whole or fractional (48, 12.5). Persists until changed; if the unit is offline it takes effect at its next check-in. |
ITEM_NUMBER (or SKU) | Your item code. Stamped on the unit for this cycle, and can supply the run time from your SKU library (below). |
PALLET_TAG, PO | Pallet / LP / LPN and purchase order, recorded against the cycle for reporting. |
Send any combination — at least one. Only PO? Fine. Pallet details on a cycle that is
already running, without touching its run time? Fine. If you send any of these fields without a
COMMAND, we treat it as set_cycle.
curl -H "X-QF-API-Key: {your-api-key}" -H "User-Agent: YourCompany-WMS/1.0" \
"https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B\
&COMMAND=set_cycle&INCUBATION=48&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4471&PO=PO12345"
→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
"controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
"applied":{"cycleTimeHours":48,"SKU":"I1-123456","PALLET_TAG":"LP-4471","PO":"PO12345"},
"cycleTimeChanged":true}
applied lists exactly what we acted on and cycleTimeChanged says whether the
run time moved — you never have to assume. An INCUBATION we cannot use rejects the whole
call; we will not quietly apply just the metadata.
Cycle time from the SKU
Let the item code decide the run time instead of sending INCUBATION every call:
&COMMAND=set_cycle&ITEM_NUMBER=I1-123456. The library builds itself from your calls: the
first call that carries an item code with an explicit INCUBATION teaches us that
item’s run time, and later calls can send the code alone. A new item without hours is registered but
the run time is left unchanged — the reply says so with cycleTimeChanged:false and a
warning. An explicit INCUBATION always wins.
The reply reports what the library learned. Three calls for the same item, in order:
# 1. First time we see I1-123456, with hours: the library records 36 h against it
&COMMAND=set_cycle&INCUBATION=36&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4471
→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
"controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
"applied":{"cycleTimeHours":36,"SKU":"I1-123456","PALLET_TAG":"LP-4471"},
"cycleTimeChanged":true,"skuRegistered":true,"skuHoursRecorded":36}
# 2. Same item, different hours: the stored run time is replaced and the reply says from what
&COMMAND=set_cycle&INCUBATION=48&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4472
→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
"controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
"applied":{"cycleTimeHours":48,"SKU":"I1-123456","PALLET_TAG":"LP-4472"},
"cycleTimeChanged":true,"skuHoursRecorded":48,"skuHoursChanged":{"from":36,"to":48}}
# 3. Item code alone: the 48 h on file is applied
&COMMAND=set_cycle&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4473
→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
"controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
"applied":{"cycleTimeHours":48,"SKU":"I1-123456","PALLET_TAG":"LP-4473"},
"cycleTimeChanged":true}
skuHoursChanged is an object with two decimal-hours members: from, the run time
that was on file, and to, the run time that replaced it (always equal to
applied.cycleTimeHours). It appears only on a call that sent INCUBATION together with an
item code that already had a different run time on file. Re-sending the same hours changes nothing,
so neither skuHoursRecorded nor skuHoursChanged appears. Whole hours are sent as plain
integers (36, not 36.0); fractional hours keep their decimals (12.5).
Size both members as DECIMAL(5,2).
Pause / resume fans
pause stops the fans and freezes the cycle timer in place; resume
continues from exactly where it stopped. DURATION (minutes, optional) is a dead-man
auto-resume: if your system never sends resume, the unit restores itself. We recommend sending
it on every pause.
curl -H "X-QF-API-Key: {your-api-key}" \
"https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=pause&DURATION=30"
curl -H "X-QF-API-Key: {your-api-key}" \
"https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=resume"
READY a moment after being paused — that is the unit behaving correctly, not a
failed command. Check state and active first if it matters to your workflow.Repeating a command
All three commands are safe to send again — set_cycle sets a value rather than adding
to one, and pause/resume set a state. Re-sending after a timeout will not compound.
4. Error responses
Alert on the error code, not the message text — messages may be reworded, codes will not change.
{"ok":false,"error":"rack_mismatch",
"message":"RACK_LOCATION does not match the rack recorded for QFM-12107. Refusing to act on a possibly wrong unit.",
"expectedRackLocation":"2X-001B"}
| HTTP | error | Meaning | What to do |
|---|---|---|---|
| 400 | missing_serial / missing_rack_location | A required identifier is absent | Fix the request |
| 400 | bad_command | Unrecognised COMMAND | Fix the request |
| 400 | nothing_to_set | set_cycle with nothing to apply | Send at least one field |
| 400 | poll_is_read_only | COMMAND=poll sent with fields that would write | Omit COMMAND, or use set_cycle |
| 400 | bad_cycle_time | INCUBATION not a number between 0.17 and 168 hours | Fix the value — nothing was applied |
| 400 | field_too_long | A request field exceeds its limit (section 5); field and maxLength say which | Shorten the value |
| 401 | unauthorized | Missing or wrong API key | Check the header; alert |
| 403 | not_authorized | That unit is not on your account | Check the serial; alert |
| 404 | unknown_serial | No QFM with that serial | Typo or decommissioned unit; alert |
| 409 | rack_mismatch | Serial is yours, rack does not match | Alert. Your mapping is stale — expectedRackLocation tells you ours |
| 409 | ambiguous_serial | Serial matches more than one unit | Contact us — a data issue on our side |
| 502 | upstream_error | We could not reach the monitoring platform | Retry with backoff; alert if sustained |
Retries: poll and all commands are safe to retry. Use exponential backoff on 502; do not retry 4xx — they will not succeed without a change to the request.
5. Field sizes and types
Size your database columns from this table. These are commitments: a value we return will never
exceed its limit, and a request value longer than its limit is refused with 400 field_too_long
rather than truncated. Every response is JSON; strings are UTF-8, numbers are plain JSON numbers
(no thousands separators, dot decimal), booleans are true/false.
Request fields
| Field | Type | Limit |
|---|---|---|
QFM_SERIAL | string | 32 characters |
RACK_LOCATION | string | 32 characters |
COMMAND | string | one of poll, set_cycle, pause, resume (9 characters max) |
ITEM_NUMBER / SKU | string | 64 characters |
PALLET_TAG, PO | string | 64 characters each |
WAREHOUSE_ID | string | 64 characters |
INCUBATION | decimal hours | 0.17 to 168 (10 minutes to 7 days) |
DURATION | integer minutes | — |
Poll response (200)
| Field | Type | Size / range | Notes |
|---|---|---|---|
ok | boolean | — | Always present. true on every successful response. |
QFM_SERIAL | string | ≤ 32 | Echo of yours. |
RACK_LOCATION | string | ≤ 32 | The rack on file with us. |
controlBox | string | ≤ 32 | Today a 12-character hex identifier. |
ts | integer | 13 digits | Epoch milliseconds UTC — use a 64-bit integer. |
WAREHOUSE_ID | string | ≤ 64 | Only when you sent it. |
state | string | ≤ 14 | One of BOOT UP, READY, SEAL TEST, BAD SEAL, RUNNING, PAUSE, COMPLETE, MOTOR FAILURE, SENSOR FAILURE, BLOW OUT. |
deltap | decimal | 2 decimal places, signed | Pascals. Normally 0 to about 300; may dip slightly negative. DECIMAL(8,2) covers anything the sensor can report. |
remaining | integer | 0 to 604 800 | Whole seconds, never fractional (7 days max). |
airtC | decimal | 2 decimal places, −55.00 to 125.00 | DECIMAL(5,2). |
airtF | decimal | 1 decimal place, −67.0 to 257.0 | DECIMAL(4,1). |
active | boolean | — | |
SKU | string | ≤ 64 | Whatever you sent as ITEM_NUMBER; empty when no cycle is running. |
airtC/airtF, deltap, state
and SKU are omitted when the unit has never reported that value or the sensor
behind it is in fault — parse by key, not by position, and allow nulls in your table.Command response (202)
| Field | Type | Size / range | Notes |
|---|---|---|---|
ok | boolean | — | The request succeeded. Check this first on every response. |
accepted | boolean | — | The command was authorised and handed to the unit. Present on command responses only. Commands are asynchronous, so accepted means queued, not applied — poll to confirm. You will not see ok:true with accepted:false. |
QFM_SERIAL, RACK_LOCATION, controlBox, WAREHOUSE_ID | string | as above | |
COMMAND | string | ≤ 9 | The command that was applied. |
applied.cycleTimeHours | decimal | 0.17 to 168 | Only when the run time was set. |
applied.SKU, applied.PALLET_TAG, applied.PO | string | ≤ 64 each | Echo of what you sent; each present only if sent. |
cycleTimeChanged, skuRegistered | boolean | — | skuRegistered only when a new item was registered. |
skuHoursRecorded | decimal | 0.17 to 168 | Only when the item library learned a run time. |
skuHoursChanged | object | from, to decimal hours | Only when a stored run time was replaced. |
warning | string | ≤ 255 | Only when present. Informational; the command was still accepted. |
Error response (4xx / 5xx)
| Field | Type | Size | Notes |
|---|---|---|---|
ok | boolean | — | Always false. |
error | string | ≤ 32 | Stable lower-case code (section 4). Alert on this. |
message | string | ≤ 255 | Human-readable; may be reworded. |
expectedRackLocation | string | ≤ 32 | With rack_mismatch only. |
field, maxLength | string, integer | ≤ 16, — | With field_too_long only. |
ignoredFields | array of strings | ≤ 5 names | With poll_is_read_only only. |
upstreamStatus | integer | 3 digits | With some upstream_error responses. |
Identity & safety
- Each facility authenticates with its own API key and is authorised to its own units only.
RACK_LOCATIONmust match the location mapped to thatQFM_SERIALor the request is refused — this prevents adjusting the wrong unit.- Units are addressed by QFM serial, which stays stable across control-box swaps;
controlBoxin every response shows which box answered. - Keep your API key out of email threads and shared files. QuickFreeze may rate-limit excessive request volumes.
Getting started
QuickFreeze issues your API key and the QFM_SERIAL ↔ RACK_LOCATION map for your units.
A good first call is a poll against one live unit, then a deliberately wrong rack location to see
409 rack_mismatch come back. Send us your SKU list with cycle times if you want
ITEM_NUMBER alone to set run times from day one.
To request access, contact your QuickFreeze representative.
