API Overview

Welcome to the Pooli API, a complementary extension to our intuitive Pooli app interface. While the app provides a user-friendly way to manage your pool, our API opens up additional possibilities, enabling advanced interactions with your pool data programmatically. This powerful combination means that you can now automate routine tasks, integrate with other systems, or even create custom applications, all while continuing to enjoy the ease and familiarity of the Pooli app. The Pooli API serves as your versatile gateway to comprehensive and efficient pool management.

Version: 1.0 (Alpha) - Date: August 4, 2025

Note: This is a beta version of the Pooli API and may be subject to changes and updates.

Key Features

• Programmatic Pool Management: Seamlessly create and delete pools using our API. This feature allows for dynamic management of pool data, offering flexibility and control to automate your pool maintenance and management tasks.
• Reading Inventory: Get real-time access to your pool inventory. View available supplies, equipment status, and reorder levels with simple API calls.
• Managing To-Dos: Stay on top of your pool maintenance tasks. The API provides functionalities to manage and update your to-do lists, helping you prioritize and schedule maintenance activities efficiently.
• Adding Logs: Easily add detailed logs to track pool maintenance, chemical levels, and more. Our API allows for quick log entries, ensuring you have up-to-date information about your pool's condition.
• Accessing All Logs: Retrieve comprehensive log data for any specified time range. This feature is ideal for analyzing trends, monitoring pool health over time, and making informed decisions about pool care.

With the Pooli API, you can create custom scripts and applications that leverage these features, streamlining your pool management process and enhancing your pool experience. Our robust, easy-to-use API is designed to empower users, developers, and pool enthusiasts alike to innovate and optimize pool care.

For feature requests, bug reports, or any questions, please email support@pooli.app.

Rate Limiting and Quotas

At Pooli, we have implemented rate limiting to ensure fair and efficient usage of our API. The rate limits vary based on the user's membership status in the Pool Club.

Pool Club Members

Pool Club members enjoy the benefit of unlimited API requests. This privilege allows for more extensive use of the API, facilitating advanced automation, integration, and application development without the concern of hitting usage caps. Discover the huge list of features and benefits of being a Pool Club member and consider signing up to enjoy these advantages.

Non-Club Members

Non-club members are subject to a rate limit of 60 requests per hour. This limit ensures that all users have fair access to the API while preventing excessive use that could impact service quality.

It is important for all users to be aware of these limits to avoid interruptions in service. If you encounter any issues or have questions about our rate limiting policies, please contact support@pooli.app.

Authentication

Securing your data is paramount. Our API uses API keys to authenticate requests. 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

Log in to your Pooli Dashboard. Navigate to the API section and generate your unique API key. This key is associated with your account and provides access to your user-specific 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

Include your API key in every request to the Pooli API. Use the key along with your user ID in the header of your requests as a bearer token.

API Base URLs

The Pooli API is available at the following endpoints:

• Production: https://api.pooli.app
• Development: https://dev-api.pooli.app

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.

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/pools

  Description: 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/:poolId

  Description: 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/pools

  Description: 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 pool parameter 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: []],
  }

  Each property in the pool object has specific data types and constraints. Some properties, such as sanitizingChemical, poolType, filterCategory, and supplimentalSanitizers, are restricted to predefined values as specified in their respective enums.

DELETE Endpoints

• Delete Specific Pool

  Endpoint: DELETE /:uid/pools/:poolId

  Description: 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/pools

  Description: 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/:poolId

  Description: 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/pools

  Description: 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 pool object structure as user pool creation.

Organization DELETE Endpoints

• Delete Specific Organization Pool

  Endpoint: DELETE /:orgId/pools/:poolId

  Description: 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/logs

  Description: 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/:logId

  Description: 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/logs

  Description: Creates a new log entry for a pool. The log structure varies based on the log type.

  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'

DELETE Endpoint

• Delete Log Entry

  Endpoint: DELETE /:uid/pools/:poolId/logs/:logId

  Description: Deletes a specific log entry for a given pool.

  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/logs

  Description: 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/:logId

  Description: 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/logs

  Description: 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).

Organization DELETE Endpoint

• Delete Organization Log Entry

  Endpoint: DELETE /:orgId/pools/:poolId/logs/:logId

  Description: Deletes a specific log entry for a given organization pool.

  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)
• chemicalReading: object, required
  • totalChlorine: number, default null
  • freeChlorine: number, default null
  • totalBromine: number, default null
  • peroxide: number, default null
  • ph: number, default null
  • temp: number, default null
  • cyanuricAcid: number, default null
  • calcium: 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 null
  • alkalinity: number, default null
  • phosphates: number, default null
  • totalDissolvedSolids: number, default null
  • combinedChlorine: number, default null
  • copper: number, default null
  • borates: number, default null
  • swgProduction: number, default null
  • testMethod: string, default null
  • biguanide: number, default null
  • iron: number, default null
  • orp: number, default null
• gallonEstimate: number, optional
• equipmentReading: object, optional
  • otherMethod: string, default null
  • swgPercent: number, default null
  • observation: string, default null
  • filterPressure: number, default null
  • testMethod: string, default null

Product Log

Type: type=product

• amount: number, default 0
• productName: string, required
• unitType: string, required
• form: string, required
• productType: string, required
• solution: object, required
  • customType: string, default null
  • form: string
  • name: string
  • percent: number, default null
  • productType: string

Note Log

Type: type=note

• note: string, required
• attachments: object, default null

Maintenance Log

Type: type=maintenance

• maintenances: array, required
  • Each item:
    • name: string
    • category: string
    • duration: number, default null
    • aggregationName: string, optional

Inventory Endpoint

This endpoint allows for retrieving inventory data related to a specific user.

GET Endpoint

• Fetch Inventory

  Endpoint: GET /:uid/inventory

  Description: 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/reminders

  Description: 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),

Organization Endpoints

These endpoints allow organizations to manage their resources including technicians, pools, and logs. Organization access requires proper authentication and authorization.

{
    "name": "Organization Pool 1",
    "poolType": "plaster",
    "filterCategory": "cartridge", 
    "sanitizingChemical": "chlorine",
    "gallonEstimate": 20000,
    "isIndoor": false,
    "supplimentalSanitizers": ["mineral"]
}

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'