TurboFlow

TurboFlow endpoints

TurboFlow lets you create visual workflows, publish immutable versions, and trigger published flows from your app or voice assistant. Most endpoints use session cookie authentication from the Talkturo app, while the trigger endpoint uses HMAC authentication so external systems can invoke a published flow securely.

Endpoint summary

Authentication

Most TurboFlow endpoints are designed for in-product flow management. Call them from a browser session authenticated to Talkturo, or from a backend that can forward a valid session cookie.

Session-authenticated endpoints

Use session auth for:

• Flow CRUD
• Publishing
• Test runs
• Run history
• Integrations
• Secrets
• Manifest and tools
• AI builder endpoints

If your request is not associated with a valid Talkturo session, these endpoints fail before business logic runs.

HMAC-authenticated trigger endpoint

Use HMAC auth for POST /api/flow/{flowId}/trigger. This endpoint is meant for external callers and published runtime execution.

To build the signature:

import crypto from "crypto";

const flowId = "flow_72c9f2ab";
const triggerSecret = "tfsec_example_1k9n3d7s4h2m8q";
const body = JSON.stringify({
  params: {
    caller_name: "Jane Chen",
    booking_id: "bk_9d31a8f4",
    priority: "high"
  },
  context: {
    assistant_id: "asst_4f0c8b21"
  }
});

const signature = crypto
  .createHmac("sha256", triggerSecret)
  .update(body)
  .digest("hex");

const response = await fetch(
  `https://app.talkturo.com/api/flow/${flowId}/trigger?sync=true`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Talkturo-Secret": signature
    },
    body
  }
);

const data = await response.json();
console.log(response.status, data);

import hashlib
import hmac
import json
import requests

flow_id = "flow_72c9f2ab"
trigger_secret = "tfsec_example_1k9n3d7s4h2m8q"

payload = {
    "params": {
        "caller_name": "Jane Chen",
        "booking_id": "bk_9d31a8f4",
        "priority": "high"
    },
    "context": {
        "assistant_id": "asst_4f0c8b21"
    }
}

body = json.dumps(payload, separators=(",", ":"))
signature = hmac.new(
    trigger_secret.encode("utf-8"),
    body.encode("utf-8"),
    hashlib.sha256
).hexdigest()

response = requests.post(
    f"https://app.talkturo.com/api/flow/{flow_id}/trigger?sync=true",
    headers={
        "Content-Type": "application/json",
        "X-Talkturo-Secret": signature,
    },
    data=body,
)

print(response.status_code, response.json())

BODY='{"params":{"caller_name":"Jane Chen","booking_id":"bk_9d31a8f4","priority":"high"},"context":{"assistant_id":"asst_4f0c8b21"}}'
SECRET='tfsec_example_1k9n3d7s4h2m8q'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST "https://app.talkturo.com/api/flow/flow_72c9f2ab/trigger?sync=true" \
  -H "Content-Type: application/json" \
  -H "X-Talkturo-Secret: $SIGNATURE" \
  -d "$BODY"

Create and manage flows

Use these endpoints to create draft flows, retrieve existing definitions, update them, and archive them when they are no longer needed.

List flows

GET /api/flow

Returns the flows available in the current authenticated session context.

Create a flow

POST /api/flow

Creates a new draft flow.

Get, update, or archive a flow

GET /api/flow/{flowId} retrieves the current flow definition. PATCH /api/flow/{flowId} updates the draft. DELETE /api/flow/{flowId} archives the flow.

Path parameters

Update behavior

Use PATCH /api/flow/{flowId} to modify draft metadata or structure. Publishing creates a runnable version; updating the draft does not affect already published versions until you publish again.

Archive behavior

Use DELETE /api/flow/{flowId} to archive a flow. Treat this as a management operation, not a runtime stop mechanism for previously completed runs.

Publish a flow

POST /api/flow/{flowId}/publish

Publishing creates a new runnable version of the flow. Trigger requests execute against a published version, not against an unpublished draft.

Path parameters

What publishing changes

