AI Agents API Reference

The AI Agents API provides endpoints for creating and managing autonomous AI agents that react to board events in real-time. Agents can assist with tutoring, moderation, time management, and custom automation tasks.

Overview

AI Agents are autonomous programs that observe board activity and take actions based on configurable instructions:

Event-Driven: React to board events (object changes, participant actions, frame navigation)
Scheduled Actions: Execute periodic tasks (timers, reminders, notifications)
Scoped Operation: Limit agent activity to specific frames, participants, or object types
Budget Control: Set rate limits and token budgets to control costs
Stealth Mode: Operate invisibly without appearing as a participant

Key Concepts

Concept	Description
Persona	Agent role: `tutor`, `moderator`, `timer`, `facilitator`, `custom`
Instructions	Behavior definition: goals, rules, triggers, schedule
Triggers	Event-action mappings (e.g., when sticky note created → evaluate answer)
Scope	Restrictions: which frames, participants, object types the agent monitors
Status	Agent state: `active`, `paused`, `completed`, `error`
Visibility	How agent appears: `visible` (shows as participant), `stealth` (hidden)

Agent Capabilities

Action Type	Description
`create_object`	Create new objects on board (sticky notes, shapes, text)
`update_object`	Modify existing objects (edit text, change color)
`delete_object`	Remove objects from board
`move_objects`	Reposition objects (organize, group)
`send_notification`	Send messages to participants
`move_to_frame`	Navigate participants to specific frames
`evaluate_answer`	Assess student responses using AI
`generate_hint`	Create helpful hints for stuck students
`summarize`	Generate content summaries
`notify_teacher`	Alert teacher to important events

Authentication

All AI Agents API endpoints require API key authentication:

bash

curl -H "X-API-Key: your-api-key" \
  https://api.boardapi.io/api/v1/boards/:boardId/agents

API keys are passed via the X-API-Key header. Get your API key from the Developer Dashboard.

Base URL

https://api.boardapi.io/api/v1

For development:

http://localhost:4000/api/v1

Endpoints Overview

Method	Endpoint	Description
`POST`	`/boards/:boardId/agents`	Create a new agent
`GET`	`/boards/:boardId/agents`	List all agents for a board
`GET`	`/boards/:boardId/agents/:id`	Get a specific agent
`PATCH`	`/boards/:boardId/agents/:id`	Update agent configuration
`DELETE`	`/boards/:boardId/agents/:id`	Delete an agent
`POST`	`/boards/:boardId/agents/:id/pause`	Pause agent activity
`POST`	`/boards/:boardId/agents/:id/resume`	Resume paused agent
`POST`	`/boards/:boardId/agents/:id/reset`	Reset agent memory
`GET`	`/boards/:boardId/agents/:id/actions`	Get agent action log
`GET`	`/boards/:boardId/agents/:id/stats`	Get agent statistics
`GET`	`/agent-presets`	List available agent presets
`GET`	`/agent-presets/:persona`	Get a specific preset

Create Agent

Creates a new autonomous AI agent on a board with custom instructions and behavior.

Request

http

POST /boards/:boardId/agents
X-API-Key: your-api-key
Content-Type: application/json

{
  "name": "AI Tutor",
  "persona": "tutor",
  "instructions": {
    "description": "Helpful AI assistant for language learning",
    "goals": [
      "Help students understand vocabulary",
      "Provide hints without giving answers",
      "Encourage critical thinking"
    ],
    "rules": [
      "Never give direct answers",
      "Always be supportive and encouraging",
      "Respond only when student asks for help"
    ],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky-note' && object.data.needsHelp",
        "action": "generate_hint",
        "params": {
          "style": "socratic"
        }
      }
    ]
  },
  "scope": {
    "frames": ["frame-uuid-1"],
    "objectTypes": ["sticky-note", "text"]
  },
  "maxActionsPerMinute": 10,
  "budgetTokens": 50000,
  "priority": 5,
  "visibility": "visible",
  "scanExisting": false
}

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID

Request Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Agent display name (max 100 characters)
`persona`	string	Yes	Agent role: `tutor`, `moderator`, `timer`, `facilitator`, `custom`
`instructions`	object	Yes	Agent behavior definition (see Instructions Schema)
`scope`	object	No	Operational restrictions (frames, participants, object types)
`maxActionsPerMinute`	number	No	Rate limit (default: 10, range: 1-60)
`budgetTokens`	number	No	Token budget limit (null = unlimited)
`priority`	number	No	Agent priority (default: 5, range: 1-10)
`visibility`	string	No	`visible` or `stealth` (default: `visible`)
`scanExisting`	boolean	No	Process existing board content on creation (default: false)

Instructions Schema

json

{
  "description": "Agent purpose and role",
  "goals": ["Goal 1", "Goal 2"],
  "rules": ["Rule 1", "Rule 2"],
  "triggers": [
    {
      "event": "object:created",
      "condition": "object.type === 'sticky-note'",
      "action": "evaluate_answer",
      "params": {},
      "allowSelfEvents": false
    }
  ],
  "schedule": [
    {
      "at": "every:5min",
      "action": "send_notification",
      "params": {
        "message": "5 minutes remaining"
      }
    }
  ]
}

Trigger Events

Event	Fires When
`object:created`	New object added to board
`object:updated`	Existing object modified
`object:deleted`	Object removed from board
`participant:joined`	User joins board
`participant:left`	User leaves board
`participant:idle`	User inactive for threshold time
`frame:entered`	Participant enters frame
`frame:left`	Participant leaves frame
`timer:tick`	Periodic timer event
`schedule:trigger`	Scheduled action fires

Schedule Syntax

Pattern	Description
`every:5min`	Every 5 minutes
`every:30sec`	Every 30 seconds
`every:1hour`	Every hour
`at:09:00`	At specific time (UTC)
`cron:/5 * * *`	Custom cron expression

Response

Status Code: 201 Created

json

{
  "id": "agent-uuid-123",
  "boardUuid": "board-uuid-456",
  "name": "AI Tutor",
  "persona": "tutor",
  "status": "active",
  "instructions": {
    "description": "Helpful AI assistant for language learning",
    "goals": ["Help students understand vocabulary"],
    "rules": ["Never give direct answers"],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky-note'",
        "action": "generate_hint"
      }
    ]
  },
  "scope": {
    "frames": ["frame-uuid-1"],
    "objectTypes": ["sticky-note", "text"]
  },
  "priority": 5,
  "visibility": "visible",
  "isThinking": false,
  "maxActionsPerMinute": 10,
  "budgetTokens": 50000,
  "spentTokens": 0,
  "stats": {
    "actionsCount": 0,
    "tokensSpent": 0,
    "lastActionAt": null
  },
  "createdAt": "2025-11-28T10:00:00Z",
  "createdBy": "user-uuid-789"
}

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'AI Tutor',
      persona: 'tutor',
      instructions: {
        description: 'Helpful AI assistant',
        goals: ['Help students'],
        rules: ['Be encouraging'],
        triggers: [
          {
            event: 'object:created',
            condition: "object.type === 'sticky-note'",
            action: 'evaluate_answer'
          }
        ]
      },
      maxActionsPerMinute: 10,
      budgetTokens: 50000
    })
  }
);

const agent = await response.json();
console.log(`Agent created: ${agent.id}`);

cURL:

bash

curl -X POST https://api.boardapi.io/api/v1/boards/board-uuid-456/agents \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Tutor",
    "persona": "tutor",
    "instructions": {
      "description": "Helpful AI assistant",
      "goals": ["Help students"],
      "rules": ["Be encouraging"],
      "triggers": [
        {
          "event": "object:created",
          "condition": "object.type === \"sticky-note\"",
          "action": "evaluate_answer"
        }
      ]
    },
    "maxActionsPerMinute": 10,
    "budgetTokens": 50000
  }'

PHP:

php

