AgentLair Docs

Base URL

https://agentlair.ai

All endpoints return JSON. No authentication required for free tier (100 requests/day).

Authentication

For unlimited requests, include your API key in the header:

curl -H "X-API-Key: al_your_key_here" "https://agentlair.ai/v1/weather?location=NYC"

Rate Limits

Tier	Limit	Headers
Free	100 requests/day	X-RateLimit-Remaining
API Key	Unlimited	Usage tracked for billing

Endpoints

GET /v1/weather

Get current weather and 7-day forecast for any location.

Parameters

Name	Type	Description
`location`	string	City name (e.g., "Austin,TX", "London", "Tokyo")
`lat`	number	Latitude (use with `lon` instead of location)
`lon`	number	Longitude
`units`	string	`metric` (default) or `imperial`

Example Request

curl "https://agentlair.ai/v1/weather?location=Austin,TX&units=imperial"

Example Response

{
  "location": {
    "query": "Austin,TX",
    "resolved": "Austin, Travis County, Texas, United States",
    "lat": 30.27,
    "lon": -97.74
  },
  "current": {
    "temperature": 75,
    "temperature_unit": "°F",
    "windspeed": 8,
    "windspeed_unit": "mph",
    "wind_direction": 180,
    "condition": "Partly cloudy",
    "condition_code": 2,
    "is_day": true
  },
  "forecast": [
    {
      "date": "2026-02-16",
      "high": 78,
      "low": 55,
      "precipitation_chance": 10,
      "condition": "Mainly clear"
    }
    // ... 7 days total
  ],
  "timezone": "America/Chicago",
  "units": "imperial"
}

GET /v1/geocode

Convert location names to coordinates (forward) or coordinates to names (reverse).

Parameters

Name	Type	Description
`q`	string	Location query for forward geocoding
`lat`	number	Latitude for reverse geocoding
`lon`	number	Longitude for reverse geocoding

Forward Geocoding

curl "https://agentlair.ai/v1/geocode?q=Eiffel+Tower"

{
  "lat": 48.8582,
  "lon": 2.2945,
  "display_name": "Eiffel Tower, Paris, France",
  "type": "attraction"
}

Reverse Geocoding

curl "https://agentlair.ai/v1/geocode?lat=40.7128&lon=-74.0060"

{
  "display_name": "New York City, New York, United States",
  "address": {
    "city": "New York",
    "state": "New York",
    "country": "United States"
  }
}

Error Handling

All errors return a consistent JSON structure:

{
  "error": "rate_limit_exceeded",
  "message": "Free tier limit of 100 requests/day exceeded.",
  "upgrade_url": "https://agentlair.ai/pricing"
}

HTTP Code	Error	Description
400	missing_params	Required parameters not provided
404	not_found	Location or resource not found
429	rate_limit_exceeded	Free tier limit hit
500	internal_error	Server error (please report)

GET /v1/time

Get current time for any location or timezone. Includes business hours check.

Parameters

Name	Type	Description
`location`	string	City name (e.g., "Tokyo", "London")
`timezone`	string	IANA timezone (e.g., "America/New_York")

Example Request

curl "https://agentlair.ai/v1/time?location=Tokyo"

Example Response

{
  "timezone": "Asia/Tokyo",
  "local_time": "2026-02-16T23:28:35",
  "day_of_week": "Monday",
  "is_business_hours": false,
  "is_weekend": false,
  "utc_offset": "GMT+9",
  "location": {
    "query": "Tokyo",
    "lat": 35.68,
    "lon": 139.76
  }
}

GET /v1/providers/health

Real-time health status for major AI providers. Check if Anthropic, OpenAI, xAI, Groq, or Google APIs are up before routing requests.

Parameters

Name	Type	Description
`provider`	string	Check single provider: `anthropic`, `openai`, `xai`, `groq`, `google`
`refresh`	boolean	Bypass 60s cache and get fresh data

Example Request (All Providers)

curl "https://agentlair.ai/v1/providers/health"

Example Response

{
  "summary": {
    "total": 5,
    "up": 5,
    "degraded": 0,
    "down": 0,
    "average_latency_ms": 245,
    "overall_status": "healthy"
  },
  "providers": [
    {
      "provider": "anthropic",
      "name": "Anthropic",
      "status": "up",
      "latency_ms": 189,
      "http_status": 401,
      "last_checked": "2026-02-16T18:32:00Z"
    },
    {
      "provider": "openai",
      "name": "OpenAI",
      "status": "up",
      "latency_ms": 156,
      "http_status": 401,
      "last_checked": "2026-02-16T18:32:00Z"
    }
    // ... xai, groq, google
  ],
  "checked_at": "2026-02-16T18:32:00Z"
}

Single Provider

curl "https://agentlair.ai/v1/providers/health?provider=anthropic"

{
  "provider": "anthropic",
  "name": "Anthropic",
  "status": "up",
  "latency_ms": 189,
  "http_status": 401,
  "last_checked": "2026-02-16T18:32:00Z"
}

Status Values

Status	Meaning
`up`	API responding normally
`degraded`	API responding with errors (5xx)
`down`	API unreachable or timed out

Caching: Results are cached for 60 seconds to avoid hammering provider APIs. Use ?refresh=true to bypass cache.

Coming Soon

More endpoints on the way:

/v1/holidays — Bank holidays, observances by country
/v1/stocks — Stock quotes and market data