Python Alerts SDK

The API Alerts Python SDK sends alerts from your Python code through API Alerts. Drop it into Django, Flask, FastAPI, Celery workers, or any Python service that needs to notify you when something important happens. Minimal setup, fire-and-forget by default with optional response handling, and zero infrastructure.

Installation

pip install apialerts

Usage

from apialerts import ApiAlerts, Event

ApiAlerts.configure('YOUR-API-KEY')

# Simple notification
ApiAlerts.send(Event(message='Deployment successful'))

# With routing (recommended for production)
ApiAlerts.send(Event(event='ci.deploy.success', message='Deployment successful'))

# With all options
ApiAlerts.send(Event(
    event='user.signup',
    message='New user signed up',
    channel='developers',
    title='New Signup',
    tags=['signup', 'organic'],
    link='https://dashboard.example.com/users/123',
    data={'plan': 'pro', 'region': 'us-east-1'},
))

Event fields

Field	Type	Required	Description
message	str	Yes	Human-readable notification text. This is what appears on the push notification lock screen.
channel	str	No	Workspace channel the push notification fires on. Defaults to the workspace default channel when omitted.
event	str	No	What kind of thing happened. Optional but recommended. Routers match this value with Unix glob (fnmatch): dotted keys like ci.deploy.success match ci.*, and free-form keys like User Signup match User *. Dotted notation is just a tidy convention, not a requirement.
title	str	No	Short headline some destinations render separately from the message body.
tags	list[str]	No	Categorisation tags for filtering and search.
link	str	No	URL associated with the event. Available as a deeplink for push notifications and as a call-to-action for routed destinations.
data	dict[str, Any]	No	Arbitrary key-value metadata. Available to non-push destinations for templating (Slack message bodies, email templates, webhook payloads).

Optional fields are omitted from the request body when None - they’re never sent as null.

Wait for the response

send is fire-and-forget and never raises. For a result you can inspect, use send_async. It never raises either - check result.success.

result = await ApiAlerts.send_async(Event(message='Deployment successful'))
if not result.success:
    print(f'Error: {result.error}')
else:
    print(f'Sent to {result.workspace} ({result.channel})')

The SendResult shape:

@dataclass
class SendResult:
    success: bool
    workspace: Optional[str]   # populated on success
    channel: Optional[str]     # populated on success
    warnings: list[str]        # non-fatal server warnings
    error: Optional[str]       # populated on failure

Send to multiple workspaces

Pass an api_key as the optional second argument to override the configured key for a single call.

ApiAlerts.send(Event(message='Deploy complete'), api_key='other-workspace-api-key')

Debug logging

Pass debug=True to configure to log success, warning, and error events via the stdlib logging module under the 'apialerts' logger.

ApiAlerts.configure('YOUR-API-KEY', debug=True)

import logging
logging.getLogger('apialerts').setLevel(logging.INFO)
logging.basicConfig()

Critical errors (missing API key, not yet configured) always log regardless of the debug flag.

Resources