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

Almost every SDK exposes 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 SDK without a singleton: it is instance-based (ApiAlertsClient::new(...)), which is more idiomatic for Rust.

Why a singleton?

It keeps the API surface tiny and the integration code identical across every language - the convention for SDKs of this shape, where PostHog, Sentry, Segment, and Datadog all default to a global singleton.

Dependency injection

Where DI is idiomatic, the SDK also exposes a constructable instance client behind a shared interface, so you can inject and mock it: C#/.NET (IApiAlertsClient, services.AddApiAlerts(...)), Kotlin/Java (ApiAlertsClient), Swift (a protocol), Dart, and PHP. The singleton is a thin facade over a default instance, so the two never drift. Each SDK’s doc covers its DI setup.

You don’t need an instance client for these two common cases:

• Sending to multiple workspaces - pass an API key as the optional last argument to any send / sendAsync call. See Sending to multiple workspaces below.
• Library authors wrapping the SDK - call setOverrides(integration, version, baseUrl) after configure to tag your library in the X-Integration header. If your wrapper misbehaves we can tell which library is responsible and report it back to you.

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 7 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)
title	No	Short headline some destinations render separately from the message body
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)
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
configure("your-api-key")
setDebug(true)

Request timeout

All SDKs apply a 30-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, Unity, Godot
Dart	apialerts	Flutter, Dart backends
Go	github.com/apialerts/apialerts-go	Servers, CLI, microservices
Godot	Godot Asset Store	Godot 4 games
Java	com.apialerts:client	Spring Boot, JVM apps
JavaScript	apialerts	Browser, Node.js, Bun
Kotlin	com.apialerts:client	KMP: Android, JVM, iOS, macOS, JS, wasm
PHP	apialerts/apialerts	Laravel, WordPress, scripts
Python	apialerts	Django, Flask, FastAPI
Ruby	apialerts	Rails, scripts
Rust	apialerts	Instance-based, no singleton
Swift	apialerts-swift	iOS, macOS, watchOS, Vapor