beam-ai-team/beam-api-reader

Beam API Reader

Complete reference for the Beam AI REST API — all endpoints, authentication, schemas, examples, and agent creation workflow.

Safety Contract

Use this skill as read-only API guidance by default. Before executing any example or script that creates tasks, uploads files, retries tasks, submits HITL decisions, updates graph nodes, publishes graphs, or creates agents, show the target workspace, endpoint, HTTP method, payload summary, and expected side effects. Require explicit user approval in the current turn. Reading docs, inspecting schemas, and drafting local request payloads do not require approval.

When to Use

• Look up Beam AI API endpoints and their parameters
• Understand authentication requirements for API calls
• Create, list, or inspect agent tasks via the API
• Build, update, or configure agents and workflows programmatically
• Create a new Beam agent from a YAML description
• Manage agent setup, views, context files, and tool optimization
• Connect via MCP (Model Context Protocol)

---

Base URLs

| Environment | Base URL | |-------------|----------| | Enterprise (Americana) | https://api.enterprise.beamstudio.ai | | Standard | https://api.beamstudio.ai | | BID (Dev) | https://api.bid.beamstudio.ai | | MCP Server | https://api.beamstudio.ai/mcp |

CRITICAL: Always use BEAM_API_URL from .env as the base URL. Do NOT hardcode api.beamlearning.io — it no longer resolves. Americana Foods workspace is on the enterprise instance (api.enterprise.beamstudio.ai). Using the wrong base URL returns a different agent with the same ID.

---

Authentication

All requests require:

| Header | Description | |--------|-------------| | x-api-key | Your Beam AI API key | | current-workspace-id | Your workspace identifier |

See authentication.md for setup details and code examples.

---

API Endpoints Summary

User

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v2/user/me | Get current authenticated user and workspaces |

Agents

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /agent | List agents in workspace (paginated, filterable) |

Agent Graph (Workflow)

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /agent-graphs/{agentId} | Get full agent workflow graph | | GET | /agent-graphs/{agentId}/nodes/lite | Get graph nodes (without tool config) | | GET | /agent-graphs/{agentId}/nodes/{nodeId} | Get detailed node information | | POST | /agent-graphs/complete | Create new agent with complete graph | | PUT | /agent-graphs/{agentId} | Update agent and its draft graph | | PATCH | /agent-graphs/update-node | Update a graph node | | PATCH | /agent-graphs/{graphId}/publish | Publish draft graph as active | | PATCH | /agent-graphs/{agentId}/nodes/{nodeId}/prompt | Update node tool prompt | | PATCH | /agent-graphs/{agentId}/nodes/{nodeId}/input-output-params | Update node I/O parameters | | POST | /agent-graphs/add-node | Add a new node to draft graph | | POST | /agent-graphs/add-edge | Add a new edge between nodes | | PUT | /agent-graphs/update-edge/{edgeId} | Update edge condition | | POST | /agent-graphs/test-node | Test a node in isolation | | GET | /agent-graphs/agent-task-nodes/{toolFunctionName} | Get task nodes by tool |

Tasks

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /agent-tasks | Create a new agent task | | GET | /agent-tasks | List tasks (paginated, filterable, groupable) | | GET | /agent-tasks/{taskId} | Get detailed task information | | GET | /agent-tasks/{taskId}/updates | Subscribe to real-time task updates (SSE) | | GET | /agent-tasks/iterate | Navigate through tasks (next/previous) | | POST | /agent-tasks/retry | Retry a failed task | | PATCH | /agent-tasks/execution/{taskId}/user-input | Submit user input for paused task | | POST | /agent-tasks/execution/{taskId}/user-consent | Approve task (HITL) | | POST | /agent-tasks/execution/{taskId}/rejection | Reject task (HITL) | | PATCH | /agent-tasks/execution/{taskId}/output-rating | Rate task output | | GET | /agent-tasks/analytics | Get agent analytics and metrics |

Agent Setup

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /agent-setup/upload | Upload context files during setup | | POST | /agent-setup/{agentId}/context-file | Add context files to existing agent | | POST | /agent-setup/agent-context/feedback | Submit context feedback | | GET | /agent-setup/session/{agentId} | Get setup session state | | POST | /agent-setup | Process setup steps (multi-step) |

