Beam AI Complete Agent Graph API

openapi: 3.2.0
info:
  title: Public Complete Agent Graph API
  description: Public endpoints to interact with agents and orchestrate tasks
  version: '1.0'
  contact: {}
servers: []
tags:
- name: Complete Agent Graph
paths:
  /agent-graphs/{agentId}:
    put:
      operationId: CompleteAgentGraphController_updateAgentGraph
      summary: Update agent and its draft graph
      description: Updates an existing agent (name, description, settings) and replaces all nodes and edges in its draft graph.
      parameters:
      - name: agentId
        required: true
        in: path
        description: The ID of the agent to update
        schema:
          type: string
      - name: saveAndPublish
        required: false
        in: query
        description: If true, publishes the draft graph as active and creates a new draft. If false (default), only updates the draft.
        schema:
          type: boolean
      - name: current-workspace-id
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentGraphDto'
      responses:
        '200':
          description: Agent and graph updated successfully (draft only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAgentGraphResponseDto'
        '404':
          description: Agent or draft graph not found
      tags:
      - Complete Agent Graph
      security:
      - bearer: []
      - x-api-key: []
  /agent-graphs/complete:
    post:
      operationId: CompleteAgentGraphController_createAgentGraph
      summary: Create a complete agent graph
      description: Creates a new agent with its complete graph structure including nodes, edges, and tool configurations. Both an active/published graph and a draft graph are created.
      parameters:
      - name: current-workspace-id
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentGraphCompleteDto'
      responses:
        '201':
          description: Agent and graph created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentGraphResponseDto'
        '400':
          description: Bad Request - Invalid input data
        '404':
          description: Tool not found and no originalTool data provided
        '409':
          description: Conflict - Invalid tool type provided
      tags:
      - Complete Agent Graph
      security:
      - bearer: []
      - x-api-key: []
components:
  schemas:
    UpdateAgentGraphDto:
      type: object
      properties:
        agentName:
          type: string
          description: New name for the agent. Leave undefined to keep the current name
          example: Updated Bitcoin Price Agent
        agentDescription:
          type: string
          description: New description for the agent. Leave undefined to keep the current description
          example: An improved agent that fetches cryptocurrency prices with better error handling
        settings:
          description: Updated configuration settings. Leave undefined to keep current settings
          allOf:
          - $ref: '#/components/schemas/AgentSettingsDto'
        nodes:
          description: The complete updated list of nodes for the agent graph. This replaces all existing nodes - provide the full node structure including any unchanged nodes
          type: array
          items:
            $ref: '#/components/schemas/CompleteAgentGraphNodeDto'
      required:
      - nodes
    UpdateAgentGraphResponseDto:
      type: object
      properties:
        draftGraphId:
          type: string
          description: UUID of the draft graph
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
          format: uuid
        agentId:
          type: string
          description: UUID of the agent
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          format: uuid
        agentName:
          type: string
          description: Name of the agent
          example: My AI Agent
      required:
      - draftGraphId
      - agentId
      - agentName
    AgentTriggerConfigurationFiltersConditions:
      type: object
      properties:
        condition:
          enum:
          - is
          - is_not
          - contain
          - does_not_contain
          - any
          - all
          - less_than
          - GREATER_than
          - count
          - exist
          - does_not_exist
          type: string
        operator:
          enum:
          - AND
          - OR
          type: string
        property:
          type: string
        value:
          type: string
      required:
      - condition
      - operator
      - property
      - value
    CompleteAgentGraphNodeToolConfigurationDto:
      type: object
      properties:
        toolFunctionName:
          type: string
          description: The unique function name used to invoke this tool
          example: GPTAction_Custom_BitcoinPriceFetcher_xjUR
        toolName:
          type: string
          description: The display name of the tool shown in the UI
          example: Bitcoin Price Fetcher
        iconSrc:
          type:
          - string
          - 'null'
          description: URL to the tool icon image
          example: null
        description:
          type: string
          description: Brief explanation of what this tool does
          example: Fetches the current Bitcoin price from CoinGecko API and returns the USD value
        requiresConsent:
          type: boolean
          description: When true, the agent will ask for user confirmation before executing this tool
          example: false
        isMemoryTool:
          type: boolean
          description: When true, this tool can access and search the agent memory/knowledge base
          example: false
        memoryLookupInstruction:
          type: string
          description: Instructions for how to search the memory when isMemoryTool is true
          example: ''
        isBackgroundTool:
          type: boolean
          description: When true, the tool runs in the background without blocking the conversation flow
          example: false
        isBatchExecutionEnabled:
          type: boolean
          description: When true, the tool can process multiple items in a single execution (batch mode)
          example: false
        accuracyScore:
          type:
          - number
          - 'null'
          description: A score (0-100) indicating the historical accuracy/success rate of this tool. Null if not yet measured
          example: null
        preferredModel:
          type:
          - string
          - 'null'
          description: 'The preferred AI model to use when executing this tool. If not specified, the system default model will be used. Common values: "gpt-4", "gpt-4o", "gpt-3.5-turbo"'
          example: gpt-4o
        fallbackModels:
          type:
          - string
          - 'null'
          pattern: /^[^\s]*$/
          description: Comma-separated list of fallback models. No spaces allowed.
          example: DEEP_SEEK,BEDROCK_CLAUDE_3_7_SONNET,BEDROCK_CLAUDE_OPUS_4_5
        prompt:
          type:
          - string
          - 'null'
          description: The prompt template that guides the AI when executing this tool. This defines how the AI should process inputs and generate outputs. Required for custom GPT tools
          example: You are a helpful assistant. Given the input parameters, fetch the current Bitcoin price and return it in a user-friendly format.
        inputParams:
          description: List of input parameters that define what data this tool needs to execute. These can be filled by AI, static values, user input, or linked from previous node outputs
          type: array
          items:
            $ref: '#/components/schemas/AgentGraphNodeToolConfigurationInputParamDto'
        outputParams:
          description: List of output parameters that this tool produces after execution. These outputs can be linked to input parameters of subsequent nodes in the graph
          type: array
          items:
            $ref: '#/components/schemas/AgentGraphNodeToolConfigurationOutputParamDto'
      required:
      - toolFunctionName
      - toolName
      - description
      - requiresConsent
      - isMemoryTool
      - memoryLookupInstruction
      - isBackgroundTool
      - isBatchExecutionEnabled
      - inputParams
      - outputParams
    AgentGraphNodeToolConfigurationOutputParamDto:
      type: object
      properties:
        isArray:
          type: boolean
          description: Whether this output parameter returns an array of values rather than a single value
          example: false
        paramName:
          type: string
          description: The technical name/key of this output parameter, used when accessing the value in subsequent nodes
          example: bitcoin_price_usd
        position:
          type: number
          description: The display order position of this parameter (0-indexed). Lower numbers appear first in the UI
          example: 0
        paramDescription:
          type: string
          description: Human-readable description explaining what this output contains and how it can be used
          example: The current price of Bitcoin in USD, extracted from the API response
        parentId:
          type:
          - string
          - 'null'
          description: For nested/hierarchical outputs, the UUID of the parent parameter. Null for top-level parameters
          example: null
        paramPath:
          type:
          - string
          - 'null'
          description: JSON path showing where this value is located in a nested response structure
          example: data.bitcoin.usd
        outputExample:
          type: string
          description: Example value demonstrating the expected output format
          example: '94523.50'
        dataType:
          type: string
          description: 'The data type of this output. Common types: string, number, boolean, object, array'
          example: number
        typeOptions:
          type:
          - object
          - 'null'
          description: Additional type configuration (e.g., enum values, format specifications, nested structure definitions)
          example:
            format: currency
            precision: 2
      required:
      - isArray
      - paramName
      - position
      - paramDescription
      - dataType
    ParamOptionDto:
      type: object
      properties:
        label:
          type: string
          description: Display label shown to users when selecting this option in a dropdown or selection UI
          example: United States
        value:
          type: string
          description: The actual value submitted when this option is selected, typically used in API calls or data processing
          example: US
      required:
      - label
      - value
    AgentGraphNodeToolConfigurationInputParamDto:
      type: object
      properties:
        fillType:
          type: string
          description: 'Determines how the parameter value is populated. Options: "ai_fill" (AI determines value), "static" (fixed value), "linked" (from previous node output), "user_input" (user provides value)'
          example: ai_fill
        position:
          type: number
          description: The display order position of this parameter (0-indexed). Lower numbers appear first in the UI
          example: 0
        question:
          type:
          - string
          - 'null'
          description: When fillType is "user_input", this question is displayed to prompt the user for input
          example: What API endpoint URL should be used?
        linkedOutputParamNodeId:
          type:
          - string
          - 'null'
          description: When fillType is "linked", this is the node ID that contains the output parameter to link to
          example: d2cbeb35-9110-426c-967a-c0dba38289a9
        linkedOutputParamName:
          type:
          - string
          - 'null'
          description: When fillType is "linked", this is the name of the output parameter from the referenced node to link to
          example: bitcoin_price_usd
        staticValue:
          type:
          - string
          - 'null'
          description: When fillType is "static", this is the fixed value that will always be used for this parameter
          example: https://api.example.com/data
        required:
          type: boolean
          description: Whether this parameter must be provided for the tool to execute. Required parameters must have a value
          example: true
        dataType:
          type: string
          description: 'The expected data type for this parameter. Common types: string, number, boolean, object, array'
          example: string
        outputExample:
          type:
          - string
          - 'null'
          description: An example value showing the expected format, helpful for AI or users when providing input
          example: https://api.coingecko.com/api/v3/simple/price
        reloadProps:
          type: boolean
          description: When true, changing this parameter value triggers a reload of dependent parameters or options
          example: false
        remoteOptions:
          type: boolean
          description: When true, the available options for this parameter are fetched from an external API rather than being static
          example: false
        options:
          description: For dropdown/select parameters, the list of available options to choose from
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ParamOptionDto'
        paramName:
          type: string
          description: The technical name/key of this parameter, used in API calls and data mapping
          example: api_url
        paramDescription:
          type: string
          description: Human-readable description explaining what this parameter is for and what value is expected
          example: The URL of the API endpoint to call
        paramTip:
          type:
          - string
          - 'null'
          description: Additional helpful tip or hint displayed in the UI to guide users when filling this parameter
          example: Make sure to include the full URL with protocol (https://)
        linkedOutputParamRules:
          description: Array of linked output param rules for conditional input resolution
          type: array
          items:
            $ref: '#/components/schemas/LinkedOutputParamRuleDto'
        linkedParamRulePrompt:
          type: string
          description: Prompt for the linked param rule (used with LLM-based conditions)
        linkedParamConfigurations:
          description: Configuration for linked param condition (conditionType, llmModel)
          allOf:
          - $ref: '#/components/schemas/ParamRuleConditionConfig'
      required:
      - fillType
      - position
      - required
      - dataType
      - reloadProps
      - remoteOptions
      - paramName
      - paramDescription
    LinkedOutputParamRuleDto:
      type: object
      properties:
        elementKey:
          type: string
          description: Element key for the rule.
        operator:
          enum:
          - equals
          - not_equals
          - greater_than
          - less_than
          - contains
          - does_not_contain
          - starts_with
          - ends_with
          - is_empty
          - is_not_empty
          type: string
          description: Comparison operator for the rule.
        comparisonValueType:
          enum:
          - static
          - output_param
          type: string
          description: Type of the comparison value.
        comparisonValue:
          type:
          - string
          - 'null'
          description: Value to compare against.
        nextRuleOperator:
          enum:
          - AND
          - OR
          type: string
          description: Logical operator linking to the next rule.
      required:
      - elementKey
      - operator
      - comparisonValueType
    AgentTriggerConfigurationFiltersGroup:
      type: object
      properties:
        operator:
          enum:
          - AND
          - OR
          type: string
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AgentTriggerConfigurationFiltersConditions'
      required:
      - operator
      - conditions
    ParamRuleConditionConfig:
      type: object
      properties:
        conditionType:
          type: string
          enum:
          - llm_based
          - rule_based
    ConditionRuleDto:
      type: object
      properties:
        sourceNodeId:
          type: string
          description: The node ID containing the source output parameter
          example: d2cbeb35-9110-426c-967a-c0dba38289a9
        sourceOutputParamName:
          type: string
          description: The name of the source output parameter to compare
          example: status
        operator:
          enum:
          - equals
          - not_equals
          - greater_than
          - less_than
          - contains
          - does_not_contain
          - starts_with
          - ends_with
          - is_empty
          - is_not_empty
          type: string
          description: The comparison operator
          example: equals
        comparisonValueType:
          enum:
          - static
          - output_param
          type: string
          description: Type of comparison value (static or output_param)
          example: static
        comparisonValue:
          type: string
          description: Static value to compare against (when comparisonValueType is static)
          example: success
        comparisonNodeId:
          type: string
          description: Node ID containing the output param to compare against (when comparisonValueType is output_param)
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        comparisonOutputParamName:
          type: string
          description: Output param name to compare against (when comparisonValueType is output_param)
          example: expectedStatus
        nextRuleOperator:
          enum:
          - AND
          - OR
          type: string
          description: Logical operator to connect to the next rule (AND/OR)
      required:
      - sourceNodeId
      - sourceOutputParamName
      - operator
      - comparisonValueType
    CompleteAgentGraphEdgeDto:
      type: object
      properties:
        sourceAgentGraphNodeId:
          type: string
          description: The UUID source node where this edge originates from (the "from" node)
          example: d2cbeb35-9110-426c-967a-c0dba38289a9
        targetAgentGraphNodeId:
          type: string
          description: The UUID of the target node where this edge leads to (the "to" node)
          example: 22b6aa40-7d7c-449f-b151-0229834b48ba
        condition:
          type: string
          description: A condition expression that must evaluate to true for the agent to follow this edge. Empty string means unconditional transition
          example: price > 50000
        isAttachmentDataPulledIn:
          type: boolean
          description: When true, any file attachments from the conversation are passed along this edge to the next node
          example: true
        conditionGroups:
          description: Condition groups for rule-based condition evaluation
          type: array
          items:
            $ref: '#/components/schemas/ConditionGroupDto'
      required:
      - sourceAgentGraphNodeId
      - targetAgentGraphNodeId
      - condition
      - isAttachmentDataPulledIn
    AgentSettingsDto:
      type: object
      properties:
        prompts:
          description: List of suggested prompts shown to users as conversation starters. These help users understand what the agent can do
          example:
          - What is the current Bitcoin price?
          - Can you fetch the latest cryptocurrency rates?
          type: array
          items:
            type: string
    ConditionGroupDto:
      type: object
      properties:
        rules:
          description: Rules within this condition group
          type: array
          items:
            $ref: '#/components/schemas/ConditionRuleDto'
        nextGroupOperator:
          enum:
          - AND
          - OR
          type: string
          description: Logical operator to connect to the next group (AND/OR)
      required:
      - rules
    AgentGraphCompleteDto:
      type: object
      properties:
        agentName:
          type: string
          description: The name of the agent to be created. This will be displayed in the UI and used to identify the agent
          example: Bitcoin Price Agent
        agentDescription:
          type: string
          description: A detailed description of what the agent does and its capabilities
          example: An AI agent that fetches real-time cryptocurrency prices and provides market insights
        settings:
          description: Configuration settings for the agent including personality, restrictions, and suggested prompts
          allOf:
          - $ref: '#/components/schemas/AgentSettingsDto'
        nodes:
          description: 'The complete list of nodes that make up the agent workflow graph. Nodes are connected by edges to form the execution flow. Must include at least one entry node (isEntryNode: true). Each node can have a tool configuration and is connected to other nodes via edges'
          type: array
          items:
            $ref: '#/components/schemas/CompleteAgentGraphNodeDto'
      required:
      - agentName
      - nodes
    CreateAgentGraphResponseDto:
      type: object
      properties:
        agentId:
          type: string
          description: UUID of the created agent
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          format: uuid
        agentName:
          type: string
          description: Name of the created agent
          example: My AI Agent
        activeGraphId:
          type: string
          description: UUID of the active/published graph
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          format: uuid
        draftGraphId:
          type: string
          description: UUID of the draft graph
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
          format: uuid
      required:
      - agentId
      - agentName
      - activeGraphId
      - draftGraphId
    NodeConfigurationsDto:
      type: object
      properties:
        conditionType:
          enum:
          - llm_based
          - rule_based
          type: string
          description: Type of condition evaluation (llm_based or rule_based)
          example: llm_based
        llmModel:
          type: string
          description: The LLM model to use for condition evaluation
          example: GPT40
        fallbackModels:
          type: string
          pattern: /^[^\s]*$/
          description: Comma-separated fallback models for condition evaluation
          example: GPT40,GPT4OMINI
        waitType:
          enum:
          - time_based
          - condition_based
          type: string
          description: Type of wait (time_based or condition_based)
          example: time_based
        timeToWaitValue:
          type: number
          description: The duration value to wait
          example: 5
        timeToWaitUnit:
          enum:
          - minutes
          - hours
          - days
          - months
          type: string
          description: The unit of time for the wait duration
          example: minutes
        linkedAgentGraphNodeId:
          type: string
          description: Custom id of the node linked to this node (e.g., source node for a variable-based loop, or the node a waiting node is linked to). The server resolves it to the persisted node id.
        rule:
          type: string
          description: Rule expression for condition-based waiting
        conditions:
          description: Condition groups for condition-based waiting
          type: array
          items:
            $ref: '#/components/schemas/AgentTriggerConfigurationFiltersGroup'
        timeoutType:
          enum:
          - no_timeout
          - set_timeout
          type: string
          description: Timeout type for the waiting node
          example: no_timeout
        timeoutValue:
          type: number
          description: Timeout duration value
        timeoutUnit:
          enum:
          - minutes
          - hours
          - days
          - months
          type: string
          description: The unit of time for the timeout duration
        onTimeout:
          enum:
          - continue
          - fail
          type: string
          description: Action to take when timeout is reached (continue or fail)
          example: continue
        iterationCount:
          type: number
          description: Number of iterations for a count-based loop (looping node only).
        linkedVariableId:
          type:
          - string
          - 'null'
          description: Output parameter to loop over for a variable-based loop (looping node only). Supply as "<sourceNodeCustomId>:<paramName>"; the server resolves it to the output param id.
          example: d2cbeb35-9110-426c-967a-c0dba38289a9:items
        alias:
          type: string
          description: Alias for nodes inside a looping node.
    CompleteAgentGraphNodeDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier (UUID). This ID is used to reference the node in edge connections (sourceAgentGraphNodeId/targetAgentGraphNodeId)
          example: d2cbeb35-9110-426c-967a-c0dba38289a9
        objective:
          type: string
          description: The goal or purpose of this node - what the AI should accomplish when it reaches this step. This is the main instruction for the node
          example: Fetch the current Bitcoin price and return it to the user in a friendly format
        evaluationCriteria:
          description: List of criteria used to evaluate if the node executed successfully. Each criterion is checked after node execution
          example:
          - The response contains a valid price number
          - The price is greater than 0
          type: array
          items:
            type: string
        isEntryNode:
          type: boolean
          description: When true, this is the starting node of the graph. The agent begins execution here. Each graph must have exactly one entry node
          example: true
        isExitNode:
          type: boolean
          description: When true, reaching this node ends the graph execution. A graph can have multiple exit nodes for different outcomes
          example: false
        nodeType:
          enum:
          - executionNode
          - conditionNode
          - waitingNode
          - entryNode
          - exitNode
          - loopingNode
          type: string
          description: The type of node (executionNode, conditionNode, entryNode, exitNode)
          example: executionNode
        nodeConfigurations:
          description: Configuration options for condition nodes (conditionType, llmModel)
          allOf:
          - $ref: '#/components/schemas/NodeConfigurationsDto'
        xCoordinate:
          type: number
          description: Horizontal position (in pixels) of the node in the visual graph editor UI
          example: 116
        yCoordinate:
          type: number
          description: Vertical position (in pixels) of the node in the visual graph editor UI
          example: 150
        isEvaluationEnabled:
          type: boolean
          description: When true, the node output is evaluated against the evaluationCriteria after each execution
          example: false
        isAttachmentDataPulledIn:
          type: boolean
          description: When true, any file attachments in the conversation are made available to this node during execution
          example: true
        onError:
          type: string
          description: 'Defines what happens when the node encounters an error. Options: "STOP" (halt execution), "CONTINUE" (proceed to next node)'
          example: STOP
        autoRetryWhenAccuracyLessThan:
          type: number
          description: When enableAutoRetryWhenAccuracyIsLow is true, the node will retry if the accuracy score falls below this threshold (0-100)
          example: 80
        autoRetryLimitWhenAccuracyIsLow:
          type: number
          description: Maximum number of retry attempts when the accuracy is below the threshold
          example: 1
        autoRetryCountWhenFailure:
          type: number
          description: Maximum number of retry attempts when the node execution fails with an error
          example: 1
        autoRetryWaitTimeWhenFailureInMs:
          type: number
          description: Time to wait (in milliseconds) between retry attempts after a failure
          example: 1000
        enableAutoRetryWhenAccuracyIsLow:
          type: boolean
          description: When true, automatically retry the node if the accuracy score is below autoRetryWhenAccuracyLessThan
          example: false
        enableAutoRetryWhenFailure:
          type: boolean
          description: When true, automatically retry the node if execution fails with an error
          example: false
        toolConfiguration:
          description: The tool configuration for this node. If the node needs to execute a specific tool (like calling an API), configure it here. Nodes without tools are handled by the AI directly
          allOf:
          - $ref: '#/components/schemas/CompleteAgentGraphNodeToolConfigurationDto'
        parentNodeId:
          type:
          - string
          - 'null'
          description: The customId of the parent loop node when this node is a child inside a loop. Used to associate loop body nodes with their parent loop.
          example: d2cbeb35-9110-426c-967a-c0dba38289a9
        childEdges:
          description: List of edges that go OUT from this node to other nodes. Each edge defines a possible path the agent can take after completing this node
          type: array
          items:
            $ref: '#/components/schemas/CompleteAgentGraphEdgeDto'
        parentEdges:
          description: List of edges that come IN to this node from other nodes. These represent the paths that lead to this node from previous steps
          type: array
          items:
            $ref: '#/components/schemas/CompleteAgentGraphEdgeDto'
      required:
      - id
      - objective
      - evaluationCriteria
      - isEntryNode
      - isExitNode
      - xCoordinate
      - yCoordinate
      - isEvaluationEnabled
      - isAttachmentDataPulledIn
      - onError
      - autoRetryWhenAccuracyLessThan
      - autoRetryLimitWhenAccuracyIsLow
      - autoRetryCountWhenFailure
      - autoRetryWaitTimeWhenFailureInMs
      - enableAutoRetryWhenAccuracyIsLow
      - enableAutoRetryWhenFailure
      - childEdges
      - parentEdges
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key