<?php
$ch = curl_init('https://api.boardapi.io/api/v1/boards/board-uuid-456/agents');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: your-api-key',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'AI Tutor',
        'persona' => 'tutor',
        'instructions' => [
            'description' => 'Helpful AI assistant',
            'goals' => ['Help students'],
            'rules' => ['Be encouraging'],
            'triggers' => [
                [
                    'event' => 'object:created',
                    'condition' => 'object.type === "sticky-note"',
                    'action' => 'evaluate_answer'
                ]
            ]
        ],
        'maxActionsPerMinute' => 10,
        'budgetTokens' => 50000
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$agent = json_decode(curl_exec($ch), true);
echo "Agent created: {$agent['id']}\n";

Use Cases

Create AI tutors for educational boards
Add moderation agents to detect inappropriate content
Set up timer agents for timed activities
Build custom automation workflows

Possible Errors

Status Code	Error	Description
`400`	`Bad Request`	Invalid agent data (missing required fields, invalid triggers)
`404`	`Not Found`	Board does not exist
`401`	`Unauthorized`	Invalid or missing API key

List All Agents

Retrieves all agents on a board with their current status and statistics.

Request

http

GET /boards/:boardId/agents
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID

Response

Status Code: 200 OK

json

[
  {
    "id": "agent-uuid-123",
    "boardUuid": "board-uuid-456",
    "name": "AI Tutor",
    "persona": "tutor",
    "status": "active",
    "priority": 5,
    "visibility": "visible",
    "isThinking": false,
    "maxActionsPerMinute": 10,
    "budgetTokens": 50000,
    "spentTokens": 1250,
    "stats": {
      "actionsCount": 15,
      "tokensSpent": 1250,
      "lastActionAt": "2025-11-28T10:30:00Z"
    },
    "createdAt": "2025-11-28T10:00:00Z",
    "createdBy": "user-uuid-789"
  },
  {
    "id": "agent-uuid-456",
    "boardUuid": "board-uuid-456",
    "name": "Timer Bot",
    "persona": "timer",
    "status": "active",
    "priority": 3,
    "visibility": "visible",
    "isThinking": false,
    "maxActionsPerMinute": 5,
    "budgetTokens": null,
    "spentTokens": 0,
    "stats": {
      "actionsCount": 6,
      "tokensSpent": 0,
      "lastActionAt": "2025-11-28T10:25:00Z"
    },
    "createdAt": "2025-11-28T10:05:00Z",
    "createdBy": "user-uuid-789"
  }
]

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const agents = await response.json();
console.log(`Total agents: ${agents.length}`);

agents.forEach(agent => {
  console.log(`- ${agent.name} (${agent.status}): ${agent.stats.actionsCount} actions`);
});

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents'

PHP:

php

<?php
$headers = ['X-API-Key: your-api-key'];
$agents = json_decode(
  file_get_contents(
    'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents',
    false,
    stream_context_create(['http' => ['header' => implode("\r\n", $headers)]])
  ),
  true
);

foreach ($agents as $agent) {
    echo "{$agent['name']} ({$agent['status']}): {$agent['stats']['actionsCount']} actions\n";
}

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Board does not exist
`401`	`Unauthorized`	Invalid API key

Get Agent

Retrieves details of a specific agent including its current state and configuration.

Request

http

GET /boards/:boardId/agents/:id
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Response

Status Code: 200 OK

json

{
  "id": "agent-uuid-123",
  "boardUuid": "board-uuid-456",
  "name": "AI Tutor",
  "persona": "tutor",
  "status": "active",
  "instructions": {
    "description": "Helpful AI assistant for language learning",
    "goals": ["Help students understand vocabulary"],
    "rules": ["Never give direct answers"],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky-note'",
        "action": "generate_hint"
      }
    ]
  },
  "scope": {
    "frames": ["frame-uuid-1"],
    "objectTypes": ["sticky-note", "text"]
  },
  "priority": 5,
  "visibility": "visible",
  "isThinking": false,
  "maxActionsPerMinute": 10,
  "budgetTokens": 50000,
  "spentTokens": 1250,
  "stats": {
    "actionsCount": 15,
    "tokensSpent": 1250,
    "lastActionAt": "2025-11-28T10:30:00Z"
  },
  "createdAt": "2025-11-28T10:00:00Z",
  "createdBy": "user-uuid-789"
}

