Overview

Senlay is a spot-level verification API for SmartSurf, outdoor AI apps, IoT products, and safety applications. It is not a weather API wrapper: each response is built to explain what is happening at a coordinate, which sources support it, how fresh they are, whether they disagree, and what the decision context means.

The Physical World Model (PWM) is a real-time, multi-layered representation of physical conditions at a coordinate. One verification request can combine available data from 21 source families — including hardware weather stations, ocean buoys, tide gauges, seismometers, models, and satellites — into a unified response your AI can immediately use.

The Senlay layer stack adds a versioned catalog for live sensors, forecast models, terrain elevation, satellite visual context, hazards, and risk operations, plus planned bathymetry, land cover/roughness, buildings/obstacles, coastline/access, and telemetry layers. Runtime status explicitly distinguishes active data from layers that are not loaded. Heavy static layers require background preprocessing and compact cached spot summaries.

For developer workflows, the response can include a pre-formatted context_string ready to inject into an LLM context. For safety workflows such as SmartSurf, Senlay can also produce risk_event records that turn physical evidence into alertable and auditable operational context.

Measured observations vs. predictions. METAR stations, ocean buoys, and tide gauges produce measured readings. Weather models produce predicted values. When they disagree, Senlay gives hardware a higher evidence weight — while still exposing freshness, distance to the source, data quality, and uncertainty so your agent can reason about how much to trust any single value.

Direct answers for agents and developers

Provenance & Evidence

Every PWM response carries source-and-freshness metadata so your agent knows how it knows. The platform is moving toward a fully structured Senlay Evidence Object per claim — this is the shape to expect:

{
  "claim": "Wave height is 0.7 m",
  "value": 0.7,
  "unit": "m",
  "evidence_type": "measured_telemetry",
  "source": {
    "type": "buoy",
    "id": "KLIH1",
    "distance_km": 18,
    "timestamp": "2026-04-18T11:48:00Z"
  },
  "freshness": "recent",
  "confidence": "medium_high",
  "model_disagreement": {
    "forecast_value": 0.5,
    "difference": 0.2
  },
  "interpretation": "Small but measurable swell; suitable for low-risk coastal activity.",
  "uncertainty": "Nearest buoy is 18 km away; local break conditions may vary."
}

Today this metadata is exposed across current_source, source_use, per-layer source labels, interaction/domain modifiers, decision context, and the context_string. Confidence scoring, freshness decay, and explicit disagreement flags are landing as part of Evidence Object v1.

Evidence-shaped context_string

The pre-formatted context_string reads like provenance-aware prose, ready to inject into any LLM:

Current Maui ocean state: 0.7 m waves measured by NDBC buoy KLIH1
18 km away, updated 12 minutes ago. Confidence medium-high.
Forecast underestimates the live measurement by 0.2 m — treat
conditions as building. Local break conditions may vary by exposure.

Authentication

Production endpoints require a Bearer token. The public /api/v1/try-sense endpoint is a limited no-key trial for browser-based chat agents.

Authorization: Bearer sl_live_your_key_here

Start with pricing: senlay.world/pricing - then create a free key, no credit card.

Quick Start

For a chat model that can browse but cannot send POST bodies or Bearer headers, use the no-key trial URL:

https://senlay.world/api/v1/try-sense?lat=15.8801&lng=108.3380&field=kitesurfing&agentName=ChatGPT_Test_Agent

For a self-updating browser view of the same request, open the live page URL:

https://senlay.world/agents/live?lat=15.8801&lng=108.3380&field=kitesurfing&agentName=ChatGPT_Test_Agent&request=Can%20I%20kite%20safely%20now%3F

For production agents, create a free key and call the authenticated API:

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.world/api/v1/pwm?lat=36.01&lng=-5.60&field=drone"

For plain text output (no JSON parsing needed):

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.world/api/v1/sense?lat=36.01&lng=-5.60&field=drone"

GET /api/v1/try-sense

Public, no-key trial endpoint for chat agents with browsing. It returns plain text, includes instructions for the model, and is rate-limited. Use this when a user wants to paste one URL into ChatGPT, Claude, Gemini, or another agent and immediately ground the conversation in live physical context.

