For agents and developers

BlueLux API & MCP

BlueLux provides public tools for pool chemistry, diagnostics, operating guidance, and Playbook search. BlueLux Operator is the professional platform we are building for pool operators, and the public calculation tools are grounded in the same deterministic chemistry work that supports our daily operation.

No authentication120 requests/minuteStructured JSONVersioned provenance

Connect your agent

Copy this sentence into an agent. The linked setup document explains BlueLux, MCP, REST, the available tools, safe use, and connection verification.

Fetch and follow the instructions to connect me to the BlueLux API and MCP from https://bluelux.com/agent-setup/prompt.md

Integration resources

Setup documentOne complete guide for people and agents Tool catalogCurrent tool names and input schemas OpenAPI 3.1REST contract for applications MCP manifestRemote server registration metadata DatasetsTargets, factors, bands, and decision trees

Live request

Try a tool

Choose a tool, edit the raw JSON request, and inspect the complete production response. No key is required.

Loading schemaPOST /api/v2/tools/calculate_pool_dose

ToolArguments (JSON)

By using these tools, you agree to the Terms of Service.

Raw response

Run the example to see the complete JSON response.

REST API

REST is the simplest option for scripts, backends, workflows, and agents with an HTTP tool. Read the catalog, choose a tool, and send a JSON object to its endpoint.

The chlorine example omits product strength so the response discloses the current generic profile. You can instead send a named product_profile_id or explicit product_strength_percent and product_density_g_ml overrides where supported. Total alkalinity is required for a field-confident acid or soda-ash result.

Shell: dose request

curl https://bluelux.com/api/v2/tools/calculate_pool_dose \
  -H 'Content-Type: application/json' \
  --data '{
    "chemical": "liquid_chlorine",
    "volume_gallons": 10000,
    "current": 1,
    "target": 5
  }'

JavaScript example

JavaScript: LSI request

const response = await fetch(
  "https://bluelux.com/api/v2/tools/calculate_lsi",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      ph: 7.8,
      total_alkalinity_ppm: 100,
      calcium_hardness_ppm: 400,
      temperature_f: 80,
      tds_ppm: 3200,
      cyanuric_acid_ppm: 50,
      calculation_profile: "bluelux_equilibrium_v1"
    })
  }
);

const data = await response.json();

MCP

Connect a compatible MCP client to https://bluelux.com/mcp. The server is public and does not require caller authentication. The setup document above includes ready-to-use Codex, Claude Code, Cursor, and generic client configuration.

Direct MCP tools/list request

Shell: MCP tools/list

curl https://bluelux.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "my-agent",
          "version": "1.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Tool reference

Open a tool to inspect its live JSON Schema, required fields, accepted values, units, omission behavior, and a request body you can copy.

Loading catalog

calculate_pool_doseCalculate exact and practical amounts for a specified chemical correction.

