SmartAlert
Start free
SectionsAPI keys

Documentation

API keys

An API key gives a program read access to the project's data: alerts and rules. A key belongs to one project. A key can't change anything in the project.

On this page

The key works only with the SmartAlert MCP server: with a key an AI assistant sees your project's data, without one only the open tools. The REST API doesn't accept keys.

Who can use them

Role
A project member who can change settings. With view-only access, keys are hidden
How many
Up to 10 active keys per project, on any plan

If the project leaves Business, its keys stop working: a request with a key gets "API keys are on Business and above". You can revoke them on any plan.

Create a key

  1. Open Settings → API keys.
  2. Click Create key and name it after where it will run, for example "Grafana" or "Report script". 1 to 60 characters.
  3. Copy the key and store it right away.

The key is shown once. SmartAlert keeps only its hash, so nobody can show it again. Lost a key? Revoke it and create a new one.

The list shows the key as its start and last 4 characters, for example sa_live_…ab12, and the time of its last request to the minute.

Send the key

A key starts with sa_live_. Secret scanners recognise it by that prefix if a key ends up in a repository by mistake.

Send the key in the Authorization header:

http
Authorization: Bearer sa_live_…

A key in the URL, the request body or a cookie is not accepted.

Keep the key like a password: in a secret manager or an environment variable, not in code.

Revoke a key

Settings → API keys, Revoke next to the key, then confirm. The key stops working at once and leaves the list. A revoked key can't be restored.

Connect to Claude / Cursor

SmartAlert MCP server: https://mcp.smart-alert.io/mcp. A ready config with your key is in Settings → API keys, the "Connect to Claude / Cursor" block.

Claude Code, file .mcp.json:

json
{
  "mcpServers": {
    "smartalert": {
      "type": "http",
      "url": "https://mcp.smart-alert.io/mcp",
      "headers": { "Authorization": "Bearer sa_live_…" }
    }
  }
}

Cursor, file ~/.cursor/mcp.json — the same without the "type" line. Without headers only the open tools work.

Tools

All tools only read.

find_contract
Keynot needed
What it returnsPublic catalogue contracts by address or name, up to 10
contract_activity
Keynot needed
What it returnsA catalogue contract's activity: totals per event, overall and for 24 hours
project_status
Keynot needed
What it returnsA published status page: contracts, their state and incidents
list_alerts
Keyneeded
What it returnsThe project's alerts for a period, 7 days by default, up to 100 per request
explain_alert
Keyneeded
What it returnsWhy it fired: the value against the threshold or norm, the rule, the contract, whether it resolved
list_rules
Keyneeded
What it returnsThe project's rules and their noise: how often they fired, how many were false. A metric rule has its metric id
metric_series
Keyneeded
What it returnsA project metric's series over a period: 7 days by default, up to 200 points. Function count, sum, avg, min or max, split by a label

A key of a project below Business doesn't open the private tools: the assistant gets "API keys work on the Business plan and above".

Limits

With a key
120 requests a minute per key

Over the limit — 429 with a Retry-After header: how many seconds to wait.

Errors

401
An unknown or revoked key
429 RATE_LIMITED
Too many MCP requests. Retry after Retry-After seconds
403 PLAN_REQUIRED
The project's plan is below Business
429 LIMIT_EXCEEDED
On create: the project already has 10 keys. Revoke one you don't need

Found a mistake or didn’t find an answer? Write to us