https://senlay.world/api/v1/try-sense?lat=36.01&lng=-5.60&field=drone&agentName=MyChatAgent

Parameters

The same live page is also available at /agents/live. It stores state in the URL, so parallel agents can use different agentName, field, request, and session values without overwriting each other.

Trial mode is intentionally limited: 8 requests/minute burst and 60 requests/hour per IP. The live page clamps automatic refresh to 120-600 seconds. For repeated use or automation, register an agent and use /api/v1/sense with Bearer auth.

GET /api/v1/pwm

Structured Physical World Model JSON containing the data that was available for this coordinate, plus source health, extended observations/feeds, satellite context, and the pre-formatted context string. Individual layers can be disabled, out of coverage, stale, or unavailable.

Parameters

Response

{
  "status": "ok",
  "active_sources": 7,
  "total_sensors": 3,
  "pwm": {
    "coordinates": { "lat": 36.01, "lng": -5.60 },
    "timestamp": "2026-04-09T12:00:00Z",
    "layers": {
      "atmosphere": {
        "current": {
          "wind_speed_10m": 33, "wind_gusts_10m": 61.9,
          "wind_direction_10m": 84, "temperature_2m": 16.5,
          "pressure_msl": 1019.5, "humidity": 48, "cloud_cover": 3
        }
      },
      "hydrosphere": {
        "current": {
          "wave_height": 1.2, "wave_period": 8.3,
          "swell_wave_height": 0.8
        }
      },
      "terrain": {
        "elevation_at_point": 18,
        "profile_kind": "terrain_elevation",
        "bathymetry_available": false,
        "is_ocean": false,
        "vertical_datum": null
      },
      "air_quality": {
        "current": {
          "pm2_5": 12.3, "pm10": 18.7,
          "uv_index": 6.2, "european_aqi": 42
        }
      }
    },
    "health": [
      { "source": "base_pwm", "status": "ok", "has_data": true },
      { "source": "ndbc_buoys", "status": "no_data", "has_data": false }
    ]
  },
  "extended": {
    "wind_sensors": [
      { "source": "metar", "name": "Rota NAS",
        "distance_km": 96.8, "wind_speed_kmh": 11.1,
        "is_hardware": true }
    ],
    "wind_cross_reference": {
      "sensor_count": 2, "average_kmh": 22,
      "confidence": "moderate"
    },
    "buoys": [],
    "tides": {
      "station_id": "9410230",
      "current_level_m": 1.2,
      "next_high": { "time": "14:30", "height_m": 1.8 }
    },
    "earthquakes": [],
    "fires": []
  },
  "satellite": {
    "sentinel2": {
      "available": true, "date": "2026-04-07",
      "cloud_cover": 12
    }
  },
  "context_string": "=== SENLAY PHYSICAL WORLD MODEL === ..."
}

Response Fields

GET /api/v1/layers/catalog and /api/v1/layers/context

The layer endpoints expose the product-level stack that Senlay uses to explain current and planned physical-world context. Public demo equivalents are available at /api/layers/catalog and /api/layers/context; authenticated API clients should use the /api/v1 paths with a Bearer key.

Layer catalog

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.world/api/v1/layers/catalog"

Returns layer metadata, recommended providers, status, cadence, license notes, output fields, and the request-time policy. The catalog includes active runtime providers and planned static providers; each entry states its access and deployment status. Open-Meteo layers are conditional on a paid customer key or compliant configured host; OpenAQ v3 and NASA FIRMS also require credentials. Heavy sources such as GEBCO and WorldCover remain planned until preprocessed and loaded. Even when loaded, the coarse GEBCO grid can provide regional depth/gradient context but cannot identify spot-scale reefs, sandbars, or obstructions and is not a navigation chart.

Spot layer context

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.world/api/v1/layers/context?lat=36.0143&lng=-5.6044&field=kitesurfing"

Returns the current coordinate-specific layer status plus derived terrain, marine, wind, sensor, and risk context. Missing heavy layers are reported as next actions instead of being loaded synchronously.

GET /api/v1/sense

