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.

Why singleton-only?

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

The two cases that look like they need an instance client both have answers:

• 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, Azure Functions
Go	github.com/apialerts/apialerts-go	Servers, CLI, microservices
JavaScript	apialerts	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, and Ruby SDKs launch with 2.0.