Frontline Flows API
View and manage flows associated with your agents
OpenAPI Specification
openapi: 3.0.0
info:
title: Public Account Flows API
version: 1.0.0
description: 'Public API for accessing agents, flows, and analytics.
## Authentication
The Public API supports two API key types. Pass the key as a Bearer token:
```
Authorization: Bearer <YOUR_API_KEY>
```
### Account API key (GENERAL)
Account-level key that acts on behalf of the entire account. Required for account-level endpoints unless noted otherwise.
### User API key (USER)
User-level key tied to a specific user. Required for write operations and user-owned resources. **Also accepted on all account-level endpoints.**
Each operation documents which key type(s) it accepts in its **Security** section.'
license:
name: Proprietary
url: https://www.getfrontline.ai/terms-and-conditions
servers:
- url: https://prod-api.getfrontline.ai
tags:
- name: Flows
description: View and manage flows associated with your agents
paths:
/public/v1/agents/{agentId}/flows:
get:
summary: List flows for an agent
operationId: listAgentFlows
description: Returns a list of flows associated with a specific agent. Nodes and logic are excluded.
security:
- accountApiKey: []
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: string
enum:
- ACTIVE
- SUSPENDED
- DELETED
- DRAFT
example: ACTIVE
required: false
name: status
in: query
responses:
'200':
description: A list of flows
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Flow'
required:
- results
description: Standard list response
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Create a flow for an agent
operationId: createAgentFlow
description: Creates a flow and an empty graph snapshot for a specific agent.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowCreateInput'
responses:
'201':
description: Created flow
content:
application/json:
schema:
$ref: '#/components/schemas/FlowDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/public/v1/agents/{agentId}/flows/{flowId}:
get:
summary: Get flow details
operationId: getAgentFlow
description: Returns flow metadata. Pass includeNodes=true to include graph nodes.
security:
- accountApiKey: []
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
- schema:
anyOf:
- type: boolean
example: false
- type: string
example: example
required: false
name: includeNodes
in: query
- schema:
anyOf:
- type: boolean
example: false
- type: string
example: example
required: false
name: draft
in: query
responses:
'200':
description: Flow details
content:
application/json:
schema:
$ref: '#/components/schemas/FlowDetail'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
summary: Update a flow
operationId: updateAgentFlow
description: Updates flow metadata or status.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowUpdateInput'
responses:
'200':
description: Updated flow
content:
application/json:
schema:
$ref: '#/components/schemas/FlowDetail'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
summary: Delete a flow
operationId: deleteAgentFlow
description: Soft deletes a flow.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
responses:
'204':
description: Flow deleted
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/public/v1/agents/{agentId}/flows/{flowId}/graph:
get:
summary: Get flow graph
operationId: getAgentFlowGraph
description: Returns the flow snapshot with nodes and edges.
security:
- accountApiKey: []
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
responses:
'200':
description: Flow graph
content:
application/json:
schema:
$ref: '#/components/schemas/FlowGraph'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/public/v1/agents/{agentId}/flows/{flowId}/nodes:
post:
summary: Create flow node
operationId: createAgentFlowNode
description: Creates a node in a flow graph.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowNodeCreateInput'
responses:
'201':
description: Created node
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowNode'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/public/v1/agents/{agentId}/flows/{flowId}/nodes/{nodeId}:
put:
summary: Update flow node
operationId: updateAgentFlowNode
description: Updates a flow node and returns the updated graph.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
- schema:
type: string
example: start_1
required: true
name: nodeId
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowNodeUpdateInput'
responses:
'200':
description: Updated graph
content:
application/json:
schema:
$ref: '#/components/schemas/FlowGraph'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
summary: Delete flow node
operationId: deleteAgentFlowNode
description: Deletes a node and removes incoming and outgoing edges.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
- schema:
type: string
example: start_1
required: true
name: nodeId
in: path
responses:
'200':
description: Updated graph
content:
application/json:
schema:
$ref: '#/components/schemas/FlowGraph'
/public/v1/agents/{agentId}/flows/{flowId}/edges:
post:
summary: Create flow edge
operationId: createAgentFlowEdge
description: Adds or replaces an edge by handle in the flow graph.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowEdgeInput'
responses:
'200':
description: Updated graph
content:
application/json:
schema:
$ref: '#/components/schemas/FlowGraph'
'409':
description: Invalid graph
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
summary: Delete flow edge
operationId: deleteAgentFlowEdge
description: Removes an edge from the flow graph.
security:
- userApiKey: []
tags:
- Flows
parameters:
- schema:
type: string
example: uuid-xxxx-xxxx
required: true
name: agentId
in: path
- schema:
type: number
nullable: true
example: 101
required: false
name: flowId
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFlowEdgeDeleteInput'
responses:
'200':
description: Updated graph
content:
application/json:
schema:
$ref: '#/components/schemas/FlowGraph'
components:
schemas:
ErrorBody:
type: object
properties:
code:
type: string
enum:
- bad_request
- unauthorized
- forbidden
- not_found
- conflict
- internal_error
- cli_outdated
example: unauthorized
message:
type: string
example: Detailed error message
details:
type: object
description: 'Optional structured details. Validation errors include `{ issues: [...] }`.'
example:
issues:
- path:
- name
message: String must contain at least 1 character(s)
code: too_small
required:
- code
- message
PublicFlowEdgeInput:
type: object
properties:
edge:
type: object
properties:
source:
type: string
example: trigger_1
sourceHandle:
type: string
example: default
target:
type: string
example: api_1
targetHandle:
type: string
example: default
required:
- source
- sourceHandle
- target
- targetHandle
required:
- edge
DynamicTablesQueryCondition:
type: object
properties:
path:
type: string
description: Field path in format [Field] or [Relation].[Field]
example: '[Status]'
operator:
type: string
example: equals
value:
nullable: true
type: object
valueType:
nullable: true
type: object
required:
- path
- operator
PublicFlowUpdateInput:
type: object
properties:
name:
type: string
minLength: 1
example: Order Routing
description:
type: string
nullable: true
example: Routes order conversations
status:
type: string
enum:
- ACTIVE
- SUSPENDED
- DELETED
- DRAFT
example: ACTIVE
required:
- name
FlowGraph:
type: object
properties:
id:
type: string
example: example
assistantId:
type: string
nullable: true
example: example
accountId:
type: number
nullable: true
example: 1
entityId:
type: number
example: 1
type:
type: string
enum:
- FLOW
- AUTOMATION
example: FLOW
nodes:
type: array
items:
$ref: '#/components/schemas/PublicFlowNode'
createdAt:
type: string
example: example
updatedAt:
type: string
nullable: true
example: example
executed:
type: boolean
default: false
example: false
breakingChangeAt:
type: string
nullable: true
example: example
breakingChangeReason:
type: string
nullable: true
example: example
required:
- entityId
- type
- nodes
- createdAt
PublicFlowNode:
type: object
properties:
nodeId:
type: string
pattern: node_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
example: node_550e8400-e29b-41d4-a716-446655440000
alias:
type: string
nullable: true
example: Start
name:
type: string
example: Start
position:
type: object
properties:
positionX:
type: number
example: 1
positionY:
type: number
example: 1
required:
- positionX
- positionY
type:
type: string
enum:
- START
- TRIGGER_INTENT
- SAY_AI
- RESPONSE_AI
- TOOLS_AI
- API
- CONDITIONAL_ROUTING
- DYNAMIC_TABLES
example: START
data:
oneOf:
- type: object
properties:
type:
type: string
enum:
- TRIGGER_INTENT
example: TRIGGER_INTENT
agenticRouting:
type: string
nullable: true
example: example
intentIds:
type: array
nullable: true
items:
type: number
example: 1
intents:
type: array
nullable: true
items:
type: object
properties:
id:
type: number
example: 1
name:
type: string
example: example
description:
type: string
nullable: true
example: example
createdAt:
type: string
nullable: true
example: example
updatedAt:
type: string
nullable: true
example: example
status:
type: string
enum:
- ACTIVE
- DELETED
example: ACTIVE
assistantId:
type: string
example: example
phrases:
type: array
items:
type: object
properties:
id:
type: number
example: 1
phrase:
type: string
example: example
required:
- id
- phrase
flowId:
type: number
nullable: true
example: 1
required:
- id
- name
- createdAt
- updatedAt
- status
- assistantId
required:
- type
- type: object
properties:
type:
type: string
enum:
- SAY_AI
example: SAY_AI
message:
type: string
nullable: true
example: example
temperature:
type: number
default: 0.7
example: 1
prompt:
type: string
nullable: true
example: example
aiModelId:
type: number
nullable: true
example: 1
model:
type: string
nullable: true
example: example
aiVendor:
type: string
nullable: true
enum:
- OPENAI
- ANTHROPIC
- GOOGLE
- AZURE
- DEEPSEEK
- LLAMA
example: OPENAI
sayWithAi:
type: boolean
example: false
required:
- type
- sayWithAi
- type: object
properties:
type:
type: string
enum:
- RESPONSE_AI
example: RESPONSE_AI
assistantId:
type: string
format: uuid
description: Owning assistant UUID. Validated against the account on save.
example: 550e8400-e29b-41d4-a716-446655440000
aiModelId:
type: number
nullable: true
example: 1
model:
type: string
example: example
aiVendor:
type: string
enum:
- OPENAI
- ANTHROPIC
- GOOGLE
- AZURE
- DEEPSEEK
- LLAMA
example: OPENAI
instructions:
type: string
nullable: true
example: example
temperature:
type: number
example: 1
captureVariables:
type: array
items:
nullable: true
type: object
exitNodeWhen:
type: string
enum:
- ALL_VARIABLES
- FLOW_TRIGGERED
- ANY_VARIABLES
example: ALL_VARIABLES
knowledgeBaseMode:
type: string
enum:
- DEFAULT
- CUSTOM
- DISABLED
default: DEFAULT
example: DEFAULT
knowledgeBaseIds:
type: array
nullable: true
items:
type: integer
minimum: 0
exclusiveMinimum: true
example: 1
required:
- type
- assistantId
- model
- aiVendor
- instructions
- temperature
- captureVariables
- exitNodeWhen
- type: object
properties:
type:
type: string
enum:
- TOOLS_AI
example: TOOLS_AI
conditions:
type: array
items:
type: object
properties:
handleId:
type: string
example: example
expression:
type: string
example: example
required:
- handleId
- expression
temperature:
type: number
example: 1
model:
type: string
example: example
aiVendor:
type: string
enum:
- OPENAI
- ANTHROPIC
- GOOGLE
- AZURE
- DEEPSEEK
- LLAMA
example: OPENAI
instructions:
type: string
nullable: true
example: example
prompt:
type: string
nullable: true
example: example
customToolIds:
type: array
nullable: true
items:
type: number
example: 1
maxIterations:
type: number
minimum: 1
maximum: 30
default: 10
example: 1
agentType:
type: string
enum:
- BASIC
- ADVANCED
default: BASIC
example: BASIC
captureVariables:
type: array
nullable: true
items:
nullable: true
type: object
knowledgeBaseMode:
type: string
enum:
- DEFAULT
- CUSTOM
- DISABLED
default: DEFAULT
example: DEFAULT
knowledgeBaseIds:
type: array
nullable: true
items:
type: integer
minimum: 0
exclusiveMinimum: true
example: 1
selectedRecordTypes:
type: array
nullable: true
items:
type: object
properties:
recordTypeId:
type: number
example: 1
read:
type: boolean
example: false
create:
type: boolean
example: false
update:
type: boolean
example: false
delete:
type: boolean
example: false
createActivity:
type: boolean
example: false
required:
- recordTypeId
systemToolsConfig:
type: object
nullable: true
properties:
webSearchEnabled:
type: boolean
default: false
example: false
urlScrapeEnabled:
type: boolean
default: false
example: false
linkedinSearchEnabled:
type: boolean
default: false
example: false
connectedAccountConfigs:
type: array
nullable: true
items:
type: object
properties:
connectedAccountId:
type: number
example: 1
useAllTools:
type: boolean
default: true
example: false
selectedToolSlugs:
type: array
nullable: true
items:
type: string
example: example
required:
- connectedAccountId
playbookIds:
type: array
nullable: true
items:
type: integer
minimum: 0
exclusiveMinimum: true
example: 1
required:
- type
- conditions
- instructions
- type: object
properties:
type:
type: string
enum:
- API
example: API
url:
type: string
format: uri
example: https://api.example.com/hook
method:
type: string
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
example: GET
headers:
type: array
items:
type: object
properties:
key:
type: string
example: example
value:
type: string
example: example
required:
- key
- value
body:
type: string
nullable: true
example: example
response:
type: string
nullable: true
example: example
parameters:
type: array
nullable: true
items:
type: object
properties:
key:
type: string
example: example
value:
type: string
example: example
required:
- key
- value
variables:
type: array
nullable: true
items:
type: object
properties:
key:
type: string
example: example
value:
type: string
example: example
fullResponse:
type: boolean
default: false
example: false
required:
- key
- value
required:
- type
- url
- method
- headers
- type: object
properties:
type:
type: string
enum:
- CONDITIONAL_ROUTING
example: CONDITIONAL_ROUTING
routingType:
type: string
enum:
- CONDITIONAL_AI
- DYNAMIC
example: CONDITIONAL_AI
conditions:
type: array
items:
type: object
properties:
handleId:
type: string
example: example
expression:
type: string
example: example
required:
- handleId
- expression
temperature:
type: number
example: 1
model:
type: string
example: example
aiVendor:
type: string
enum:
- OPENAI
- ANTHROPIC
- GOOGLE
- AZURE
- DEEPSEEK
- LLAMA
example: OPENAI
required:
- type
- routingType
- conditions
- type: object
properties:
type:
type: string
enum:
- DYNAMIC_TABLES
example: DYNAMIC_TABLES
tableId:
type: number
nullable: true
example: 1
recordTypeId:
type: number
nullable: true
example: 1
targetRecordTypeId:
type: number
nullable: true
description: Destination record type id. Required when actionType is CHANGE_RECORD_TYPE.
example: 12
actionType:
type: string
nullable: true
enum:
- CREATE
- UPDATE
- DELETE
- SEARCH
- SEARCH_BY_ID
- CHANGE_RECORD_TYPE
description: 'Operation to run. Required-field rules per action: CREATE → rowData; UPDATE → rowId + rowData; DELETE / SEARCH_BY_ID → rowId; CHANGE_RECORD_TYPE → rowId + targetRecordTypeId.'
example: CREATE
rowData:
type: object
nullable: true
additionalProperties:
nullable: true
type: object
inputModeByField:
type: object
nullable: true
additionalProperties:
type: string
enum:
- INPUT
- VARIABLE
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/frontline/refs/heads/main/openapi/frontline-flows-api-openapi.yml