Trigger a workflow

curl --request POST \
  --url https://dibby.ai/api/runs \
  --header 'Content-Type: application/json' \
  --data '
{
  "worfklowId": "<string>",
  "inputs": {}
}
'

import requests

url = "https://dibby.ai/api/runs"

payload = {
    "worfklowId": "<string>",
    "inputs": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({worfklowId: '<string>', inputs: {}})
};

fetch('https://dibby.ai/api/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dibby.ai/api/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'worfklowId' => '<string>',
    'inputs' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dibby.ai/api/runs"

	payload := strings.NewReader("{\n  \"worfklowId\": \"<string>\",\n  \"inputs\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://dibby.ai/api/runs")
  .header("Content-Type", "application/json")
  .body("{\n  \"worfklowId\": \"<string>\",\n  \"inputs\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dibby.ai/api/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"worfklowId\": \"<string>\",\n  \"inputs\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "run_abc123",
  "versionName": "1.0",
  "status": "RUNNING",
  "createdAt": "2025-01-15T10:30:00Z",
  "steps": 5,
  "stepsCompleted": 2,
  "output": null
}

POST

runs

Trigger a workflow

curl --request POST \
  --url https://dibby.ai/api/runs \
  --header 'Content-Type: application/json' \
  --data '
{
  "worfklowId": "<string>",
  "inputs": {}
}
'

import requests

url = "https://dibby.ai/api/runs"

payload = {
    "worfklowId": "<string>",
    "inputs": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({worfklowId: '<string>', inputs: {}})
};

fetch('https://dibby.ai/api/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dibby.ai/api/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'worfklowId' => '<string>',
    'inputs' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dibby.ai/api/runs"

	payload := strings.NewReader("{\n  \"worfklowId\": \"<string>\",\n  \"inputs\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://dibby.ai/api/runs")
  .header("Content-Type", "application/json")
  .body("{\n  \"worfklowId\": \"<string>\",\n  \"inputs\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dibby.ai/api/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"worfklowId\": \"<string>\",\n  \"inputs\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "run_abc123",
  "versionName": "1.0",
  "status": "RUNNING",
  "createdAt": "2025-01-15T10:30:00Z",
  "steps": 5,
  "stepsCompleted": 2,
  "output": null
}

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

worfklowId

string

required

The UUID of your workflow. Found in your workflow’s URL.

inputs

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.

Example Request

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);

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)

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..."
    }
  }'

Response

string

Unique identifier for this workflow run

versionName

string

Version of the workflow that was executed

status

string

Current status of the run. Possible values: PENDING, RUNNING, FINISHED, FAILED

createdAt

string

Timestamp when the run was created

steps

number

Total number of steps in the workflow

stepsCompleted

number

Number of steps completed so far

output

object

The workflow’s output data (only available when status is FINISHED)

{
  "id": "run_abc123",
  "versionName": "1.0",
  "status": "RUNNING",
  "createdAt": "2025-01-15T10:30:00Z",
  "steps": 5,
  "stepsCompleted": 2,
  "output": null
}

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:

{
  "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

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

Get run status

Learn how to check the status and retrieve results of a workflow run

Get run status

API Documentation

Endpoints

Trigger a workflow

Overview

Request

Example Request

Response

Input requirements

Example

Sending documents

JavaScript helper

Next steps

Get run status

​Overview

​Request

​Example Request

​Response

​Input requirements

​Example

​Sending documents

​JavaScript helper

​Next steps

Get run status

Overview

Request

Example Request

Response

Input requirements

Example

Sending documents

JavaScript helper

Next steps