How to Document Cooling Sources, Feeds, and Device Intakes
A working procedure for building a cooling record from the plant to the cold plate: the order to create each record, the API calls, the fields that matter, and the checks that catch gaps.

On this page
- Decide the scope and the naming before the first write
- Create the source before the feed
- Create one feed per loop and attach the rack
- Build the device type template once
- Apply the template and fix the installed details
- Link each intake to the outflow that supplies it
- Set the rack cooling values
- Verify the chain in one read
- Close the blanks as a worklist
- Work the list, then repeat on the next rack
Cooling documentation fails in the same place power documentation used to fail: at the boundary between the plant and the rack. The chiller has a name, the rack has a number, and the loop that connects them lives in a commissioning document that nobody opens after handover. When a feed is rebalanced or a CDU is swapped, the record does not move with it.
This procedure builds the cooling record from the top down, in the order the coolant actually flows. You will create the source, the feed, the device type template, the installed ports, and the upstream link, using the Obelinf API so the steps can become a script. Each step ends with a check that the record is complete before the next record depends on it. The goal is not a perfect plant diagram on day one. The goal is a chain that answers which loop cools this rack, what it is rated for, and which port on which device is connected to it.
Decide the scope and the naming before the first write
Pick one site and one rack loop. A site wide cooling survey produces a lot of partial rows, while one completed loop produces a pattern the next loop can copy. Before the first API call, collect the facts in one place. Every row in this table becomes a field in a record, and a fact you cannot find is a known gap rather than a reason to guess.
| Fact | Where it comes from | Record and field |
|---|---|---|
| Plant equipment and its type | Nameplate, commissioning report | Source name, type, rated_capacity_w |
| Fluid in the loop | Commissioning report, fluid label | Source fluid |
| Loop name and the rack it serves | Row schedule, rack drawing | Feed name, rack_id |
| Design capacity and flow | Loop schedule, CDU selection | Feed capacity_w, max_flow_lpm |
| Supply and return temperatures | Commissioning baseline | Feed supply_temp_c, return_temp_c |
| Device model ports | OEM datasheet, cold plate manual | Template name, connector, diameter_mm, max_flow_lpm |
| Installed connection | Physical label, as built drawing | Intake or outflow label, connector |
| What supplies each intake | Manifold drawing, CDU port map | Intake cooling_outflow_id |
Set the API variables once and keep them for the session. The trailing path is your organization slug, and the same key works for every cooling endpoint.
export OBELINF_API_KEY="your_read_write_key"
export OBELINF_ORG="acme-netops"
export API="https://api.obelinf.com/${OBELINF_ORG}"
curl --fail --silent --show-error \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/sites?q=nyc" \
| jq -r '.sites[] | [.id, .name, .slug] | @tsv'
Use a naming scheme that encodes the site, the asset, and the loop. A source can be nyc1-chiller-1 and nyc1-tower-1. A feed is usually the rack name plus the loop index, for example R07-L1, because that is what the row schedule already calls it. The feed name must be unique inside its source, so the same R07-L1 can exist on two chillers without a conflict, which is correct when two plants serve the same rack.
Create the source before the feed
A cooling source is one cooling or heat rejection asset at one site. The type list is fixed: chiller, cooling-tower, dry-cooler, crac, crah, heat-exchanger, and other. The status list is active, planned, maintenance, offline, failed, and retired. The fluid list is water, water-glycol, dielectric, refrigerant, and other.
cat > source-chiller.json <<JSON
{
"name": "Chiller 1",
"slug": "nyc1-chiller-1",
"site_id": "${SITE_ID}",
"type": "chiller",
"status": "active",
"fluid": "water-glycol",
"rated_capacity_w": 400000,
"description": "Primary chilled water plant, west yard"
}
JSON
curl --fail --silent --show-error -X POST \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
--data @source-chiller.json \
"${API}/cooling/sources" \
| jq '.cooling_source | {id, name, type, status, fluid, rated_capacity_w}'
Save the returned id as SOURCE_ID. The slug is unique per organization, so a second site cannot reuse nyc1-chiller-1 even though the name is local to that site. That is deliberate: a slug appears in URLs and scripts, and a slug that resolves to two records is a support ticket waiting to happen.
Record the source capacity only when the nameplate or the commissioning report gives you a number. A guessed capacity becomes the ceiling for every downstream utilization report, and a wrong ceiling is harder to notice than a blank.
Create one feed per loop and attach the rack
A feed carries coolant from a source to a rack. It stores capacity in watts, maximum flow in liters per minute, and supply and return temperatures in Celsius. The rack is optional, so a planned loop can be recorded before the rack exists, but an active feed without a rack should be treated as a documentation gap.
curl --fail --silent --show-error -X POST \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"name\":\"R07-L1\",\"cooling_source_id\":\"${SOURCE_ID}\",\"rack_id\":\"${RACK_ID}\",\"status\":\"active\",\"capacity_w\":80000,\"max_flow_lpm\":115,\"supply_temp_c\":18,\"return_temp_c\":28,\"description\":\"Direct to chip loop for R07\"}" \
"${API}/cooling/feeds" \
| jq '.cooling_feed | {id, name, rack_name, capacity_w, max_flow_lpm, supply_temp_c, return_temp_c}'
The three numbers are a set, and they have to agree. Water at a 10 degree rise carries about 0.695 kW per liter per minute, so an 80 kW loop at 18 to 28 degrees needs about 115 liters per minute. PG25 carries about 0.667 kW per liter per minute, so the same loop needs about 120. If a record claims 80 kW, 45 liters per minute, and a 9 degree rise, it can only carry about 28 kW, and one of the three values is wrong.
declared 80,000 W / 115 L/min / 18 to 28 C -> carried 80.2 kW OK
declared 80,000 W / 45 L/min / 18 to 27 C -> carried 28.2 kW MISMATCH
This check is worth running on every feed you import. It catches the most common cooling documentation error, which is a capacity copied from a CDU datasheet into a row that still has the flow from an older install.
Build the device type template once
Ports repeat across a device model, so the device type is the right place to describe them. The template endpoint replaces both lists in one call, which means you must send intake_templates and outflow_templates every time. Sending only the intakes deletes the outflows.
curl --fail --silent --show-error -X PUT \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"intake_templates": [
{"name":"Cold Plate In","connector":"uqd","diameter_mm":12,"max_flow_lpm":20,"description":"Primary cold plate supply"}
],
"outflow_templates": [
{"name":"Cold Plate Out","connector":"uqd","diameter_mm":12,"max_flow_lpm":20,"description":"Primary cold plate return"}
]
}' \
"${API}/cooling/device-types/${DEVICE_TYPE_ID}/templates" \
| jq '{intakes: [.intake_templates[] | {name, connector, max_flow_lpm}], outflows: [.outflow_templates[] | {name, connector, max_flow_lpm}]}'
The connector list is uqd, uqdb, qdc, camlock, npt, bsp, and other. Diameter is in millimeters and flow in liters per minute. If the OEM datasheet gives a flow in gallons per minute, convert it before the write and keep the original value in the description, so the next reader can see where the number came from.
Name the template after the physical function, not after the server model. Cold Plate In and Cold Plate Out survive a hardware refresh, while B200-tray-1-in has to be rewritten every generation and makes cross model reporting harder.
Apply the template and fix the installed details
Creating a device of that type copies the templates onto the device automatically. For devices that already exist, apply the templates explicitly. The operation creates missing ports by name and leaves existing ports alone, so it is safe to run after a template update.
curl --fail --silent --show-error -X POST \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/cooling/devices/${DEVICE_ID}/apply-templates" \
| jq '.'
The device also needs its cooling method, because the rack and site reports count liquid cooled devices separately. The values are air, liquid, hybrid, and immersion.
curl --fail --silent --show-error -X PATCH \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"cooling_method":"liquid"}' \
"${API}/devices/${DEVICE_ID}" \
| jq '.device | {name, cooling_method, rack_name}'
The template is design intent and the installed port is reality. When a technician finds a different connector or a lower flow limit on the actual unit, patch the port rather than editing the template, because the next device of that type should still get the standard values.
curl --fail --silent --show-error -X PATCH \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"label":"CPU1 IN","connector":"uqd","diameter_mm":12,"max_flow_lpm":18}' \
"${API}/cooling/intakes/${INTAKE_ID}" \
| jq '{name, label, connector, diameter_mm, max_flow_lpm, upstream_outflow}'
Port names are not editable through the patch endpoint. That is a feature, not an omission: the name is the key that matches a port to its template, so renaming a port would silently break the next apply. If a port is genuinely misnamed, delete it and recreate it with the correct name.
Link each intake to the outflow that supplies it
This is the step that turns a list of ports into a cooling path. A server intake points at the outflow that feeds it, which might be a port on a row manifold, a CDU, or another device. Create or find the upstream outflow first. The organization wide outflow list is the quickest way to find one by name or device.
curl --fail --silent --show-error \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/cooling/outflows" \
| jq -r '.cooling_outflows[] | [.id, .device_name, .name, (.connector // "NO CONNECTOR"), (.max_flow_lpm // "NO FLOW")] | @tsv'
Use the returned ID to patch the intake. Setting the field to null clears the link without deleting the port.
curl --fail --silent --show-error -X PATCH \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"cooling_outflow_id\":\"${UPSTREAM_OUTFLOW_ID}\"}" \
"${API}/cooling/intakes/${INTAKE_ID}" \
| jq '{name, device_name, upstream_outflow: (.upstream_outflow | {name, device_name})}'
A clean trace for a direct to chip server is intake on the server, upstream outflow on the CDU, and the CDU itself documented as a device in the rack. If the CDU has no ports yet, create them with POST /cooling/devices/:id/outflows first. Do not point a server intake at another server intake, and do not use the link to express a shared manifold branch that does not physically exist, because the trace is only as honest as the link.
Set the rack cooling values
The rack carries the envelope that its feeds and devices have to fit inside. The capability values are none, air, hybrid, and liquid, and the capacity is in watts. Set both when the rack drawing or the colocation contract gives you the numbers.
curl --fail --silent --show-error -X PATCH \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"cooling_capability":"liquid","cooling_capacity_w":80000}' \
"${API}/racks/${RACK_ID}" \
| jq '.rack | {name, cooling_capability, cooling_capacity_w}'
The rack capacity wins over the sum of the feed capacities when both exist. That ordering is intentional: a rack can have two 60 kW feeds for redundancy and a real thermal limit of 80 kW, and using the feed sum would make the rack look larger than the room can cool. When the rack has no capacity, the summary falls back to the feed sum so a converted rack still reports something useful.
Verify the chain in one read
The rack summary is the completeness check, because it joins the rack, its feeds, the devices inside it, and the port counts into one response.
curl --fail --silent --show-error \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/cooling/summary/rack/${RACK_ID}" \
| jq '{
rack: .rack_name,
capability: .cooling_capability,
rack_capacity_w: .cooling_capacity_w,
feed_capacity_w,
heat_load_w,
utilization_pct,
devices: .device_count,
liquid_devices: .liquid_device_count,
ports: {intakes: .intake_count, outflows: .outflow_count}
}'
{
"rack": "R07",
"capability": "liquid",
"rack_capacity_w": 80000,
"feed_capacity_w": 80000,
"heat_load_w": 24000,
"utilization_pct": 30,
"devices": 3,
"liquid_devices": 3,
"ports": { "intakes": 3, "outflows": 3 }
}
Three results need a decision, not just a note. If heat_load_w is zero while the rack is populated, the devices have no power draw and no device type fallback, so the utilization number is meaningless. If feed_capacity_w is zero, the feed exists without a capacity or the rack has no feeds at all. If liquid_device_count is lower than the number of devices with cold plates, the cooling method was never set on the device.
The device summary answers the port question for one server, including the upstream link.
curl --fail --silent --show-error \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/cooling/devices/${DEVICE_ID}/cooling" \
| jq '{
device: .device_name,
method: .cooling_method,
rack: .rack_name,
feed: .feed_name,
flow_lpm: .total_max_flow_lpm,
intakes: [.intakes[] | {name, label, connector, upstream: .upstream_outflow.device_name}]
}'
Close the blanks as a worklist
The last step is a query that turns the gaps into a list with a name attached. Start with the feeds, because a feed without a rack or a capacity breaks the rack report for every device in that rack.
curl --fail --silent --show-error \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/cooling/feeds?site_id=${SITE_ID}&all=true" \
| jq -r '.cooling_feeds[]
| select(.rack_id == null or .capacity_w == null or .max_flow_lpm == null)
| [.name, .cooling_source_name, (.rack_name // "NO RACK"), (.capacity_w // "NO CAPACITY"), (.max_flow_lpm // "NO FLOW")]
| @tsv'
This next query finds the feeds whose capacity, flow, and temperatures do not agree. It is the same heat balance as above, applied to every feed in the site at once.
curl --fail --silent --show-error \
-H "Authorization: Bearer ${OBELINF_API_KEY}" \
"${API}/cooling/feeds?site_id=${SITE_ID}&all=true" \
| jq -r '.cooling_feeds[]
| select(.capacity_w and .max_flow_lpm and .supply_temp_c and .return_temp_c)
| ((.return_temp_c - .supply_temp_c) * .max_flow_lpm * 0.0697) as $carried_kw
| select($carried_kw < (.capacity_w / 1000 * 0.8))
| [.name, (.capacity_w / 1000 | floor), (.max_flow_lpm | floor), ($carried_kw | floor)]
| @tsv'
R07-L1 80 45 28
R12-L1 60 34 21
Both rows are candidates for correction, not proof of a fault. A loop may be designed to run a wider temperature rise than the record shows, or the declared capacity may include a future rack, in which case the description should say so. The query is there to make that decision visible.
Work the list, then repeat on the next rack
A cooling record is finished when the rack summary can answer three questions without a phone call: what cools this rack, what is the loop rated for, and how close is the rack to that rating. The worklist above gets you there. The order of fixes matters less than closing each loop completely before starting the next one, because a half documented rack produces more false confidence than an undocumented one.
Start with the rack that has the highest heat load today. Its utilization number is the one most likely to change a decision, and the feed behind it is the one most likely to have a real capacity number you can verify against a commissioning report. Once that chain is clean, rack management and device inventory give you the pattern to copy for the next row.
Frequently Asked Questions
What records do you need to document a cooling chain?
Should I create the cooling source or the feed first?
Does one cooling feed represent supply and return?
Why is my feed capacity higher than the flow can carry?
What is the difference between an intake and an outflow?
How do I know a rack cooling record is complete?
Stop reaching for a spreadsheet
Obelinf keeps every subnet, device, circuit, and rack in one live source of truth, with audit logs and a topology view. Free for personal use.
Related Articles

Introducing Cooling Management in Obelinf
Obelinf now documents cooling sources, rack feeds, and device coolant ports next to your power and rack data, and derives heat load from the power draw you already record.
Read more
How to Document Power Sources, Panels, Breakers, and Feeds
A working procedure for building a power distribution record from source to rack: the order to create each record, the API calls, the fields that matter, and the checks that catch gaps.
Read more
Direct to Chip vs Rear Door vs Immersion Cooling
How direct to chip, rear door, and immersion liquid cooling compare on density, PUE, cost, and retrofit fit, and how to choose between them for your data center.
Read more