Simplified endpoint — returns only the context_string as plain text. Content-Type: text/plain. Ideal for agents that don't want to parse JSON.

Parameters

Same as /api/v1/pwm: lat (required), lng (required), and optional field for the reasoning mode.

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.world/api/v1/sense?lat=36.01&lng=-5.60&field=drone"

Returns the full Physical World Model as a plain text block. No parsing needed — inject it into your agent so it can reason from current physical context.

GET /api/v1/risk-events

Authenticated endpoint for operational risk events. Use it when an application needs more than context text: a station dashboard, lifeguard workflow, fleet monitor, school safety view, or IoT alert pipeline can read structured events that summarize the detected risk, severity, coordinates, sources, and recommended review path.

SmartSurf is the first proving ground: Traccar GPS movement and local triggers identify a possible rider or board problem, then Senlay adds environmental evidence before the system escalates or stays quiet. The endpoint is decision support, not a certified rescue authority.

Risk responses can also include risk_assessment: an aggregate deterministic state with score, alert band, confidence, reasons, recommended action, escalation stage, incident state, source provenance, session phase, and field-validation metadata. This is the SmartSurf early-warning contract: it is meant to show recoverability risk and coordination needs, not to diagnose drowning or claim rescue dispatch.

Related endpoints

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.world/api/v1/risk-events?lat=15.8801&lng=108.3380&field=kitesurfing"

lat and lng are required for the current risk endpoint. It derives the current event set for that coordinate; status is not a supported query filter. Use /api/v1/risk-events/recent for persisted records and its documented type, severity, subject, time-window, and location filters.

Risk event shape

{
  "type": "rider_stopped_offshore",
  "severity": "monitor",
  "status": "active",
  "lat": 15.8801,
  "lng": 108.3380,
  "source": "smartsurf",
  "evidence": {
    "movement": "stopped_or_drifting",
    "distance_from_shore_m": 820,
    "wind_context": "offshore component possible",
    "confidence": "medium"
  },
  "recommendation": "Ask rider to confirm OK before notifying station."
}

Aggregate assessment shape

{
  "risk_score": 82,
  "risk_level": "high",
  "alert_band": {
    "id": "critical",
    "label": "Critical",
    "default_text": "Possible emergency. Use last known position and response plan."
  },
  "confidence": "medium-high",
  "session_phase": "in_session",
  "reasons": [
    "signal_loss_after_worsening_drift: Possible emergency..."
  ],
  "recommended_action": "Lock last known position and use the local response plan.",
  "escalation_stage": "emergency_review",
  "incident_state": "active_ack_required",
  "source_provenance": {
    "has_tracker_telemetry": true,
    "has_environment_context": true
  },
  "safety_disclaimer": "Decision support only. Humans remain final safety authority."
}

POST /api/v1/agent-register

Dedicated registration for AI agents — no password needed. Only agentName is required. The first response displays an API key and recovery token once. If you supply ownerEmail, the (ownerEmail, agentName) pair becomes a stable identity: a later request must include the current recovery token and rotates both credentials instead of revealing the old API key.

curl -X POST https://senlay.world/api/v1/agent-register \
  -H "Content-Type: application/json" \
  -d '{"agentName": "MyAgent"}'

curl -X POST https://senlay.world/api/v1/agent-register \
  -H "Content-Type: application/json" \
  -d '{"ownerEmail": "your_real_email@domain.com", "agentName": "MyAgent"}'

Request Body

Response

{
  "success": true,
  "apiKey": "sl_live_xxxxxxxxxxxxxxxx",
  "keyPreview": "sl_live_xxxx…xxxx",
  "recoveryToken": "sl_recover_xxxxxxxxxxxxxxxx",
  "agentName": "MyAgent",
  "existing": false,
  "rotated": false,
  "message": "Save the API key and recovery token now; neither is shown again."
}

Store both secrets outside logs and source control. For an existing identity, send the current recoveryToken; a successful response has existing: true and rotated: true, and returns new credentials. The old API key stops working.

POST /api/v1/agent-lookup

