{"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":"python","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,"search_vec":"'0.4.8':5 'activ':42 'ai':36,52 'ai-pow':35 'allow':29 'api':47 'applic':28 'autom':17,38,50 'client':2,4,12,48 'codeword':1,3,15,23 'especi':25 'execut':31 'facilit':20 'fastapi':27,51 'frequent':45 'interact':21 'librari':9,40 'maintain':43 'manag':33 'platform':18 'power':37 'programmat':30 'provid':10 'python':8 'serverless':16,53 'updat':46 'workflow':24,49","created_at":"2026-04-16T17:00:01.661347+00:00","updated_at":"2026-04-16T17:00:01.661347+00:00","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'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.8","cli_name":"codewords-client","cli_version":"sh: 1: codewords-client: not found","type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/codewords-client/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","workflow","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}