• Creates a versioned runtime snapshot
• Makes the flow triggerable through the trigger endpoint
• Associates runtime execution with the published version
• Enables HMAC-based external invocation through the version's trigger_secret

Trigger a published flow

POST /api/flow/{flowId}/trigger

This is the runtime entry point for TurboFlow. It executes a published flow with caller-supplied parameters and optional execution context.

Query parameters

Headers

Request body

Async trigger example

Async mode returns immediately with a run identifier. Use it when the caller can poll or observe results later.

Async response fields

Sync trigger example

Sync mode waits up to about 30 seconds for the flow to complete and returns the final output inline.

Sync response fields

Choose sync or async

Test a flow before publishing

TurboFlow includes test endpoints for validating draft behavior without going through the published trigger path.

Run the whole flow in test mode

POST /api/flow/{flowId}/test-run

Runs the flow in test mode. Use this while building a draft or validating changes before publishing.

Path parameters

Run a single node in test mode

POST /api/flow/{flowId}/test-run/node

Runs one node in isolation. Use it to debug tool configuration, input mapping, or branch logic without executing the entire graph.

Path parameters

Inspect run history

GET /api/flow/{flowId}/runs

Returns historical executions for a flow. Use run history to audit production triggers, inspect failures, and correlate external events with TurboFlow execution.

Path parameters

What run history is for

• Verifying that async trigger requests were accepted and executed
• Investigating failed runs after sync or async execution
• Reviewing runtime behavior for a published flow version
• Correlating a run_id from the trigger response with stored execution records

Manifest and tools

These endpoints help you discover what TurboFlow can connect to and how a specific flow exposes tool behavior.

Get connector manifest

GET /api/flow/manifest

Returns the connector manifest used by the workflow builder. Use it to inspect available integration capabilities and tool definitions exposed by the platform.

List available tools

GET /api/flow/tools

Returns the connectors and tools available to the current account and environment.

Get a flow tool schema

GET /api/flow/{flowId}/tool-schema

Returns tool schema information for a specific flow.

Manage integrations

TurboFlow integrations let flows connect to external providers and retrieve provider-specific configuration options.

Integration endpoints

• GET /api/flow/integrations
• POST /api/flow/integrations
• DELETE /api/flow/integrations
• GET /api/flow/integrations/{integrationId}
• DELETE /api/flow/integrations/{integrationId}
• GET /api/flow/integrations/{integrationId}/options

OAuth flow

Use the OAuth endpoints when an integration requires delegated access.

Provider webhooks

TurboFlow also exposes inbound webhook handlers for supported providers.

• POST /api/flow/integrations/webhooks/{provider} receives provider webhook deliveries for supported integrations such as Cal.com, Calendly, and Slack.
• GET /api/flow/integrations/webhooks/meta handles verification for Meta webhook setup.
• POST /api/flow/integrations/webhooks/meta receives Meta lead ads webhook events.

Manage secrets

Secrets store encrypted credentials and provider configuration used by flows and integrations.

Secret endpoints

• GET /api/flow/secrets
• POST /api/flow/secrets
• DELETE /api/flow/secrets
• GET /api/flow/secrets/{secretId}
• DELETE /api/flow/secrets/{secretId}
• GET /api/flow/secrets/providers

Path parameters

Secret providers

GET /api/flow/secrets/providers lists the available secret providers that TurboFlow can use for encrypted secret storage and connection management.

Use the AI builder endpoints

The AI builder endpoints help generate or refine flow definitions from natural-language instructions.

Streaming builder endpoint

GET /api/flow/ai/robert and POST /api/flow/ai/robert

Use these endpoints for AI-assisted flow building with streaming behavior. The route supports both GET and POST.

Related AI endpoints

• POST /api/flow/ai/robert-batch for batch AI flow building
• POST /api/flow/ai/describe-parameter to generate a flow parameter description
• POST /api/flow/ai/describe-tool to generate a tool description

Common workflow

This sequence shows how the main lifecycle fits together from draft creation to external execution.

Related endpoints