Discover agents associated with the signed-in owner's email address. This route requires a valid Senlay account session and a verified sign-in identity whose email exactly matches ownerEmail; password-only accounts remain fail-closed until an explicit verification/link flow exists. It returns masked key metadata only. Full keys and recovery tokens are never returned. If an API key is lost but you kept the recovery token, rotate the credentials through /api/v1/agent-register. If both secrets are lost, contact support. Rate-limited to 20 lookups/hour per signed-in user.

curl -X POST https://senlay.world/api/v1/agent-lookup \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ownerEmail": "your_real_email@domain.com"}'

Response

{
  "success": true,
  "ownerEmail": "your_real_email@domain.com",
  "count": 2,
  "agents": [
    {
      "agentName": "MyAgent",
      "keyPreview": "sl_live_4947…9109",
      "tier": "free",
      "requestsToday": 12,
      "requestsTotal": 348,
      "lastRequestDate": "2026-04-14",
      "createdAt": "2026-04-10 08:22:11"
    }
  ],
  "message": "Only masked key metadata is available. Use the agent recovery token to rotate lost credentials."
}

POST /api/register

Standard registration for developers (with password).

Response: { success, userId, email, apiKey, keyPreview }. The full apiKey is returned once in this response; later profile responses include only its masked preview.

POST /api/login

Login for dashboard access.

Response: { success, userId, email, apiKeys, sessionToken, sessionExpiresAt }. Use the session token as Authorization: Bearer <sessionToken> for account/profile routes. API-key entries contain masked keyPreview values, never full stored keys.

GET /api/spots

Returns all curated sensor locations. No authentication required.

Response: JSON array of spots with name, country, lat, lng, type, notes.

GET /api/conditions

Returns current wind + wave data for curated spots. Senlay caches this aggregate for 15 minutes. No authentication required.

Response: JSON array with name, wind_speed, wind_direction, wind_gusts, temperature, wave_height, wave_period, swell_height.

Data Sources

Senlay can aggregate data from 21 source families where available. Not all sources have data at every location — coastal areas have the most hardware sensors. The API returns the available context and marks gaps or uncertainty where needed.

Open-Meteo deployment note: its free hosted API is for non-commercial use. Commercial deployments must use the paid customer-api.open-meteo.com endpoint with an API key, or a compliant self-hosted service. Open-Meteo data attribution is required. Review the current terms and commercial configuration before deployment.

Windy deployment note: Stations and Webcams are separate products with separate credentials. Open-station access is governed by the current Windy Stations terms and Aggregator Open Data Licence. Confirm that the configured agreement permits the intended use; preserve required operator credits and show Windy's Add new station link with presented station data.

HARDWARE identifies physical-instrument observations. MODEL identifies forecasts or estimates. SATELLITE identifies orbital observation products. OFFICIAL FEED identifies published alerts, products, or event catalogs rather than a direct local sensor reading. Fresh, quality-controlled, relevant hardware usually carries more evidence weight than a model, but distance, calibration, representativeness, and timestamps still matter.

Agentic Tooling

Use Senlay as a function/tool in AI agent frameworks. Let the AI decide when it needs physical world data.

OpenAI Function Definition

{
  "type": "function",
  "function": {
    "name": "sense_physical_world",
    "description": "Get real-time physical world data for a coordinate. Returns available atmosphere, ocean, terrain, air quality, live hardware sensors, earthquakes, fires, and satellite context from 21 source families where available.",
    "parameters": {
      "type": "object",
      "properties": {
        "lat": { "type": "number", "description": "Latitude (-90 to 90)" },
        "lng": { "type": "number", "description": "Longitude (-180 to 180)" }
      },
      "required": ["lat", "lng"]
    }
  }
}

Claude Tool Definition

{
  "name": "sense_physical_world",
  "description": "Perceive available real-time physical conditions at a coordinate from 21 source families including hardware weather stations, ocean buoys, tide gauges, seismometers, and satellites.",
  "input_schema": {
    "type": "object",
    "properties": {
      "lat": { "type": "number", "description": "Latitude (-90 to 90)" },
      "lng": { "type": "number", "description": "Longitude (-180 to 180)" }
    },
    "required": ["lat", "lng"]
  }
}

Implementation Example

