Docs

REST API

Everything the API offers is scoped to your workspace and authenticated with an API key. The base URL is https://magesentinel.com/api/v1.

← All docs · Updated 2026-10-26

Authentication

Create a key in the dashboard under API keys. Keys start with cg_ and are shown once; keep it as a secret in your CI. Send it on every request as a bearer token. Requests without a key, or with anything other than an API key, get 401. Delete a key in the dashboard to revoke it at once.

bash

curl -H "Authorization: Bearer $MAGESENTINEL_API_KEY" \
  https://magesentinel.com/api/v1/stores

Every response is JSON with the result under data. Errors carry a message under error and the matching HTTP status:

json

{ "data": [ { "id": "cmssp3dol0007dgj7luxpe85j", "url": "https://example-shop.com/", "platform": "magento2" } ] }

{ "error": "Invalid or missing API key" }

Endpoints

All paths are relative to https://magesentinel.com/api/v1. The examples on the API keys page of the dashboard show the full response of each read endpoint.

text

GET    /stores                        List your stores
POST   /stores                        Add a store
GET    /stores/{id}                   One store, with its monitors
PATCH  /stores/{id}                   Update a store
DELETE /stores/{id}                   Remove a store

GET    /monitors                      List your monitors
POST   /monitors                      Add a monitor
PATCH  /monitors/{id}                 Update a monitor
DELETE /monitors/{id}                 Remove a monitor
POST   /monitors/{id}/run             Start a check now
GET    /monitors/{id}/uptime          Hourly uptime

GET    /runs                          Runs (storeId, monitorId, status, flowType, limit)
GET    /runs/{id}                     One run, with its checkout payload
GET    /runs/{id}/evidence            Screenshots captured for a run
GET    /runs/stats                    The numbers behind the success rate

GET    /incidents                     Incidents
GET    /incidents/{id}                One incident
GET    /alerts                        Alerts that have been sent
GET    /alert-channels                Your alert channels
GET    /overview/board                Per-step latency across stores

Start a check after a deploy

Find the monitor id with GET /monitors, then start a check from the last step of your deploy:

bash

curl -X POST -H "Authorization: Bearer $MAGESENTINEL_API_KEY" \
  https://magesentinel.com/api/v1/monitors/MONITOR_ID/run

The answer is 202. The check runs within a minute or two and alerts through your usual channels if a step fails:

json

{ "data": { "jobId": "…", "status": "queued" } }

To make the pipeline wait for the result, start the check and poll the newest run of that monitor. This script needs curl and jq:

bash

#!/usr/bin/env bash
# Start a check and fail the pipeline if it does not PASS within 5 minutes.
set -euo pipefail
API=https://magesentinel.com/api/v1
AUTH="Authorization: Bearer $MAGESENTINEL_API_KEY"
SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -fsS -X POST -H "$AUTH" "$API/monitors/$MONITOR_ID/run" > /dev/null

for i in $(seq 1 30); do
  sleep 10
  run=$(curl -fsS -H "$AUTH" "$API/runs?monitorId=$MONITOR_ID&limit=1" | jq -r --arg s "$SINCE" \
    '.data[0] | select(.startedAt >= $s) | .status')
  case "$run" in
    PASS) echo "Checkout OK"; exit 0 ;;
    FAIL) echo "Checkout FAILED"; exit 1 ;;
  esac
done
echo "No result in time"; exit 1

In GitHub Actions, store the key as a secret and call the script as the last step:

yaml

# .github/workflows/deploy.yml (last step)
- name: Check the checkout
  env:
    MAGESENTINEL_API_KEY: ${{ secrets.MAGESENTINEL_API_KEY }}
    MONITOR_ID: ${{ vars.MAGESENTINEL_MONITOR_ID }}
  run: ./scripts/check-checkout.sh

Limits

Each API key may make 60 requests a minute and start at most 6 checks every 10 minutes. Scheduled checks are not affected and keep the cadence of your plan. Over the limit the API answers 429 with Retry-After in seconds:

json

HTTP/1.1 429 Too Many Requests
Retry-After: 600

{ "error": "Too many check runs: at most 6 every 10 minutes per API key" }