Everything you need to know about using your CodeWords API key.
Overview
The CodeWords API lets any external application trigger your workflows with simple HTTP requests. Whether you're building a web app, mobile app, or connecting to third-party services, it's easy to connect to CodeWords.
Your API key will be under theAdvanced tab withinAPI keys & Environment variables section:
cwk- for standard reusable keys (most common)
cwotk- for one-time keys (extra security for sensitive operations)
Treat your API key like a password, keep it secret and store it as an environment variable.
How the API works
Base URL: https://runtime.codewords.ai
The endpoints you'll use:
Quick tasks: POST /run/{serviceId} (under two minutes)
Heavy lifting: POST /run_async/{serviceId} (up to 30 minutes)
Check results: GET /result/{request_id} (for async calls)
Watch progress: GET /logs/{request_id} (live streaming)
Upload files: POST /file (when your workflow needs files)
Authentication: Just add "Authorization: Bearer {YOUR_API_KEY}" to your headers.
Quick synchronous calls
Perfect for automations that finish fast (under two minutes). Your request waits for the result and gets it back immediately.
Using cURL
Python example
Install the CodeWords client first:
JavaScript/TypeScript example
Install the client:
Asynchronous calls for heavy lifting
For automations that need more time (up to 30 minutes), use async execution. You'll get a request ID immediately, then check back for results.
Using cURL
Python example
TypeScript example
Working with files
When your CodeWords automation needs file inputs, upload them first and pass the download URLs.
Upload and process pattern
Integrating with web apps
Here's how to add CodeWords to a Flask web application:
Error handling best practices
Make your API calls bulletproof with smart retry logic:
FAQs
What is the CodeWords API used for?
The CodeWords API lets you trigger and control workflows directly from any app or system using simple HTTP requests. You can build web or mobile apps that run CodeWords automations seamlessly in the background.
What’s the difference between sync and async API calls?
Synchronous (/run): Best for fast workflows that finish in under two minutes.
Asynchronous (/run_async): Designed for longer jobs (up to 30 minutes). You get a request ID instantly and can check progress or results later.
How do I authenticate requests?
Include your API key in the request header:
Authorization: Bearer YOUR_API_KEY
This ensures that every API call is securely linked to your CodeWords account.
Can I upload files to my workflows?
Yes. Use the /file endpoint to upload any file your automation needs. CodeWords returns a secure download URL you can include in your workflow inputs.
What programming languages are supported?
You can call the API from any language that supports HTTP requests. Official clients are available for Python and JavaScript/TypeScript, making integration effortless.
How long can an API job run?
Synchronous jobs run for up to 2 minutes, while asynchronous workflows can run for up to 30 minutes before timing out.
import os
from codewords_client import AsyncCodewordsClient
import asyncio
# Set your API key as environment variable
# export CODEWORDS_API_KEY=cwk-your-api-key-here
async def enrich_linkedin_profiles(spreadsheet_id: str):
"""Call the LinkedIn enricher and get results back immediately."""
async with AsyncCodewordsClient() as client:
try:
response = await client.run(
service_id="linkedin-enricher",
inputs={
"spreadsheet": spreadsheet_id,
"include_email": False,
"output_columns": ["bio", "location", "current_job"]
}
)
response.raise_for_status()
return response.json()
except Exception as e:
if "504" in str(e) or "timeout" in str(e).lower():
raise TimeoutError("Service took too long - try async instead")
raise
# Usage
async def main():
try:
result = await enrich_linkedin_profiles("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")
print(f"Processed {result['processed_count']} profiles")
print(f"Success rate: {result['success_rate']:.1%}")
except TimeoutError:
print("That took too long - consider using async execution")
asyncio.run(main())
npm install @codewords/client
import { createServiceClient } from "@codewords/client";
// Set your API key as environment variable
const client = createServiceClient(process.env.CODEWORDS_API_KEY!);
interface LinkedInRequest {
spreadsheet: string;
include_email: boolean;
output_columns: string[];
}
async function enrichLinkedInProfiles(request: LinkedInRequest) {
try {
const result = await client.runService(
"linkedin-enricher", // service ID
"", // path (empty for main endpoint)
request // your data
);
return result;
} catch (error) {
if (error.response?.status === 504) {
throw new Error("Service timed out - try async execution");
}
throw error;
}
}
// Usage
const request = {
spreadsheet: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
include_email: false,
output_columns: ["bio", "location", "current_job"]
};
const result = await enrichLinkedInProfiles(request);
console.log(`Processed ${result.processed_count} profiles`);
# 1. Start the async job
curl -X POST https://runtime.codewords.ai/run_async/linkedin-enricher \
-H "Authorization: Bearer cwk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"spreadsheet": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"include_email": true,
"output_columns": ["bio", "location", "current_job", "education"]
}'
# Response: {"request_id": "req_abc123def456"}
# 2. Check if it's done (might return 408 if still running)
curl -X GET "https://runtime.codewords.ai/result/req_abc123def456" \
-H "Authorization: Bearer cwk-your-api-key-here"
# Not ready: HTTP 408 Request Timeout
# Ready: Full result with status 200
# 3. Optional: Watch live logs
curl -X GET "https://runtime.codewords.ai/logs/req_abc123def456" \
-H "Authorization: Bearer cwk-your-api-key-here" \
-H "Accept: text/event-stream"
from codewords_client import AsyncCodewordsClient
import asyncio
async def enrich_profiles_async(spreadsheet_id: str):
"""Start a big job and wait for it to finish."""
async with AsyncCodewordsClient() as client:
# Start the job in background
handle = await client.run(
service_id="linkedin-enricher",
inputs={
"spreadsheet": spreadsheet_id,
"include_email": True,
"output_columns": ["bio", "location", "current_job", "education"]
},
in_background=True # This makes it async
)
print(f"Started background job: {handle.request_id}")
# Wait for it to finish (up to 10 minutes)
response = await handle.result(timeout_seconds=600)
return response.json()
# Usage
async def main():
result = await enrich_profiles_async("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")
print(f"Async job completed!")
print(f"Processed {result['processed_count']} profiles")
asyncio.run(main())
import { createServiceClient } from "@codewords/client";
const client = createServiceClient(process.env.CODEWORDS_API_KEY!);
async function enrichProfilesAsync(request: LinkedInRequest) {
// Start async execution
const requestId = await client.runAsync(
"linkedin-enricher",
"",
request
);
console.log(`Started async job: ${requestId}`);
// Wait for results (10 minutes max)
const result = await client.pollResult(600000);
if (result.responseStatus === 200) {
return result.responseJson;
} else {
throw new Error(`Job failed with status ${result.responseStatus}`);
}
}
from codewords_client import AsyncCodewordsClient
async def process_my_csv(file_path: str):
"""Upload a local file and process it with CodeWords."""
async with AsyncCodewordsClient() as client:
# Read your local file
with open(file_path, 'rb') as f:
file_content = f.read()
# Upload to CodeWords
download_url = await client.upload_file_content(
filename="data.csv",
file_content=file_content
)
# Process with your automation
response = await client.run(
service_id="csv-processor",
inputs={
"csv_file": download_url,
"processing_options": {"header_row": True}
}
)
return response.json()
# Usage
result = await process_my_csv("./my-data.csv")
print(f"Processed {result['row_count']} rows")
from flask import Flask, request, jsonify
from codewords_client import AsyncCodewordsClient
import asyncio
app = Flask(__name__)
@app.route('/analyze-spreadsheet', methods=['POST'])
def analyze_spreadsheet():
"""API endpoint that calls CodeWords behind the scenes."""
data = request.get_json()
spreadsheet_id = data.get('spreadsheet_id')
if not spreadsheet_id:
return jsonify({"error": "spreadsheet_id required"}), 400
async def call_codewords():
async with AsyncCodewordsClient() as client:
response = await client.run(
service_id="linkedin-enricher",
inputs={
"spreadsheet": spreadsheet_id,
"include_email": False,
"output_columns": ["bio", "location", "current_job"]
}
)
return response.json()
try:
result = asyncio.run(call_codewords())
return jsonify(result)
except Exception as e:
if "timeout" in str(e).lower():
return jsonify({"error": "Analysis timed out"}), 408
return jsonify({"error": str(e)}), 500
if __name__ == '__main__':
app.run(debug=True)
from codewords_client import AsyncCodewordsClient
import asyncio
import logging
async def bulletproof_call(
service_id: str,
inputs: dict,
max_retries: int = 3
):
"""Make a robust call with automatic retry and timeout handling."""
async with AsyncCodewordsClient() as client:
for attempt in range(max_retries):
try:
# Try sync first
response = await client.run(
service_id=service_id,
inputs=inputs
)
return response.json()
except Exception as e:
if "timeout" in str(e).lower() or "504" in str(e):
# Switch to async for timeouts
logging.info("Switching to async mode due to timeout...")
handle = await client.run(
service_id=service_id,
inputs=inputs,
in_background=True
)
response = await handle.result(timeout_seconds=600)
return response.json()
# Retry on other errors
if attempt < max_retries - 1:
await asyncio.sleep(2 ** attempt) # Exponential backoff
continue
raise
# Usage
try:
result = await bulletproof_call("my-automation", {"input": "data"})
print("Success!")
except Exception as e:
print(f"Failed after retries: {e}")
