Install & Compatibility
Where this runs
tested against v0.2.4 · 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
py 3.9
✕ build_error
✕ build_error
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncCodewordsClient
✓ from codewords_client import AsyncCodewordsClient
This quickstart demonstrates how to initialize the CodeWords client with an API key (preferably from an environment variable) and execute both synchronous (`run`) and asynchronous (`run_async`) CodeWords workflows. It also shows a basic polling mechanism to retrieve results from asynchronous operations. Replace `your-sync-workflow-id` and `your-async-workflow-id` with your actual workflow IDs.
import os
import asyncio
from codewords_client import AsyncCodewordsClient
async def run_workflow():
api_key = os.environ.get('CODEWORDS_API_KEY', 'your_codewords_api_key_here')
if not api_key or api_key == 'your_codewords_api_key_here':
print("Please set the CODEWORDS_API_KEY environment variable or replace the placeholder.")
return
async with AsyncCodewordsClient(api_key=api_key) as client:
try:
# Example: Run a synchronous workflow (for tasks under 2 minutes)
print("Running synchronous workflow...")
sync_result = await client.run(
service_id="your-sync-workflow-id",
data={
"input_param1": "value1",
"input_param2": "value2"
}
)
print(f"Synchronous workflow result: {sync_result}")
# Example: Run an asynchronous workflow (for longer tasks)
print("Running asynchronous workflow...")
async_request = await client.run_async(
service_id="your-async-workflow-id",
data={
"large_data": ["item1", "item2", "..."]
}
)
print(f"Asynchronous workflow initiated. Request ID: {async_request.request_id}")
# Poll for async result (simplified)
while True:
status_response = await client.get_result(async_request.request_id)
if status_response.status == 'completed':
print(f"Async workflow completed. Result: {status_response.result}")
break
elif status_response.status == 'failed':
print(f"Async workflow failed. Error: {status_response.error}")
break
else:
print(f"Async workflow status: {status_response.status}. Waiting...")
await asyncio.sleep(5)
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
asyncio.run(run_workflow())
codewords-client --version
Errors
Common errors & fixes
HTTP 401 Unauthorized
The CodeWords API key is missing, invalid, or incorrectly formatted in the Authorization header.
fixEnsure your `CODEWORDS_API_KEY` environment variable is set correctly and the `api_key` argument to `AsyncCodewordsClient` is populated with a valid key. Keys typically start with `cwk-`.
HTTP 504 Gateway Timeout
A synchronous workflow executed via `client.run()` took longer than the allowed two-minute execution limit.
fixFor workflows that may exceed two minutes, switch to asynchronous execution using `client.run_async()` and then poll for the result with `client.get_result()`.
KeyError: 'serviceId'
The `service_id` provided to `client.run()` or `client.run_async()` does not correspond to an existing workflow on the CodeWords platform, or there's a typo.
fixVerify the `service_id` against your deployed workflows in the CodeWords dashboard. Ensure it's correctly specified in your client code.
Upgrade
Version history
0.4.8latest on PyPI · released Apr 8, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.11 or newer to run.
fastapioptionalCodeWords platform workflows are based on FastAPI; while not a direct dependency of the client library, it's a core component of the ecosystem it interacts with.
pydanticoptionalOften used with FastAPI for data validation in CodeWords workflows.