Get started
Create a key in the Pooli Pro app, then call the REST API, or connect an AI assistant with OAuth and no key. Pro uses the same Pooli account and the same API Keys screen.
Generate a key
- Open Settings.
- Under Account & Services, tap API Keys.
- Tap Generate API Key.
The API key created dialog shows a masked key. Copy key only copies the key. The Authorization header row has its own Copy authorization header button, which copies the full Bearer <key> value.
Keys stay in the list, so you can copy them later. Each key row also has the Authorization header copy. Treat a key like a password. Tap Delete on its row to revoke it immediately.
REST
Send this header on every request. Bearer is the literal word, then one space, then the key:
Authorization: Bearer <API_KEY>
The API Keys screen also shows a copyable User ID for REST routes that take {uid}. Organization routes take {orgId} instead. The same key works on those routes when its user is an owner, an admin, or an active technician. GET /v1/me returns the user id too.
Connect an AI assistant (MCP)
Connect Claude, ChatGPT, or Grok with the Pooli connector. You sign in with your Pooli account in the browser, so there is no API key to copy. The server exposes 22 tools: 12 personal logging tools, plus 10 Pooli Pro organization tools for route, stops, jobs, and service reports.
MCP: connector URL, personal and organization tool list, and advanced API key setup. Step by step for each app: Connect Pooli to your AI assistant.
Rate limits
Requests are rate limited per hour. Accounts with an active owner premium (Pool Club) subscription are limited to 150 requests per hour. Standard accounts are limited to 10 requests per hour. The limit is per user and is shared by all of that user's API keys and connected AI assistants. See Rate Limiting and Quotas.
MCP
The Pooli MCP server lets Claude, ChatGPT, Grok, and other MCP clients act as you in Pooli Pro. Sign in with OAuth in the browser. There is no API key to copy. The server registers 22 tools: 12 personal logging tools, and 10 Pooli Pro organization tools. Organization tools are always on the server. They refuse if the signed-in account has no organization.
Connect
- Connector URL:
https://mcp.pooli.app/mcp - Sign in: OAuth. The assistant opens a Pooli sign-in page and you approve access. Pooli then gives the assistant its own API key.
- Disconnect: delete the assistant's key in the app under AI Assistants and API Keys.
https://mcp.pooli.app/mcp
Step by step for Claude, ChatGPT, and Grok: Connect Pooli to your AI assistant. Developers building a client can read OAuth sign-in.
Tools
Ask in plain language and the assistant picks the right tool. With exactly one organization, that organization is used automatically.
Personal / logging
12 tools for pools on the signed-in account.
| Tool | What it does |
|---|---|
whoami | Shows which Pooli account you are signed in as, your organizations and role, whether Club or a technician seat is covered, and how many requests you have left this hour. |
resolve_pool | Finds a pool by a fragment of its name, such as "oasis". Leave the name out to list your pools. |
list_maintenance_catalog | Lists the maintenance tasks you can record, built in and custom. |
match_maintenance | Matches a phrase like "brushed the walls" to catalog tasks before recording. |
record_maintenance | Records maintenance tasks on a pool. |
record_note | Adds a note to a pool. It can include photos (JPEG, PNG, GIF, or WebP, up to 4 per call). |
update_note | Edits a note, or adds more photos to it. Photos are added, never replaced. |
record_test | Records a water test: pH, chlorine, alkalinity, cyanuric acid, and the other readings. |
record_product | Records a chemical or product you added, with amount and unit. |
record_meter | Records a meter reading: pressure, temperature, salt cell, feeder, or water. |
record_swim | Records a swim: number of swimmers and duration. |
record_visit | Turns one sentence into several logs. Example: "emptied the skimmers and brushed the walls at the oasis". |
Pooli Pro / organization
10 tools for the signed-in organization. They are always registered. They refuse if the account has no organization. One organization is used automatically. With several, the assistant asks which one. Accounts without an organization keep using the personal tools above.
| Tool | What it does |
|---|---|
search_customers | Finds a customer by name, email, phone, or address, and shows their pools. |
my_route | Lists stops for today, or for a date you name, with the pool, address, and which photos each stop needs. |
add_stop | Schedules a new stop for a pool, at the local time you say. |
set_org_time_zone | Owners and admins only. Changes the organization's time zone. |
start_stop | Starts the job when you arrive. It tells you which photos are still needed. |
pause_job | Pauses an in-progress job. |
resume_job | Resumes a paused job. |
add_job_photo | Adds before, after, or gate photos to the job. |
complete_job | Finishes the job. If a required photo is missing, it names it and nothing is completed. |
send_report | Shows you who will get the service report and a preview. It emails the customer only after you confirm. |
Logging tools (record_test, record_maintenance, and so on) still work during a Pro stop if you pass the poolId from my_route or start_stop.
A stop, start to finish
- "What is on my route today?" The assistant calls
my_route. - "Start the Martinez stop." It calls
start_stop. - Log the work with
record_test,record_maintenance,record_product, andadd_job_photo. - "Finish the job." It calls
complete_job. If a required photo is missing, it names it and nothing is completed. - "Send the report." The assistant shows the recipients and a preview. It emails the customer only after you confirm.
Technicians can schedule only their own stops and work only their own visits. Owners and admins can schedule any technician.
Advanced: connect with an API key
Use an API key only when a client cannot sign in with OAuth but can set a request header. Never paste a key into a chat message.
- Server URL:
https://mcp.pooli.app/mcp - Transport: Streamable HTTP
- Header name:
Authorization - Header value:
Bearer <API_KEY>. Use Copy authorization header to copy the full value.
Some clients take the key alone and add Bearer themselves. If the client has a separate token or API key field, paste just the key into that field.
No user ID is needed for MCP. The server resolves your account from the key or from the OAuth sign-in. Note and job photo tools can attach photos (JPEG, PNG, GIF, or WebP, about 1.5 MB each, 4 per call, 12 photos per note).
API Overview
The Pooli API is the same platform API used by Pooli Pro. Route owners use it to connect organization data (technicians, pools, logs, inventory, and reminders) to internal tools, billing systems, and custom workflows. Homeowner-scoped endpoints still exist for accounts that also use the consumer app.
Version: 1.0 (Alpha). Date: August 4, 2025
This is a beta API and may change. Organization endpoints are the ones Pro teams should start with.
What Pro teams typically automate
- Organization technicians: list techs, filter by status, and update approval state.
- Organization pools: pull the route book, including assigned vs unassigned stops.
- Service logs: write and read water tests, treatments, and visit history.
- Inventory: read stock levels across warehouse and vehicle locations.
- CSV import: bulk-load customers, pools, and products from the app or dashboard.
Generate keys in the Pooli Pro app (same account you use to log in). See Get started. To connect Claude, ChatGPT, or Grok, see MCP. Questions and feature requests: support@pooli.app or kevin@pooli.app.
This page is a Pro-branded copy of the pooli.app API docs. See the sync plan at the bottom of this page for how the two sites stay aligned.
Rate Limiting and Quotas
Rate limits keep the API fair and stable. The window is one hour. Limits vary by account status (owner premium / Club access versus standard).
Owner premium (Club) accounts
Accounts with an active owner premium (Pool Club) subscription are limited to 150 requests per hour.
Standard accounts
Standard accounts are limited to 10 requests per hour.
Shared across keys and assistants
The limit is per user. All of a user's API keys and connected AI assistants count against the same hourly total.
Stay inside these hourly limits to avoid interruptions. Questions: support@pooli.app.
Authentication
Securing your data is paramount. Our API uses API keys to authenticate requests. AI assistants get a regular API key through the OAuth sign-in. Each key is user-specific, ensuring secure access to your Pooli documents. Follow these steps to authenticate your API requests:
Step 1: Generate Your API Key
Create your API key in the Pooli Pro app. The screens and buttons are in Get started. The key belongs to your user and provides access to that user's documents.
Rate Limiting
Rate limiting is applied on a per-user basis to ensure fair usage and system stability. Be mindful of your request frequency to stay within the rate limits.
Using the API Key
Send the API key on every request as Authorization: Bearer YOUR_API_KEY. Bearer is the literal word, then one space, then the key. Routes that take {uid} use the User ID from the API Keys screen. See Get started.
API Base URLs
The Pooli API is available at the following endpoints:
- Production:
https://api.pooli.app - Development:
https://dev-api.pooli.app
OAuth sign-in for AI assistants and apps
The Pooli MCP connector signs users in with OAuth instead of an API key. The user approves access in the browser, and the client gets a regular Pooli API key that runs as that user. The tools the server exposes are listed under MCP. Any MCP client or app that supports OAuth with dynamic client registration can use the same flow. API keys stay supported as the advanced option.
- Issuer:
https://api.pooli.app - Metadata:
GET https://api.pooli.app/.well-known/oauth-authorization-server - Scope:
pooli - Resource:
https://mcp.pooli.app/mcp
curl 'https://api.pooli.app/.well-known/oauth-authorization-server'
Read the endpoint URLs from the metadata document rather than hard-coding them.
Register a client
Endpoint: POST /oauth/register
Description: Dynamic client registration. Register to get a client ID, then use it on the authorize and token requests. Registration is stateless. The client ID is signed, so Pooli does not keep a client record.
Authorize
Endpoint: GET /oauth/authorize
Description: Sends the user to the Pooli sign-in and approval page. Send response_type=code, your client_id, redirect_uri, scope=pooli, resource=https://mcp.pooli.app/mcp, a state value, and a PKCE challenge with code_challenge_method=S256. PKCE with S256 is required.
Authorization responses include the iss parameter (RFC 9207). Check that it equals https://api.pooli.app before you use the code.
https://api.pooli.app/oauth/authorize
?response_type=code
&client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&scope=pooli
&resource=https%3A%2F%2Fmcp.pooli.app%2Fmcp
&state=STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
The redirect URI must match a registered one exactly. For loopback redirect URIs, the port can differ from the one you registered.
Token
Endpoint: POST /oauth/token
Description: Exchanges an authorization code for a Pooli API key. The body is form-encoded (application/x-www-form-urlencoded), not JSON.
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=AUTHORIZATION_CODE" \
--data-urlencode "redirect_uri=REDIRECT_URI" \
--data-urlencode "client_id=CLIENT_ID" \
--data-urlencode "code_verifier=CODE_VERIFIER" \
'https://api.pooli.app/oauth/token'
The access_token in the response is a regular Pooli API key. It starts with pooli_oak_. The response has no expires_in and no refresh_token, because the key does not expire. It works until the user deletes it. Store it like any other secret.
Revoke
Endpoint: POST /oauth/revoke
Description: Revokes the access token you send, which deletes that API key. Users can also delete the key in the Pooli app, as described below.
Using the OAuth key
Send the pooli_oak_ key to the API as a Bearer credential, exactly like any other API key:
curl -X GET \
-H "Authorization: Bearer pooli_oak_YOUR_KEY" \
'https://api.pooli.app/v1/me'
A key that was deleted gets a 401 with this header. Send the user through sign-in again to get a new key:
WWW-Authenticate: Bearer error="invalid_token"
The OAuth key uses the same rate limits as any API key: 10 requests per hour, or 150 per hour for Club. There is one limit per user, shared by all of that user's API keys and connected assistants. See Rate Limiting and Quotas.
Connected assistants appear in the app's existing API keys list, labeled with the assistant's name and the date it was connected. To disconnect one, delete that key in the app under AI Assistants and API Keys. There is no separate list of connected apps.
Not supported
Client ID Metadata Documents (CIMD, where the client ID is a URL) are not supported. Register with POST /oauth/register instead.
Versioning
API versions are specified in the url. The current version is v1. For example, to fetch all pools for a user:
curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
'https://api.pooli.app/v1/users/YOUR_USER_ID/pools'
To fetch a specific pool:
curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
'https://api.pooli.app/v1/users/YOUR_USER_ID/pools/YOUR_POOL_ID'
Replace YOUR_ACCESS_TOKEN, YOUR_USER_ID, and YOUR_POOL_ID with your actual API token, user ID, and pool ID respectively.
Organization endpoints
These are the first-class Pro routes. All require a signed-in organization context.
Organization Endpoints
These endpoints allow organizations to manage their resources including technicians, pools, and logs. Organization access requires proper authentication and authorization.
Technician Management
Get Organization Technicians
Endpoint: GET /:orgId/technicians
Description: Retrieves all technicians associated with the organization.
Parameters: orgId (path) - Organization ID.
Query Parameters: status (optional) - Filter by technician status (e.g., "pending").
Update Technician Status
Endpoint: POST /:orgId/technicians/:techId/status
Description: Approve or reject a technician request.
Parameters: orgId (path) - Organization ID, techId (path) - Technician ID.
Body Parameters: status (string) - New status, message (string, optional) - Status message.
Pool Management
Get All Organization Pools
Endpoint: GET /:orgId/pools
Description: Retrieves all pools associated with the organization. Includes sanitized data.
Parameters: orgId (path) - Organization ID.
Query Parameters: assigned (optional) - Filter for assigned/unassigned pools.
Get Specific Organization Pool
Endpoint: GET /:orgId/pools/:poolId
Description: Retrieves detailed information about a specific pool.
Parameters: orgId (path) - Organization ID, poolId (path) - Pool ID.
Create Organization Pool
Endpoint: POST /:orgId/pools
Description: Creates a new pool for the organization. Uses the same pool data format as user pools.
Parameters: orgId (path) - Organization ID.
Body Parameters: pool (object) - Pool data with same structure as user pool creation.
name and gallonEstimate are required. isIndoor is a boolean and defaults to false. Sending isIndoor: true is accepted. New pools do not get a built-in target table copied onto them. A test log falls back to your saved default targets, then the built-in table for the pool type.
Example Pool Object:
{
"name": "Organization Pool 1",
"poolType": "plaster",
"filterCategory": "cartridge",
"sanitizingChemical": "chlorine",
"gallonEstimate": 20000,
"isIndoor": false,
"supplimentalSanitizers": ["mineral"]
}
Delete Organization Pool
Endpoint: DELETE /:orgId/pools/:poolId
Description: Deletes a specific pool from the organization.
Parameters: orgId (path) - Organization ID, poolId (path) - Pool ID.
Log Management
Get Organization Pool Logs
Endpoint: GET /:orgId/pools/:poolId/logs
Description: Retrieves all log entries for an organization pool. Supports pagination and filtering.
Parameters: orgId (path) - Organization ID, poolId (path) - Pool ID.
Query Parameters: startAfter (optional) - Pagination cursor, type (optional) - Log type filter.
Get Specific Organization Log
Endpoint: GET /:orgId/pools/:poolId/logs/:logId
Description: Retrieves a specific log entry for an organization pool.
Parameters: orgId (path) - Organization ID, poolId (path) - Pool ID, logId (path) - Log ID.
Create Organization Pool Log
Endpoint: POST /:orgId/pools/:poolId/logs
Description: Creates a new log entry for an organization pool. Uses the same log structure and types as user logs.
Creating type=test runs the same analysis as saving a water test in the app. The server stores relatedProblems, recommendations, csi and targets on the log. It works the same way as the user route. The 201 response data is still only the log id, so read the log to see the results. A client-sent relatedProblems or recommendations value is replaced. A client-sent targets object is used as sent.
Readings. Send readings in chemicalReading. Four keys are new: mg, kh, nitrites and nitrates. Each is a number or null, like the other reading keys.
What is stored.
relatedProblems: the problems found, in the same form the app saves. A test problem haswaterTestType,testVal,lowRange,highRange,problemType,problemClassanddoseToCenter. Chlorine problems also haveadjustedForCYAandcyaValUsedForAdjustmentwhen the CYA-adjusted band was used. A combined problem is also possible.recommendations: one entry per problem, in the order the app shows them. Each entry hasproblemTypeanditems. An item hasproduct(name,productType,percent,custom, or null when no product fits),amount,unit(fluidOunces,ounces,pounds,gallonsand so on) andwaits. A wait hasuntil(nextTreatment,retestorswim),minutes(or null) and, for some waits, aconditionandtestType. A combined problem has one item per fix, andoptionProblemTypenames the problem each item fixes.csi:valueis the Langelier saturation index, or null when it cannot be worked out.confidenceishigh,mediumorlow, and it drops when hardness or temperature had to be estimated.targets: the target ranges the analysis used, in the app's targets shape.
How the analysis works. Free and total chlorine use the CYA-adjusted band when adjust for CYA is on. That setting is on by default when CYA is a visible test and the pool has not turned it off. Saved FC and TC minimums do not replace that band. Alkalinity problems store adjusted alkalinity, the app default. A derived calcium or total hardness pair is ignored, and a total hardness reading alone can drive CSI. Retest minutes scale with pool size, pool type, how far the dose moves the reading, and how close the reading is to the edge of its range. Products come from the current product catalog, your custom products, your saved default product for each type, and the products hidden on the pool. Targets come from the pool, then your saved default targets, then the built-in table for the pool type. Earlier tests on the pool inside the app lookback window fill in readings this test left out (CSI and CYA).
Known limits.
- The API always uses US units (gallons, fluid ounces, ounces, pounds). The metric display settings in the app do not change it.
- The API does not use inventory links or the product choice made in the phone's product picker.
- Changing
chemicalReadinglater with PATCH does not rerun the analysis. Create a new test to get new results. - Default targets saved at the organization level are not applied.
- For a back-dated test, CSI history is measured from the test's own time.
Parameters: orgId (path) - Organization ID, poolId (path) - Pool ID.
Query Parameters: type (required) - Log type (test, maintenance, product, etc.).
Body Parameters: Log data structure varies by type - see log types section below.
Example Test Log Creation:
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chemicalReading": {
"temp": 78,
"orp": 500,
"ph": 7.1,
"alkalinity": 100,
"calcium": 250,
"cyanuricAcid": 50
}
}' \
'https://api.pooli.app/v1/organizations/{orgId}/pools/{poolId}/logs?type=test'
Example Test Log Creation with the new readings:
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chemicalReading": {
"ph": 7.9,
"freeChlorine": 3,
"alkalinity": 90,
"calcium": 300,
"mg": 40,
"kh": 80,
"nitrites": 0,
"nitrates": 10
}
}' \
'https://api.pooli.app/v1/organizations/{orgId}/pools/{poolId}/logs?type=test'
# 201
{"success":true,"message":"created","data":"LOG_ID"}
# GET .../logs/LOG_ID (excerpt)
{
"id": "LOG_ID",
"type": "test",
"relatedProblems": [{"problemType":"highPH","waterTestType":"ph","testVal":7.9}],
"recommendations": [
{
"problemType": "highPH",
"items": [{
"product": {"name":"Muriatic Acid","productType":"phDown","percent":14.5,"custom":false},
"amount": 37.5,
"unit": "fluidOunces",
"waits": [
{"until":"nextTreatment","minutes":15},
{"until":"retest","minutes":60}
]
}]
}
],
"csi": {"value":0.1,"confidence":"high"},
"targets": { ... }
}
Note create
POST /v1/organizations/{orgId}/pools/{poolId}/logs?type=note accepts a JSON photos array. Do not use multipart. Each item is a base64 string, or an object { "data": "<base64 or data URL>", "filename": "skimmer.jpg", "contentType": "<ignored>" }. contentType is ignored. The server sniffs the image type from the bytes. Allowed types are JPEG, PNG, GIF, and WebP. PDF, HEIC, HEIF, and AVIF are rejected. Create with photos requires note (string). Do not send attachments and photos together. An empty photos array is ignored. The unversioned /organizations/{orgId}/... alias accepts the same body.
Caps are 1.5 MB (1,500,000 decoded bytes) per photo, 4 photos per request, and 12 photos per note. The JSON body limit is 10 MB. A create with photos counts as one request for rate limiting (10 per hour, or 150 per hour for an active owner premium (Pool Club) subscription). See Rate Limiting and Quotas. The 201 body is unchanged: data is the new log id.
GET returns stored attachments. Each photo has this shape:
{
"attachmentType": "photo",
"firestorePath": "users/{uploaderUid}/{sha256}{ext}",
"description": "<filename or sha256+ext>",
"url": "<Firebase Storage download URL>"
}
Errors are JSON { "error", "message", "status" }. 400 Validation Error: unsupported type, bad base64, too many photos, photos on a non-note, or photos together with attachments. 413 File Too Large: a decoded photo is over 1,500,000 bytes. The wrong user or organization returns 403. A missing pool returns 404.
Example note with photos:
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"note":"Skimmer basket is full","creatorName":"Alex","photos":[{"filename":"skimmer.jpg","data":"<base64 JPEG, PNG, GIF, or WebP>"}]}' \
'https://api.pooli.app/v1/organizations/{orgId}/pools/{poolId}/logs?type=note'
# 201
{"success":true,"message":"Log created successfully","data":"LOG_ID"}
Update Organization Pool Log
Endpoint: PATCH /:orgId/pools/:poolId/logs/:logId
Description: Updates a log entry for an organization pool.
Note patch
When the stored log type is note, PATCH /v1/organizations/{orgId}/pools/{poolId}/logs/{logId} accepts the same JSON photos array as note create. PATCH appends photos. It does not replace photos already on the note. Omit photos for a text-only update. Do not use multipart. Each item is a base64 string, or an object { "data": "<base64 or data URL>", "filename": "skimmer.jpg", "contentType": "<ignored>" }. contentType is ignored. The server sniffs the image type from the bytes. Allowed types are JPEG, PNG, GIF, and WebP. PDF, HEIC, HEIF, and AVIF are rejected. Do not send attachments and photos together. An empty photos array is ignored.
Caps are 1.5 MB (1,500,000 decoded bytes) per photo, 4 photos per request, and 12 photos per note. The JSON body limit is 10 MB. A patch with photos counts as one request for rate limiting (10 per hour, or 150 per hour for an active owner premium (Pool Club) subscription). See Rate Limiting and Quotas.
GET and this PATCH return stored attachments. Each photo has this shape:
{
"attachmentType": "photo",
"firestorePath": "users/{uploaderUid}/{sha256}{ext}",
"description": "<filename or sha256+ext>",
"url": "<Firebase Storage download URL>"
}
Errors are JSON { "error", "message", "status" }. 400 Validation Error: unsupported type, bad base64, too many photos, photos on a non-note, or photos together with attachments. 413 File Too Large: a decoded photo is over 1,500,000 bytes. The wrong user or organization returns 403. A missing note or pool returns 404.
Example: append a photo:
curl -X PATCH \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"photos":[{"filename":"skimmer.jpg","data":"<base64 JPEG, PNG, GIF, or WebP>"}]}' \
'https://api.pooli.app/v1/organizations/{orgId}/pools/{poolId}/logs/{logId}'
Delete Organization Pool Log
Endpoint: DELETE /:orgId/pools/:poolId/logs/:logId
Description: Deletes a specific log entry from an organization pool. Deleting a note removes the log document. Storage objects for its photos are left in place, the same as the app.
Parameters: orgId (path) - Organization ID, poolId (path) - Pool ID, logId (path) - Log ID.
Organization Authentication
Access Requirements: Organization endpoints require that the API key holder is either:
- Organization Owner: User ID matches the organization's
ownerUserId - Active Technician: User exists in organization's technicians collection with
status: "active"
Error Response: Unauthorized users receive 403 Access denied: Not authorized for this organization
Customers & pools CSV import
Bulk import customers and pools. Upload in the app or call Firebase Callable customers-importCsv.
See the CSV Import Guide on pooli.app for columns and examples. A Pro-hosted copy of that guide is planned in a follow-up.
User endpoints
Still valid for accounts that also hold homeowner / personal pool data.
Pools Endpoints
Manage and retrieve information about pools with these endpoints. They allow you to fetch, create, and delete pool data associated with a specific user or organization.
GET Endpoints
-
Fetch All Pools
Endpoint:
GET /:uid/poolsDescription: Retrieves a list of all pools associated with the given user ID (uid). Includes sanitized data.
Parameters:
uid(path) - User ID for pool association. -
Fetch Specific Pool
Endpoint:
GET /:uid/pools/:poolIdDescription: Retrieves detailed information about a specific pool associated with the user ID (uid).
Parameters:
uid(path) - User ID,poolId(path) - Pool ID.
POST Endpoints
-
Create Pool
POST Endpoint: Create Pool
Endpoint:
POST /:uid/poolsDescription: Creates a new pool associated with the given user ID (uid). The pool data must adhere to a specific format, as outlined below.
URL Parameters:
uid(path) - User ID.Body Parameters: The
poolparameter is a complex object with the following properties:{ "name": [String], "poolType": ["vinyl", "plaster", "fiberglass", default: "plaster"], "filterCategory": ["de", "sand", "cartridge", default: "cartridge"], "sanitizingChemical": ["chlorine", "bromine", "swg", "biguanides", "peroxide", "natural", "freshwater"], "gallonEstimate": [Number], "isIndoor": [Boolean, default: false], "supplimentalSanitizers": ["mineral", "ozone", "uv", "ionize", "aop", "enzyme", "unknown", default: []], }nameandgallonEstimateare required.isIndooris a boolean and defaults to false. SendingisIndoor: trueis accepted. New pools do not get a built-in target table copied onto them. A test log falls back to your saved default targets, then the built-in table for the pool type.Each property in the
poolobject has specific data types and constraints. Some properties, such assanitizingChemical,poolType,filterCategory, andsupplimentalSanitizers, are restricted to predefined values as specified in their respective enums.
DELETE Endpoints
-
Delete Specific Pool
Endpoint:
DELETE /:uid/pools/:poolIdDescription: Deletes a specific pool identified by poolId for the given user ID (uid).
Parameters:
uid(path) - User ID,poolId(path) - Pool ID to be deleted.
Organization Pool Endpoints
These endpoints allow organizations to manage pools. Organization access requires proper authentication and authorization.
Organization GET Endpoints
-
Fetch All Organization Pools
Endpoint:
GET /:orgId/poolsDescription: Retrieves a list of all pools associated with the given organization ID. Includes sanitized data.
Parameters:
orgId(path) - Organization ID for pool association. -
Fetch Specific Organization Pool
Endpoint:
GET /:orgId/pools/:poolIdDescription: Retrieves detailed information about a specific pool associated with the organization ID.
Parameters:
orgId(path) - Organization ID,poolId(path) - Pool ID.
Organization POST Endpoints
-
Create Organization Pool
Endpoint:
POST /:orgId/poolsDescription: Creates a new pool associated with the given organization ID. Uses the same pool data format as user pools.
Parameters:
orgId(path) - Organization ID.Body Parameters: Same
poolobject structure as user pool creation.
Organization DELETE Endpoints
-
Delete Specific Organization Pool
Endpoint:
DELETE /:orgId/pools/:poolIdDescription: Deletes a specific pool identified by poolId for the given organization ID.
Parameters:
orgId(path) - Organization ID,poolId(path) - Pool ID to be deleted.
Logs Endpoints
These endpoints allow for the management and retrieval of log entries related to pool maintenance, tests, products, and more. Available for both user pools and organization pools.
GET Endpoints
-
Fetch All Logs for a Pool
Endpoint:
GET /:uid/pools/:poolId/logsDescription: Retrieves all log entries for a specific pool. Supports pagination and filtering by log type.
Parameters:
uid(path),poolId(path),startAfter(query, optional),type(query, optional). -
Fetch Specific Log Entry
Endpoint:
GET /:uid/pools/:poolId/logs/:logIdDescription: Retrieves a specific log entry by its ID for a given pool.
Parameters:
uid(path),poolId(path),logId(path).
POST Endpoint
-
Create Log Entry
Endpoint:
POST /:uid/pools/:poolId/logsDescription: Creates a new log entry for a pool. The log structure varies based on the log type.
Creating
type=testruns the same analysis as saving a water test in the app. The server storesrelatedProblems,recommendations,csiandtargetson the log. The 201 responsedatais still only the log id, so read the log to see the results. A client-sentrelatedProblemsorrecommendationsvalue is replaced. A client-senttargetsobject is used as sent.Readings. Send readings in
chemicalReading. Four keys are new:mg,kh,nitritesandnitrates. Each is a number or null, like the other reading keys.What is stored.
relatedProblems: the problems found, in the same form the app saves. A test problem haswaterTestType,testVal,lowRange,highRange,problemType,problemClassanddoseToCenter. Chlorine problems also haveadjustedForCYAandcyaValUsedForAdjustmentwhen the CYA-adjusted band was used. A combined problem is also possible.recommendations: one entry per problem, in the order the app shows them. Each entry hasproblemTypeanditems. An item hasproduct(name,productType,percent,custom, or null when no product fits),amount,unit(fluidOunces,ounces,pounds,gallonsand so on) andwaits. A wait hasuntil(nextTreatment,retestorswim),minutes(or null) and, for some waits, aconditionandtestType. A combined problem has one item per fix, andoptionProblemTypenames the problem each item fixes.csi:valueis the Langelier saturation index, or null when it cannot be worked out.confidenceishigh,mediumorlow, and it drops when hardness or temperature had to be estimated.targets: the target ranges the analysis used, in the app's targets shape.
How the analysis works. Free and total chlorine use the CYA-adjusted band when adjust for CYA is on. That setting is on by default when CYA is a visible test and the pool has not turned it off. Saved FC and TC minimums do not replace that band. Alkalinity problems store adjusted alkalinity, the app default. A derived calcium or total hardness pair is ignored, and a total hardness reading alone can drive CSI. Retest minutes scale with pool size, pool type, how far the dose moves the reading, and how close the reading is to the edge of its range. Products come from the current product catalog, your custom products, your saved default product for each type, and the products hidden on the pool. Targets come from the pool, then your saved default targets, then the built-in table for the pool type. Earlier tests on the pool inside the app lookback window fill in readings this test left out (CSI and CYA).
Known limits.
- The API always uses US units (gallons, fluid ounces, ounces, pounds). The metric display settings in the app do not change it.
- The API does not use inventory links or the product choice made in the phone's product picker.
- Changing
chemicalReadinglater with PATCH does not rerun the analysis. Create a new test to get new results. - Default targets saved at the organization level are not applied.
- For a back-dated test, CSI history is measured from the test's own time.
Parameters:
uid(path),poolId(path),type(query),data(body).Example Request:
curl -X POST \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "chemicalReading": { "temp": 78, "orp": 500, "ph": 7.1, "alkalinity": 100, "calcium": 250, "cyanuricAcid": 50 } }' \ 'https://api.pooli.app/v1/users/{userId}/pools/{poolId}/logs?type=test'Development Endpoint:
'https://api-dev.pooli.app/v1/users/{userId}/pools/{poolId}/logs?type=test'Example Request with the new readings:
curl -X POST \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "chemicalReading": { "ph": 7.9, "freeChlorine": 3, "alkalinity": 90, "calcium": 300, "mg": 40, "kh": 80, "nitrites": 0, "nitrates": 10 } }' \ 'https://api.pooli.app/v1/users/{userId}/pools/{poolId}/logs?type=test' # 201 {"success":true,"message":"created","data":"LOG_ID"} # GET .../logs/LOG_ID (excerpt) { "id": "LOG_ID", "type": "test", "relatedProblems": [{"problemType":"highPH","waterTestType":"ph","testVal":7.9}], "recommendations": [ { "problemType": "highPH", "items": [{ "product": {"name":"Muriatic Acid","productType":"phDown","percent":14.5,"custom":false}, "amount": 37.5, "unit": "fluidOunces", "waits": [ {"until":"nextTreatment","minutes":15}, {"until":"retest","minutes":60} ] }] } ], "csi": {"value":0.1,"confidence":"high"}, "targets": { ... } }Note create
POST /v1/users/{uid}/pools/{poolId}/logs?type=noteaccepts a JSONphotosarray. Do not use multipart. Each item is a base64 string, or an object{ "data": "<base64 or data URL>", "filename": "skimmer.jpg", "contentType": "<ignored>" }.contentTypeis ignored. The server sniffs the image type from the bytes. Allowed types are JPEG, PNG, GIF, and WebP. PDF, HEIC, HEIF, and AVIF are rejected. Create with photos requiresnote(string). Do not sendattachmentsandphotostogether. An emptyphotosarray is ignored. The unversioned/users/{uid}/...alias accepts the same body.Caps are 1.5 MB (1,500,000 decoded bytes) per photo, 4 photos per request, and 12 photos per note. The JSON body limit is 10 MB. A create with photos counts as one request for rate limiting (10 per hour, or 150 per hour for an active owner premium (Pool Club) subscription). See Rate Limiting and Quotas. The 201 body is unchanged:
datais the new log id.GET returns stored
attachments. Each photo has this shape:{ "attachmentType": "photo", "firestorePath": "users/{uploaderUid}/{sha256}{ext}", "description": "<filename or sha256+ext>", "url": "<Firebase Storage download URL>" }Errors are JSON
{ "error", "message", "status" }. 400 Validation Error: unsupported type, bad base64, too many photos, photos on a non-note, orphotostogether withattachments. 413 File Too Large: a decoded photo is over 1,500,000 bytes. The wrong user returns 403. A missing pool returns 404.Example request:
curl -X POST \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"note":"Skimmer basket is full","creatorName":"Alex","photos":[{"filename":"skimmer.jpg","data":"<base64 JPEG, PNG, GIF, or WebP>"}]}' \ 'https://api.pooli.app/v1/users/{userId}/pools/{poolId}/logs?type=note' # 201 {"success":true,"message":"Log created successfully","data":"LOG_ID"}
PATCH Endpoint
-
Update Log Entry
Endpoint:
PATCH /:uid/pools/:poolId/logs/:logIdDescription: Updates a log entry for a pool.
Note patch
When the stored log type is
note,PATCH /v1/users/{uid}/pools/{poolId}/logs/{logId}accepts the same JSONphotosarray as note create. PATCH appends photos. It does not replace photos already on the note. Omitphotosfor a text-only update. Do not use multipart. Each item is a base64 string, or an object{ "data": "<base64 or data URL>", "filename": "skimmer.jpg", "contentType": "<ignored>" }.contentTypeis ignored. The server sniffs the image type from the bytes. Allowed types are JPEG, PNG, GIF, and WebP. PDF, HEIC, HEIF, and AVIF are rejected. Do not sendattachmentsandphotostogether. An emptyphotosarray is ignored.Caps are 1.5 MB (1,500,000 decoded bytes) per photo, 4 photos per request, and 12 photos per note. The JSON body limit is 10 MB. A patch with photos counts as one request for rate limiting (10 per hour, or 150 per hour for an active owner premium (Pool Club) subscription). See Rate Limiting and Quotas.
GET and this PATCH return stored
attachments. Each photo has this shape:{ "attachmentType": "photo", "firestorePath": "users/{uploaderUid}/{sha256}{ext}", "description": "<filename or sha256+ext>", "url": "<Firebase Storage download URL>" }Errors are JSON
{ "error", "message", "status" }. 400 Validation Error: unsupported type, bad base64, too many photos, photos on a non-note, orphotostogether withattachments. 413 File Too Large: a decoded photo is over 1,500,000 bytes. The wrong user returns 403. A missing note or pool returns 404.Example request:
curl -X PATCH \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"photos":[{"filename":"skimmer.jpg","data":"<base64 JPEG, PNG, GIF, or WebP>"}]}' \ 'https://api.pooli.app/v1/users/{userId}/pools/{poolId}/logs/{logId}'
DELETE Endpoint
-
Delete Log Entry
Endpoint:
DELETE /:uid/pools/:poolId/logs/:logIdDescription: Deletes a specific log entry for a given pool. Deleting a note removes the log document. Storage objects for its photos are left in place, the same as the app.
Parameters:
uid(path),poolId(path),logId(path).
Organization Log Endpoints
These endpoints allow organizations to manage log entries for their pools. Organization access requires proper authentication and authorization.
Organization GET Endpoints
-
Fetch All Logs for an Organization Pool
Endpoint:
GET /:orgId/pools/:poolId/logsDescription: Retrieves all log entries for a specific organization pool. Supports pagination and filtering by log type.
Parameters:
orgId(path),poolId(path),startAfter(query, optional),type(query, optional). -
Fetch Specific Organization Log Entry
Endpoint:
GET /:orgId/pools/:poolId/logs/:logIdDescription: Retrieves a specific log entry by its ID for a given organization pool.
Parameters:
orgId(path),poolId(path),logId(path).
Organization POST Endpoint
-
Create Organization Log Entry
Endpoint:
POST /:orgId/pools/:poolId/logsDescription: Creates a new log entry for an organization pool. Uses the same log structure and types as user logs.
Parameters:
orgId(path),poolId(path),type(query),data(body).Note create
POST /v1/organizations/{orgId}/pools/{poolId}/logs?type=noteaccepts a JSONphotosarray. Do not use multipart. Each item is a base64 string, or an object{ "data": "<base64 or data URL>", "filename": "skimmer.jpg", "contentType": "<ignored>" }.contentTypeis ignored. The server sniffs the image type from the bytes. Allowed types are JPEG, PNG, GIF, and WebP. PDF, HEIC, HEIF, and AVIF are rejected. Create with photos requiresnote(string). Do not sendattachmentsandphotostogether. An emptyphotosarray is ignored. The unversioned/organizations/{orgId}/...alias accepts the same body.Caps are 1.5 MB (1,500,000 decoded bytes) per photo, 4 photos per request, and 12 photos per note. The JSON body limit is 10 MB. A create with photos counts as one request for rate limiting (10 per hour, or 150 per hour for an active owner premium (Pool Club) subscription). See Rate Limiting and Quotas. The 201 body is unchanged:
datais the new log id.GET returns stored
attachments. Each photo has this shape:{ "attachmentType": "photo", "firestorePath": "users/{uploaderUid}/{sha256}{ext}", "description": "<filename or sha256+ext>", "url": "<Firebase Storage download URL>" }Errors are JSON
{ "error", "message", "status" }. 400 Validation Error: unsupported type, bad base64, too many photos, photos on a non-note, orphotostogether withattachments. 413 File Too Large: a decoded photo is over 1,500,000 bytes. The wrong user or organization returns 403. A missing pool returns 404.Example request:
curl -X POST \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"note":"Skimmer basket is full","creatorName":"Alex","photos":[{"filename":"skimmer.jpg","data":"<base64 JPEG, PNG, GIF, or WebP>"}]}' \ 'https://api.pooli.app/v1/organizations/{orgId}/pools/{poolId}/logs?type=note' # 201 {"success":true,"message":"Log created successfully","data":"LOG_ID"}
Organization PATCH Endpoint
-
Update Organization Log Entry
Endpoint:
PATCH /:orgId/pools/:poolId/logs/:logIdDescription: Updates a log entry for an organization pool. The stored log type must be
noteto attach photos.Note patch
When the stored log type is
note,PATCH /v1/organizations/{orgId}/pools/{poolId}/logs/{logId}accepts the same JSONphotosarray as note create. PATCH appends photos. It does not replace photos already on the note. Omitphotosfor a text-only update. Do not use multipart. Each item is a base64 string, or an object{ "data": "<base64 or data URL>", "filename": "skimmer.jpg", "contentType": "<ignored>" }.contentTypeis ignored. The server sniffs the image type from the bytes. Allowed types are JPEG, PNG, GIF, and WebP. PDF, HEIC, HEIF, and AVIF are rejected. Do not sendattachmentsandphotostogether. An emptyphotosarray is ignored.Caps are 1.5 MB (1,500,000 decoded bytes) per photo, 4 photos per request, and 12 photos per note. The JSON body limit is 10 MB. A patch with photos counts as one request for rate limiting (10 per hour, or 150 per hour for an active owner premium (Pool Club) subscription). See Rate Limiting and Quotas.
GET and this PATCH return stored
attachments. Each photo has this shape:{ "attachmentType": "photo", "firestorePath": "users/{uploaderUid}/{sha256}{ext}", "description": "<filename or sha256+ext>", "url": "<Firebase Storage download URL>" }Errors are JSON
{ "error", "message", "status" }. 400 Validation Error: unsupported type, bad base64, too many photos, photos on a non-note, orphotostogether withattachments. 413 File Too Large: a decoded photo is over 1,500,000 bytes. The wrong user or organization returns 403. A missing note or pool returns 404.Example request:
curl -X PATCH \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"photos":[{"filename":"skimmer.jpg","data":"<base64 JPEG, PNG, GIF, or WebP>"}]}' \ 'https://api.pooli.app/v1/organizations/{orgId}/pools/{poolId}/logs/{logId}'
Organization DELETE Endpoint
-
Delete Organization Log Entry
Endpoint:
DELETE /:orgId/pools/:poolId/logs/:logIdDescription: Deletes a specific log entry for a given organization pool. Deleting a note removes the log document. Storage objects for its photos are left in place, the same as the app.
Parameters:
orgId(path),poolId(path),logId(path).
Log Types and Their Fields
The following rules define the required and optional fields for each log type. Common fields for all logs include:
creatorName: string (optional)createdAt: date (defaults to current date if not provided)updatedAt: date (optional)
Test Log
Used to record pool chemical and equipment readings.
Type: type=test
scan: object, optional (default: null)targets: object, optional (as defined by targetParser). A value you send is used as sent.chemicalReading: object, requiredtotalChlorine: number, default nullfreeChlorine: number, default nulltotalBromine: number, default nullperoxide: number, default nullph: number, default nulltemp: number, default nullcyanuricAcid: number, default nullcalcium: number, default null (total hardness - includes magnesium and other minerals)cch: number, default null (calcium hardness - calcium content only, always less than total hardness)salt: number, default nullalkalinity: number, default nullphosphates: number, default nulltotalDissolvedSolids: number, default nullcombinedChlorine: number, default nullcopper: number, default nullborates: number, default nullswgProduction: number, default nulltestMethod: string, default nullbiguanide: number, default nulliron: number, default nullorp: number, default nullmg: number, default nullkh: number, default nullnitrites: number, default nullnitrates: number, default null
gallonEstimate: number, optionalequipmentReading: object, optionalotherMethod: string, default nullswgPercent: number, default nullobservation: string, default nullfilterPressure: number, default nulltestMethod: string, default null
Product Log
Type: type=product
amount: number, default 0productName: string, requiredunitType: string, requiredform: string, requiredproductType: string, requiredsolution: object, requiredcustomType: string, default nullform: stringname: stringpercent: number, default nullproductType: string
Note Log
Type: type=note
User and organization note create and log patch accept photos. Those sections above list the item shapes, allowed types, caps, rate-limit counting, and the stored attachments shape GET returns.
note: string, required on createphotos: array, optional. A base64 string, or{ "data", "filename", "contentType" }.contentTypeis ignored.attachments: stored photos returned by GET and PATCH. Do not sendattachmentstogether withphotos.
Maintenance Log
Type: type=maintenance
maintenances: array, required- Each item:
name: stringcategory: stringduration: number, default nullaggregationName: string, optional
- Each item:
Inventory Endpoint
This endpoint allows for retrieving inventory data related to a specific user.
GET Endpoint
-
Fetch Inventory
Endpoint:
GET /:uid/inventoryDescription: Retrieves the inventory data associated with the specified user ID (uid).
Parameters:
uid(path) - User ID for which the inventory data is to be fetched.
Reminders Endpoint
This endpoint allows for retrieving reminders data related to a specific user.
GET Endpoint
-
Fetch Reminders
Endpoint:
GET /:uid/pools/:poolId/remindersDescription: Retrieves the reminders data associated with the specified user ID (uid) and pool.
Parameters:
uid(path) - User ID for which the reminders data is to be fetched,poolId(path),
Duplication plan
This site copies API section kits from src/pages/api-documentation/sections/ and edits the overview plus rate-limit copy for Pro. Follow-up work: extract shared section kits (or a gulp copy step) so DIY and Pro cannot drift, then port the CSV guide and any new org endpoints here in the same PR that adds them to pooli.app.