Quick Start

Platform API quick start

Use the Platform API to invoke Flows and work with project resources such as Flows, evaluations, search indexes, documents, and datasets. This guide sends one synchronous Flow request with curl.

Before you begin

You need:

• An Account ID
• A Project ID
• A published Flow and its Flow ID
• A Flow API key or Project API key

You can copy the account and project IDs from Project Settings → Information. Open the Flow and select Settings → API to generate a Flow API key, or open Project Settings → API Keys to generate a Project API key.

Treat an API key like a password. Store it in a secret manager or environment variable and never commit it to source control.

Base URL

All API routes in this documentation use:

https://api.botdojo.com/api

Make your first request

Set the placeholders, then run the command:

export BOTDOJO_API_KEY="YOUR_API_KEY"
export BOTDOJO_ACCOUNT_ID="YOUR_ACCOUNT_ID"
export BOTDOJO_PROJECT_ID="YOUR_PROJECT_ID"
export BOTDOJO_FLOW_ID="YOUR_FLOW_ID"

curl --request POST \
  --url "https://api.botdojo.com/api/v1/accounts/YOUR_ACCOUNT_ID/projects/YOUR_PROJECT_ID/flows/YOUR_FLOW_ID/run" \
  --header "Authorization: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "options": {
      "stream": "none"
    },
    "body": {
      "text_input": "Hello from the BotDojo API"
    }
  }'

Replace each YOUR_* value in the URL and headers with the corresponding value. The body object must match the input schema configured on the Flow's Start node.

Read the response

A completed request returns a Flow Request record. The response field contains the output produced by the Flow's End node.

{
  "id": "FLOW_REQUEST_ID",
  "flow_id": "YOUR_FLOW_ID",
  "flow_session_id": "FLOW_SESSION_ID",
  "status": "complete",
  "response": {
    "text": "Hello! How can I help?"
  }
}

Save the flow_session_id and pass it in a later request when the Flow should continue the same conversation or session state.

Choose the right key

Key	Scope	Use it when
Flow API key	One Flow	An application only needs to run a specific Flow.
Project API key	Project resources	A trusted backend needs broader programmatic project access.

Use the narrowest scope that supports the application. See Authorization for headers, identifiers, and key handling.

Next steps

• Review every request option in Flow Request.
• Create state before a run with Create Session.
• Upload project documents with Upload File.
• Explore resource methods in the API Reference.