HTTP API reference

The MeshedFlow HTTP API lets you read your telemetry, manage your content origins, and pull pilot reports programmatically. This page documents the endpoints a tenant-role token (the SDK/API token issued to your account) is allowed to call.

Base URL and auth

• Base URL — the control plane on your tenant’s host (the API served alongside your portal, e.g. https://app.meshedflow.com).
• Auth — a Bearer token: your SDK/API token.

Authorization: Bearer <your-sdk-token>

Your token carries your customerId. The API uses it to scope every read to your own streams, using the <customerId>:<name> boundary rule from Authentication.

What a tenant token can call

A tenant token is deliberately scoped. It can read its own streams, metrics, timeseries, exports, and pilot reports, and manage its own content origins. Platform-wide reads are refused — see Not available to tenant tokens.

Telemetry

GET /telemetry/streams

Lists your stream ids. A tenant token sees only streams attributed to your customerId. Add ?detail=1 to get a per-stream summary table instead of ids.

Query params: window (24h default, 7d, 30d, 1h, all), detail (1 / true).

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/streams?window=24h"

{ "streams": ["cust_20260808_eb8790f7:live-demo", "cust_20260808_eb8790f7:vod-42"] }

With ?detail=1, each entry is a summary object (streamId, totalSessions, totalBytesOffloaded, totalBytesFallback, avgOffloadRatio, avgPeerCount, avgBufferHealth, activePeers, live, lastSeenAt).

GET /telemetry/metrics/:streamId

Aggregated metrics for one of your streams. Requesting a stream that isn’t attributed to your customerId returns 403.

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/metrics/cust_20260808_eb8790f7:live-demo?window=24h"

{
  "streamId": "cust_20260808_eb8790f7:live-demo",
  "totalSessions": 1842,
  "totalBytesOffloaded": 734000000000,
  "totalBytesFallback": 266000000000,
  "avgOffloadRatio": 0.734,
  "avgPeerCount": 6.1,
  "avgBufferHealth": 12.4
}

Caution

GET /telemetry/metrics (no :streamId) is the platform-wide aggregate and is refused for tenant tokens — see below. Use the per-stream form.

GET /telemetry/timeseries

Bucketed series for one of your streams. A tenant token must name one of its own streams with ?streamId= — without it the request would return the platform-wide series, so it’s refused (403). A streamId that isn’t yours also returns 403.

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/timeseries?streamId=cust_20260808_eb8790f7:live-demo&bucketSeconds=600"

GET /telemetry/export

Streams an export of one of your streams. Requires the telemetry:read capability (which a tenant token has) and, like timeseries, requires ?streamId= naming one of your own streams — otherwise the request is refused rather than exporting the platform-wide aggregate.

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/export?streamId=cust_20260808_eb8790f7:live-demo&window=7d" \
  -o export.json

Content origins

The per-tenant allowlist that /manifest/sign enforces. Both routes accept your tenant id or your customerId in :id, and a tenant session may manage only its own list.

GET /control/tenants/:id/origins

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/tenants/cust_20260808_eb8790f7/origins"

{ "origins": ["https://cdn.example.com"] }

PUT /control/tenants/:id/origins

Replaces your allowlist. Origins must be valid http/https URLs with a host. An empty array clears your allowlist and falls back to the platform default.

curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"origins":["https://cdn.example.com","https://vod.example.com/hls"]}' \
  "https://app.meshedflow.com/control/tenants/cust_20260808_eb8790f7/origins"

{ "origins": ["https://cdn.example.com", "https://vod.example.com/hls"] }

Note

The allowlist is enforced upstream at the signer, so a PUT is pushed to the control plane synchronously — if the control plane refuses or is unreachable, the request returns 502 and nothing is saved.

Pilot reports

GET /control/reports/pilot/:streamId

A structured pilot report for one of your streams. Requires the telemetry:read capability; a tenant token may only request a stream attributed to it (403 otherwise). By default returns JSON; add ?format= for other renderings.

Query params: format (json default, md / markdown, html), bucketSeconds (60–21600, default 600).

# JSON (default)
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/reports/pilot/cust_20260808_eb8790f7:live-demo"

# Downloadable Markdown or self-contained HTML
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/reports/pilot/cust_20260808_eb8790f7:live-demo?format=html" \
  -o pilot-report.html

See Analytics & pilot reports for what the report contains and how its cost figures are computed.

Manifest

GET /manifest/public-key

Public (no auth). Returns the ECDSA P-256 verification key (a JWK) SDK clients use to verify peer segments.

Tip

You normally don’t call this — the SDK fetches it automatically (autoFetchManifestPublicKey, on by default) to verify every peer segment. It’s documented here for completeness. Signing (POST /manifest/sign) is performed by the control plane on the SDK’s behalf; it is not a tenant-facing integration endpoint.

curl "https://app.meshedflow.com/manifest/public-key"

{ "kty": "EC", "crv": "P-256", "x": "…", "y": "…", "use": "sig", "alg": "ES256" }

Not available to tenant tokens

The following return 403 for a tenant-role token because they read across every customer on the shared fleet and have no per-customer meaning:

• GET /telemetry/metrics — platform-wide aggregate. Use GET /telemetry/metrics/:streamId instead.
• Platform-wide billing reads — GET /billing/summary, GET /billing/invoices, and any /billing/customers/…, /billing/usage/…, or /billing/invoices/… route naming a customer other than yours.

Tenant-management routes such as the tenant list and tenant detail (GET /control/tenants, GET /control/tenants/:id) require the tenants:read capability, which a tenant-role token does not carry — the origins routes above are the exception, gated by a customer-match check rather than that capability.

Related

• SDK reference — the loader that calls this API for you.
• Authentication & provisioning — token scoping and the boundary rule.