Example Requests

JavaScript/TypeScript:

javascript

const agentId = 'agent-uuid-123';
const response = await fetch(
  `https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/${agentId}`,
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const agent = await response.json();
console.log(`Agent: ${agent.name}`);
console.log(`Status: ${agent.status}`);
console.log(`Actions: ${agent.stats.actionsCount}`);
console.log(`Tokens spent: ${agent.spentTokens}/${agent.budgetTokens}`);

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123'

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Update Agent

Updates agent configuration such as instructions, scope, or rate limits.

Request

http

PATCH /boards/:boardId/agents/:id
X-API-Key: your-api-key
Content-Type: application/json

{
  "name": "AI Tutor v2",
  "instructions": {
    "description": "Enhanced AI assistant",
    "goals": ["Help students", "Track progress"],
    "rules": ["Be encouraging", "Provide hints only"],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky-note'",
        "action": "evaluate_answer"
      }
    ]
  },
  "maxActionsPerMinute": 15,
  "budgetTokens": 100000
}

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Request Body Parameters

All fields are optional. Only provided fields will be updated.

Parameter	Type	Description
`name`	string	New agent name (max 100 characters)
`instructions`	object	Updated behavior definition
`scope`	object	New operational restrictions
`maxActionsPerMinute`	number	New rate limit (range: 1-60)
`budgetTokens`	number	New token budget (null = unlimited)
`priority`	number	New priority (range: 1-10)

Response

Status Code: 200 OK

json

{
  "id": "agent-uuid-123",
  "boardUuid": "board-uuid-456",
  "name": "AI Tutor v2",
  "persona": "tutor",
  "status": "active",
  "instructions": {
    "description": "Enhanced AI assistant",
    "goals": ["Help students", "Track progress"],
    "rules": ["Be encouraging", "Provide hints only"],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky-note'",
        "action": "evaluate_answer"
      }
    ]
  },
  "maxActionsPerMinute": 15,
  "budgetTokens": 100000,
  "spentTokens": 1250,
  "stats": {
    "actionsCount": 15,
    "tokensSpent": 1250,
    "lastActionAt": "2025-11-28T10:30:00Z"
  },
  "createdAt": "2025-11-28T10:00:00Z",
  "createdBy": "user-uuid-789"
}

Example Requests

JavaScript/TypeScript:

javascript

// Increase rate limit
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      maxActionsPerMinute: 20,
      budgetTokens: 100000
    })
  }
);

const updated = await response.json();
console.log(`Updated: ${updated.name}`);

cURL:

bash

curl -X PATCH https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "maxActionsPerMinute": 20,
    "budgetTokens": 100000
  }'

Possible Errors

Status Code	Error	Description
`400`	`Bad Request`	Invalid update data
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Delete Agent

Permanently removes an agent and its action history.

Request

http

DELETE /boards/:boardId/agents/:id
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Response

Status Code: 204 No Content

