Install & Compatibility
Where this runs
tested against v1.29.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.156s · 43.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.3s · import 1.057s · 45MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Knock
✓ from knockapi import Knock
AsyncKnock
✓ from knockapi import AsyncKnock
email_sender
✓ from knockknock import email_sender
✗ from knockapi import email_sender
There is a separate, unrelated library called 'knockknock' for ML training notifications.
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}")
Debug
Known issues
breakingUpgrading 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.fixRefer 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.
affects: <1.0.0 to >=1.0.0
gotchaAPI 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.fixAccess data via object attributes (e.g., `response.workflow_run_id`) or convert to a dictionary using `response.model_dump()`.
affects: >=1.0.0
gotchaThe `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.fixEnsure 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.
affects: <1.24.1
gotchaThere 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.fixDouble-check your `import` statements to ensure they are `from knockapi import ...`.
affects: All versions
gotchaFor 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).fixWrap API calls in `try...except` blocks to catch and handle `knockapi.APIError` subclasses appropriately.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'knockapi'
This error occurs when the 'knockapi' library is not installed, or there is a naming conflict with other Python packages like 'knockknock' or 'knockpy' which can lead to incorrect import statements.
fixEnsure the correct library is installed using `pip install knockapi` and that your import statements are `from knockapi import Knock` or `from knockapi import AsyncKnock`.
knockapi.AuthenticationError
This error indicates that the API request failed due to an invalid, missing, or expired API key, or insufficient permissions. This corresponds to a 401 (Unauthorized) or 403 (Permission Denied) HTTP status code from the Knock API.
fixProvide a valid secret API key during client initialization, either directly or via the `KNOCK_API_KEY` environment variable. Ensure the key has the necessary permissions in your Knock dashboard.
knockapi.APIConnectionError: The server could not be reached
This error is raised when the library is unable to establish a connection with the Knock API, often due to network connectivity problems, DNS issues, or a request timeout.
fixCheck your internet connection, verify the API endpoint is reachable, and ensure no firewalls or network configurations are blocking the connection. You can also adjust the client's `timeout` setting during initialization.
AttributeError: 'WorkflowTriggerResponse' object has no attribute 'get'
This typically occurs when trying to access response data from the Knock API using dictionary-style `.get()` methods (e.g., `response.get('key')`), but the response is a Pydantic model object, not a raw dictionary, especially after upgrading to `knockapi` v1.0+.
fixAccess properties using dot notation (e.g., `response.workflow_run_id`). If a dictionary representation is required, use `response.model_dump()` (for Pydantic v2) or `response.dict()` (for Pydantic v1) to convert the model to a dictionary.
AttributeError: 'Knock' object has no attribute 'notify'
This error arises when using code written for `knockapi` v0.x with a v1.0+ client. The `client.notify()` method was removed in version 1.0 as part of significant breaking changes to the SDK.
fixMigrate your code to use `client.workflows.trigger()` instead of `client.notify()`. Refer to the official v1.0 upgrade guide for a comprehensive list of method name changes and API design updates.
Upgrade
Version history
1.29.0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
httpxrequiredPowers the synchronous and asynchronous HTTP clients by default.
aiohttpoptionalOptional dependency for improved concurrency performance with the async client.