def sense_physical_world(lat, lng):
    """Call this when your AI needs to evaluate physical conditions."""
    response = requests.get(
        "https://senlay.world/api/v1/sense",
        params={"lat": lat, "lng": lng},
        headers={"Authorization": f"Bearer {SENLAY_KEY}"}
    )
    return response.text  # Ready to inject into context

Understanding the PWM

The context_string

The most important field in the response. It's a pre-formatted text block designed to be injected directly into an LLM's system prompt or user message. It summarizes the available sensor/model data, provenance, and explicit gaps in natural language. No JSON parsing is required, but clients must still respect source health and uncertainty.

HARDWARE vs MODEL

Direct observation records can include an is_hardware boolean. Official alerts, event catalogs, satellite products, and some provider summaries are separate feed types and must not be relabeled as local hardware measurements.

• is_hardware: true — physical sensor measurement (METAR station, ocean buoy, tide gauge)
• is_hardware: false — computer model forecast/estimate

Hardware readings are measured observations; models are predictions. When they disagree, the hardware value generally carries more weight — subject to freshness, distance from the query location, station calibration, and contextual relevance. Senlay surfaces those dimensions rather than asserting ground truth.

Cross-referencing

When multiple wind sensors are available, Senlay calculates:

• wind_cross_reference.average_kmh — average across the accepted, valid, physically distinct comparison stations
• wind_cross_reference.min_kmh / max_kmh — range
• wind_cross_reference.confidence — "high" (3+ sensors agree) or "moderate" (2 sensors)

Error Handling

Some sensor sources may fail independently — the API still returns successfully with whatever data is available. Check active_sources to see how many sources responded.

Rate Limits

Senlay is currently in open beta. Each free account has a shared allowance of 100 authenticated API calls per day across all of its active keys. Every authenticated request presented for processing counts against that account allowance, including cache hits; creating another key does not create another allowance. Caching reduces upstream work and latency, not customer usage. Invalid requests or upstream failures may also consume quota after authentication, so validate inputs and handle errors.

For details on future plans and pricing, see the Pricing page.

What a verification request attempts

• Configured model layers for atmosphere, hydrosphere, terrain, and air quality; any layer may be unavailable, disabled, outside coverage, or fail independently
• Extended hardware, hazard, satellite, and community source checks where coverage and provider terms allow
• Early Modifier Engine — working demos of physics-based calculators (terrain-wind hints, wave modifiers, gust-factor analysis, ET0, orographic effects). Deeper validated models under development.
• Pre-formatted context_string ready for LLM injection
• Per-source health reporting so clients can distinguish returned data from unavailable, disabled, no-data, or failed sources

Code Examples

Python + Claude

import anthropic, requests

pwm = requests.get(
    "https://senlay.world/api/v1/pwm",
    params={"lat": 36.01, "lng": -5.60},
    headers={"Authorization": "Bearer sl_live_your_key"}
).json()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    system=f"Use this current spot-level verification:\n\n{pwm['context_string']}",
    messages=[{"role": "user", "content": "Is it safe to fly a drone here?"}]
)

Python + OpenAI

from openai import OpenAI
import requests

pwm = requests.get(
    "https://senlay.world/api/v1/pwm",
    params={"lat": 36.01, "lng": -5.60},
    headers={"Authorization": "Bearer sl_live_your_key"}
).json()

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": pwm["context_string"]},
        {"role": "user", "content": "Should I irrigate today?"}
    ]
)

JavaScript

const res = await fetch(
  "https://senlay.world/api/v1/pwm?lat=36.01&lng=-5.60",
  { headers: { Authorization: "Bearer sl_live_your_key" } }
);
const pwm = await res.json();

// Inject into ANY LLM system prompt:
const systemPrompt = `Physical World Model:\n\n${pwm.context_string}`;

// Works with Claude, GPT, Gemini, Llama, Mistral, Cohere...

Plain text with /sense

# Simplest possible integration — no JSON parsing
context = requests.get(
    "https://senlay.world/api/v1/sense",
    params={"lat": 36.01, "lng": -5.60},
    headers={"Authorization": f"Bearer {SENLAY_KEY}"}
).text

# context is ready to inject directly into any LLM