No response body is returned on success.

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123',
  {
    method: 'DELETE',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

if (response.status === 204) {
  console.log('Agent deleted successfully');
}

cURL:

bash

curl -X DELETE \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123'

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Pause Agent

Stops the agent from reacting to new events. Agent remains on the board but inactive.

Request

http

POST /boards/:boardId/agents/:id/pause
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Response

Status Code: 200 OK

json

{
  "id": "agent-uuid-123",
  "boardUuid": "board-uuid-456",
  "name": "AI Tutor",
  "persona": "tutor",
  "status": "paused",
  "isThinking": false,
  "stats": {
    "actionsCount": 15,
    "tokensSpent": 1250,
    "lastActionAt": "2025-11-28T10:30:00Z"
  },
  "createdAt": "2025-11-28T10:00:00Z",
  "createdBy": "user-uuid-789"
}

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/pause',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const agent = await response.json();
console.log(`Agent ${agent.name} is now ${agent.status}`);

cURL:

bash

curl -X POST \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/pause'

Use Cases

Pause agent during group discussion
Temporarily disable agent for teacher intervention
Stop agent when activity changes

Possible Errors

Status Code	Error	Description
`400`	`Bad Request`	Agent is already paused
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Resume Agent

Resumes a paused agent, allowing it to react to events again.

Request

http

POST /boards/:boardId/agents/:id/resume
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Response

Status Code: 200 OK

json

{
  "id": "agent-uuid-123",
  "boardUuid": "board-uuid-456",
  "name": "AI Tutor",
  "persona": "tutor",
  "status": "active",
  "isThinking": false,
  "stats": {
    "actionsCount": 15,
    "tokensSpent": 1250,
    "lastActionAt": "2025-11-28T10:30:00Z"
  },
  "createdAt": "2025-11-28T10:00:00Z",
  "createdBy": "user-uuid-789"
}

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/resume',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const agent = await response.json();
console.log(`Agent ${agent.name} resumed`);

cURL:

bash

curl -X POST \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/resume'

Possible Errors

Status Code	Error	Description
`400`	`Bad Request`	Agent is not paused
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Reset Agent Memory

Clears the agent's working memory (context between events). Instructions and configuration remain unchanged.

Request

http

POST /boards/:boardId/agents/:id/reset
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Response

Status Code: 200 OK

json

{
  "id": "agent-uuid-123",
  "boardUuid": "board-uuid-456",
  "name": "AI Tutor",
  "persona": "tutor",
  "status": "active",
  "isThinking": false,
  "stats": {
    "actionsCount": 15,
    "tokensSpent": 1250,
    "lastActionAt": "2025-11-28T10:30:00Z"
  },
  "createdAt": "2025-11-28T10:00:00Z",
  "createdBy": "user-uuid-789"
}

Example Requests

JavaScript/TypeScript:

javascript

// Reset agent memory for new activity
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/reset',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const agent = await response.json();
console.log('Agent memory reset');

cURL:

bash

curl -X POST \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/reset'

Use Cases

Clear agent context when starting new activity
Reset agent state after error
Force agent to re-evaluate situation

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Get Agent Action Log

Retrieves the history of all actions performed by the agent.

Request

http

GET /boards/:boardId/agents/:id/actions?limit=50&offset=0
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Query Parameters

Parameter	Type	Required	Description
`limit`	number	No	Maximum actions to return (default: 50)
`offset`	number	No	Number of actions to skip (default: 0)

Response

Status Code: 200 OK

json

[
  {
    "id": "action-uuid-1",
    "agentId": "agent-uuid-123",
    "triggerEventType": "object:created",
    "triggerEventData": {
      "objectId": "obj-123",
      "type": "sticky-note",
      "data": {
        "text": "What is photosynthesis?"
      }
    },
    "shouldAct": true,
    "reasoning": "Student asked a question about photosynthesis. Should provide a hint.",
    "actionType": "generate_hint",
    "actionParams": {
      "style": "socratic",
      "targetObjectId": "obj-123"
    },
    "success": true,
    "result": {
      "hintObjectId": "obj-456",
      "hintText": "Think about how plants get energy from sunlight..."
    },
    "errorMessage": null,
    "tokensUsed": 85,
    "latencyMs": 1250,
    "createdAt": "2025-11-28T10:30:15Z"
  },
  {
    "id": "action-uuid-2",
    "agentId": "agent-uuid-123",
    "triggerEventType": "participant:idle",
    "triggerEventData": {
      "participantId": "user-789",
      "idleDurationMs": 300000
    },
    "shouldAct": true,
    "reasoning": "Student has been idle for 5 minutes. Send gentle reminder.",
    "actionType": "send_notification",
    "actionParams": {
      "message": "Need any help? Feel free to ask!",
      "participantId": "user-789"
    },
    "success": true,
    "result": {
      "notificationSent": true
    },
    "errorMessage": null,
    "tokensUsed": 42,
    "latencyMs": 850,
    "createdAt": "2025-11-28T10:25:00Z"
  }
]

Response Fields

Field	Type	Description
`id`	string	Action log entry UUID
`agentId`	string	Agent UUID
`triggerEventType`	string	Event that triggered this action
`triggerEventData`	object	Event payload data
`shouldAct`	boolean	Whether agent decided to act
`reasoning`	string	Agent's reasoning for decision
`actionType`	string	Type of action performed
`actionParams`	object	Action parameters
`success`	boolean	Whether action completed successfully
`result`	object	Action result data
`errorMessage`	string	Error details (if failed)
`tokensUsed`	number	LLM tokens consumed
`latencyMs`	number	Action execution time
`createdAt`	string	ISO 8601 timestamp

Example Requests

JavaScript/TypeScript:

javascript

// Get last 100 actions
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/actions?limit=100',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const actions = await response.json();
console.log(`Total actions: ${actions.length}`);

// Analyze action success rate
const successful = actions.filter(a => a.success).length;
console.log(`Success rate: ${(successful / actions.length * 100).toFixed(1)}%`);

cURL:

bash

# Get last 50 actions
curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/actions?limit=50'

Use Cases

Debug agent behavior
Analyze action patterns
Monitor token usage per action
Track agent performance

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

Get Agent Statistics

Returns aggregate statistics about the agent's activity.

Request

http

GET /boards/:boardId/agents/:id/stats
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`boardId`	string	Board UUID
`id`	string	Agent UUID

Response

Status Code: 200 OK

json

{
  "actionsCount": 47,
  "tokensSpent": 3850,
  "lastActionAt": "2025-11-28T10:45:30Z",
  "successRate": 0.957,
  "averageLatencyMs": 1120,
  "actionsByType": {
    "generate_hint": 18,
    "evaluate_answer": 12,
    "send_notification": 10,
    "create_object": 7
  },
  "budgetRemaining": 46150,
  "budgetPercentUsed": 7.7
}

Response Fields

Field	Type	Description
`actionsCount`	number	Total actions performed
`tokensSpent`	number	Total LLM tokens consumed
`lastActionAt`	string	ISO 8601 timestamp of last action
`successRate`	number	Percentage of successful actions (0-1)
`averageLatencyMs`	number	Average action execution time
`actionsByType`	object	Breakdown of actions by type
`budgetRemaining`	number	Remaining token budget (if set)
`budgetPercentUsed`	number	Budget utilization percentage

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/stats',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const stats = await response.json();
console.log(`Agent stats:`);
console.log(`- Total actions: ${stats.actionsCount}`);
console.log(`- Tokens spent: ${stats.tokensSpent}`);
console.log(`- Success rate: ${(stats.successRate * 100).toFixed(1)}%`);
console.log(`- Budget used: ${stats.budgetPercentUsed.toFixed(1)}%`);

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/stats'

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Agent or board not found
`401`	`Unauthorized`	Invalid API key

List Agent Presets

Retrieves available predefined agent personas with default configurations.

Request

http

GET /agent-presets
X-API-Key: your-api-key

Response

Status Code: 200 OK

json

[
  {
    "id": "preset-uuid-1",
    "name": "AI Tutor",
    "persona": "tutor",
    "description": "Helpful AI assistant that provides hints and guidance without giving direct answers",
    "avatarUrl": "https://cdn.boardapi.io/avatars/tutor.png",
    "defaultInstructions": {
      "description": "AI tutor for educational boards",
      "goals": [
        "Help students understand concepts",
        "Provide hints without giving answers",
        "Encourage critical thinking"
      ],
      "rules": [
        "Never give direct answers",
        "Always be supportive",
        "Adapt to student level"
      ],
      "triggers": [
        {
          "event": "object:created",
          "condition": "object.data.needsHelp === true",
          "action": "generate_hint"
        }
      ]
    },
    "configurableFields": ["scope", "maxActionsPerMinute", "budgetTokens"],
    "category": "education",
    "isActive": true,
    "createdAt": "2025-11-01T00:00:00Z"
  },
  {
    "id": "preset-uuid-2",
    "name": "Moderator Bot",
    "persona": "moderator",
    "description": "Monitors board activity and enforces rules",
    "avatarUrl": "https://cdn.boardapi.io/avatars/moderator.png",
    "defaultInstructions": {
      "description": "Content moderation agent",
      "goals": [
        "Maintain respectful environment",
        "Detect inappropriate content",
        "Alert teacher to issues"
      ],
      "rules": [
        "Flag offensive content",
        "Be impartial",
        "Escalate serious issues"
      ],
      "triggers": [
        {
          "event": "object:created",
          "action": "evaluate_content"
        }
      ]
    },
    "configurableFields": ["scope"],
    "category": "moderation",
    "isActive": true,
    "createdAt": "2025-11-01T00:00:00Z"
  }
]

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/agent-presets',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const presets = await response.json();
console.log('Available agent presets:');
presets.forEach(preset => {
  console.log(`- ${preset.name} (${preset.persona}): ${preset.description}`);
});

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/agent-presets'

Use Cases

Display preset selector in UI
Quick-start agent creation
Discover available agent types

Possible Errors

Status Code	Error	Description
`401`	`Unauthorized`	Invalid API key

Get Agent Preset

Retrieves details of a specific agent preset including default instructions.

Request

http

GET /agent-presets/:persona
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`persona`	string	Preset identifier (e.g., `tutor`, `moderator`)

Response

Status Code: 200 OK

json

{
  "id": "preset-uuid-1",
  "name": "AI Tutor",
  "persona": "tutor",
  "description": "Helpful AI assistant that provides hints and guidance without giving direct answers",
  "avatarUrl": "https://cdn.boardapi.io/avatars/tutor.png",
  "defaultInstructions": {
    "description": "AI tutor for educational boards",
    "goals": [
      "Help students understand concepts",
      "Provide hints without giving answers",
      "Encourage critical thinking"
    ],
    "rules": [
      "Never give direct answers",
      "Always be supportive",
      "Adapt to student level"
    ],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.data.needsHelp === true",
        "action": "generate_hint"
      }
    ]
  },
  "configurableFields": ["scope", "maxActionsPerMinute", "budgetTokens"],
  "category": "education",
  "isActive": true,
  "createdAt": "2025-11-01T00:00:00Z"
}

