Flow Request

This API endpoint allows you to run a specific flow within a project by sending a POST request with the required parameters.

Endpoint

POST https://api.botdojo.com/api/v1/accounts/{account_id}/projects/{account_id}/flows/{flow_id}/run

Request

The request body should be a JSON object with the following structure:

• body (object, required): The input of the flow or The Schema of the StartNode
• options (object, optional): The options for running the flow.
  • flow_session_id (string, optional): The ID of the flow session. If null a new session will be created. Pass the sessions id for Memory Nodes to track conversation history.
  • version (string, optional): The version of the flow see Releases
  • stream (string, optional): The type of streaming for the flow request. Possible values are "none" or "http". See HTTP Streaming below for details.
  • stream_events (array, optional): Filter which events to stream when using stream: "http". If not specified, all events stream by default. Available events: onNewToken, onLog, onIntermediateStepUpdate, onToolStart, onToolEnd, onFlowStart, onFlowEnd. See HTTP Streaming below.
  • override (object, optional): The override properties for the flow
  • evalOptions (object, optional): Options for running Evaluations
    • runMode (string, required): Possible values are "async", "block", or "skip". Default is "async"
      • skip: Evaluations are not run
      • block: The request waits until all Evaluations have run
      • async: Evals are run is a seperate job after the request has completed
    • runs (array, optional): What Evaluations to run. By default it will run Evaluations set to AutoRun
      • flowEvalId (string, required): The Flow ID of the Evaluation
      • flowEvalExternalInput (object, optional): The external input data for the flow evaluation Setup

Example Request

