> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt > Use this file to discover all available pages before exploring further. # Update workflow > Update workflow name, tools, system prompt, model, or other settings. Send only the fields you want to change. ## OpenAPI ````yaml /api-reference/openapi.json patch /api/v1/workflow/manager/update/{id} openapi: 3.0.0 info: title: Flowra API (API Key Endpoints) description: >- **Flowra** is an AI-powered platform for building agents, workflows, and integrations. ### Capabilities - **Tools & Toolkits** – Define and group tools for agents and workflows. - **Workflows** – Orchestrate steps and automate processes. - **Triggers** – Schedule or event-based execution. - **Auth & Connections** – OAuth, API keys, and connected accounts. - **MCP** – Model Context Protocol server integration. - **Knowledge / RAG** – Add files and URLs for retrieval-augmented generation. ### Authentication Use the **x-api-key** header with a project API key to access endpoints that support API Key auth. Create and manage API keys in the dashboard under your project settings. Only endpoints that support API Key authentication via the @ApiKeyEnabled() decorator. Send x-api-key (required). On multi-tenant endpoints, optionally send x-username to act as an external user. version: '1.0' contact: name: Flowra url: https://flowra.dev servers: - url: https://flowra.dev description: Flowra API security: [] tags: - name: Users description: User profile - name: External Users description: End-user identities inside a project (x-username) - name: Auth Configs description: OAuth and API key configs for toolkits - name: Connected Accounts description: OAuth connected accounts and link creation - name: Toolkits description: List and search toolkits - name: Tools description: List, execute, and manage tools - name: Skills description: Browse, create, import, and install skills - name: Workflow & Agent description: Create, run, and inspect workflows and agents - name: Triggers description: Schedule and event-based trigger instances - name: Chat description: Threads and streaming agent runs - name: File description: Upload, list, and download files - name: Knowledge description: RAG knowledge collections - name: Table description: Collections and documents - name: Sandbox description: Ephemeral and durable code sandboxes - name: Browser description: Live browser sessions and view - name: LLM description: List AI models and generate completions - name: MCP description: MCP server management - name: usage description: Credit balance and usage ledger for the project API key paths: /api/v1/workflow/manager/update/{id}: patch: tags: - Workflow & Agent summary: Update workflow description: >- Update workflow name, tools, system prompt, model, or other settings. Send only the fields you want to change. operationId: WorkflowManagerController_update parameters: - name: id required: true in: path description: Workflow (agent) ID schema: example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: string - name: x-username in: header required: false description: >- External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context. schema: type: string default: (project default user) example: customer_alice requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWorkflowDto' responses: '200': description: Workflow updated successfully content: application/json: schema: $ref: '#/components/schemas/WorkflowResponseDtoSuccessResponse' example: success: true message: Operation completed successfully data: id: '' name: '' description: '' projectId: '' agent: prompt: '' modelSettings: {} capabilities: {} behavior: {} identity: {} skillIds: - '' subAgentIds: - '' knowledgeCollectionIds: - '' databaseCollectionIds: - '' databaseAccessPolicies: {} starterPrompts: - '' avatarUrl: '' tools: mode: NORMAL discoveryWhitelist: true pinnedSlugs: - '' externalMcpConfigs: - '' connectionCallbackUrl: '' visitorOwnerConnections: enabled: true toolkits: [] inputSchema: {} outputSchema: {} graph: nodes: - id: '' type: action toolSlug: '' inputMapping: {} code: '' agent: {} outputSchema: {} edges: - from: '' to: '' condition: '' inputSchema: {} outputSchema: {} provenance: createdByAgent: true productCreationDepth: 0 createdFromWorkflowId: '' hideFromAgentPicker: true marketplaceClone: sourceWorkflowId: '' clonedAt: '' skillIdMap: {} knowledgeIdMap: {} databaseIdMap: {} subAgentIdMap: {} avatarFileIdMap: {} setupState: answers: {} completedStepIds: - '' triggers: - kind: manual expression: '' timezone: '' toolSlug: '' triggerToolInput: {} triggerId: '' toolkitName: '' toolkitLogo: '' workflowType: static isActive: true lifecycle: draft isPublic: true version: '' clonedFromWorkflowId: '' clonedFromVersion: '' executionCount: 0 successfulExecutionCount: 0 failedExecutionCount: 0 lastExecutedAt: '' connections: - id: '' connectionId: '' toolkitSlug: '' displayName: '' label: '' createdAt: '' updatedAt: '' tools: - toolSlug: '' toolName: '' toolkitName: '' toolkitLogo: '' subAgents: - '' createdAt: '2024-01-01T00:00:00.000Z' updatedAt: '2024-01-01T00:00:00.000Z' sourceVersionLatest: 1.0.2 toolkitAuthConfigs: - toolkitSlug: '' authConfigId: '' name: '' authScheme: '' status: '' toolkitConnections: - toolkitSlug: '' connectedAccountId: '' displayName: '' label: '' status: '' authConfigId: '' marketplaceCategory: '' marketplaceAudience: '' marketplaceTagline: '' marketplaceSetupGuide: '' marketplaceSetupSpec: {} marketplaceSetupSkillId: '' marketplaceSetupSkillSlug: '' marketplaceHighlights: - '' marketplaceIsListed: true marketplaceCapabilities: hasSkills: true skillCount: 0 hasKnowledge: true hasDatabase: true hasCron: true requiresAuth: true toolkitCount: 0 subAgentCount: 0 toolCount: 0 security: - x-api-key: [] - x-api-key: [] x-username: [] components: schemas: UpdateWorkflowDto: type: object properties: name: type: string description: Workflow display name example: Support bot description: type: string description: Short description shown in the workflow list example: Answers product questions and escalates billing issues. agent: $ref: '#/components/schemas/CreateAgentSpecDto' graph: $ref: '#/components/schemas/WorkflowGraphDto' provenance: $ref: '#/components/schemas/CreateAgentProvenanceDto' triggers: description: Replace cron / channel triggers. Empty array clears them. type: array items: $ref: '#/components/schemas/UpdateWorkflowTriggerDto' workflowType: type: string enum: - static - agent description: '`agent` is an open LLM path; `static` is a locked graph' example: agent isActive: type: boolean description: Whether the workflow is active (cron/webhooks fire only when true) example: true isPublic: type: boolean description: Whether other projects can select this agent example: false lastExecutedAt: format: date-time type: string description: Last execution timestamp (ISO 8601). Usually set by the server. example: '2026-09-03T10:00:00.000Z' WorkflowResponseDtoSuccessResponse: type: object properties: success: type: boolean description: Success status example: true message: type: string description: Success message example: Operation completed successfully data: type: object properties: id: type: string name: type: string description: type: string projectId: type: string agent: type: object properties: prompt: type: string modelSettings: type: object capabilities: type: object behavior: type: object identity: type: object skillIds: type: array items: type: string subAgentIds: type: array items: type: string knowledgeCollectionIds: type: array items: type: string databaseCollectionIds: type: array items: type: string databaseAccessPolicies: type: object starterPrompts: type: array items: type: string avatarUrl: type: string tools: type: object properties: mode: enum: - NORMAL - META type: string discoveryWhitelist: type: boolean pinnedSlugs: type: array items: type: string externalMcpConfigs: type: array items: type: string connectionCallbackUrl: type: string nullable: true visitorOwnerConnections: $ref: >- #/components/schemas/AgentVisitorOwnerConnectionsResponseDto required: - mode inputSchema: type: object outputSchema: type: object required: - prompt - tools graph: type: object properties: nodes: type: array items: type: object properties: id: type: string type: type: string enum: - action - code - llm_agent - start - end - human_wait toolSlug: type: string inputMapping: type: object code: type: string agent: $ref: '#/components/schemas/GraphNodeAgentResponseDto' outputSchema: type: object required: - id - type edges: type: array items: type: object properties: from: type: string to: type: string condition: type: string required: - from - to inputSchema: type: object outputSchema: type: object required: - nodes - edges provenance: type: object properties: createdByAgent: type: boolean productCreationDepth: type: number createdFromWorkflowId: type: string hideFromAgentPicker: type: boolean marketplaceClone: type: object properties: sourceWorkflowId: type: string clonedAt: type: string skillIdMap: type: object knowledgeIdMap: type: object databaseIdMap: type: object subAgentIdMap: type: object avatarFileIdMap: type: object setupState: type: object properties: answers: type: object completedStepIds: type: array items: type: string required: - marketplaceClone triggers: type: array items: type: object properties: kind: type: string enum: - manual - cron - trigger_tool expression: type: string timezone: type: string toolSlug: type: string triggerToolInput: type: object triggerId: type: string toolkitName: type: string toolkitLogo: type: string required: - kind workflowType: type: string enum: - static - agent isActive: type: boolean lifecycle: type: string enum: - draft - ready description: >- Completeness lifecycle. draft = incomplete build (cannot activate); ready = may set isActive true. isPublic: type: boolean description: >- Whether this workflow (agent) is public for select in other projects version: type: string description: >- Version in form 1.0.x; incremented on each update (for marketplace update check) clonedFromWorkflowId: type: string nullable: true description: 'If cloned from marketplace: source workflow id' clonedFromVersion: type: string nullable: true description: Source workflow version at clone time (e.g. 1.0.1) executionCount: type: number successfulExecutionCount: type: number description: Number of executions that finished with status completed failedExecutionCount: type: number description: Number of executions that finished with status failed or timeout lastExecutedAt: type: string connections: type: array items: type: object properties: id: type: string connectionId: type: string toolkitSlug: type: string displayName: type: string nullable: true description: User-defined label from connected_accounts.displayName label: type: string nullable: true description: >- Human label (displayName, else toolkit name). Never a UUID. createdAt: type: string updatedAt: type: string required: - id - connectionId - toolkitSlug - createdAt - updatedAt tools: description: Pinned tools from workflow_tools join (enriched). type: array items: type: object properties: toolSlug: type: string toolName: type: string toolkitName: type: string toolkitLogo: type: string required: - toolSlug - toolName - toolkitName subAgents: description: Resolved child specialists (hidden from the agent list). type: array items: type: string createdAt: format: date-time type: string updatedAt: format: date-time type: string sourceVersionLatest: type: string description: >- When workflow is cloned from marketplace: latest version of source (for "update available" UI). example: 1.0.2 toolkitAuthConfigs: description: 'Agent-only: toolkitSlug → AuthConfig bindings.' type: array items: type: object properties: toolkitSlug: type: string authConfigId: type: string name: type: string nullable: true authScheme: type: string nullable: true status: type: string nullable: true required: - toolkitSlug - authConfigId toolkitConnections: description: >- Static + cron agents: preferred ConnectedAccount binds (chat/trigger do not use these). type: array items: type: object properties: toolkitSlug: type: string connectedAccountId: type: string displayName: type: string nullable: true label: type: string nullable: true description: >- Human label (displayName or provider identity). Never a UUID. status: type: string nullable: true authConfigId: type: string nullable: true required: - toolkitSlug - connectedAccountId marketplaceCategory: type: string nullable: true description: Marketplace listing category marketplaceAudience: type: string nullable: true description: 'Marketplace audience: for_you | for_your_users | both' marketplaceTagline: type: string nullable: true marketplaceSetupGuide: type: string nullable: true marketplaceSetupSpec: type: object nullable: true marketplaceSetupSkillId: type: string nullable: true marketplaceSetupSkillSlug: type: string nullable: true marketplaceHighlights: nullable: true type: array items: type: string marketplaceIsListed: type: boolean description: When false, listing is hidden from the public catalog marketplaceCapabilities: type: object properties: hasSkills: type: boolean skillCount: type: number hasKnowledge: type: boolean hasDatabase: type: boolean hasCron: type: boolean requiresAuth: type: boolean toolkitCount: type: number subAgentCount: type: number toolCount: type: number required: - id - name - projectId - triggers - workflowType - isActive - lifecycle - isPublic - version - executionCount - successfulExecutionCount - failedExecutionCount - connections - tools - createdAt - updatedAt - marketplaceCapabilities example: id: '' name: '' description: '' projectId: '' agent: prompt: '' modelSettings: {} capabilities: {} behavior: {} identity: {} skillIds: - '' subAgentIds: - '' knowledgeCollectionIds: - '' databaseCollectionIds: - '' databaseAccessPolicies: {} starterPrompts: - '' avatarUrl: '' tools: mode: NORMAL discoveryWhitelist: true pinnedSlugs: - '' externalMcpConfigs: - '' connectionCallbackUrl: '' visitorOwnerConnections: enabled: true toolkits: [] inputSchema: {} outputSchema: {} graph: nodes: - id: '' type: action toolSlug: '' inputMapping: {} code: '' agent: {} outputSchema: {} edges: - from: '' to: '' condition: '' inputSchema: {} outputSchema: {} provenance: createdByAgent: true productCreationDepth: 0 createdFromWorkflowId: '' hideFromAgentPicker: true marketplaceClone: sourceWorkflowId: '' clonedAt: '' skillIdMap: {} knowledgeIdMap: {} databaseIdMap: {} subAgentIdMap: {} avatarFileIdMap: {} setupState: answers: {} completedStepIds: - '' triggers: - kind: manual expression: '' timezone: '' toolSlug: '' triggerToolInput: {} triggerId: '' toolkitName: '' toolkitLogo: '' workflowType: static isActive: true lifecycle: draft isPublic: true version: '' clonedFromWorkflowId: '' clonedFromVersion: '' executionCount: 0 successfulExecutionCount: 0 failedExecutionCount: 0 lastExecutedAt: '' connections: - id: '' connectionId: '' toolkitSlug: '' displayName: '' label: '' createdAt: '' updatedAt: '' tools: - toolSlug: '' toolName: '' toolkitName: '' toolkitLogo: '' subAgents: - '' createdAt: '2024-01-01T00:00:00.000Z' updatedAt: '2024-01-01T00:00:00.000Z' sourceVersionLatest: 1.0.2 toolkitAuthConfigs: - toolkitSlug: '' authConfigId: '' name: '' authScheme: '' status: '' toolkitConnections: - toolkitSlug: '' connectedAccountId: '' displayName: '' label: '' status: '' authConfigId: '' marketplaceCategory: '' marketplaceAudience: '' marketplaceTagline: '' marketplaceSetupGuide: '' marketplaceSetupSpec: {} marketplaceSetupSkillId: '' marketplaceSetupSkillSlug: '' marketplaceHighlights: - '' marketplaceIsListed: true marketplaceCapabilities: hasSkills: true skillCount: 0 hasKnowledge: true hasDatabase: true hasCron: true requiresAuth: true toolkitCount: 0 subAgentCount: 0 toolCount: 0 required: - success - message - data CreateAgentSpecDto: type: object properties: prompt: type: string description: System prompt / instructions for the agent example: You are a helpful support agent. Prefer short answers. modelSettings: $ref: '#/components/schemas/CreateAgentModelSettingsDto' capabilities: $ref: '#/components/schemas/CreateAgentCapabilitiesDto' skillIds: description: Skill IDs to attach as playbooks. type: array items: type: string subAgentIds: description: Child agent workflow IDs (one level). type: array items: type: string knowledgeCollectionIds: description: Knowledge collection IDs this agent can access. type: array items: type: string databaseCollectionIds: description: Database collection IDs this agent can access. type: array items: type: string databaseAccessPolicies: type: object description: Per-collection end-user access policies (keyed by collectionId). additionalProperties: true starterPrompts: description: Suggested starter prompts (max 8, each max 200 chars). type: array items: type: string maxLength: 200 avatarUrl: type: string maxLength: 500 description: Optional agent avatar (`file:` or https URL). behavior: $ref: '#/components/schemas/CreateAgentBehaviorDto' identity: $ref: '#/components/schemas/CreateAgentIdentityDto' tools: $ref: '#/components/schemas/CreateAgentToolsDto' inputSchema: type: object description: Extra chat inputs for this agent (JSON Schema). outputSchema: type: object description: >- Structured shape for the agent final answer, keyed by field name. Each value is { type, required?, description? }. Omit for free-form text replies. additionalProperties: true WorkflowGraphDto: type: object properties: nodes: description: Graph nodes type: array items: $ref: '#/components/schemas/WorkflowNodeDto' edges: description: Directed edges between nodes type: array items: $ref: '#/components/schemas/WorkflowEdgeDto' inputSchema: type: object description: JSON Schema for workflow input outputSchema: type: object description: JSON Schema for workflow output required: - nodes - edges CreateAgentProvenanceDto: type: object properties: createdByAgent: type: boolean description: True when another agent created this workflow example: false productCreationDepth: type: number description: Nesting depth when created from another agent (0 = user-created) example: 0 createdFromWorkflowId: type: string description: Parent workflow ID if this agent was spawned from another example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 hideFromAgentPicker: type: boolean description: Hide from the agent picker in the dashboard example: false UpdateWorkflowTriggerDto: type: object properties: kind: type: string description: 'Trigger kind (static may use manual; agents: cron|trigger_tool)' enum: - manual - cron - trigger_tool example: cron expression: type: string description: Cron expression (required when kind is cron) example: 0 9 * * 1-5 timezone: type: string description: IANA timezone for cron example: UTC toolSlug: type: string description: Trigger tool slug (required when kind is trigger_tool) example: gmail_new_gmail_message triggerToolInput: type: object description: Trigger tool configuration example: labelIds: - INBOX triggerId: type: string description: Registered trigger instance id example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 AgentVisitorOwnerConnectionsResponseDto: type: object properties: enabled: type: boolean toolkits: type: array items: $ref: '#/components/schemas/AgentVisitorOwnerToolkitGrantResponseDto' required: - enabled - toolkits GraphNodeAgentResponseDto: type: object properties: prompt: type: string modelSettings: type: object toolSlugs: type: array items: type: string knowledgeCollectionIds: type: array items: type: string databaseCollectionIds: type: array items: type: string databaseAccessPolicies: type: object required: - prompt CreateAgentModelSettingsDto: type: object properties: model: type: string description: Model identifier (e.g. openai/gpt-4o-mini) example: openai/gpt-4o-mini temperature: type: number minimum: 0 maximum: 2 description: Temperature 0-2 example: 0.7 maxTokens: type: number description: Max tokens example: 4096 cacheToolsAndPrompt: type: boolean description: Cache tools and prompt example: true topP: type: number minimum: 0 maximum: 1 description: Nucleus sampling top_p (0–1) example: 1 topK: type: number minimum: 1 description: Top-K sampling example: 40 frequencyPenalty: type: number minimum: -2 maximum: 2 description: Frequency penalty (−2 to 2) example: 0 presencePenalty: type: number minimum: -2 maximum: 2 description: Presence penalty (−2 to 2) example: 0 repetitionPenalty: type: number minimum: 0 maximum: 2 description: Repetition penalty (0–2) example: 1 minP: type: number minimum: 0 maximum: 1 description: min_p sampling (0–1) example: 0 topA: type: number minimum: 0 maximum: 1 description: Top-A sampling (0–1) example: 0 seed: type: number description: Random seed for deterministic generation example: 42 stop: description: Stop sequences example: - END type: array items: type: string logitBias: type: object description: Token id → bias map additionalProperties: type: number example: '50256': -100 topLogprobs: type: number minimum: 0 maximum: 20 description: Top logprobs to return per token (0–20) example: 0 reasoningEffort: type: string enum: - none - low - medium - high description: >- Reasoning / thinking effort (OpenRouter). none=off; low|medium|high when model supports reasoning_effort. example: medium CreateAgentCapabilitiesDto: type: object properties: computer: $ref: '#/components/schemas/CreateAgentComputerDto' generalPurpose: $ref: '#/components/schemas/CreateAgentGeneralPurposeDto' summarization: $ref: '#/components/schemas/CreateAgentSummarizationDto' todoList: $ref: '#/components/schemas/CreateAgentTodoListDto' toolRetry: $ref: '#/components/schemas/CreateAgentToolRetryDto' modelFallback: $ref: '#/components/schemas/CreateAgentModelFallbackDto' toolSelector: $ref: '#/components/schemas/CreateAgentToolSelectorDto' humanApproval: $ref: '#/components/schemas/CreateAgentHumanApprovalDto' modelCallLimit: $ref: '#/components/schemas/CreateAgentModelCallLimitDto' toolCallLimit: $ref: '#/components/schemas/CreateAgentToolCallLimitDto' userFriendlyErrors: type: boolean description: Enable user-friendly error messages example: true longTermMemory: $ref: '#/components/schemas/CreateAgentLongTermMemoryDto' CreateAgentBehaviorDto: type: object properties: persona: $ref: '#/components/schemas/CreateAgentPersonaDto' guardrails: $ref: '#/components/schemas/CreateAgentGuardrailsDto' escalation: $ref: '#/components/schemas/CreateAgentEscalationDto' usageCaps: $ref: '#/components/schemas/CreateAgentUsageCapsDto' cannedResponses: $ref: '#/components/schemas/CreateAgentCannedResponsesDto' CreateAgentIdentityDto: type: object properties: mode: type: string enum: - anonymous - collect - required description: >- anonymous (default) | collect (optional form) | required (gate before chat) methods: description: >- How the end user may prove identity: host_hmac, host_jwt, email_otp, channel_native, sdk_username, toolkit_connection type: array items: type: string collect: description: 'Profile fields to collect: name, email, phone' type: array items: type: string linkBy: description: Join the same person across surfaces by verified email and/or phone type: array items: type: string allowedEmailDomains: description: >- When set, verified email must match one of these domains (e.g. acme.com) type: array items: type: string maxLength: 255 toolkitSlug: type: string maxLength: 128 description: >- Toolkit slug whose ACTIVE connected account proves identity when methods includes toolkit_connection CreateAgentToolsDto: type: object properties: mode: enum: - NORMAL - META type: string description: NORMAL = explicit list, META = meta + discovery filters. example: NORMAL discoveryWhitelist: type: boolean description: >- When mode is META: true = discovery limited to pinned toolkit slugs; false = exclude those slugs. pinnedSlugs: description: Pinned tool slugs (synced to workflow_tools). example: - gmail_send_email - gmail_fetch_emails type: array items: type: string externalMcpConfigs: description: >- External MCP configs: [{ name, url, headers?, tools }]. tools = selected tool slugs from that MCP. type: array items: $ref: '#/components/schemas/CreateAgentExternalMcpConfigDto' connectionCallbackUrl: type: string nullable: true maxLength: 2048 description: >- OAuth return URL after linking toolkit accounts. Empty string clears. example: https://myapp.com/oauth/callback visitorOwnerConnections: $ref: '#/components/schemas/CreateAgentVisitorOwnerConnectionsDto' WorkflowNodeDto: type: object properties: id: type: string description: Node id referenced by edges example: n_start type: type: string enum: - action - code - llm_agent - start - end - human_wait description: Node type example: action toolSlug: type: string description: Tool slug when type is action example: gmail_send_email inputMapping: type: object description: Maps previous-node output / input into this node’s arguments example: to: '{{input.email}}' code: type: string description: Source when type is code agent: $ref: '#/components/schemas/GraphNodeAgentDto' humanMessage: type: string description: Prompt shown to a human when type is human_wait example: Approve sending this email? outputSchema: type: object description: JSON Schema for this node’s output required: - type WorkflowEdgeDto: type: object properties: from: type: string description: Source node id example: n_start to: type: string description: Target node id example: n_send condition: type: string description: Optional JS expression; edge is taken when it evaluates truthy example: output.approved === true required: - from - to AgentVisitorOwnerToolkitGrantResponseDto: type: object properties: toolkitSlug: type: string toolSlugs: type: array items: type: string required: - toolkitSlug CreateAgentComputerDto: type: object properties: enabled: type: boolean description: >- Enable Flowra Computer (E2B sandbox + execute + chat Computer chip) for this agent example: true templateId: type: string description: E2B template name or ID (optional; falls back to server default) example: code-interpreter-v1 maxDurationSec: type: number minimum: 1 description: Wall-clock cap for billing and session (seconds) example: 3600 CreateAgentGeneralPurposeDto: type: object properties: enabled: type: boolean description: >- Enable general-purpose deep-agent posture without requiring a real computer example: false CreateAgentSummarizationDto: type: object properties: enabled: type: boolean description: Enable summarization middleware example: true trigger: type: object description: Trigger conditions keep: type: object description: Keep rule model: type: string description: Model used for summarization example: openai/gpt-4o-mini maxTokensBeforeSummary: type: number description: Max tokens for summary generation example: 1024 prefix: type: string description: Prefix to add to summary message example: '## Conversation so far' CreateAgentTodoListDto: type: object properties: enabled: type: boolean description: Enable todo/planning tool example: true strict: type: boolean description: Strict planning mode example: false CreateAgentToolRetryDto: type: object properties: enabled: type: boolean description: Enable tool retry example: true maxRetries: type: number minimum: 0 description: Max retries example: 2 backoffFactor: type: number minimum: 0 description: Backoff factor example: 2 initialDelayMs: type: number minimum: 0 description: Initial delay ms example: 500 maxDelayMs: type: number minimum: 0 description: Max delay ms example: 8000 jitter: type: boolean description: Add jitter to backoff example: true tools: description: Retry only these tool names type: array items: type: string onFailure: type: string description: Behavior when retries exhausted enum: - continue - error CreateAgentModelFallbackDto: type: object properties: enabled: type: boolean description: Enable model fallback (resilience) fallbackModels: description: Fallback model ids in order type: array items: type: string CreateAgentToolSelectorDto: type: object properties: enabled: type: boolean description: Enable LLM tool selector model: type: string description: Selector model maxTools: type: number minimum: 1 description: Max tools to include alwaysInclude: description: >- Tool names always kept by the selector (from agent-assigned tools). Does not count against maxTools. type: array items: type: string autoEnableIfToolCountGte: type: number minimum: 1 description: Auto enable if tool count >= N CreateAgentHumanApprovalDto: type: object properties: enabled: type: boolean description: Enable human approval for sensitive tools mode: type: string description: Approval mode enum: - sensitiveOnly sensitiveToolNames: description: Tool names requiring approval type: array items: type: string alwaysAllowedToolNames: description: Tool names always allowed (no approval) type: array items: type: string allowedDecisions: description: Allowed decisions type: array items: type: string messageToUser: type: string description: Message shown to user on approval request CreateAgentModelCallLimitDto: type: object properties: enabled: type: boolean description: Enable model call limit threadLimit: type: number minimum: 1 description: Max model calls per thread runLimit: type: number minimum: 1 description: Max model calls per run/invocation exitBehavior: type: string description: Exit behavior enum: - end - error CreateAgentToolCallLimitDto: type: object properties: enabled: type: boolean description: Enable tool call limit middleware threadLimit: type: number minimum: 1 description: Max tool calls per thread runLimit: type: number minimum: 1 description: Max tool calls per run/invocation exitBehavior: type: string description: >- When limit exceeded: continue (block with errors), end (stop), or error (throw) enum: - continue - end - error toolName: type: string description: If set, limits apply only to this tool name (otherwise all tools) CreateAgentLongTermMemoryDto: type: object properties: enabled: type: boolean description: >- When true, the agent can remember important details about each person across chats (only for this agent). Uses deep-agent memory; does not require computer. instructions: type: string maxLength: 4000 description: >- Plain-language guidance for what to remember (e.g. reply style, nickname). Skip temporary one-off chatter. CreateAgentPersonaDto: type: object properties: displayName: type: string maxLength: 120 description: Name the agent introduces itself with. role: type: string maxLength: 200 description: What the agent does, in one short phrase. tone: type: string enum: - professional - friendly - empathetic - concise - technical - playful verbosity: type: string enum: - brief - balanced - detailed language: type: string enum: - match_user - fa - en - ar - tr emoji: type: string enum: - never - sparing - free styleNotes: type: string maxLength: 2000 description: Extra style notes, appended verbatim. CreateAgentGuardrailsDto: type: object properties: bannedTopics: description: Subjects the agent must decline. type: array items: type: string maxLength: 200 neverPromise: description: Things the agent must never commit to. type: array items: type: string maxLength: 200 refusalMessage: type: string maxLength: 1000 description: What the agent says when it declines. groundingMode: type: string enum: - 'off' - prefer_sources - strict pii: $ref: '#/components/schemas/CreateAgentGuardrailsPiiDto' CreateAgentEscalationDto: type: object properties: enabled: type: boolean triggers: description: Situations that require a human. type: array items: type: string maxLength: 200 afterFailedAttempts: type: number minimum: 1 maximum: 10 action: type: string enum: - reply_only - notify_tool - human_approval description: >- reply_only and notify_tool pause messaging-channel auto-reply until an operator hands back. human_approval is tool HITL only. notifyToolSlug: type: string maxLength: 200 description: Tool used to notify a human; must also be pinned. summaryTemplate: type: string maxLength: 1000 description: Shape of the handoff summary. handoffMessage: type: string maxLength: 1000 description: What the agent says while handing off. CreateAgentUsageCapsDto: type: object properties: enabled: type: boolean messagesPerUserPerDay: type: number minimum: 1 description: Per end user, per rolling day. maxTurnsPerConversation: type: number minimum: 1 maxCreditsPerConversation: type: number minimum: 1 onExceeded: type: string enum: - stop - escalate exceededMessage: type: string maxLength: 1000 description: Shown to the end user once a cap is hit. CreateAgentCannedResponsesDto: type: object properties: greeting: type: string maxLength: 1000 fallback: type: string maxLength: 1000 description: Used when the agent genuinely does not know. outOfHours: type: string maxLength: 1000 businessHours: $ref: '#/components/schemas/CreateAgentBusinessHoursDto' CreateAgentExternalMcpConfigDto: type: object properties: name: type: string description: MCP config name example: internal-docs url: type: string description: MCP server URL example: https://mcp.example.com/sse headers: type: object description: Optional headers additionalProperties: type: string example: Authorization: Bearer sk_live_... tools: description: Selected tool slugs from this MCP example: - search_docs type: array items: type: string CreateAgentVisitorOwnerConnectionsDto: type: object properties: enabled: type: boolean description: >- When true, granted toolkits run as the workflow owner for channel/embed visitors. Default false. toolkits: description: >- Toolkits (optionally limited to specific slugs) that may use the owner account. type: array items: $ref: '#/components/schemas/CreateAgentVisitorOwnerToolkitGrantDto' GraphNodeAgentDto: type: object properties: prompt: type: string description: Node-local system prompt example: Extract the invoice total. modelSettings: type: object description: Model settings for this node example: model: openai/gpt-4o-mini temperature: 0 toolSlugs: description: Tool slugs this node may call example: - gmail_send_email type: array items: type: string knowledgeCollectionIds: description: Knowledge collection IDs attached to this node example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string databaseCollectionIds: description: Table collection IDs attached to this node type: array items: type: string databaseAccessPolicies: type: object description: Per-collection access policies for table tools CreateAgentGuardrailsPiiDto: type: object properties: enabled: type: boolean rules: type: array items: $ref: '#/components/schemas/CreateAgentPiiRuleDto' CreateAgentBusinessHoursDto: type: object properties: timezone: type: string maxLength: 64 description: IANA timezone, e.g. Asia/Tehran. days: description: 0 = Sunday … 6 = Saturday. type: array items: type: number maximum: 6 minimum: 0 start: type: string maxLength: 5 description: HH:mm end: type: string maxLength: 5 description: HH:mm CreateAgentVisitorOwnerToolkitGrantDto: type: object properties: toolkitSlug: type: string maxLength: 128 description: Toolkit slug whose owner account visitors may use. toolSlugs: description: >- If set and non-empty, only these tool slugs may use the owner account. type: array items: type: string CreateAgentPiiRuleDto: type: object properties: type: type: string enum: - email - credit_card - ip - mac_address - url - custom strategy: type: string enum: - block - redact - mask - hash pattern: type: string maxLength: 500 description: Regex source. Required when type is `custom`. applyToInput: type: boolean applyToOutput: type: boolean securitySchemes: x-api-key: type: apiKey in: header name: x-api-key description: >- Project API key. Create and manage keys in the dashboard under Project → API Keys. Send as header: x-api-key: x-username: type: apiKey in: header name: x-username description: >- Optional. External user username. If omitted, Flowra uses the project’s default external user. Send as header: x-username: ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.