Example Requests

JavaScript/TypeScript:

javascript

// Get tutor preset and create agent from it
const preset = await fetch(
  'https://api.boardapi.io/api/v1/agent-presets/tutor',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
).then(r => r.json());

// Create agent using preset instructions
const agent = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: preset.name,
      persona: preset.persona,
      instructions: preset.defaultInstructions,
      maxActionsPerMinute: 10
    })
  }
).then(r => r.json());

console.log(`Created ${agent.name} from preset`);

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/agent-presets/tutor'

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Preset not found
`401`	`Unauthorized`	Invalid API key

Response Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Agent created successfully
`204`	No Content	Agent deleted successfully
`400`	Bad Request	Invalid agent data or parameters
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Agent, board, or preset not found
`500`	Internal Server Error	Server error occurred

Common Use Cases

Create a Tutor Agent

javascript

// Create AI tutor that helps with vocabulary
const tutor = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Vocabulary Helper',
      persona: 'tutor',
      instructions: {
        description: 'Helps students learn new vocabulary',
        goals: [
          'Provide contextual hints',
          'Explain word usage',
          'Encourage practice'
        ],
        rules: [
          'Never translate directly',
          'Give examples in sentences',
          'Be patient and encouraging'
        ],
        triggers: [
          {
            event: 'object:created',
            condition: "object.type === 'sticky-note' && object.data.needsHelp",
            action: 'generate_hint',
            params: {
              hintType: 'contextual'
            }
          }
        ]
      },
      scope: {
        frames: ['vocabulary-frame-uuid'],
        objectTypes: ['sticky-note']
      },
      maxActionsPerMinute: 15,
      budgetTokens: 100000
    })
  }
).then(r => r.json());

