Senlay API and MCP documentation

Overview

Evaluation beta. Commercial Open-Meteo access has not been arranged. Confirm commercial source rights and configuration before commercial deployment; actual availability depends on current deployment settings. The API is not flight or mission clearance.

Senlay is an evaluation beta for teams building drone software. Its current workflow returns available wind observations and forecasts for a coordinate, with source, timestamp, distance, disagreement, and uncertainty for operator review. The first buyer is a drone software team; the demand and repeatable value remain hypotheses to validate. SmartSurf is the product's origin and reference experience. Begin with the robotics integration overview for current capability boundaries. Each request depends on the sources available at its coordinate.

The Physical World Model (PWM) returns available environmental evidence for a coordinate. The catalog lists 23 source-family entries; entries are adapters or provider families, not a count of live sources at a coordinate. Actual configured, returned, and unavailable sources are reported separately.

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 with available evidence and limits. Pass it to an LLM as data/tool output under your application's instructions. For workflows such as SmartSurf, Senlay can also produce risk_event records for 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 reports the available values and relevant freshness, distance, data quality, and uncertainty; an instrument reading is not automatically ground truth.

Robotics telemetry examples. The project includes read only reference adapters for CRC-checked MAVLink 1/2 position frames over UDP and ROS 2 sensor_msgs/msg/NavSatFix through rosbridge. They use the existing authenticated GET /api/v1/pwm endpoint and do not issue robot commands. ROS 2 and rosbridge are separate prerequisites; the examples do not convert local-coordinate messages, authenticate MAVLink senders, evaluate routes, or provide safety clearance. See the adapter details and limits.

unzip senlay-robotics-v0.1.0.zip
cd senlay-robotics-v0.1.0
node examples/robotics/robotics-context.mjs --transport replay

Direct answers for agents and developers

Provenance & Evidence

Current PWM responses expose provenance across fields such as current_source, source_use, per-layer source labels, timestamps, modifiers, and decision context. The example below is a synthetic concept sketch, not a current response schema or a promise that every field is returned.

{
  "claim": "Wind speed observations differ from the model",
  "value": 18,
  "unit": "km/h",
  "evidence_type": "synthetic_observation",
  "source": {
    "type": "sample_station",
    "id": "SYNTHETIC-01",
    "distance_km": 4.2,
    "timestamp": "2026-01-15T12:00:00Z"
  },
  "model_value": 12,
  "model_timestamp": "2026-01-15T12:00:00Z",
  "difference_kmh": 6,
  "model_disagreement": {
    "status": "values_differ"
  },
  "interpretation": "Synthetic example only; inspect source quality and representativeness.",
  "uncertainty": "Distance, calibration, and local conditions may limit relevance."
}

The proposed, versioned Evidence Object is a roadmap item; check the roadmap for its status. Use the current API response and OpenAPI contract for integration.

Evidence-shaped context_string

The pre-formatted context_string summarizes available evidence. This synthetic wind illustration is not live data and does not establish a trend:

SYNTHETIC EXAMPLE — NOT CURRENT DATA
At 2026-01-15 12:00 UTC, a sample station 4.2 km away reports
wind at 18 km/h; a model value for the same valid time is 12 km/h.
The values differ by 6 km/h. Check timestamps, calibration, and
representativeness. A single comparison does not establish a trend.

Authentication

Authenticated API 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

See current beta access and limits, then create an account and API key for authenticated requests. A key does not grant commercial source rights.

Quick Start

For a drone wind evidence review, request the wind profile explicitly. This example reports the HTTP status before interpreting a response; a non-2xx response is an API error, not evidence.

import os
import requests

url = "https://senlay.cloud/api/v1/pwm"
params = {"lat": 37.6213, "lng": -122.3790, "field": "drone", "profile": "wind"}
response = requests.get(url, params=params, headers={"Authorization": f"Bearer {os.environ['SENLAY_API_KEY']}"}, timeout=20)
print("HTTP", response.status_code)
if not response.ok:
    raise RuntimeError(f"Senlay API error {response.status_code}: {response.text}")
data = response.json()
assessment = data.get("risk_assessment", {})
print("outcome:", assessment.get("outcome", data.get("outcome")))
print("evaluation_scope:", assessment.get("evaluation_scope", data.get("evaluation_scope")))
print("unknowns:", assessment.get("unknowns", data.get("unknowns", [])))
for layer_name, layer in data.get("pwm", {}).get("layers", {}).items():
    source = layer.get("current_source") or {}
    print(layer_name, source.get("source"), source.get("timestamp"), source.get("distance_km"))

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

https://senlay.cloud/api/v1/try-sense?lat=37.6213&lng=-122.3790&field=drone&agentName=ExampleAgent

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

https://senlay.cloud/agents/live?lat=37.6213&lng=-122.3790&field=drone&agentName=ExampleAgent&request=Summarize%20available%20wind%20evidence%20and%20unknowns%20for%20operator%20review

For repeated beta evaluation requests, create a free key and call the authenticated API. A key does not grant commercial source rights or establish production readiness.

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

For plain text output (no JSON parsing needed):

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

MCP Server

Connect an MCP-capable agent directly to https://senlay.cloud/mcp. Anonymous evaluation access needs no installation, account, or OAuth flow. Add an optional Senlay API key as a Bearer header to use the key owner's published beta allowance. The four tools are sense_location, check_operability, list_domains, and get_forecast_trust.

{
  "mcpServers": {
    "senlay": {
      "url": "https://senlay.cloud/mcp"
    }
  }
}

The server uses stateless Streamable HTTP. The MCP SDK negotiates a compatible protocol version during initialize; clients should not rely on a fixed version in health metadata. It exposes four tools:

