SDK Overview
Every API Alerts SDK follows the same design, so if you know how one works, you know how they all work. This page explains the shared patterns.
Configure once, send anywhere
All SDKs expose a global singleton. Configure it once at startup (in your main, AppDelegate, _ready, etc.), then call send from anywhere in your codebase without passing clients around.
ApiAlerts.configure("your-api-key")
// anywhere, any file
ApiAlerts.send(Event(message = "Deploy complete"))configure is idempotent. Subsequent calls are no-ops and the first call wins.
Rust is the only exception. It is instance-based (
ApiAlertsClient::new(...)) rather than a singleton, which is more idiomatic for Rust.
Two send methods
Every SDK exposes the same two methods:
| Method | Behaviour |
|---|---|
send(event) | Fire-and-forget. Never throws, never panics. Returns immediately. |
sendAsync(event) | Waits for the response. Returns the result or an error. |
Use send when you don’t care about confirmation. Use sendAsync when you want to verify delivery or read workspace/channel from the response.
The Event object
All 6 fields are consistent across every SDK. Only message is required.
| Field | Required | Description |
|---|---|---|
message | Yes | The notification body |
channel | No | Target channel (defaults to workspace default) |
event | No | Event key for routing rules (e.g. ci.deploy) |
tags | No | Categorisation tags |
link | No | URL to open from the notification |
data | No | Arbitrary JSON object for template variables or metadata |
Optional fields are omitted from the request body when not set. They are never sent as null.
The result
sendAsync returns a result object with:
| Field | Description |
|---|---|
workspace | Name of the workspace the event was delivered to |
channel | Channel it was delivered to |
warnings | Non-fatal notices from the API (e.g. deprecated fields) |
Most SDKs also include success (bool) and error (string) directly on the result, so errors are returned rather than thrown. Go, Swift, Kotlin, and Rust use their language’s native error mechanism instead ((T, error), Result<T, E>, etc.).
Sending to multiple workspaces
Pass an API key directly to override the configured key for a single call:
// Languages with optional params (JS, Python, Kotlin, Swift, etc.)
sendAsync(event, apiKey: "other-workspace-key")
// Languages without optional params (Go, Rust, Godot)
sendWithKeyAsync("other-workspace-key", event)Debug logging
Debug mode logs successful sends, warnings, and errors to stderr/output. It is off by default.
// Languages with optional params
configure("your-api-key", debug: true)
// Go, Rust, Godot
configure("your-api-key")
setDebug(true)Request timeout
All SDKs apply a 15-second timeout to every HTTP request. Requests that exceed this limit fail with a network error and return a failure result, so they never hang indefinitely.
Available SDKs
| Language | Package | Notes |
|---|---|---|
| C# | ApiAlerts | ASP.NET, Blazor, Azure Functions |
| Go | github.com/apialerts/apialerts-go | Servers, CLI, microservices |
| JavaScript | @apialerts/apialerts-js | Browser, Node.js, Bun |
| Kotlin | com.apialerts:client | KMP: Android, JVM, iOS, macOS, JS, wasm |
| Python | apialerts | Django, Flask, FastAPI |
| Rust | apialerts | Instance-based, no singleton |
| Swift | apialerts-swift | iOS, macOS, watchOS, Vapor |
Java, Dart, PHP, Ruby, and Godot SDKs launch with 2.0.