SignalKin API

Send events in from any system, read and act on conversations and alerts, and receive SignalKin events by webhook.

Base address: https://api.signalkin.ai/v1 · OpenAPI 3.1 description

Authentication

Create a key in Settings → Developers and send it as a Bearer token. Each key has scopes; a call without the right scope gets 403.

curl https://api.signalkin.ai/v1/events \
  -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: line2-overheat-0925" \
  -d '{"source":"scada-line-2","severity":"urgent","title":"Motor 3 over 95 °C","body":"Sensor T-3 reads 97 °C","dedupe_key":"line2-motor3"}'

Limits and retries

600 requests a minute per key (429 above). On POST, send an Idempotency-Key header: the first response is replayed for 24 hours.

Errors

Every error has the same shape. Anything outside your workspace is a plain 404.

{ "error": { "code": "not_found", "message": "Not found.", "request_id": "req_…" } }

Endpoints

post	/v1/events	Raise an event; sorted and escalated like a message	events:write
get	/v1/conversations	List conversations, newest first	conversations:read
get	/v1/conversations/{id}	One conversation	conversations:read
get	/v1/conversations/{id}/messages	Messages, newest first	conversations:read
post	/v1/conversations/{id}/messages	Reply through the conversation's channel	conversations:write
post	/v1/conversations/{id}/assign	Assign to a member (or unassign)	conversations:write
post	/v1/conversations/{id}/level	Change the level (feedback for the AI)	conversations:write
post	/v1/conversations/{id}/resolve	Resolve	conversations:write
get	/v1/alerts	List alerts	alerts:read
get	/v1/alerts/{id}	One alert with its escalation timeline	alerts:read
post	/v1/alerts/{id}/acknowledge	Acknowledge (stops escalation)	alerts:write
post	/v1/alerts/{id}/resolve	Resolve	alerts:write
get	/v1/oncall/now	Who is on call now, per team	oncall:read
get	/v1/contacts	List or search contacts	contacts:read
post	/v1/contacts	Create or update a contact (matched by any identity)	contacts:write

Webhooks

SignalKin POSTs JSON events to your address, signed with your endpoint's secret. Retries back off for 24 hours; after 50 failures in a row the endpoint is paused and admins are emailed.

Events

message.received · message.classified · conversation.assigned · conversation.resolved · alert.opened · alert.escalated · alert.acknowledged · alert.resolved · channel.disconnected

Verify the signature

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, header, rawBody) {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "") ?? [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}