git.stella-ops.org/docs/api/notify-sdk-examples.md

Notifier SDK Usage Examples (rules, incidents, quiet hours)

Work of this type must also be applied everywhere it should be applied. Keep examples air-gap friendly and deterministic.

Prerequisites

• Token with scopes: notify.viewer for reads, notify.operator for writes (tenant-scoped).
• Tenant header: X-StellaOps-Tenant: <tenant-id>.
• Base URL: https://api.stellaops.example.com.
• OpenAPI document: /.well-known/openapi (served by Notifier).

Rules CRUD

cURL

# Create rule
curl -X POST "$BASE/api/v1/notify/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-Tenant: acme-prod" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleId": "rule-attest-fail",
    "tenantId": "acme-prod",
    "name": "Attestation failures to SOC",
    "match": { "eventKinds": ["attestor.verification.failed"] },
    "actions": [{
      "actionId": "act-soc",
      "channel": "chn-soc-webhook",
      "template": "tmpl-attest-verify-fail",
      "digest": "instant"
    }]
  }'

# List rules (paginated)
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-StellaOps-Tenant: acme-prod" \
     "$BASE/api/v1/notify/rules?pageSize=50"

TypeScript (OpenAPI-generated client)

import { RulesApi, Configuration } from "./generated/notify-client";

const api = new RulesApi(new Configuration({
  basePath: process.env.BASE,
  accessToken: process.env.TOKEN
}));

await api.createRule({
  xStellaOpsTenant: "acme-prod",
  notifyRule: {
    ruleId: "rule-attest-fail",
    tenantId: "acme-prod",
    name: "Attestation failures to SOC",
    match: { eventKinds: ["attestor.verification.failed"] },
    actions: [{
      actionId: "act-soc",
      channel: "chn-soc-webhook",
      template: "tmpl-attest-verify-fail",
      digest: "instant"
    }]
  }
});

Python (OpenAPI-generated client)

from notify_client import RulesApi, Configuration, ApiClient

config = Configuration(host=BASE, access_token=TOKEN)
with ApiClient(config) as client:
    api = RulesApi(client)
    api.create_rule(
        x_stella_ops_tenant="acme-prod",
        notify_rule={
            "ruleId": "rule-attest-fail",
            "tenantId": "acme-prod",
            "name": "Attestation failures to SOC",
            "match": {"eventKinds": ["attestor.verification.failed"]},
            "actions": [{
                "actionId": "act-soc",
                "channel": "chn-soc-webhook",
                "template": "tmpl-attest-verify-fail",
                "digest": "instant"
            }]
        }
    )

Incident acknowledge

cURL

curl -X POST "$BASE/api/v1/notify/incidents/inc-telemetry/ack" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-Tenant: acme-prod" \
  -H "Content-Type: application/json" \
  -d '{"ackToken":"<dsse-token>"}' \
  -i

TypeScript

import { IncidentsApi } from "./generated/notify-client";
await new IncidentsApi(config).ackIncident({
  incidentId: "inc-telemetry",
  xStellaOpsTenant: "acme-prod",
  inlineObject: { ackToken: process.env.ACK_TOKEN }
});

Quiet hours

cURL

curl -X POST "$BASE/api/v1/notify/quiet-hours" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-Tenant: acme-prod" \
  -H "Content-Type: application/json" \
  -d '{
    "quietHoursId": "qh-default",
    "windows": [{
      "timezone": "UTC",
      "days": ["Mon","Tue","Wed","Thu","Fri"],
      "start": "22:00",
      "end": "06:00"
    }],
    "exemptions": [{
      "eventKinds": ["attestor.verification.failed"],
      "reason": "Always alert on attestation failures"
    }]
  }'

Smoke-test recipe (SDK CI)

• Generate client from /.well-known/openapi (ts/python/go) with deterministic options.
• Run:
  1. create rule → list rules → delete rule.
  2. set quiet hours → get quiet hours.
  3. ack incident with dummy token (expect 2xx or validation error envelope).
• Assert deterministic headers: X-OpenAPI-Scope=notify, ETag stable for identical spec bytes.