Skip to main content
Welcome to the Beam AI API documentation. This API allows you to programmatically interact with the Beam platform to create, manage, and execute AI agents.

Base URL

All API requests should be made to:
https://api.beamstudio.ai

Authentication

The Beam AI API uses bearer token authentication. You’ll need to:
  1. Obtain an access token using your API key
  2. Include the token in the Authorization header of subsequent requests
  3. Include your current-workspace-id header for workspace-specific operations
Learn more in the Authentication section.

Quick Start

Here’s a simple example to get you started:
// 1. Get access token
const authResponse = await fetch('https://api.beamstudio.ai/auth/access-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ apiKey: 'your-api-key' })
});
const { accessToken } = await authResponse.json();

// 2. Create a task
const taskResponse = await fetch('https://api.beamstudio.ai/agent-tasks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'current-workspace-id': 'your-workspace-id',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agent_123456',
    input: { message: 'Hello, agent!' }
  })
});
const task = await taskResponse.json();

API Sections

Authentication

Manage access tokens and authentication for API requests.

Users

Retrieve information about authenticated users and their workspaces.

Agents

List and manage AI agents in your workspace.

Agent Graphs

Access agent workflow structures and configurations.

Agent Tasks

Create, monitor, and analyze agent task executions.

Error Handling

The API uses standard HTTP status codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 500 - Internal Server Error

Support

Need help with the API?

Changelog

Stay updated with the latest API changes in our Changelog.