{"id":8021,"library":"codewords-client","title":"CodeWords Client","description":"CodeWords Client (0.4.8) is a Python library providing a client for the CodeWords serverless automation platform. It facilitates interaction with CodeWords workflows, especially for FastAPI applications, allowing programmatic execution and management of AI-powered automations. The library is actively maintained with frequent updates.","status":"active","version":"0.4.8","language":"en","source_language":"en","source_url":"https://codewords.ai","tags":["API client","workflow automation","FastAPI","AI","serverless"],"install":[{"cmd":"pip install codewords-client","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.11 or newer to run.","package":"python","optional":false},{"reason":"CodeWords 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.","package":"fastapi","optional":true},{"reason":"Often used with FastAPI for data validation in CodeWords workflows.","package":"pydantic","optional":true}],"imports":[{"symbol":"AsyncCodewordsClient","correct":"from codewords_client import AsyncCodewordsClient"}],"quickstart":{"code":"import os\nimport asyncio\nfrom codewords_client import AsyncCodewordsClient\n\nasync def run_workflow():\n    api_key = os.environ.get('CODEWORDS_API_KEY', 'your_codewords_api_key_here')\n    if not api_key or api_key == 'your_codewords_api_key_here':\n        print(\"Please set the CODEWORDS_API_KEY environment variable or replace the placeholder.\")\n        return\n\n    async with AsyncCodewordsClient(api_key=api_key) as client:\n        try:\n            # Example: Run a synchronous workflow (for tasks under 2 minutes)\n            print(\"Running synchronous workflow...\")\n            sync_result = await client.run(\n                service_id=\"your-sync-workflow-id\",\n                data={\n                    \"input_param1\": \"value1\",\n                    \"input_param2\": \"value2\"\n                }\n            )\n            print(f\"Synchronous workflow result: {sync_result}\")\n\n            # Example: Run an asynchronous workflow (for longer tasks)\n            print(\"Running asynchronous workflow...\")\n            async_request = await client.run_async(\n                service_id=\"your-async-workflow-id\",\n                data={\n                    \"large_data\": [\"item1\", \"item2\", \"...\"]\n                }\n            )\n            print(f\"Asynchronous workflow initiated. Request ID: {async_request.request_id}\")\n\n            # Poll for async result (simplified)\n            while True:\n                status_response = await client.get_result(async_request.request_id)\n                if status_response.status == 'completed':\n                    print(f\"Async workflow completed. Result: {status_response.result}\")\n                    break\n                elif status_response.status == 'failed':\n                    print(f\"Async workflow failed. Error: {status_response.error}\")\n                    break\n                else:\n                    print(f\"Async workflow status: {status_response.status}. Waiting...\")\n                    await asyncio.sleep(5)\n\n        except Exception as e:\n            print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(run_workflow())\n","lang":"python","description":"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."},"warnings":[{"fix":"Use `os.environ.get('CODEWORDS_API_KEY')` to retrieve your API key. Obtain your API key from the CodeWords account dashboard under the Advanced tab.","message":"Always secure your CodeWords API key. Treat it like a password and store it as an environment variable (e.g., `CODEWORDS_API_KEY`) rather than hardcoding it in your application.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For workflows that might exceed two minutes, use `client.run_async()` to get an immediate request ID, then poll for results using `client.get_result(request_id)`.","message":"Choose the correct API endpoint for workflow execution: use `/run` for quick tasks expected to complete under two minutes, and `/run_async` for longer-running operations (up to 30 minutes) to avoid HTTP 504 Gateway Timeout errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Utilize the CodeWords platform's built-in debugging tools, including asking 'Cody' (the AI assistant) in the chat interface, reviewing execution logs, and testing with simplified data.","message":"When troubleshooting workflow issues, remember that `codewords-client` calls interact with the CodeWords platform. Many issues are workflow-specific (e.g., incorrect logic, data transformations) rather than client-library bugs.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure 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-`.","cause":"The CodeWords API key is missing, invalid, or incorrectly formatted in the Authorization header.","error":"HTTP 401 Unauthorized"},{"fix":"For workflows that may exceed two minutes, switch to asynchronous execution using `client.run_async()` and then poll for the result with `client.get_result()`.","cause":"A synchronous workflow executed via `client.run()` took longer than the allowed two-minute execution limit.","error":"HTTP 504 Gateway Timeout"},{"fix":"Verify the `service_id` against your deployed workflows in the CodeWords dashboard. Ensure it's correctly specified in your client code.","cause":"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.","error":"KeyError: 'serviceId'"}]}