Quickstart

Create an API keyCopy Anchor Link

In Lodol, go to Settings › API Keys and create a key with the workflows:read, workflows:execute and executions:read scopes. Copy it: the full key is shown only once.

Keep it in an environment variable rather than in your code:

export LODOL_API_KEY="sk_live_..."

Find your workflowCopy Anchor Link

List your workflows to get the id of the one to run.

curl https://api-prod.lodol.com/api/v1/workflows \
  -H "Authorization: Bearer $LODOL_API_KEY"

Each workflow lists the inputs it declares, if any:

{
  "workflows": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "name": "Monthly Client Report",
      "description": "Builds a client's monthly report and emails it to them",
      "inputs": [
        { "name": "client", "type": "text", "required": true, "default": null, "description": "The client to report on" }
      ]
    }
  ]
}

Start a runCopy Anchor Link

Start the workflow with its inputs. The Idempotency-Key makes the request safe to retry: sending it again returns the same run instead of starting another.

curl -X POST https://api-prod.lodol.com/api/v1/workflows/665f1a2b3c4d5e6f7a8b9c0d/run-async \
  -H "Authorization: Bearer $LODOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-report-2026-05" \
  -d '{"inputs": {"client": "Acme"}}'

The API answers straight away with 202 Accepted and the run's ID, while the run carries on in the background:

{
  "execution_id": "683b2c3d4e5f6a7b8c9d0e1f",
  "workflow_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "version_id": "6683e1c4b2a9d7f0e5c3a1b2",
  "status": "queued",
  "is_trigger_listener": false,
  "created_at": "2026-04-14T10:30:00+00:00"
}

A workflow with no required inputs can be started without a body.

Wait for the resultCopy Anchor Link

Check the run until it finishes: success, failed or stopped. A run that succeeded has what the workflow handed back in outputs, one field per output it declares; one that failed says why in error.

curl https://api-prod.lodol.com/api/v1/executions/683b2c3d4e5f6a7b8c9d0e1f \
  -H "Authorization: Bearer $LODOL_API_KEY"

{
  "execution_id": "683b2c3d4e5f6a7b8c9d0e1f",
  "workflow_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "version_id": "6683e1c4b2a9d7f0e5c3a1b2",
  "workflow_name": "Monthly Client Report",
  "status": "success",
  "is_trigger_listener": false,
  "created_at": "2026-04-14T10:30:00+00:00",
  "started_at": "2026-04-14T10:30:00+00:00",
  "completed_at": "2026-04-14T10:30:45+00:00",
  "error": null,
  "outputs": { "total": 1250, "summary": "A good month for Acme" }
}

Every check counts toward your rate limit, so poll every few seconds rather than in a tight loop. To see what each step produced along the way, add include_step_results=true.