{"id":5283,"library":"knockapi","title":"Knock Python API Library","description":"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.","status":"active","version":"1.24.1","language":"en","source_language":"en","source_url":"https://github.com/knocklabs/knock-python","tags":["notifications","API client","workflow","async","sync","pydantic","realtime"],"install":[{"cmd":"pip install knockapi","lang":"bash","label":"Standard installation"},{"cmd":"pip install knockapi[aiohttp]","lang":"bash","label":"For async support with aiohttp"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false},{"reason":"Powers the synchronous and asynchronous HTTP clients by default.","package":"httpx","optional":false},{"reason":"Optional dependency for improved concurrency performance with the async client.","package":"aiohttp","optional":true}],"imports":[{"symbol":"Knock","correct":"from knockapi import Knock"},{"symbol":"AsyncKnock","correct":"from knockapi import AsyncKnock"},{"note":"There is a separate, unrelated library called 'knockknock' for ML training notifications.","wrong":"from knockapi import email_sender","symbol":"email_sender","correct":"from knockknock import email_sender"}],"quickstart":{"code":"import os\nfrom knockapi import Knock\n\n# Initialize the client with your API key from an environment variable\n# KNOCK_API_KEY environment variable is used by default if not explicitly provided\nclient = Knock(api_key=os.environ.get('KNOCK_API_KEY', ''))\n\n# Trigger a workflow (ensure 'dinosaurs-loose' workflow exists in Knock dashboard)\ntry:\n    response = client.workflows.trigger(\n        key=\"dinosaurs-loose\",\n        recipients=[\"dnedry\"],\n        data={\n            \"dinosaur\": \"triceratops\"\n        },\n    )\n    print(f\"Workflow run ID: {response.workflow_run_id}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to >=1.0.0"},{"fix":"Access data via object attributes (e.g., `response.workflow_run_id`) or convert to a dictionary using `response.model_dump()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.24.1"},{"fix":"Double-check your `import` statements to ensure they are `from knockapi import ...`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap API calls in `try...except` blocks to catch and handle `knockapi.APIError` subclasses appropriately.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}