Agent Views

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /agent-views | List all views | | GET | /agent-views/{viewId}/records | List records from a view | | GET | /agent-views/{viewId}/columns/{columnId}/links/{recordId} | List linked records |

Context Files

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /context/agent/{agentId}/file/{fileId}/download | Download a context file |

Tools, Optimization & Models

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /tool/active-tools | Search/list active tools (filter by type, keyword) | | GET | /custom-tool/preferred-models | Get list of available/preferred LLM models | | POST | /tool/optimize/{toolFunctionName} | Optimize tool performance | | POST | /tool/optimization-status/thread/{threadId} | Check optimization status |

---

Reference Documents

| Document | Contents | |----------|----------| | authentication.md | API key setup, headers, code examples | | user-endpoints.md | User profile and workspace endpoint | | agent-endpoints.md | Agent listing + all graph/workflow endpoints | | task-endpoints.md | Task CRUD, SSE, HITL, rating, analytics | | agent-setup-endpoints.md | Agent setup flow and configuration | | agent-views-endpoints.md | Structured data views and records | | tool-endpoints.md | Tool search, attach to node, optimization | | context-files-endpoints.md | Context file download | | mcp-connection.md | MCP server connection and available tools | | response-schemas.md | Common response objects and status codes |

---

Quick Example

import requests

API_KEY = "your-api-key"
WORKSPACE_ID = "your-workspace-id"
BASE_URL = os.getenv("BEAM_API_URL", "https://api.enterprise.beamstudio.ai")

headers = {
    "x-api-key": API_KEY,
    "current-workspace-id": WORKSPACE_ID,
    "Content-Type": "application/json"
}

# List agents
response = requests.get(f"{BASE_URL}/agent", headers=headers)
agents = response.json()

# Create a task
task_payload = {
    "agentId": "your-agent-id",
    "taskQuery": { "query": "Process this request" }
}
response = requests.post(f"{BASE_URL}/agent-tasks", headers=headers, json=task_payload)
task = response.json()

# Update a node prompt
prompt_payload = { "prompt": "Extract customer name and email." }
response = requests.patch(
    f"{BASE_URL}/agent-graphs/AGENT_ID/nodes/NODE_ID/prompt",
    headers=headers, json=prompt_payload
)

---

---

Create Agent from YAML

Deploy a new Beam agent from a YAML description using scripts/create_agent_from_prompt.py.

Key Rules

1. Entry node is always bare — no tool config, no params, no prompt. Objective = "Entry Node". If the YAML marks a processing node as is_entry: true, prepend a separate bare entry node and connect it to that processing node.
2. toolFunctionName is auto-generated by the script as GPTAction_Custom_{CamelCaseName} — never set manually.
3. Linked params use linked_node + linked_param in the spec. linked_node = the key of the source node (= YAML id value). YAML may call this field linked_node_id — remap it.
4. No UUIDs in the spec — the script generates all UUIDs.
5. on_error: "CONTINUE" only for non-critical nodes (e.g. Slack notifications). All others: "STOP".
6. Loop nodes (node_type: "loopingNode") must have ≥1 child. Children set parent_node: "<loop-key>"; the script resolves it to parentNodeId.

Spec Format

