Knock Python API Library

1.24.1 · active · verified Mon Apr 13

The Knock Python library provides convenient access to the Knock REST API from any Python 3.9+ application. Knock is a notification infrastructure platform that helps developers build and manage notification workflows across multiple channels including email, push, SMS, Slack, and in-app feeds. The library offers both synchronous and asynchronous clients powered by `httpx` and includes type definitions for all request parameters and response fields. It is generated with Stainless and follows semantic versioning conventions.

Warnings

breaking Upgrading from v0.x to v1.0 introduced significant breaking changes. Client initialization, method naming (e.g., `client.users.identify()` is now `client.users.update()`, `client.notify()` removed), method parameters (now positional, `data` wrapper removed for user properties), and response types (Pydantic models instead of dictionaries) have changed.
Fix: Refer to the official v1.0 upgrade guide for a complete list of changes and migration instructions. Update client initialization and method calls according to the new API design.
gotcha API responses are Pydantic model instances, not raw Python dictionaries. If you need a dictionary representation (e.g., for JSON serialization), use the `.model_dump()` method (Pydantic v2) or `.dict()` (Pydantic v1) on the response object.
Fix: Access data via object attributes (e.g., `response.workflow_run_id`) or convert to a dictionary using `response.model_dump()`.
gotcha The `knockapi` library relies on Pydantic for its models. A bug fix in v1.24.1 addressed an issue where `by_alias` was not passed unless explicitly set when dumping models. While a bug fix, users relying on previous (potentially incorrect) behavior with Pydantic aliases might observe changes.
Fix: Ensure your Pydantic model configurations and usage of `model_dump(by_alias=...)` are as intended. The library's internal fix makes its Pydantic usage more explicit and correct.
gotcha There are other Python libraries with similar names, such as `knockknock` (for machine learning notifications) and `knockpy` (for variable selection). Ensure you are importing `Knock` or `AsyncKnock` from `knockapi` to use the correct client for the Knock notification platform.
Fix: Double-check your `import` statements to ensure they are `from knockapi import ...`.
gotcha For robust applications, implement comprehensive error handling. The `knockapi` client raises specific exceptions like `knockapi.APIConnectionError` (network issues), `knockapi.RateLimitError` (429 status), and `knockapi.APIStatusError` (other 4xx/5xx responses).
Fix: Wrap API calls in `try...except` blocks to catch and handle `knockapi.APIError` subclasses appropriately.

Install

pip install knockapi Standard installation
pip install knockapi[aiohttp] For async support with aiohttp

Imports

Knock
```
from knockapi import Knock
```
AsyncKnock
```
from knockapi import AsyncKnock
```
email_sender
```
from knockknock import email_sender
```
There is a separate, unrelated library called 'knockknock' for ML training notifications.

Quickstart

Initializes the synchronous Knock client using an API key from an environment variable and triggers a sample workflow. Ensure the `KNOCK_API_KEY` environment variable is set and a workflow with the key `dinosaurs-loose` exists in your Knock dashboard.

import os
from knockapi import Knock

# Initialize the client with your API key from an environment variable
# KNOCK_API_KEY environment variable is used by default if not explicitly provided
client = Knock(api_key=os.environ.get('KNOCK_API_KEY', ''))

# Trigger a workflow (ensure 'dinosaurs-loose' workflow exists in Knock dashboard)
try:
    response = client.workflows.trigger(
        key="dinosaurs-loose",
        recipients=["dnedry"],
        data={
            "dinosaur": "triceratops"
        },
    )
    print(f"Workflow run ID: {response.workflow_run_id}")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →