API Documentation

Authentication

All API requests require an API key. Include your key in the X-API-Key header:

curl -H "X-API-Key: ilystics_live_your_key_here" \
                https://ilystics.com/api/endpoints/v1/mud-risk?lat=38.9&lng=-77.25

Get your API key from the Settings page.

Rate Limits & Pricing

Tier	Requests/Day	Price
FREE	10	$0/mo	Sign Up
BASIC	500	$19/mo	Get Started
PRO	5,000	$49/mo	Get Started

💡 Tip: Project Protection subscribers ($149/mo) get Pro API access (5,000/day) included! Rate limits reset at midnight UTC.

Endpoints

GET /api/endpoints/v1/mud-risk

Get current mud risk for a single location.

Parameter	Type	Description
lat required	number	Latitude (-90 to 90)
lng required	number	Longitude (-180 to 180)
soil	string	Soil type: clay, silt, sand, loam, rock, mixed

Example Response:

{
                    "success": true,
                    "location": { "lat": 38.9, "lng": -77.25 },
                    "soil_type": "clay",
                    "risk_level": "high",
                    "drying_days_remaining": 2.5,
                    "precipitation_7d_inches": 1.25,
                    "timestamp": "2026-02-03T14:00:00-05:00"
                    }

POST /api/endpoints/v1/bulk-risk

Get mud risk for multiple locations in one request.

Request Body:

{
                    "locations": [
                    { "lat": 38.9, "lng": -77.25 },
                    { "lat": 39.1, "lng": -77.4 }
                    ],
                    "soil": "clay"
                    }

Max locations: Free=5, Basic=20, Pro=50

POST /api/endpoints/v1/estimate

Generate mud day estimate based on 10-year historical data.

Request Body:

{
                    "zip": "90210",
                    "soil": "clay",
                    "start_date": "2026-03",
                    "end_date": "2026-09"
                    }

POST /api/endpoints/v1/history

Get 15 years of historical weather for a specific date and ZIP code. Shows weather conditions for that exact day (month/day) across all available years.

Request Body:

{
                    "zip": "20110",
                    "date": "2026-03-15"
                    }

Example Response:

{
                    "success": true,
                    "location": { "zip": "20110", "name": "Manassas, VA", "lat": 38.75, "lng": -77.47 },
                    "target_date": { "month": 3, "day": 15, "label": "Mar 15" },
                    "date_specific": {
                    "rain_probability_pct": 40,
                    "avg_precip_in": 0.12,
                    "avg_high_f": 55.3,
                    "years_analyzed": 15,
                    "rain_years": 6,
                    "dry_years": 9,
                    "year_by_year": [...]
                    },
                    "monthly_averages": [...]
                    }

POST /api/endpoints/v1/weather-anomaly

Compare current weather to 5-year historical baseline.

Request Body:

{
                    "lat": 38.9,
                    "lng": -77.25,
                    "start_date": "2026-01-01",
                    "end_date": "2026-06-30"
                    }

GET /api/endpoints/v1/soil-lookup

Get estimated soil type for a location.

Parameter	Type	Description
lat required	number	Latitude
lng required	number	Longitude

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid API key
RATE_LIMITED	429	Daily rate limit exceeded. Resets at midnight UTC.
INVALID_REQUEST	400	Missing required parameters
SERVER_ERROR	500	Internal server error

AI & MCP Integrations

Connect Ilystics to AI assistants, custom GPTs, and developer tools.

OpenAPI Specification

Machine-readable API contract for code generators, Postman, and AI platforms:

https://ilystics.com/openapi.json

MCP Server (Claude, Cursor)

Install the Ilystics MCP server to use our tools directly in Claude Desktop or Cursor:

{
                "mcpServers": {
                "ilystics": {
                "command": "npx",
                "args": ["-y", "@ilystics/mcp-server"],
                "env": {
                "ILYSTICS_API_KEY": "your_api_key_here"
                }
                }
                }
                }

Add the above to your Claude Desktop or Cursor MCP config. Your AI assistant will then have access to all five Ilystics tools: mud risk, delay estimation, weather history, anomaly detection, and soil lookup.

ChatGPT / AI Plugin Discovery

AI platforms can auto-discover our API via the standard plugin manifest:

https://ilystics.com/.well-known/ai-plugin.json

Support

Questions? Contact us at support@ilystics.com