Attribute	Requirement	Type or values	Definition
`chemical`	Required	liquid_chlorine \| muriatic_acid \| sodium_bicarbonate \| calcium_chloride \| cyanuric_acid \| pool_salt \| soda_ash	Chemical or product family to calculate.
`context`	Optional	objectDefault: null	Optional explicit facility context.If omitted: Facility assessment is not performed; no residential defaults are inserted.
`context.use_type`	Optional	residential \| commercialDefault: null	Residential or commercial use, only when known.If omitted: Unknown; residential use is never inferred.
`context.water_body_type`	Optional	pool \| spa \| wading_pool \| spray_groundDefault: null	Pool, spa, wading pool or spray ground, only when known.If omitted: Unknown.
`context.facility_type`	Optional	private_residential \| hoa_apartment \| hotel \| gym_club \| municipal \| school \| therapy \| splash_pad \| otherDefault: null	Specific facility classification, such as private residential, HOA/apartment or hotel.If omitted: Unknown; use alone does not establish legal classification.
`context.environment`	Optional	indoor \| outdoorDefault: null	Indoor or outdoor setting, only when known.If omitted: Unknown.
`context.feed_method`	Optional	manual \| automatic \| mixedDefault: null	Manual, automatic or mixed chemical addition.If omitted: Unknown; manual-addition requirements are not silently assumed absent.
`context.sanitizer_system`	Optional	liquid_chlorine \| salt_generator \| trichlor \| dichlor \| bromine \| mixedDefault: null	Actual sanitizer delivery system, including salt generation or stabilized chlorine products.If omitted: Unknown; stabilizer use is not inferred.
`context.sanitizer`	Optional	chlorine \| bromineDefault: null	Chlorine or bromine sanitizer, only when known.If omitted: Unknown.
`context.jurisdiction`	Optional	stringmin length 1, max length 120Default: null	Applicable jurisdiction supplied by the caller.If omitted: Unknown. No jurisdiction is inferred.
`context.operating_profile_id`	Optional	stringmin length 1, max length 120Default: null	Explicit operating profile identifier.If omitted: No operating profile is inferred.
`application_policy_id`	Optional	stringDefault: null	Select bluelux_bounded_v1 explicitly to request its practical application quantities.If omitted: Only the exact correction is calculated; no practical recommendation or application projection is returned.
`volume_gallons`US gallons	Required	integermin 100, max 2000000	Total water volume used to scale the calculation.
`current`pH or ppm	Required	numbermin 0, max 100000	Current measured value. For acid and soda ash this is pH; otherwise it is concentration.
`target`pH or ppm	Required	numbermin 0, max 100000	Desired value after the calculated correction.
`product_profile_id`	Optional	stringmin length 1, max length 120Default: null	A named product profile from the published profile dataset.If omitted: The disclosed default profile for the selected chemical is used.
`product_strength_percent`%	Optional	numbergreater than 0, max 100Default: null	Explicit active strength or purity override.If omitted: The resolved product profile supplies strength.
`product_concentration_basis`	Optional	available_chlorine_trade_percent \| available_chlorine_weight_percent \| sodium_hypochlorite_weight_percentDefault: null	Liquid chlorine only. Without property overrides, use the selected profile's basis and density. A strength-only override means trade percent; explicit weight bases require strength and density.
`product_density_g_ml`g/mL	OptionalMuriatic acid only.	numbergreater than 0, max 3Default: null	Explicit acid product density override when the label or SDS supports it.
`total_alkalinity_ppm`ppm	OptionalNeeded for field-confident muriatic acid and soda ash guidance.	numbermin 0, max 1000Default: null	Measured total alkalinity as calcium carbonate.
`cyanuric_acid_ppm`ppm	Optional	numbermin 0, max 1000Default: null	Measured cyanuric acid used for chlorine context and carbonate alkalinity correction.If omitted: The response discloses the contract default or provisional calculation path.
`borates_ppm_as_boron`ppm as boron	OptionalMuriatic acid and soda ash only.	numbermin 0, max 1000Default: null	Borate reading used by the pH adjustment model.
`free_chlorine_ppm`ppm	OptionalMuriatic acid and soda ash only.	numbermin 0, max 100Default: null	Free chlorine reading used by the pH adjustment model.
`temperature_f`°F	Optional	numbermin 32, max 140Default: null	Water temperature.If omitted: The response discloses any default used.
`tds_ppm`ppm	Optional	numbergreater than 0, max 20000Default: null	Total dissolved solids.If omitted: The response discloses any default used.

POST /api/v2/tools/calculate_pool_dose

{
  "chemical": "liquid_chlorine",
  "volume_gallons": 10000,
  "current": 1,
  "target": 5,
  "application_policy_id": null,
  "context": {
    "use_type": null,
    "water_body_type": null,
    "sanitizer": null
  }
}

calculate_lsiCalculate LSI using the versioned BlueLux chemistry contract.

