Skip to main content
MoleSignal exposes a single versioned HTTP API (v1). This page covers the conventions that apply to every endpoint. The individual endpoints — with request/response schemas and a live playground — are listed in the sidebar.

​
Base URL

All endpoints are served under /api/v1. In the sandbox that is: 
http://localhost:5080/api/v1
In production, swap in your own host (for example https://molesignal.example.com/api/v1).

​
Authentication

Every endpoint requires a bearer token unless noted otherwise: 
Authorization: Bearer <token>
The token can be either:
  • a JWT obtained from POST /api/v1/auth/login, or
  • an API token shaped ms_<prefix>_<secret> (see Security).
Only three routes are unauthenticated: /api/v1/healthz, /api/v1/auth/login, and /metrics.

​
Requests

  • Request bodies are JSON (Content-Type: application/json), except the ingest endpoints that emulate other protocols (Elasticsearch _bulk, Loki, Prometheus remote_write), which take their native formats.
  • Timestamps are microseconds since the Unix epoch — both in ingested records (_timestamp) and in query time ranges (time_range.start / time_range.end).
  • Tenancy: every request is scoped to your org_id. The server rewrites an org_id predicate into every query plan, so data never crosses orgs.

​
Successful responses

2xx responses return JSON. The shape depends on the endpoint (each is documented on its own page). For example, the query endpoint returns: 
{
  "rows": [{ "level": "error", "count": 12 }],
  "columns": ["level", "count"],
  "scanned_rows": 10432,
  "took_ms": 18,
  "cache_hit": false
}
Some endpoints stream results as NDJSON when you send Accept: application/x-ndjson; streaming bypasses the query_result cache.

​
Error responses

Errors return a uniform JSON envelope with a single error message: 
{
  "error": "invalid argument: time_range.start must be < end"
}

​
Status codes

CodeMeaning
200Success
400Invalid argument
401Unauthorized — token missing or invalid
403Forbidden — insufficient role or license
404Not found, or a cross-org lookup
409Conflict — unique constraint or state conflict
413Quota exhausted (storage cap)
429Rate limited (ingest/query QPS quota)

​
Rate limits & quotas

Each org has per-tenant quotas on ingest QPS, query QPS, and storage. Exceeding them returns 429 (rate) or 413 (storage), each accompanied by an audit entry and an alert. See Security.

​
Endpoints

The endpoints are grouped in the sidebar:

Authentication

Ingest

Query

Streams

Alerting

Correlation & web

Administration

Some endpoints (SSO, clusters, connectors, copilot, RUM) are gated behind paid/feature builds — see Paid-edition endpoints.