{"openapi":"3.1.0","info":{"title":"CodeWords Runtime API","version":"1.0.0","summary":"Run, poll, and stream CodeWords workflows and WhatsApp agents.","description":"Public HTTP API for CodeWords, the AI agent platform at https://codewords.ai. Authenticate with a `cwk-` API key or an OAuth 2.0 access token. Workflows are Python services identified by `serviceId`. Synchronous runs complete in about two minutes; longer jobs should use `/run_async/{serviceId}` then poll `/result/{requestId}`. See https://docs.codewords.ai/automations/calling-codewords-workflows.md","contact":{"name":"CodeWords support","email":"hello@codewords.ai","url":"https://www.codewords.ai/developers"},"license":{"name":"Proprietary","url":"https://www.codewords.ai/terms-conditions"},"termsOfService":"https://www.codewords.ai/terms-conditions"},"servers":[{"url":"https://runtime.codewords.ai","description":"Production CodeWords runtime"}],"tags":[{"name":"Workflows","description":"Run deployed CodeWords services and fetch results."},{"name":"Files","description":"Upload files for workflow inputs."},{"name":"Webhooks","description":"Inbound POST triggers generated per workflow."},{"name":"MCP","description":"Model Context Protocol endpoint for coding agents."}],"security":[{"bearerAuth":[]},{"oauth2":["api:read","api:write"]}],"paths":{"/run/{serviceId}":{"post":{"operationId":"runWorkflowSync","tags":["Workflows"],"summary":"Run a CodeWords workflow synchronously","description":"Execute a deployed workflow and wait for the JSON result. Use this for jobs that finish in under two minutes. On timeout the runtime returns HTTP 504; retry with `runWorkflowAsync`.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Deployed workflow / service identifier (for example `linkedin-enricher`).","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."}}}},"responses":{"200":{"description":"Workflow completed. Body is the service's JSON output.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."}}}},"401":{"description":"Missing or invalid API key / OAuth token.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"404":{"description":"Unknown serviceId.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"504":{"description":"Synchronous execution exceeded the runtime timeout. Use runWorkflowAsync.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}},"/run_async/{serviceId}":{"post":{"operationId":"runWorkflowAsync","tags":["Workflows"],"summary":"Start a CodeWords workflow asynchronously","description":"Start a long-running workflow and return a `request_id` immediately. Poll `getWorkflowResult` and optionally stream `getWorkflowLogs`.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Deployed workflow / service identifier.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."}}}},"responses":{"200":{"description":"Workflow accepted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["request_id"],"properties":{"request_id":{"type":"string","description":"Opaque run identifier used with /result and /logs."}}}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"404":{"description":"Unknown serviceId.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}},"/result/{requestId}":{"get":{"operationId":"getWorkflowResult","tags":["Workflows"],"summary":"Get an asynchronous workflow result","description":"Poll an async run. HTTP 408 means the workflow is still running. HTTP 200 includes `responseStatus` and `responseJson` when complete.","parameters":[{"name":"requestId","in":"path","required":true,"description":"The `request_id` returned by runWorkflowAsync.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Run finished.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["id","responseStatus"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"serviceId":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"responseStatus":{"type":"integer"},"responseJson":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."},"responseContent":{"type":"string"}}}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"404":{"description":"Unknown requestId.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"408":{"description":"Run is still in progress. Retry later.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}},"/logs/{requestId}":{"get":{"operationId":"getWorkflowLogs","tags":["Workflows"],"summary":"Stream workflow logs","description":"Read logs for a run. Send `Accept: text/event-stream` to stream lines as server-sent events while the workflow is running.","parameters":[{"name":"requestId","in":"path","required":true,"description":"The `request_id` returned by runWorkflowAsync.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Log text or an event stream of log lines.","content":{"text/plain":{"schema":{"type":"string"}},"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}},"404":{"description":"Unknown requestId.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}},"/file":{"post":{"operationId":"createFileUpload","tags":["Files"],"summary":"Create a file upload slot","description":"Allocate an upload URL for a workflow input file. PUT the bytes to `upload_uri`, then pass `download_uri` as a workflow input. Do not construct S3 URLs yourself.","parameters":[{"name":"filename","in":"query","required":true,"description":"Original filename, including extension (for example `data.csv`).","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Upload slot created.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["upload_uri","download_uri"],"properties":{"upload_uri":{"type":"string","format":"uri","description":"Pre-signed PUT destination for the file bytes."},"download_uri":{"type":"string","format":"uri","description":"Stable URL to pass as a workflow input after the PUT succeeds."}}}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}},"/webhook/{webhookPath}":{"post":{"operationId":"invokeWorkflowWebhook","tags":["Webhooks"],"summary":"Invoke a workflow webhook","description":"POST JSON to a Cody-generated webhook URL to start that workflow. The URL is the credential — do not share it. Only POST is supported. See https://docs.codewords.ai/automations/webhooks.md","security":[],"parameters":[{"name":"webhookPath","in":"path","required":true,"description":"Opaque path Cody generated for this webhook (includes a unique id and workflow name).","schema":{"type":"string","minLength":1},"style":"simple","explode":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."}}}},"responses":{"200":{"description":"Webhook accepted. Body may include the workflow result for API-style automations.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."}}}},"404":{"description":"Unknown webhook path.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}},"/run/devx_mcp/mcp/":{"post":{"operationId":"callCodeWordsMcp","tags":["MCP"],"summary":"Call the CodeWords MCP server","description":"JSON-RPC Model Context Protocol endpoint used by Cursor, Claude, ChatGPT, and other agents to build and run CodeWords workflows. Authenticate with a Bearer API key or OAuth token. Streamable HTTP transport. See https://docs.codewords.ai/features/chatgpt-connector.md","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"jsonrpc":{"type":"string"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"CodeWords API key from https://codewords.agemo.ai/#settings/api-keys. Keys start with `cwk-` (reusable) or `cwotk-` (one-time). Paid plans only. OAuth access tokens from the authorization server are also accepted as Bearer tokens."},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authorization code with PKCE. Discovery: https://codewords.ai/.well-known/oauth-authorization-server","flows":{"authorizationCode":{"authorizationUrl":"https://codewords.agemo.ai/oauth/authorize","tokenUrl":"https://codewords.agemo.ai/api/oauth/token","refreshUrl":"https://codewords.agemo.ai/api/oauth/token","scopes":{"api:read":"Read workflow status, logs, and results","api:write":"Run workflows, upload files, and mutate resources"}}}}},"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["detail"],"properties":{"detail":{"description":"Human-readable error message.","type":"string"},"error":{"description":"Machine-readable error code when present.","type":"string"}}},"JsonObject":{"type":"object","additionalProperties":true,"description":"JSON object. Workflow input and output fields are defined by each service's own schema."}}},"externalDocs":{"description":"CodeWords developer resources","url":"https://www.codewords.ai/developers"}}