Attribute	Requirement	Type or values	Definition
`ph`pH	Required	numbermin 0, max 14	Measured water pH.
`total_alkalinity_ppm`ppm	RequiredNeeded for field-confident muriatic acid and soda ash guidance.	numbergreater than 0, max 1000	Measured total alkalinity as calcium carbonate.
`calcium_hardness_ppm`ppm	Required	numbergreater than 0, max 10000	Measured calcium hardness as calcium carbonate.
`temperature_f`°F	Optional	numbermin 32, max 140Default: null	Water temperature.If omitted: The response discloses any default used.
`tds_ppm`ppm	Optional	numbergreater than 0, max 100000Default: null	Total dissolved solids.If omitted: The response discloses any default used.
`cyanuric_acid_ppm`ppm	Optional	numbermin 0, max 1000Default: null	Measured cyanuric acid used for chlorine context and carbonate alkalinity correction.If omitted: The response discloses the contract default or provisional calculation path.
`calculation_profile`	Optional	bluelux_equilibrium_v1 \| phta_2024_table_v1Default: bluelux_equilibrium_v1	Versioned LSI calculation profile.If omitted: The revised BlueLux equilibrium profile is selected.

POST /api/v2/tools/calculate_lsi

{
  "ph": 7.8,
  "total_alkalinity_ppm": 100,
  "calcium_hardness_ppm": 400,
  "temperature_f": 80,
  "tds_ppm": 3200,
  "cyanuric_acid_ppm": 50
}

list_product_profilesList the versioned product profiles used by deterministic calculations.

This tool accepts an empty JSON object; it has no input attributes.

POST /api/v2/tools/list_product_profiles

{}

get_product_profileGet the properties and version of one calculation product profile.

Attribute	Requirement	Type or values	Definition
`profile_id`	Required	string	Identifier of a published versioned product profile.

POST /api/v2/tools/get_product_profile

{
  "profile_id": "bluelux-liquid-chlorine-12_5"
}

get_metals_protocolReturn the diagnostic sequence for suspected metal staining or colored water.

Attribute	Requirement	Type or values	Definition
`symptom`	Optional	stringmax length 500	Plain-language observation used to focus the diagnostic protocol.If omitted: The response returns the general protocol.
`confirmed_metal`	Optional	iron \| copper \| manganese \| unknown	Metal identified by a reliable test, or unknown.If omitted: The metal is treated as unknown.

POST /api/v2/tools/get_metals_protocol

{
  "symptom": "rust-colored stains after chlorine was added",
  "confirmed_metal": "iron"
}

get_nutrient_thresholdsInterpret phosphate and nitrate readings as operating context rather than universal health limits.

Attribute	Requirement	Type or values	Definition
`phosphate_ppb`ppb	Optional	number	Measured orthophosphate result.If omitted: Phosphate-specific interpretation is omitted.
`nitrate_ppm`ppm	Optional	number	Measured nitrate result.If omitted: Nitrate-specific interpretation is omitted.

POST /api/v2/tools/get_nutrient_thresholds

{
  "phosphate_ppb": 500,
  "nitrate_ppm": 12
}

diagnose_filter_circulationReturn deterministic checks from pressure, flow, and pump-prime observations.

Attribute	Requirement	Type or values	Definition
`filter_pressure_psi`psi	Optional	number	Current operating filter pressure.If omitted: No numeric pressure comparison is produced.
`baseline_pressure_psi`psi	Optional	number	Clean-filter pressure for this equipment under comparable conditions.If omitted: No percentage change from baseline is produced.
`visible_flow`	Optional	normal \| low \| none \| surging	Observed return-flow condition.
`pump_primed`	Optional	boolean	Whether the pump has a stable water-filled prime.

POST /api/v2/tools/diagnose_filter_circulation

{
  "filter_pressure_psi": 22,
  "baseline_pressure_psi": 14,
  "visible_flow": "low",
  "pump_primed": true
}

get_seasonal_checklistReturn an ordered residential or public-facility checklist.

Attribute	Requirement	Type or values	Definition
`action`	Required	startup \| shutdown	Checklist direction.
`facility_type`	Optional	residential \| public	Residential or public-facility context.If omitted: Residential is used by the current tool.

POST /api/v2/tools/get_seasonal_checklist

{
  "action": "startup",
  "facility_type": "residential"
}

search_playbookReturn ranked Playbook passages with versions, sources, and canonical URLs.

Attribute	Requirement	Type or values	Definition
`query`	Required	stringmin length 2, max length 500	Natural-language Playbook search query.
`limit`	Optional	integermin 1, max 8	Maximum number of ranked passages to return.If omitted: The service applies its default result count.

