Automations via API

Below is the step by step guide on calling your automations by using CodeWords API.

1. Get Your API Key

First, obtain your API key from the CodeWords Dashboard.

API Key Types:

• cwk- - Standard reusable keys (recommended)

• cwotk- - One-time keys (for sensitive operations)

2. Basic API Information

Base URL: https://runtime.codewords.ai

Authentication: Include this header in all requests:

codeAuthorization: Bearer YOUR_API_KEY_HERE

Content Type: Always use:

codeContent-Type: application/json

3. Synchronous API Calls (≤120 seconds)

Use for workflows that complete quickly (under 2 minutes).

cURL Example:

bash
curl -X POST https://runtime.codewords.ai/run/YOUR_SERVICE_ID \
  -H "Authorization: Bearer cwk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{ "input_field_1": "value1", "input_field_2": "value2" }'

Python Example:

python
#Install: pip install codewords client 
import os from codewords_client 
import AsyncCodewordsClient 

async def call_workflow(): 
    async with AsyncCodewordsClient() as client: response = await client.run( service_id="your-service-id", inputs={ "input_field_1": "value1", "input_field_2": "value2" } ) response.raise_for_status() 
    return response.json() # Usage import asyncio result = asyncio.run(call_workflow()) print(result)

JavaScript/TypeScript Example:

//Install: npm install @codewords/client 
import { createServiceClient } from "@codewords/client"; const client = createServiceClient(process.env.CODEWORDS_API_KEY); async function callWorkflow() { const result = await client.runService( "your-service-id", "", 
// path (empty for main endpoint) 
{ input_field_1: "value1", input_field_2: "value2" } ); return result; }

4. Asynchronous API Calls (>120 seconds)

Use for long-running workflows to avoid timeouts.

cURL Example:

# 1. Start async execution 
curl -X POST https://runtime.codewords.ai/run_async/YOUR_SERVICE_ID \ -H "Authorization: Bearer cwk-your-api-key-here" \ -H "Content-Type: application/json" \ -d '{"input_field": "value"}' 
# Response: {"request_id": "req_abc123def456"} 

# 2. Poll for results 
curl -X GET "https://runtime.codewords.ai/result/req_abc123def456" \ -H "Authorization: Bearer cwk-your-api-key-here" 

# 3. Stream logs (optional) 
curl -X GET "https://runtime.codewords.ai/logs/req_abc123def456" \ -H "Authorization: Bearer cwk-your-api-key-here" \ -H "Accept: text/event-stream"

Python Example:

async def call_workflow_async(): async with AsyncCodewordsClient() as client: 
# Start async execution 
handle = await client.run( service_id="your-service-id", inputs={"input_field": "value"}, in_background=True ) print(f"Started: {handle.request_id}") 
# Wait for completion (10 minute timeout) 
response = await handle.result(timeout_seconds=600) return response.json()

JavaScript Example:

async function callWorkflowAsync() { // Start async execution 
const requestId = await client.runAsync( "your-service-id", "", { input_field: "value" } ); console.log(`Started: ${requestId}`); 
// Poll for results (10 minute timeout) 
const result = await client.pollResult(600000); return result.responseJson; }

5. File Upload Workflow

For workflows that need file inputs:

cURL Example:

# 1. Create file upload 
curl -X POST "https://runtime.codewords.ai/file?filename=data.csv" \ -H "Authorization: Bearer cwk-your-api-key-here" 
# Response: {"upload_uri": "...", "download_uri": "..."} 

# 2. Upload file content 
curl -X PUT "UPLOAD_URI_FROM_STEP_1" \ -H "Content-Type: text/csv" \ -H "x-amz-acl: public-read" \ --data-binary @data.csv 

# 3. Use download URL in workflow call 
curl -X POST https://runtime.codewords.ai/run/your-service-id \ -H "Authorization: Bearer cwk-your-api-key-here" \ -H "Content-Type: application/json" \ -d '{"file_input": "DOWNLOAD_URI_FROM_STEP_1"}'

Python Example:

async def upload_and_process_file(file_path: str): 
    async with AsyncCodewordsClient() as client: 
            file with open(file_path, 'rb') as f: 
                    file_content = f.read()
        download_url = await client.upload_file_content(filename="data.csv", file_content=file_content)    
        # Process with workflow 
        response = await client.run( service_id="your-service-id", inputs={"file_input": download_url} ) 
        return response.json()

6. Error Handling Best Practices

Handle Timeouts:

try: response = await client.run(service_id="your-service", inputs=data) 
response.raise_for_status()
    return response.json()

except Exception as e: 
    if "504" in str(e) or "timeout" in str(e).lower(): 
        # Switch to async for long-running tasks 
        handle = await client.run(service_id="your-service", inputs=data, in_background=True)
        response = await handle.result(timeout_seconds=600) 
        return response.json() raise

Implement Retries:

async def robust_call(service_id: str, inputs: dict, max_retries: int = 3): 
    for attempt in range(max_retries): 
        try: 
            async with AsyncCodewordsClient() as client: 
                response = await client.run(service_id=service_id, inputs=inputs) 
                response.raise_for_status() 
                return response.json() 
        except Exception as e: 
            if attempt == max_retries - 1: 
                raise await asyncio.sleep(2 ** attempt) # Exponential backoff

7. Environment Setup

Set API Key as Environment Variable:

Linux/Mac:

bashexport CODEWORDS_API_KEY=cwk-your-api-key-here

Windows:

cmdset CODEWORDS_API_KEY=cwk-your-api-key-here

8. Security Best Practices

1. Store API keys securely as environment variables

2. Never expose API keys in client-side code

3. Use HTTPS only (CodeWords enforces this)

4. Implement rate limiting in your application

5. Validate inputs before sending to CodeWords

6. Use one-time keys for sensitive operations

7. Rotate keys regularly from the dashboard