SignalOS Public API

Read/write access to SignalOS's measured brand-visibility data, webhook subscriptions on domain events, and an MCP server for AI agents. Every response carries the same honesty contract the in-app UI follows — a value is never presented with more certainty than the underlying measurement supports.

Which plans include the API

API and MCP access aren't included on any plan that's published right now. See pricing for what each plan includes.

If your plan changes to one without API access, your existing keys stop working on their next request. They aren't deleted, and they work again if you move to a plan that includes it.

See pricing →

Authentication

Every request carries Authorization: Bearer sk_.... Create a key in Settings → API Keys, optionally narrowed to specific scopes (an unrestricted key can do anything your role can). Session cookies are not accepted on /api/public/v1.

Scope	Grants
measurements:read	Read measurement runs and observations
findings:read	Read findings
recommendations:read	Read recommendations
queries:read	Read the tracked query universe
queries:write	Create and modify tracked queries
annotations:read	Read annotations
annotations:write	Create and modify annotations
webhooks:read	Read webhook subscriptions and delivery logs
webhooks:write	Create, modify and rotate webhook subscriptions
mcp:read	Query the MCP server's read-only tools (Ask SignalOS templates, cited real data)

Try it now — sandbox

The sandbox demo organization hasn't been seeded in this environment yet — these examples will work once it has (see the admin demo-org seed action).

Every response is provenanced

Measurements, findings, and recommendations each carry a provenance object: confidence (interval/level/method — null when the underlying method has nothing calibrated to report, never a fabricated number), sample size, whether the value is measured or modelled, and a drill_url back into SignalOS showing the real evidence.

Pagination, sorting, sparse fieldsets

Every list endpoint accepts limit (default 25, max 200), offset, sort (a field name, prefix with - for descending), and fields (comma-separated sparse fieldset). See the OpenAPI spec for the full route list.

Webhooks

Subscribe to domain events with a real, durable delivery queue (at-least-once, exponential backoff, dead-letter with manual replay). Current event types: query.createdannotation.created

curl -X POST "https://signalos.xonik.com/api/public/v1/webhooks" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/signalos","eventTypes":["query.created"]}'

Each delivery is signed: X-Signalos-Signature is an HMAC-SHA256 over {keyId}.{timestamp}.{nonce}.{sha256(body)}, with X-Signalos-Webhook-Id, X-Signalos-Timestamp, and X-Signalos-Nonce carrying the inputs — verify with the secret shown once at subscription creation.

MCP server

Point an MCP-capable agent at https://signalos.xonik.com/api/public/v1/mcp (Streamable HTTP transport) with the same Bearer key, scoped to mcp:read. Tools: list_ask_templates, ask_signalos, and get_share_of_voice — every one backed by a real, deterministic template over real rows (the same catalog Ask SignalOS uses in-app), returning cited real rows or an honest refusal, never a fabricated fact.

{
  "mcpServers": {
    "signalos": {
      "url": "https://signalos.xonik.com/api/public/v1/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}