Skip to main content
MoleSignal exposes a versioned HTTP API. Product endpoints normally use /api/v1; probes, Prometheus metrics, public share links, and selected compatibility protocols also use top-level paths.

​
Base URL

For a local instance:
In production, replace the host with the externally reachable URL configured for the deployment.

​
Bearer authentication

Protected endpoints accept a login JWT or an API token:
API tokens use ms_<prefix>_<secret>. Authentication creates an IAM context containing the subject, active organization or platform scope, and effective permissions.

​
Public and self-authenticating routes

Routes that cannot use a normal organization bearer token validate a route-specific narrow credential or policy. Current examples include:
  • sign-in, signup policy, and password reset;
  • health and Prometheus metrics;
  • public resource-share exchange and share-session requests;
  • signed file downloads and public avatars;
  • Stripe and push-connector webhooks.
Do not treat a public route as unrestricted. The handler validates signup policy, a share token, download token, signature, or connector credential.

​
Authorization

A protected endpoint can require several conditions:
  • an organization permission such as streams.query;
  • a platform permission such as sys.licenses.read;
  • a feature entitlement such as agent;
  • ownership, a resource relationship, or a cross-organization grant;
  • an active organization or billing state.
Use GET /api/v1/iam/capabilities to inspect the current subject’s effective snapshot. Do not infer access from a role label or hidden navigation item.

​
Requests

  • Most bodies use JSON with Content-Type: application/json.
  • Compatibility intake endpoints use protocol-native payloads, including Protobuf, NDJSON, or compressed request bodies.
  • Fields ending in _micros contain Unix time in microseconds.
  • Native telemetry records use _timestamp; follow the endpoint schema when converting SDK time.
  • Path ids and stream names must be URL-encoded when inserted into a URL.
  • Organization scope comes from the authenticated IAM context, not a model- or browser-supplied organization id.

​
Query and long-running responses

The query family supports regular JSON, NDJSON streaming, running-query control, and asynchronous search jobs. Streaming callers should handle partial network delivery and client cancellation. Large Agent evidence, generated reports, profile blobs, and exports can be stored as files and downloaded through a scoped token rather than embedded in JSON.

​
Errors

API errors use an HTTP status and a JSON error message. Common statuses are: Responses can include X-Request-Id and X-Trace-Id. Include both identifiers when reporting a server-side failure.

​
Browse the API

Current API catalog

Map route families to product capabilities and authorization.

Authentication recipes

Sign in and manage API tokens.

Intake recipes

Send native JSON and protocol-compatible telemetry.

Query recipes

Run SQL, PromQL-compatible, streaming, and saved queries.

Alerting recipes

Manage rules, incidents, channels, and escalations.

Enterprise capabilities

Understand feature entitlements and protected system license APIs.
Last modified on August 9, 2026