API ReferenceFlows

Get flow

GET /api/v1/flows/:flowId

Returns full flow details including definition, layout, and connected phones.

Authentication

AuthorizationBearer

Pass a JWT access token or an API key (prefixed with tif_live_) as a Bearer token.

Path parameters

flowIdstringRequiredformat: "uuid"
Flow ID

Response

Flow details
accountIdstringformat: "uuid"
Account that owns this flow
analysisOverridestring

Call analysis behavior override: “use_account_default”, “enabled”, or “disabled”

connectedPhoneslist of objects
Phone numbers currently connected to this flow
createdAtdatetime
Timestamp when the flow was created
idstringformat: "uuid"
Unique identifier of the flow
namestring
Display name of the flow
recordingOverridestring

Recording behavior override: “use_account_default”, “enabled”, or “disabled”

statusenum
Current lifecycle status of the flow
tagslist of strings

User-defined tags for filtering and organization

updatedAtdatetime
Timestamp when the flow was last updated
versionstring

Current semantic version (X.Y.Z)

versionslist of objects

Available published versions (newest first)

voicemailEnabledboolean

Whether voicemail detection is enabled (outbound Twilio calls only)

analysisInstructionsstring or nullOptional
Custom analysis instructions appended to the base analysis prompt
definitionobject or nullOptional

The canonical flow definition — single source of truth for flow logic, shared by the API and the visual builder.

Visual nodes (LLM, TTS, STT, prompt, end_call) collapse into properties:

  • Service nodes -> services.*
  • Prompt nodes -> agent.prompt
  • Action nodes -> agent.functions[]
  • Edges are implicit — relationships expressed as data, not connections
descriptionstring or nullOptional
Description of the flow's purpose
layoutobject or nullOptional

Visual builder layout (positions, viewport, UI state). Opaque to the API: stored and returned as-is.

maxCallDurationobject or nullOptional

Hard call-duration cap settings for a flow.

Omitting this block leaves the cap OFF. Sending it fully replaces the flow’s cap config.

publishedAtdatetime or nullOptional
Timestamp when the flow was last published
userIdleobject or nullOptional

User-idle hangup settings for a flow.

Sending this block fully replaces the flow’s idle config. Omitting it on update leaves the existing config untouched; sending it with only enabled resets the other fields to their defaults. A flow that was never configured has idle hangup ON.

voicemailMessagestring or nullOptional

Static voicemail message spoken verbatim (skips the composer LLM call)

voicemailMessagePromptstring or nullOptional

Instruction for composing the voicemail message (ignored if message is set)

voicemailResponseDelaySecsfloat or nullOptional
Seconds to wait after the callee stops speaking before leaving the message

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error