POST /api/v2/tools/search_playbook

{
  "query": "free chlorine is low and pH is high",
  "limit": 3
}

plan_pool_treatmentStateless maintenance guidance from supplied readings and the selected versioned policy. Preserve notice, holds, units and warnings.

Attribute	Requirement	Type or values	Definition
`policy_profile`	Optional	object	Exact treatment policy profile_id and version. Explicit null is invalid.If omitted: Supported residential chlorine pools use bluelux-residential-maintenance@1.0.0. Other contexts use bluelux-context-review@1.0.0 with treatment holds. The response reports defaulted status.
`policy_profile.profile_id`	Required	stringmin length 1, max length 120	See the live OpenAPI contract for this field.
`policy_profile.version`	Required	stringmin length 1, max length 40	See the live OpenAPI contract for this field.
`custom_products`	Optional	object	Explicit strength, concentration basis and applicable density by chemical. Mutually exclusive with a named profile for that chemical; see the integration guide.
`volume_gallons`US gallons	Optional	integermin 100, max 2000000Default: null	Total water volume used to scale the calculation.
`ph`pH	Optional	numbermin 0, max 14Default: null	Measured water pH.
`free_chlorine`	Optional	numbermin 0, max 100Default: null	See the live OpenAPI contract for this field.
`total_chlorine`	Optional	numbermin 0, max 100Default: null	See the live OpenAPI contract for this field.
`total_alkalinity`	Optional	numbermin 0, max 1000Default: null	See the live OpenAPI contract for this field.
`cyanuric_acid`	Optional	numbermin 0, max 1000Default: null	See the live OpenAPI contract for this field.
`calcium_hardness`	Optional	numbermin 0, max 10000Default: null	See the live OpenAPI contract for this field.
`salt`	Optional	numbermin 0, max 10000Default: null	See the live OpenAPI contract for this field.
`tds`	Optional	numbermin 0, max 20000Default: null	See the live OpenAPI contract for this field.
`temperature`	Optional	numbermin 32, max 140Default: null	See the live OpenAPI contract for this field.
`algae`	Optional	none \| some \| heavyDefault: null	See the live OpenAPI contract for this field.
`scale`	Optional	none \| some \| heavyDefault: null	See the live OpenAPI contract for this field.
`water_clarity`	Optional	clear \| cloudy \| greenDefault: null	See the live OpenAPI contract for this field.
`organic_load`	Optional	low \| medium \| highDefault: null	See the live OpenAPI contract for this field.
`leaf_load`	Optional	unknown \| low \| medium \| highDefault: null	See the live OpenAPI contract for this field.
`algae_history`	Optional	none \| recent \| recurringDefault: null	See the live OpenAPI contract for this field.
`algae_prone`	Optional	unknown \| none \| recent \| recurringDefault: null	See the live OpenAPI contract for this field.
`sun_exposure`	Optional	unknown \| full_sun \| mixed \| heavy_shadeDefault: null	See the live OpenAPI contract for this field.
`circulation`	Optional	unknown \| good \| poorDefault: null	See the live OpenAPI contract for this field.
`circulation_risk`	Optional	unknown \| good \| watch \| poorDefault: null	See the live OpenAPI contract for this field.
`salt_cell_status`	Optional	unknown \| ok \| needs_maintenance \| offlineDefault: null	See the live OpenAPI contract for this field.
`tablet_status`	Optional	unknown \| empty \| low \| adequateDefault: null	See the live OpenAPI contract for this field.
`context`	Optional	objectDefault: null	Optional explicit facility context.If omitted: Facility assessment is not performed; no residential defaults are inserted.
`context.use_type`	Optional	residential \| commercialDefault: null	Residential or commercial use, only when known.If omitted: Unknown; residential use is never inferred.
`context.water_body_type`	Optional	pool \| spa \| wading_pool \| spray_groundDefault: null	Pool, spa, wading pool or spray ground, only when known.If omitted: Unknown.
`context.facility_type`	Optional	private_residential \| hoa_apartment \| hotel \| gym_club \| municipal \| school \| therapy \| splash_pad \| otherDefault: null	Specific facility classification, such as private residential, HOA/apartment or hotel.If omitted: Unknown; use alone does not establish legal classification.
`context.environment`	Optional	indoor \| outdoorDefault: null	Indoor or outdoor setting, only when known.If omitted: Unknown.
`context.feed_method`	Optional	manual \| automatic \| mixedDefault: null	Manual, automatic or mixed chemical addition.If omitted: Unknown; manual-addition requirements are not silently assumed absent.
`context.sanitizer_system`	Optional	liquid_chlorine \| salt_generator \| trichlor \| dichlor \| bromine \| mixedDefault: null	Actual sanitizer delivery system, including salt generation or stabilized chlorine products.If omitted: Unknown; stabilizer use is not inferred.
`context.sanitizer`	Optional	chlorine \| bromineDefault: null	Chlorine or bromine sanitizer, only when known.If omitted: Unknown.
`context.jurisdiction`	Optional	stringmin length 1, max length 120Default: null	Applicable jurisdiction supplied by the caller.If omitted: Unknown. No jurisdiction is inferred.
`context.operating_profile_id`	Optional	stringmin length 1, max length 120Default: null	Explicit operating profile identifier.If omitted: No operating profile is inferred.
`reading_source`	Optional	digital \| taylor_kit \| strip \| unknownDefault: null	See the live OpenAPI contract for this field.
`confirmed_readings`	Optional	arrayDefault: null	See the live OpenAPI contract for this field.
`product_profile_ids`	Optional	objectDefault: null	Named products from the existing public catalog, keyed by chemical.
`reading_times`	Optional	object	Measurement ISO date/time per field; explicit null means date unknown. Chat stamps newly submitted readings as just taken unless the technician supplies another date. Preserve stored dates on reuse.If omitted: Newly supplied readings are treated as just taken.
`reading_origins`	Optional	object	Source of each supplied reading: provided, image, history or unknown.If omitted: Provided is reported for newly submitted readings.

