Skip to main content

​
Tasks API

POST /agent-tasks
Create a new task session to execute an agent with specified inputs and configuration.

​
Headers

​
x-api-key
string
required
Your API key for authentication
​
current-workspace-id
string
required
Your workspace ID

​
Request Body

​
agentId
string
required
The unique identifier of the agent to execute
​
input
object
required
Input data for the agent. Structure depends on the agent’s configuration.
​
mode
string
Execution mode: “auto” or “manual”. Default is “auto”.
​
webhookUrl
string
Optional webhook URL to receive task completion notifications

​
Response

​
id
string
Unique identifier for the created task
​
agentId
string
ID of the agent being executed
​
status
string
Current status of the task (e.g., “pending”, “running”, “completed”, “failed”)
​
url
string
URL to view the task execution in the Beam platform
​
createdAt
string
ISO 8601 timestamp of when the task was created

​
Example Request

curl -X POST https://api.beamstudio.ai/agent-tasks \
  -H "x-api-key: your-api-key" \
  -H "current-workspace-id: your-workspace-id" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123456",
    "input": {
      "customerEmail": "customer@example.com",
      "issueType": "billing"
    },
    "mode": "auto"
  }'

​
Example Response

{
  "id": "task_abc123",
  "agentId": "agent_123456",
  "status": "pending",
  "url": "https://app.beam.ai/tasks/task_abc123",
  "createdAt": "2024-03-21T10:30:00Z"
}

​
Task Execution Modes

​
Auto Mode

In auto mode, the agent executes all steps automatically without requiring user intervention for decisions or approvals.

​
Manual Mode

In manual mode, the agent will pause at decision points and wait for user input before proceeding to the next step.

​
Webhooks

You can provide a webhook URL to receive notifications when the task completes. The webhook will receive a POST request with the task details and results. 
{
  "taskId": "task_abc123",
  "agentId": "agent_123456",
  "status": "completed",
  "result": {
    // Task output data
  },
  "completedAt": "2024-03-21T10:35:00Z"
}