REST API

Base URL

This deployment's API is at https://coastal-intelligence.triskelionaisystems.com/api. Every path below is relative to it. Send the key as Authorization: Bearer <key> (or X-API-Key); see Authentication and keys. Responses are JSON (application/json) except the CSV export.

Endpoints

One GET route per tool, with the same checks, rate limit and audit as over MCP. Required query parameters are marked; the others are optional. Argument meanings are on the MCP server page, tool by tool.

Other partner endpoints

• GET /agency/tools: the tool list with argument names and types, for REST clients that want to discover it at run time.
• GET /bays/{bay_id}/risk-index: the risk index as JSON or, with format=csv, as a signed CSV file; GET /exports/signing-key: the public key that checks it. See Risk index and signed exports.
• GET /datasets: the public dataset registry with licences and attribution lines. See Data model and licences.
• POST /sites/{site_id}/observations: the observations webhook for loggers and gateways (a different key). See Observations webhook.

Date rules

• from and to are UTC days, YYYY-MM-DD, inclusive, and must lie inside the key's approved range.
• Omitted, to is today plus the 10-day forecast horizon and from is 30 days before to, both clipped to the approved range.
• One call covers at most 366 days and returns at most 20,000 rows; above either limit the answer is 422.
• Timestamps in rows (ts, start, end) are ISO 8601 in UTC.

Response envelope

The five fields every data row carries

Tool-specific row fields (for example value_max and worst_label for a bay signal aggregate; bias, rmse, mae for skill; index, level, suppressed for the risk index) are described in each tool's entry on the MCP server page and in the live reference below.

Example of the shape

Shape only. Every value below is a placeholder in angle brackets or a list of the allowed values; it is not a reading, and no example on this site shows measured data.

{
  "tool": "get_signals",
  "scope": {
    "request_id": "<integer>",
    "organisation": "<your organisation>",
    "bays": [
      "<bay id>"
    ],
    "products": [
      "signals",
      "<...>"
    ],
    "aggregation": "bay | site",
    "from": "<YYYY-MM-DD>",
    "to": "<YYYY-MM-DD>"
  },
  "notice": "<the standing notice>",
  "level": "bay",
  "target": "<bay id>",
  "from": "<YYYY-MM-DD>",
  "to": "<YYYY-MM-DD>",
  "count": "<number of rows>",
  "rows": [
    {
      "bay_id": "<bay id>",
      "kind": "thermal | bloom | runoff | growth",
      "ts": "<ISO 8601, UTC>",
      "n_sites": "<integer>",
      "n_series": "<integer>",
      "value_max": "<number | null>",
      "value_mean": "<number | null>",
      "worst_label": "low | watch | stress | critical | null",
      "labels": {
        "<label>": "<count>"
      },
      "source": "coastal-intel",
      "product": "signal:<kind>:bay",
      "scale": "regional",
      "lead_hours": "<integer | null>",
      "licence": "<licence id>"
    }
  ],
  "licences": [
    {
      "id": "<licence id>",
      "name": "<licence name>",
      "provider": "<provider>",
      "url": "<url>"
    }
  ],
  "attribution": [
    "<attribution line>"
  ]
}

Examples in curl, Python and JavaScript

Each example reads bay-level signals; replace the placeholders. The key comes from the AGENCY_KEY environment variable.

curl

curl -H "Authorization: Bearer $AGENCY_KEY" \
  "https://coastal-intelligence.triskelionaisystems.com/api/agency/signals?target=<bay id>&from=<YYYY-MM-DD>&to=<YYYY-MM-DD>"

Python

import os
import requests  # pip install requests

API = "https://coastal-intelligence.triskelionaisystems.com/api"
headers = {"Authorization": f"Bearer {os.environ['AGENCY_KEY']}"}

res = requests.get(
    f"{API}/agency/signals",
    params={"target": "<bay id>", "from": "<YYYY-MM-DD>", "to": "<YYYY-MM-DD>"},
    headers=headers,
    timeout=30,
)
if res.status_code == 429:
    print("rate limited; retry after", res.headers.get("Retry-After"), "seconds")
res.raise_for_status()
data = res.json()
for row in data["rows"]:
    print(row["ts"], row["kind"], row["worst_label"], row["licence"])
print(*data["attribution"], sep="\n")  # cite these when you publish

JavaScript

const API = "https://coastal-intelligence.triskelionaisystems.com/api";
const params = new URLSearchParams({ target: "<bay id>", from: "<YYYY-MM-DD>", to: "<YYYY-MM-DD>" });
const res = await fetch(`${API}/agency/signals?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AGENCY_KEY}` },
});
if (res.status === 429) throw new Error(`rate limited; retry after ${res.headers.get("Retry-After")} s`);
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();
for (const row of data.rows) console.log(row.ts, row.kind, row.worst_label, row.licence);
console.log(data.attribution.join("\n")); // cite these when you publish

Live interactive reference

The API serves its own OpenAPI document at https://coastal-intelligence.triskelionaisystems.com/api/openapi.json (version 0.1.0) and an interactive reference at https://coastal-intelligence.triskelionaisystems.com/api/docs. It covers the whole API, including the routes the web app uses; the tags for partners are agency, data-reference, observations, risk-index. Routes under other tags need a signed-in web session and are not part of the partner API.