POST /api/v2/tools/plan_pool_treatment

{
  "volume_gallons": 20000,
  "ph": 7.8,
  "free_chlorine": 1,
  "total_alkalinity": 80,
  "cyanuric_acid": 40,
  "calcium_hardness": 350,
  "temperature": 80,
  "tds": 1500,
  "context": {
    "use_type": "residential",
    "water_body_type": "pool",
    "sanitizer": "chlorine"
  }
}

list_policy_profilesDiscover supported scope, versions and documented defaults.

This tool accepts an empty JSON object; it has no input attributes.

POST /api/v2/tools/list_policy_profiles

{}

get_policy_profileResolve an exact policy ID and version without fallback.

Attribute	Requirement	Type or values	Definition
`profile_id`	Required	string	Identifier of a published versioned product profile.
`version`	Required	string	Exact available policy version from discovery; never silently falls back.

POST /api/v2/tools/get_policy_profile

{
  "profile_id": "bluelux-residential-maintenance",
  "version": "1.0.0"
}

Results and errors

Successful resultsChemistry tools return versioned facts: supplied inputs, calculation status, facility assessment, quantities, constraints, reason codes and provenance. The website explains those facts locally; integrations should use the structured fields rather than display wording. Dose results separate exact_amount from recommended_amount and disclose rounding, caps, remaining modeled correction, and the selected product profile.

ErrorsInvalid inputs return structured 4xx errors. If the calculation service is unavailable, the API returns an error instead of inventing a result.

The engine behind the API

Informed by BlueLux Operator

BlueLux Operator is the agent-first operating platform we are building for professional pool operators. The public API is a narrow, documented calculation surface and does not provide access to private customer data or operating workflows.

Learn about BlueLux Operator and register interest

Safety and operating scope

These tools provide calculations and operating guidance from the inputs supplied. Confirm pool volume, measurements, units, product concentration, and facility type. Follow the returned scope and sources. Product labels, Safety Data Sheets, manufacturer instructions, emergency directions, and controlling codes take precedence. Public aquatic facilities require facility-plan and jurisdiction review.