Integrations

Workflow APIs

Turn any workflow into a callable HTTP endpoint. Expose it to external systems with a custom slug, optional bearer-token authentication, and synchronous or asynchronous execution.

How It Works

Each workflow can be assigned an apiSettings block that enables a public endpoint. When enabled, the workflow is reachable at /api/workflows/public/:idOrSlug. The endpoint accepts a JSON payload, validates optional authentication, creates a task, and returns either the completed result (synchronous) or a task ID (asynchronous).

Custom Endpoint Slug

Assign a human-readable endpoint name instead of exposing the internal MongoDB ID.

Bearer Authentication

Protect the endpoint with API keys. Keys are bcrypt-hashed and verified on each request.

Sync & Async Modes

Choose between immediate response with the workflow result, or fire-and-forget task creation.

Enabling a Workflow API

Enable the API endpoint from the Workflow Settings panel in the UI, or update the workflow directly via the API.

workflow-api-settings.json

{
  "apiSettings": {
    "enabled": true,
    "endpointName": "summarize-report",
    "authentication": true,
    "sync": false
  }
}

Public Endpoint Reference

POST/api/workflows/public/:idOrSlug

Invoke a workflow by its MongoDB ID or custom endpoint slug.

Request

Headers

Content-Type: application/json
Authorization: Bearer <api_key>  # required if authentication is enabled

Body

{
  "input": {
    "topic": "AI automation trends",
    "format": "markdown"
  }
}

Responses

200 OK (async)

{
  "ok": true,
  "taskId": "task_xyz",
  "workflowId": "wf_abc"
}

200 OK (sync)

{
  "ok": true,
  "taskId": "task_xyz",
  "result": { "summary": "..." },
  "stepResults": [ ... ]
}

API Key Management

API keys are created per user via POST /api/keys. Each key is bcrypt-hashed before storage. The raw key is returned exactly once at creation. Keys can be revoked at any time. When a workflow endpoint has authentication: true, the backend compares the bearer token against all active keys for the workflow owner.

Security Notes

• Public workflow endpoints do not require login, but can be locked behind API keys.
• If authentication is disabled, anyone with the slug can trigger the workflow.
• Ownership is enforced: only the workflow owner can enable/disable the public endpoint.