11 min read

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.

ByAndré Ribeiro· Founder, Obelinf
How to Document Cooling Sources, Feeds, and Device Intakes
How to Document Cooling Sources, Feeds, and Device Intakes · November 13, 2026
On this page

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.

The six writes in a documented cooling chain, in order WRITE ORDER FOR A COOLING CHAIN 1 Source plant asset 2 Feed loop to rack 3 Template device type 4 Apply ports on device 5 Upstream intake link 6 Verify one read source feed templates ports link report Each step depends on the one before it. A feed needs a source, an intake needs an outflow to point at, and the verification read is only meaningful once the ports exist. Start at the source you can name, not at the rack you cannot reach.

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
Two feed records checked against the heat balance equation HEAT BALANCE CHECK rated capacity, flow and temperature rise are one equation: kW = L/min x 0.0697 x delta T R07-L1 as designed 80 kW / 115 L/min / 10 K 115 x 0.0697 x 10 = 80.2 kW values agree R07-L1 as copied 80 kW / 45 L/min / 9 K 45 x 0.0697 x 9 = 28.2 kW capacity is not supported by the flow A mismatch does not tell you which value is wrong. It tells you which record to take back to the loop schedule.

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.

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}]
    }'
Cooling questions mapped to the record and field that answers each one WHAT EACH RECORD PROVES Question Evidence Field to check What cools this rack? Feed and its source source_id / rack_id How much heat can it take? Rack capacity, then feed sum cooling_capacity_w How much heat is there? Device draw, then type draw heat_load_w What feeds this intake? Intake to upstream outflow upstream_outflow A rack summary with a heat load, a capacity and a port count is a documented loop. Anything less is a draft.

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?
You need one record per real asset and one record per coolant path: a source for the plant equipment, a feed for each loop that serves a rack, device type templates for the ports a device model has, and an intake and outflow record on each installed device. If you stop at the source and never record the feed or the ports, you have a cooling inventory without a cooling path.
Should I create the cooling source or the feed first?
Create the source first, then the feed, then the templates, then the device ports. That order follows the physical path and lets every record reference the one above it while the details are still in front of you. A feed cannot exist without a source, and an intake cannot point at an outflow that has not been created yet.
Does one cooling feed represent supply and return?
Yes. One feed describes both directions of a single loop, which matches how a row manifold or a rack CDU is installed: coolant goes out and comes back through the same loop. Create two feeds only when the physical design really has independent supply and return paths, and name them so the pair is obvious.
Why is my feed capacity higher than the flow can carry?
The three numbers are a set: capacity, flow, and the supply to return temperature difference. A loop that claims 80 kW at 45 liters per minute and a 9 degree rise can only carry about 28 kW. One of the three values is wrong, usually because the capacity came from a sales sheet while the flow came from an older installation.
What is the difference between an intake and an outflow?
An intake is the cold side where coolant enters a device, and an outflow is the warm side where it leaves. The intake can point at the upstream outflow that supplies it, which is how you trace a loop through a CDU or manifold. Outflows do not store a parent intake, because one outflow can supply several downstream intakes.
How do I know a rack cooling record is complete?
A complete rack has a source, at least one feed with a capacity and a flow, a cooling capability, a cooling capacity, and at least one device with the liquid cooling method and both ports recorded. Read the rack summary and confirm that heat load is above zero, feed capacity matches the sum of the feeds, and utilization is a number rather than a blank.

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