{
  "options": {
    "stream": "none"
  },
  "body": {
    "text_input": "Hello"
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY" -d '{
  "options": {
    "stream": "none"
  },
  "body": {
    "text_input": "Hello"
  }
}' "http://api.botdojo.com/api/v1/accounts/[account-id]/projects/[project-id]/flows/[flow-id]/run"

Response

• startTime (string): The timestamp when the Flow Request started.
• id (string): The unique identifier for the Flow Request.
• flow_id (string): The identifier of the flow that is being executed.
• flow_session_id (string): The session identifier associated with the Flow Request.
• body (object): The input data provided to the flow.
• requestParams (object): Parameters used for the flow request.
  • stream (string): The type of streaming used for the flow request.
• override (object): The Flow Properties used when executing the flow Flow Properties
• status (string): The status of the Flow Request, e.g., 'complete' or 'error'
• top_request_id (string): The top-level Flow Request ID
• userMessage (object): The message from the user initiating the flow.
  • id (string): The identifier of the user message.
  • date (string): The timestamp of the user message.
  • role (string): The role of the message sender, typically 'user'.
  • content (string): The content of the user message.
• flow_history_id (string): The flow history version
• version (string): The release of the flow being executed Releases
• response (object): The response generated by the Flow. End Node Schema
• aiMessage (object): The message generated by the AI in response to the user's input.
  • id (string): The identifier of the AI message.
  • date (string): The timestamp of the AI message.
  • role (string): The role of the message sender, 'assistant'
  • steps (array): Calls to Agent Tools and their response
  • content (string): The content of the AI message.
• eval_job_id (string): The identifier for the evaluation job associated with the flow.
• endTime (string): The timestamp when the Flow Request ended.
• duration (number): The duration of the Flow Request in milliseconds.
• created (string): The timestamp when the Flow Request was created.

Example Response

{
  "tags": [],
  "startTime": "2024-04-26T21:13:33.678Z",
  "id": "[flowrequest-id]",
  "flow_id": "[flow-id]",
  "flow_session_id": "[flow-session-id]",
  "body": {
    "question": "Hello"
  },
  "requestParams": {
    "stream": "none",
  },
  "override": {
    "botdojo/node/retriever/botdojo_0.indexId": "120501b0-e1f1-11ee-9df8-03f66a85a640",
    "botdojo/node/language_model_function_0.languageModel": {
      "model_id": "gpt-4",
      "provider_id": "botdojo/integration/provider/openai"
    },
    "botdojo/node/language_model_function_0.temperature": 0.04
  },
  "status": "complete",
  "top_request_id": "[flowrequest-id]",
  "runOptions": {},
  "userMessage": {
    "id": "d6d170e1-0411-11ef-8d8b-371c51221d9a",
    "date": "2024-04-26T21:13:33.678Z",
    "role": "user",
    "content": "Hello"
  },
  "flow_history_id": "afe2ae20-fcb6-11ee-bc50-0d9d5b5f1465",
  "version": "0.0.0",
  "response": {
    "text": "Hello! How can I assist you today?\n\n-----\n"
  },
  "aiMessage": {
    "id": "d8bffa70-0411-11ef-8d8b-371c51221d9a",
    "date": "2024-04-26T21:13:36.919Z",
    "role": "assistant",
    "steps": [],
    "content": "Hello! How can I assist you today?\n\n-----\n"
  },
  "eval_job_id": "d8c02180-0411-11ef-8d8b-371c51221d9a",
  "endTime": "2024-04-26T21:13:37.494Z",
  "duration": 3816,
  "created": "2024-04-26T21:13:37.496Z",
  "owner_uid": "[user-id]",
  "modified": "2024-04-26T21:13:37.497Z",
  "account_id": "[account-id]",
  "modified_uid": "[user-id]",
  "project_id": "[project-id]"
}

HTTP Streaming

HTTP streaming allows you to receive real-time events as your flow executes, including token-by-token text generation, execution logs, and agent reasoning steps.

Enabling Streaming

Set stream: "http" in the request options:

{
  "options": {
    "stream": "http"
  },
  "body": {
    "text_input": "Tell me a story"
  }
}

Stream Format

Events are sent as Newline Delimited JSON (NDJSON), where each line is a complete JSON object:

{"tag":"onLog","data":{...}}
{"tag":"onNewToken","data":{"token":"Hello"}}
{"tag":"onIntermediateStepUpdate","data":{...}}

The final response (flow result) is sent as the last line without a tag field:

{"status":"complete","response":{"answer":"..."}}

Available Events

Event	Description
onLog	Flow execution logs and traces
onNewToken	Token-by-token streaming from language models
onIntermediateStepUpdate	Agent reasoning and tool usage steps
onFlowStart	Flow execution started
onFlowEnd	Flow execution completed
onToolStart	Tool execution started
onToolEnd	Tool execution completed

Filtering Events

By default, all events are streamed. To receive only specific events, use stream_events:

{
  "options": {
    "stream": "http",
    "stream_events": ["onNewToken", "onLog"]
  },
  "body": {
    "text_input": "Tell me a story"
  }
}

Example: Streaming with curl

curl -N -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
    "options": {
      "stream": "http"
    },
    "body": {
      "text_input": "Tell me a story"
    }
  }' \
  "https://api.botdojo.com/api/v1/accounts/[account-id]/projects/[project-id]/flows/[flow-id]/run"

Note: Use the -N flag to disable buffering and see events in real-time.

Example: Consuming Stream in JavaScript

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    body: { text_input: 'Tell me a story' },
    options: { stream: 'http' }
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop() || '';
  
  for (const line of lines) {
    if (line.trim()) {
      const event = JSON.parse(line);
      
      // Handle streaming events
      if (event.tag === 'onNewToken') {
        console.log(event.data.token);
      }
      
      // Final result has no tag
      if (!event.tag) {
        console.log('Complete:', event);
      }
    }
  }
}

Example: Token Streaming

When streaming tokens from a language model, you'll receive onNewToken events:

{"tag":"onNewToken","data":{"token":"Once"}}
{"tag":"onNewToken","data":{"token":" upon"}}
{"tag":"onNewToken","data":{"token":" a"}}
{"tag":"onNewToken","data":{"token":" time"}}

Accumulate the tokens to build the complete response in real-time.

Response Headers

When streaming is enabled, the server sets these headers:

• Content-Type: application/x-ndjson
• Transfer-Encoding: chunked
• Cache-Control: no-cache
• Connection: keep-alive

Error Responses

• 400 Bad Request: The request is invalid or missing required parameters.
• 401 Unauthorized: The provided API key is invalid or missing.
• 404 Not Found: The specified account, project, or flow does not exist.
• 500 Internal Server Error: An unexpected error occurred during the Flow Request.