Run a Published Jinba Flow with the REST API

Call a published Jinba Flow with the REST API, pass flow inputs, and inspect run results.

Publish a flow, then call the endpoint shown in its Triggers panel. The panel provides the exact URL and secret for that flow.

The Triggers panel shows the published flow endpoint, its secret key, and a ready-to-copy cURL request

Before you start

• Publish the flow you want to call.
• Add an INPUT_* step for each value the caller must provide. The step ID is the argument name.
• Copy the endpoint and secret key from the flow’s Triggers panel.

Treat the secret key like a password. Store it securely and do not commit it to source control.

Run a flow synchronously

A synchronous request waits for the flow to finish. The API returns the run ID, status, and step outputs.

Set the URL and secret to the values shown in the Triggers panel, then send a request:

export JINBA_FLOW_URL="https://api.jinba.io/api/v2/external/flows/FLOW_ID/published-run"
export JINBA_FLOW_KEY="YOUR_FLOW_SECRET"

curl -X POST "$JINBA_FLOW_URL" \
  -H "Authorization: Bearer $JINBA_FLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      { "name": "name", "value": "Jinba" }
    ],
    "mode": "sync"
  }'

Replace FLOW_ID and YOUR_FLOW_SECRET with the values from the panel. The name argument must match the ID of an input step in the published flow. The mode field is optional; it defaults to sync.

A successful response has status: "success". It includes an id for the run and stepOutputs keyed by step ID. Each tool’s result shape depends on that tool. If the flow uses OUTPUT_* steps, their values also appear in result. A run that fails returns status: "failed"; check error and the failed step’s entry in stepOutputs.

Call the flow from code

These examples read the URL and secret from the same JINBA_FLOW_URL and JINBA_FLOW_KEY environment variables.

Python (with the requests package):

import os

import requests

response = requests.post(
    os.environ["JINBA_FLOW_URL"],
    headers={"Authorization": f"Bearer {os.environ['JINBA_FLOW_KEY']}"},
    json={
        "args": [{"name": "name", "value": "Jinba"}],
        "mode": "sync",
    },
)
response.raise_for_status()

run = response.json()
print(run["id"], run["status"])
print(run["stepOutputs"])

JavaScript (Node.js 18 or later, run as an ES module such as call-flow.mjs):

const response = await fetch(process.env.JINBA_FLOW_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JINBA_FLOW_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    args: [{ name: "name", value: "Jinba" }],
    mode: "sync",
  }),
});
if (!response.ok) {
  throw new Error(`Flow request failed: ${response.status} ${await response.text()}`);
}

const run = await response.json();
console.log(run.id, run.status, run.stepOutputs);

Both print the run ID, its status, and the step outputs. A non-2xx response raises an error instead.

Pass numbers, JSON, and webhook payloads

Every argument value must be a string. The API rejects a request that sends a number, boolean, or object as a value. Send numbers and booleans as text, such as "10" or "true", and serialize structured data to a JSON string.

For example, a webhook receiver can forward the event it received to a flow. Here, webhook_data is the ID of an INPUT_* step in the flow:

export async function forwardToFlow(event) {
  const response = await fetch(process.env.JINBA_FLOW_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JINBA_FLOW_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      args: [{ name: "webhook_data", value: JSON.stringify(event) }],
      mode: "async",
    }),
  });
  if (!response.ok) {
    throw new Error(`Flow request failed: ${response.status}`);
  }
  return response.json();
}

The webhook_data step receives the whole event as JSON text. Async mode lets the receiver respond without waiting for the flow to finish; the returned id identifies the run.

To hand the flow a file already stored in Jinba Flow, pass jinbaflow://<fileId> as the value of an INPUT_FILE step. The server resolves it to a download URL before the flow runs. Only files in the flow’s own workspace resolve, whether the reference is a run argument or is saved in the flow’s steps and whatever starts the run (an API key, a webhook, a Slack message, a schedule). A reference to a file in another workspace reaches the flow unchanged, even if the flow’s owner or the key’s creator can access that workspace.

Run a flow asynchronously

For a flow that should continue in the background, set mode to async:

{
  "args": [
    { "name": "name", "value": "Jinba" }
  ],
  "mode": "async"
}

The response includes the run id and status: "running". To retrieve the run record and its output, send an authenticated GET request to:

https://api.jinba.io/api/v2/external/flow-runs/RUN_ID

This lookup uses a workspace-scoped API key. The flow-specific secret from the Triggers panel is for calling the published flow; it does not authorize workspace run-history access.

A workspace API key works only on its own workspace. It cannot reach other workspaces, organization settings, or your account, even if you are a member of them, and GET /api/v2/workspaces (the list of your workspaces) answers 404 to it. Within its workspace it also cannot manage API keys, members, invites, or access settings, change the workspace’s visibility, share flows or publish templates, act on approval requests, use the chat relay, or archive, freeze, restore, delete, or move the workspace to another organization. Sign in to perform those operations.

Check a failed request

• 401 Unauthorized: Check that the request includes the flow secret in the Authorization: Bearer header.
• 404 Not Found: Confirm the flow ID is correct and the flow has a published version.
• The flow runs but an input is empty: Use the exact ID of the INPUT_* step as the name in args.
• A step returns an error: Inspect that step’s output and check its tool documentation for required inputs, credentials, and permissions.

See Debug a failed run to inspect step errors in Jinba Flow.