> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dibby.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger a workflow

> Start a workflow run with the POST /runs endpoint

## Overview

Use the `POST /runs` endpoint to trigger a workflow run. This endpoint accepts inputs that match your workflow's Start Node configuration and returns a run object with status and tracking information.

## Request

<ParamField body="worfklowId" type="string" required>
  The UUID of your workflow. Found in your workflow's URL.
</ParamField>

<ParamField body="inputs" type="object" required>
  Input data for your workflow. Must exactly match the parameters defined in your Start Node.

  **Important:** The keys and types must match your Start Node configuration exactly, or the request will fail.
</ParamField>

## Example Request

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch("https://dibby.ai/api/runs", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflowId: "737de5f8-759c-4a5b-bf9a-4cd08ac7f2e0",
      inputs: {
        customerName: "Alice",
        invoicePdf: "data:application/pdf;base64,JVBERi0xLjcKJ...",
      },
    }),
  });

  const run = await response.json();
  console.log(run);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://dibby.ai/api/runs",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Content-Type": "application/json"
      },
      json={
          "workflowId": "737de5f8-759c-4a5b-bf9a-4cd08ac7f2e0",
          "inputs": {
              "customerName": "Alice",
              "invoicePdf": "data:application/pdf;base64,JVBERi0xLjcKJ..."
          }
      }
  )

  run = response.json()
  print(run)
  ```

  ```bash cURL theme={null}
  curl -X POST https://dibby.ai/api/runs \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "workflowId": "737de5f8-759c-4a5b-bf9a-4cd08ac7f2e0",
      "inputs": {
        "customerName": "Alice",
        "invoicePdf": "data:application/pdf;base64,JVBERi0xLjcKJ..."
      }
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique identifier for this workflow run
</ResponseField>

<ResponseField name="versionName" type="string">
  Version of the workflow that was executed
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the run. Possible values: `PENDING`, `RUNNING`, `FINISHED`,
  `FAILED`
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the run was created
</ResponseField>

<ResponseField name="steps" type="number">
  Total number of steps in the workflow
</ResponseField>

<ResponseField name="stepsCompleted" type="number">
  Number of steps completed so far
</ResponseField>

<ResponseField name="output" type="object">
  The workflow's output data (only available when status is `FINISHED`)
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "run_abc123",
    "versionName": "1.0",
    "status": "RUNNING",
    "createdAt": "2025-01-15T10:30:00Z",
    "steps": 5,
    "stepsCompleted": 2,
    "output": null
  }
  ```
</ResponseExample>

## Input requirements

The `inputs` object must exactly match your Start Node configuration.

### Example

If your Start Node expects:

* `customerName` (string)
* `invoicePdf` (document)

Then your inputs must include both fields with matching types:

```json theme={null}
{
  "customerName": "Alice",
  "invoicePdf": "data:application/pdf;base64,JVBERi0xLjcKJ..."
}
```

Any mismatch in keys or types will result in an error.

## Sending documents

Files must be base64-encoded with the appropriate data URI prefix.

### JavaScript helper

```javascript theme={null}
export const fileToBase64 = (file) =>
  new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });

// Usage
const file = document.querySelector('input[type="file"]').files[0];
const base64String = await fileToBase64(file);

// Use in API call
const response = await fetch("https://dibby.ai/api/runs", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workflowId: "YOUR_APP_ID",
    inputs: {
      document: base64String,
    },
  }),
});
```

## Next steps

<Card title="Get run status" icon="chart-line" href="/api-reference/endpoint/get">
  Learn how to check the status and retrieve results of a workflow run
</Card>