console.log(`Created tutor: ${tutor.id}`);

Create a Timer Agent

javascript

// Create timer that sends periodic reminders
const timer = await fetch(
  'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Activity Timer',
      persona: 'timer',
      instructions: {
        description: 'Countdown timer for timed activities',
        goals: ['Track time', 'Send reminders'],
        rules: ['Be concise', 'Show time remaining'],
        triggers: [],
        schedule: [
          {
            at: 'every:5min',
            action: 'send_notification',
            params: {
              message: '5 minutes elapsed'
            }
          },
          {
            at: 'every:1min',
            action: 'update_object',
            params: {
              objectId: 'timer-display',
              updateType: 'decrement'
            }
          }
        ]
      },
      visibility: 'visible',
      maxActionsPerMinute: 5
    })
  }
).then(r => r.json());

console.log(`Timer started: ${timer.id}`);

Monitor Agent Performance

javascript

// Periodically check agent stats
setInterval(async () => {
  const stats = await fetch(
    'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/stats',
    {
      headers: {
        'X-API-Key': 'your-api-key'
      }
    }
  ).then(r => r.json());

  console.log(`Agent stats:`);
  console.log(`- Actions: ${stats.actionsCount}`);
  console.log(`- Tokens: ${stats.tokensSpent}/${stats.budgetRemaining + stats.tokensSpent}`);
  console.log(`- Success: ${(stats.successRate * 100).toFixed(1)}%`);

  // Pause agent if budget nearly exhausted
  if (stats.budgetPercentUsed > 90) {
    await fetch(
      'https://api.boardapi.io/api/v1/boards/board-uuid-456/agents/agent-uuid-123/pause',
      {
        method: 'POST',
        headers: {
          'X-API-Key': 'your-api-key'
        }
      }
    );
    console.log('Agent paused: budget nearly exhausted');
  }
}, 60000); // Check every minute