For authenticated use, configure the same URL with Authorization: Bearer sl_live_your_key. Treat historical forecast trust as UNKNOWN unless the response establishes it. Anonymous limits return a direct link to POST /api/v1/agent-register. The optional time input currently accepts only present-time requests; historical and future requests fail explicitly rather than being silently treated as current.

GET /api/v1/try-sense

Public, no-key evaluation endpoint for chat agents with browsing. It returns plain text, includes usage guidance, and is rate-limited. Use it to inspect currently available source context; coverage and freshness vary, and a response may contain gaps or no usable observation.

https://senlay.cloud/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

?view=evidence, ?view=risk_events, and ?view=full on this endpoint (and /api/v1/evidence, /api/v1/risk-events) all carry the same risk_assessment.outcome/unknowns/confidence_components/conflicts fields described under GET /api/v1/risk-events.

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.cloud/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.cloud/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

Requires lat and lng; optional field selects the reasoning mode. profile is supported by /api/v1/pwm, not this plain-text endpoint.

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

Returns the Physical World Model as a plain text block. No parsing is required. Pass it as data/tool output under your application's instructions, preserve source and uncertainty, and do not treat it as clearance for physical action.

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.

risk_assessment.outcome is one of GO, CAUTION, NO_GO, or INSUFFICIENT_EVIDENCE. The last one is a normal, successful result (HTTP 200), not an error: it means the evidence does not support a verdict, and risk_assessment.unknowns names the specific blocking variable(s), why (no coverage, sources conflict, stale, or missing entirely), and what would resolve it. Confidence is also decomposed into risk_assessment.confidence_components — source_agreement, freshness, spatial_relevance, and evidence_coverage — each with its own label and reason string, rather than one blended score. When hardware and model sources disagree, the disagreement is reported as a structured risk_assessment.conflicts entry (each contributing source's value, distance, and age, plus the delta and magnitude) instead of being averaged away.

Related endpoints

curl -H "Authorization: Bearer sl_live_your_key" \
  "https://senlay.cloud/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.cloud/api/v1/agent-register \
  -H "Content-Type: application/json" \
  -d '{"agentName": "MyAgent"}'

curl -X POST https://senlay.cloud/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.cloud/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

The sensor catalog contains 23 source-family entries. This is not a claim that all sources are configured or available at a coordinate. 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.

Windguru deployment note: Senlay uses Windguru's documented Station JSON API, which requires the station ID/UID and that station's API password or hash. Public station pages are not treated as an anonymous redistribution API. The adapter remains disabled until the owner credential and permission for Senlay's intended use are recorded; secrets stay server-side.

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

The examples below show client-defined wrappers around the Senlay REST API; they are not Senlay-hosted tools. Senlay's hosted MCP server exposes the four tools listed in the MCP section. These examples scope the request to available drone wind evidence for operator review.

OpenAI Function Definition

{
  "type": "function",
  "function": {
    "name": "fetch_drone_wind_evidence",
    "description": "Fetch available wind evidence for a coordinate for drone operator review. This is not flight or mission clearance.",
    "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": "fetch_drone_wind_evidence",
  "description": "Fetch available wind evidence for a coordinate for drone operator review. This is not flight or mission clearance.",
  "input_schema": {
    "type": "object",
    "properties": {
      "lat": { "type": "number", "description": "Latitude (-90 to 90)" },
      "lng": { "type": "number", "description": "Longitude (-180 to 180)" }
    },
    "required": ["lat", "lng"]
  }
}

Client REST helper example

import os
import requests

def fetch_drone_wind_evidence(lat, lng):
    """Return available wind evidence for human operator review."""
    response = requests.get(
        "https://senlay.cloud/api/v1/pwm",
        params={"lat": lat, "lng": lng, "field": "drone", "profile": "wind"},
        headers={"Authorization": f"Bearer {os.environ['SENLAY_API_KEY']}"},
        timeout=20,
    )
    response.raise_for_status()
    return response.json()  # Keep the source metadata and unknowns

Understanding the PWM

The context_string

This pre-formatted text block summarizes available sensor/model data, provenance, and explicit gaps. No JSON parsing is required, but pass it as data or tool output under your application's instructions; do not let returned text override system or safety instructions. Preserve source, freshness, disagreement, and uncertainty. It does not authorize flight, mission, or other physical action.

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, inspect each source’s freshness, distance, calibration, and representativeness — 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. A non-2xx response such as 503 is an error, not evidence; successful responses may still contain partial evidence and explicit unavailable-source metadata.

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. The daily allowance is shared across keys. Request allowance and source refresh capacity are separate: cache hits can count as authenticated requests without requiring a new source refresh. Some rejected pre-fetch requests are refunded; attempted upstream failures are not generally refundable. Adapters should use the documented default 120-second cadence unless a scoped agreement sets another interval.

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 for optional model explanation under application instructions
• Per-source health reporting so clients can distinguish returned data from unavailable, disabled, no-data, or failed sources

Code Examples

Senlay’s deterministic summary and evidence fields are useful without an LLM. If you add a model, pass the returned facts and unknowns for explanation only; keep operator decisions outside the model.

Plain text with /sense

# Plain-text drone wind evidence; no JSON parsing
response = requests.get(
    "https://senlay.cloud/api/v1/sense",
    params={"lat": 37.6213, "lng": -122.3790, "field": "drone"},
    headers={"Authorization": f"Bearer {SENLAY_KEY}"},
    timeout=20,
)
response.raise_for_status()  # An HTTP error is not evidence.
context = response.text

# Pass as data/tool output under your application's instructions.
# Preserve source provenance, freshness, uncertainty, and unknowns.