List Agents - Beam Academy

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

current-workspace-id

string

required

Query Parameters

pageNum

number

Required range: x >= 1

pageSize

number

Required range: 1 <= x <= 1000000

type

enum<string>

Filter agents by type (beam-os, user-agent, pre-configured-agent)

Available options:

beam-os,

user-agent,

pre-configured-agent

Example:

"beam-os"

searchQuery

string

Search agents by name or description

Example:

"customer support"

agentCategoryId

string

Filter agents by category ID

Example:

"cat_123456"

Response

200 - application/json

List of agents retrieved successfully

agents

object[]

required

Array of agents available in the workspace

Show child attributes

agents.name

string

required

The display name of the agent

Example:

"Customer Support Agent"

agents.creatorId

string

required

The user ID who created this agent

Example:

"123e4567-e89b-12d3-a456-426614174001"

agents.type

enum<string>

required

The type of agent (beam-os, user-agent, or pre-configured-agent)

Available options:

beam-os,

user-agent,

pre-configured-agent

Example:

"beam-os"

agents.vectorDbId

string

required

The vector database ID used for this agent's knowledge base

Example:

"123e4567-e89b-12d3-a456-426614174002"

agents.category

object

required

Show child attributes

agents.category.title

string

required

The name or title of this agent category

Example:

"Customer Support"

agents.category.publish

boolean

required

Indicates whether this category is published and visible to users

Example:

true

agents.category.id

string

required

agents.category.createdAt

string<date-time>

required

agents.category.updatedAt

string<date-time>

required

agents.category.deletedAt

string<date-time>

agents.id

string

required

agents.createdAt

string<date-time>

required

agents.updatedAt

string<date-time>

required

agents.description

string

A detailed description of what this agent does and its capabilities

Example:

"This agent handles customer inquiries, support tickets, and provides automated responses"

agents.workspaceId

string

The workspace ID this agent belongs to

Example:

"123e4567-e89b-12d3-a456-426614174000"

agents.defaultTaskId

string

The default task template ID to use when starting new tasks with this agent

Example:

"task_template_001"

agents.themeIconUrl

string

URL to the agent's icon or avatar image

Example:

"https://example.com/icons/agent-icon.png"

agents.agentCategoryId

string

The category ID this agent belongs to for organization and filtering

Example:

"cat_customer_service"

agents.userAccessTokenId

string

The user access token ID for authentication in agent operations

Example:

"123e4567-e89b-12d3-a456-426614174003"

agents.agentSetupSessionId

string

The setup session ID used during agent configuration

Example:

"123e4567-e89b-12d3-a456-426614174004"

agents.agentIntroMessage

string

The introductory message displayed when users first interact with this agent

Example:

"Hello! I'm your customer support assistant. How can I help you today?"

agents.agentSetupMessage

string

The message displayed during agent setup to guide users through configuration

Example:

"Let's configure your agent to handle customer support tasks"

agents.skipAgentSetupSop

boolean

agents.deletedAt

string<date-time>

Example:

[]

count

number

required

Total number of agents matching the query

Example:

42

API Reference

Authorizations

Headers

Query Parameters

Response