Next Steps

WebSocket Events - Real-time agent communication
Board API - Parent board operations
Frames API - Frame-scoped agents
Integration Guide - Complete examples

AI Agents API Reference ​

Overview ​

Key Concepts ​

Agent Capabilities ​

Authentication ​

Base URL ​

Endpoints Overview ​

Create Agent ​

Request ​

URL Parameters ​

Request Body Parameters ​

Instructions Schema ​

Trigger Events ​

Schedule Syntax ​

Response ​

Example Requests ​

Use Cases ​

Possible Errors ​

List All Agents ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Get Agent ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Update Agent ​

Request ​

URL Parameters ​

Request Body Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Delete Agent ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Pause Agent ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Use Cases ​

Possible Errors ​

Resume Agent ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Reset Agent Memory ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Use Cases ​

Possible Errors ​

Get Agent Action Log ​

Request ​

URL Parameters ​

Query Parameters ​

Response ​

Response Fields ​

Example Requests ​

Use Cases ​

Possible Errors ​

Get Agent Statistics ​

Request ​

URL Parameters ​

Response ​

Response Fields ​

Example Requests ​

Possible Errors ​

List Agent Presets ​

AI Agents API Reference

Overview

Key Concepts

Agent Capabilities

Authentication

Base URL

Endpoints Overview

Create Agent

Request

URL Parameters

Request Body Parameters

Instructions Schema

Trigger Events

Schedule Syntax

Response

Example Requests

Use Cases

Possible Errors

List All Agents

Request

URL Parameters

Response

Example Requests

Possible Errors

Get Agent

Request

URL Parameters

Response

Example Requests

Possible Errors

Update Agent

Request

URL Parameters

Request Body Parameters

Response

Example Requests

Possible Errors

Delete Agent

Request

URL Parameters

Response

Example Requests

Possible Errors

Pause Agent

Request

URL Parameters

Response

Example Requests

Use Cases

Possible Errors

Resume Agent

Request

URL Parameters

Response

Example Requests

Possible Errors

Reset Agent Memory

Request

URL Parameters

Response

Example Requests

Use Cases

Possible Errors

Get Agent Action Log

Request

URL Parameters

Query Parameters

Response

Response Fields

Example Requests

Use Cases

Possible Errors

Get Agent Statistics

Request

URL Parameters

Response

Response Fields

Example Requests

Possible Errors

List Agent Presets