{
  "agentName": "string",
  "agentDescription": "string",
  "personality": "string",
  "restrictions": "string",
  "prompts": ["example prompt 1"],
  "nodes": [
    {
      "key": "entry",
      "objective": "Entry Node",
      "is_entry": true,
      "x": 250, "y": 0,
      "edges": [{ "target": "first-node-key", "name": "", "condition": "" }]
    },
    {
      "key": "node-key",
      "name": "Tool Display Name",
      "objective": "What this node does",
      "is_entry": false,
      "x": 250, "y": 200,
      "model": "BEDROCK_CLAUDE_SONNET_4",
      "tool_name": "Tool Display Name",
      "tool_description": "One-line description",
      "prompt": "Full LLM instruction prompt",
      "on_error": "STOP",
      "enable_retry": false,
      "retry_count": 1,
      "retry_wait_ms": 1000,
      "fallback_models": null,
      "evaluation_criteria": [],
      "input_params": [
        {
          "name": "param_name",
          "description": "what this param is",
          "type": "string|object|number|boolean",
          "is_array": false,
          "fill_type": "user_fill",
          "fill_type_options": "user_fill (default)|ai_fill|static|linked|from_memory",
          "static_value": null,
          "linked_node": null,
          "linked_param": null,
          "output_example": null,
          "required": true,
          "position": 0
        }
      ],
      "output_params": [
        {
          "name": "param_name",
          "description": "what this output contains",
          "type": "string|object|number|boolean",
          "is_array": false,
          "output_example": null,
          "position": 0
        }
      ],
      "edges": [{ "target": "next-key", "name": "Edge label", "condition": "" }]
    }
  ]
}

Positioning: entry at y=0, processing nodes at y=200, x increments by 300 per step. Models: BEDROCK_CLAUDE_SONNET_4 (default) or BEDROCK_CLAUDE_OPUS_4_5 (complex generation). Conditional edges: "condition": "" = unconditional; "condition": "sum is odd" = conditional branch.

Loop Nodes

A loop node (node_type: "loopingNode") has no toolConfiguration. Its children live alongside it in the top-level nodes[] array, but each child carries "parent_node": "<loop-key>" so the script sets parentNodeId to the loop's UUID.

Auto-assigned by the script — do not set manually:

• Loop objective is always "N: Loop" (1-based across all loops in the agent; first loop → "1: Loop", second → "2: Loop", …). Any objective you put on a loop is overwritten.
• Child nodes inside a loop get a numeric alias ("1", "2", "3", …) in the order they appear in the spec, stored on the child's nodeConfigurations.alias. The loop itself has no alias.

Rules:

• A loop must have at least one child (validated).
• Loops cannot be nested — a loopingNode cannot have parent_node set (validated).

{
  "key": "my-loop",
  "node_type": "loopingNode",
  "x": 250, "y": 200,
  "loop_config": {
    "iteration_count": 3,
    "linked_variable_node": null,
    "linked_variable_param": null
  },
  "edges": [{ "target": "after-loop", "name": "", "condition": "" }]
},
{
  "key": "loop-body",
  "name": "Process Item",
  "objective": "Process a single iteration",
  "parent_node": "my-loop",
  "x": 550, "y": 200,
  "tool_name": "Process Item",
  "prompt": "…",
  "input_params": [...],
  "output_params": [...],
  "edges": []
}

Use iteration_count for count-based loops, or linked_variable_node + linked_variable_param for variable-based loops (the script resolves these to linkedVariableId + linkedAgentGraphNodeId).

Workflow

Step 1: Parse YAML Extract agent metadata and all node definitions. Map YAML linked_node_id → spec linked_node.

Step 2: Build spec JSON

• Prepend a bare entry node connecting to the first processing node
• All processing nodes: is_entry: false
• Write to /tmp/beam_agent_spec.json

Step 3: Dry run

python3 scripts/create_agent_from_prompt.py --spec-file /tmp/beam_agent_spec.json --dry-run 2>&1 | head -30

Verify node names, input/output counts, and linked params look correct.

Step 4: Create agent

python3 scripts/create_agent_from_prompt.py --spec-file /tmp/beam_agent_spec.json

Report Agent ID and Draft Graph ID to the user.

Error Reference

| Error | Cause | Fix | |---|---|---| | Linked param 'node.param' not found | linked_node/linked_param typo | Check source node key and output param name match exactly | | API Error 400 | Malformed payload | Run --dry-run, inspect JSON | | API Error 401 | Bad API key | Check BEAM_API_KEY in .env | | Agent created but nodes empty | Wrong tool function prefix | Ensure tool_name is set on every non-entry node |

---

Related Skills

• beam-get-agent-analytics — Get agent performance metrics
• beam-get-task-details — Get details for a specific task
• beam-debug-issue-tasks — Debug failed tasks
• beam-retry-tasks — Retry failed tasks