Developers

Workflows

On this page you can learn how to start an existing workflow through the API, and what the prerequisites are.

Learn this page in your AI agent

Open it in Claude or ChatGPT and ask anything about it, or copy the Markdown and use it in any AI agent.

Claude ChatGPT View as Markdown

How to start a workflow

Starting a workflow through the API takes a few steps. Most of them happen in Askpilot, before you send a single request.

  1. Create the workflow in Askpilot. The API can only start a workflow that already exists. If you do not have one yet, create it in Askpilot first, then come back here.
  2. Give it an API trigger. A workflow can only be started from the API when its trigger is set to API and it is switched on. Without that trigger, a start request is refused. You can add the trigger in Workflows → Your workflow → Settings.
  3. Check its settings. A start does not change anything about the workflow. It runs with the settings it already has in Askpilot: for the person who has access to it, with the sources selected for it, and with auto-run if enabled. You can see and change all of this in Workflows → Your workflow → Settings.
  4. Get its ID. Before you start a workflow you need to get its ID. Call List Workflows in the API reference: it returns the workflows in your organization with their IDs, and you can search by name. If you already know the ID, Get Workflow returns that one workflow with its details: its trigger, sources, who has access and other settings. Both calls need a key with the workflows:read scope.
  5. Start it through the API. Call Start Workflow in the API reference with the workflow's ID. Askpilot opens a new session for the person with access and runs the workflow in it. The response includes the ID of that session.
  6. Start another workflow in the same session, if you need to. With that session ID you can start another workflow in the same session instead of opening a new one. Keep in mind that the new workflow brings its own settings: its selected sources, its auto-run setting and everything else replace those of the workflow that started the session.