> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Base URLs, authentication, permissions, request conventions, streaming, and error handling.

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:

```text theme={null}
http://localhost:5080/api/v1
```

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:

```http theme={null}
Authorization: Bearer <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:

| Status | Meaning                                                                  |
| ------ | ------------------------------------------------------------------------ |
| `400`  | Invalid request or unsupported parameter.                                |
| `401`  | Missing, invalid, expired, or route-specific credential.                 |
| `402`  | Organization service is paused by billing or trial policy.               |
| `403`  | Permission, resource relationship, scope, or license feature is missing. |
| `404`  | Resource is absent or not visible in the authorized scope.               |
| `409`  | State or uniqueness conflict.                                            |
| `413`  | Payload or storage limit exceeded.                                       |
| `429`  | Rate limit exceeded.                                                     |
| `500`  | Internal failure; use request and trace ids for correlation.             |

Responses can include `X-Request-Id` and `X-Trace-Id`. Include both identifiers when reporting a server-side
failure.

## Browse the API

<CardGroup cols={2}>
  <Card title="Current API catalog" icon="list" href="/en-US/api/catalog">
    Map route families to product capabilities and authorization.
  </Card>

  <Card title="Authentication recipes" icon="key" href="/en-US/api/auth/login">
    Sign in and manage API tokens.
  </Card>

  <Card title="Intake recipes" icon="inbox" href="/en-US/api/intake/native-json">
    Send native JSON and protocol-compatible telemetry.
  </Card>

  <Card title="Query recipes" icon="magnifying-glass" href="/en-US/api/query/execute">
    Run SQL, PromQL-compatible, streaming, and saved queries.
  </Card>

  <Card title="Alerting recipes" icon="bell" href="/en-US/api/alerting/list-rules">
    Manage rules, incidents, channels, and escalations.
  </Card>

  <Card title="Enterprise capabilities" icon="key" href="/en-US/api/admin/paid-edition">
    Understand feature entitlements and protected system license APIs.
  </Card>
</CardGroup>