JustFlows docs

API reference

Start the published workflow version

POST /api/v1/workflows/{workflow_id}/runs

cURL

curl --request POST \
  --url '/api/v1/workflows/{workflow_id}/runs' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": {
    "order_id": 1842,
    "customer_email": "customer@example.com"
  }
}'

JavaScript

const response = await fetch('/api/v1/workflows/{workflow_id}/runs', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "payload": {
      "order_id": 1842,
      "customer_email": "customer@example.com"
    }
  })
});

const data = await response.json();

Python

import requests

response = requests.request(
    "POST",
    "/api/v1/workflows/{workflow_id}/runs",
    headers={
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    json={
      "payload": {
        "order_id": 1842,
        "customer_email": "customer@example.com"
      }
    },
)

print(response.json())

PHP

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', '/api/v1/workflows/{workflow_id}/runs', [
    'headers' => [
        'Authorization' => 'Bearer <token>',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'payload' => [
            'order_id' => 1842,
            'customer_email' => 'customer@example.com',
        ],
    ],
]);

echo $response->getBody();

Go

package main

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

func main() {
	body := strings.NewReader(`{
  "payload": {
    "order_id": 1842,
    "customer_email": "customer@example.com"
  }
}`)
	req, _ := http.NewRequest("POST", "/api/v1/workflows/{workflow_id}/runs", body)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Ruby

require "net/http"

uri = URI("/api/v1/workflows/{workflow_id}/runs")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "payload": {
      "order_id": 1842,
      "customer_email": "customer@example.com"
    }
  }
JSON

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

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("/api/v1/workflows/{workflow_id}/runs"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
        {
          "payload": {
            "order_id": 1842,
            "customer_email": "customer@example.com"
          }
        }
        """))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Authorization

A bearer token in the Authorization header.

Path parameters

NameTypeRequiredDescription
workflow_idstringYes

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoOptional unique key for this logical attempt. Supplying the same key and request returns the original run for 24 hours. When omitted, the request starts normally without protection against duplicate runs caused by caller retries.
X-Request-IdstringNo

Request body

application/json

NameTypeRequiredDescription
payloadobjectNo

Responses

202 · The run was accepted. On a replay the Idempotent-Replayed response header is true.
NameTypeRequiredDescription
dataRunReferenceYes
data.idstringYes
data.objectstringYes
data.workflow_idstring or nullYes
data.statusstringYesOne of: pending, running, waiting, finished, failed, canceled
data.started_atstring (date-time) or null (date-time)No
data.finished_atstring (date-time) or null (date-time)No
data.created_atstring (date-time) or null (date-time)Yes
data.updated_atstring (date-time) or null (date-time)Yes
request_idstringYes
{
  "data": {
    "id": "string",
    "object": "run",
    "workflow_id": "string",
    "status": "pending",
    "started_at": "2024-01-01T00:00:00Z",
    "finished_at": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "request_id": "string"
}
401 · The Bearer token is missing, malformed, expired, or revoked.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
403 · The token lacks the required ability.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
404 · The resource was not found in the token workspace.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
409 · The operation conflicts with current state or idempotency history.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
422 · The request is invalid or the workspace cannot perform the operation.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
429 · A per-token rate limit was exceeded.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
503 · The site administrator has disabled the Workspace API.
NameTypeRequiredDescription
errorobjectYes
error.codestringYes
error.messagestringYes
error.detailsobjectNo
request_idstringYes
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}