AI Generation

Generate contextually relevant board objects automatically using natural language prompts. The AI analyzes your board's existing content and creates new objects that match your theme, style, and requirements.

Feature Availability

AI Generation is available on Professional tier and above:

• Starter: Not available
• Professional: 50 requests/month
• Business: 200 requests/month
• Enterprise: 1000 requests/month

See Pricing for details.

Overview

AI Generation enables you to create board objects using simple prompts like "Create 10 task cards for project planning" or "Generate team org chart nodes". The system:

• Analyzes board context to understand existing themes and patterns
• Generates structured content matching your custom object type schemas
• Positions objects smartly to avoid collisions with existing content
• Maintains consistency by building upon your board's current state

Key Benefits

Benefit	Description
Context-Aware	Analyzes up to 50 existing objects to maintain thematic consistency
Smart Positioning	Automatically finds free space and arranges objects in grids or layouts
Custom Object Support	Works with your registered custom object types and schemas
Quota Management	Integrated with tier-based quotas and usage tracking
Fast Generation	Typical response time: 3-8 seconds for 10 objects

How It Works

1. Context Analysis

When you enable context analysis (use_board_context: true), the AI examines your board:

┌─────────────────────────────────────────────────┐
│          AI GENERATION WORKFLOW                 │
├─────────────────────────────────────────────────┤
│                                                  │
│  Your Prompt                                    │
│  "Create 10 vocabulary cards about animals"     │
│       │                                          │
│       ├─► Context Analysis                      │
│       │   • Scans 50 most recent objects        │
│       │   • Detects themes (food, animals...)   │
│       │   • Analyzes difficulty level            │
│       │   • Identifies object types used         │
│       │                                          │
│       ├─► Content Generation                    │
│       │   • GPT creates objects matching theme   │
│       │   • Follows your custom object schemas   │
│       │   • Maintains difficulty progression     │
│       │                                          │
│       ├─► Smart Positioning                     │
│       │   • Detects existing object bounds       │
│       │   • Finds free space (auto/below/right)  │
│       │   • Arranges in grid layout              │
│       │   • Validates no collisions              │
│       │                                          │
│       └─► Objects Created on Board              │
│                                                  │
└─────────────────────────────────────────────────┘

2. Theme Detection

The AI identifies up to 10 common themes in your existing content across EdTech, SaaS, and Business contexts:

Category	Theme	Example Keywords
EdTech	Food	apple, banana, restaurant, eat, drink
	Animals	cat, dog, bird, fish, elephant
	School	teacher, student, book, homework
	Travel	airport, hotel, ticket, journey
SaaS	Development	code, bug, feature, sprint, deploy
	Project Management	task, deadline, milestone, kanban, backlog
	Product	roadmap, release, version, feedback
Business	Organization	CEO, manager, department, team, structure
	Finance	budget, revenue, profit, invoice, sales
	Marketing	campaign, customer, lead, conversion, brand

When you prompt "Add 5 more items", the AI continues the detected theme automatically.

3. Difficulty Progression

The AI analyzes object count to estimate difficulty level:

Object Count → Difficulty Level
0 objects    → 'none'
1-4 objects  → 'beginner'
5-14 objects → 'intermediate'
15-29 objects → 'advanced'
30+ objects  → 'expert'

When generating new content, it can either:

• Match the current difficulty level
• Progress to the next level (beginner → intermediate)
• Follow your explicit prompt ("advanced vocabulary")

4. Smart Positioning

Objects are positioned using collision-free algorithms:

Placement Strategies:

Strategy	Behavior	Use Case
auto (default)	Try placing right first, fallback to below if no space	General use
below	Place objects below existing content	Adding new sections
right	Place objects to the right of existing content	Extending horizontally
position	Start from custom {x, y} coordinates	Precise control

Grid Layout:

• Default: 5 columns
• Card size: 220x180 pixels
• Spacing: 30 pixels between objects
• Canvas bounds: 2000x2000 pixels

Use Cases

EdTech: Learning Content

Generate educational materials for online courses:

// Vocabulary flashcards
{
  prompt: "Create 15 intermediate English words about travel with Spanish translations",
  options: {
    use_board_context: true,
    layout: "grid"
  }
}

SaaS: Project Management

Create task boards for development teams:

// Sprint planning
{
  prompt: "Generate 10 task cards for MVP development: authentication, database setup, API endpoints, frontend UI, testing",
  options: {
    use_board_context: false,
    layout: "grid"
  }
}

Business: Organization Planning

Build organizational structures:

// Org chart
{
  prompt: "Create org chart nodes for a tech startup: CEO, CTO, CFO, Engineering Lead, Product Manager, Marketing Director",
  options: {
    use_board_context: false,
    placement: "auto"
  }
}

Contextual Expansion

Build upon existing board content:

// Analyze and extend
{
  prompt: "Analyze existing vocabulary cards and generate 10 related words at the next difficulty level",
  options: {
    use_board_context: true,
    max_context_objects: 50
  }
}

// Theme continuation
{
  prompt: "Add 8 more cards similar to what's already on the board",
  options: {
    use_board_context: true,
    placement: "auto"
  }
}

Fresh Board Creation

Start a new board from scratch:

// No context needed
{
  prompt: "Create 20 beginner Spanish vocabulary words about daily activities",
  options: {
    use_board_context: false,  // Skip context analysis
    layout: "grid",
    placement: "position",
    start_position: { x: 100, y: 100 }
  }
}

Practical Examples

Example 1: Task Cards for SaaS Development

Prompt:

Create 10 task cards for website redesign project.
Include: title, description, status, priority.

Generated Objects:

[
  {
    "type": "task-card",
    "data": {
      "title": "Create high-fidelity design mockups",
      "description": "Finalize desktop and mobile mockups for key pages",
      "status": "In Progress",
      "priority": "High"
    }
  },
  {
    "type": "task-card",
    "data": {
      "title": "Implement responsive navigation",
      "description": "Build mobile-first navigation with hamburger menu",
      "status": "To Do",
      "priority": "Medium"
    }
  }
  // ... 8 more cards
]

Positioning: 5x2 grid, starting below existing content

Time: ~4 seconds

Cost: 1 AI credit

Example 2: Organization Chart for Business

Board State:

• Empty board

Prompt:

Create organization chart for a tech startup with 8 key positions.
Include: name, position title, department, email.

Generated Objects:

[
  {
    "type": "org-chart-node",
    "data": {
      "name": "Sofia Ramirez",
      "position_title": "Chief Executive Officer (CEO)",
      "department": "Executive",
      "email": "sofia.ramirez@startup.com"
    }
  },
  {
    "type": "org-chart-node",
    "data": {
      "name": "Alex Chen",
      "position_title": "Chief Technology Officer (CTO)",
      "department": "Engineering",
      "email": "alex.chen@startup.com"
    }
  }
  // ... 6 more nodes
]

Smart Feature: AI generates realistic names and properly structures reporting hierarchy.

Example 3: Context-Aware Expansion

Scenario: Product board needs additional features for next sprint

Existing Board:

• 12 task cards about "user authentication" theme
• Status: mixed (some done, some in progress)

Prompt:

Add 8 more tasks continuing the current development theme

AI Response:

• Analyzes context: authentication theme detected
• Generates related tasks: "password reset flow", "OAuth integration", "2FA setup", "session management"
• Maintains theme consistency
• Places below existing cards

Best Practices

Writing Effective Prompts

Good Prompts ✅

✅ "Create 10 task cards for MVP development. Include: title, description, status (todo/in progress/done), priority (high/medium/low)"

• Specific count (10)
• Clear purpose (MVP development)
• Explicit fields (title, description, status, priority)
• Field values specified

✅ "Generate org chart nodes for a tech startup with 8 positions: CEO, CTO, CFO, Engineering Lead, Product Manager, Marketing Director, Sales Lead, Operations Manager"

• Clear context (tech startup)
• Specific number (8)
• Lists exact positions

✅ "Add 5 more tasks continuing the current development theme"

• Leverages context analysis
• Flexible topic (auto-detected)
• Maintains consistency

Bad Prompts ❌

❌ "Make some items"

• Too vague
• No object type specified
• Unknown quantity

❌ "x"

• Too short (<10 characters)
• Violates minimum prompt length

❌ [3000 character essay]

• Exceeds 2000 character limit
• Wastes tokens

Optimizing Context Usage

When to Enable Context:

✅ "Add more cards to the existing theme" → Context: ON ✅ "Generate quiz based on current board" → Context: ON ✅ "Continue at next difficulty level" → Context: ON

When to Disable Context:

✅ Creating a brand new board from scratch → Context: OFF ✅ Generating unrelated content → Context: OFF ✅ Saving API costs → Context: OFF

Adjusting Context Depth:

// Light context (faster, cheaper)
{
  options: {
    max_context_objects: 10  // Analyze only 10 objects
  }
}

// Deep context (better consistency)
{
  options: {
    max_context_objects: 50  // Analyze up to 50 objects
  }
}

Handling Errors

Quota Exceeded (402):

try {
  const result = await generateContent(request);
} catch (error) {
  if (error.status === 402) {
    // Show upgrade modal
    showUpgradePrompt({
      current: error.data.current,
      limit: error.data.limit,
      resetAt: error.data.resetAt
    });
  }
}

Payload Too Large (413):

// Board has 120 objects, max is 50
{
  statusCode: 413,
  message: "Board has too many objects (120). Maximum: 50",
  suggestion: "Disable 'use_board_context' or reduce max_context_objects"
}

// Solutions:
// 1. Disable context
options.use_board_context = false;

// 2. Reduce context depth
options.max_context_objects = 20;

// 3. Create a new board

Timeout (500):

// Generation took >30 seconds
{
  statusCode: 500,
  message: "AI provider error: timeout"
}

// Solutions:
// 1. Reduce context depth
options.max_context_objects = 20;

// 2. Disable context
options.use_board_context = false;

// 3. Simplify prompt
// Instead of: "Create 50 detailed cards..."
// Use: "Create 10 simple cards..."

Integration Example

Complete workflow for integrating AI Generation into your application:

import BoardAPI from '@boardapi/sdk';

const client = new BoardAPI({
  apiKey: process.env.BOARDAPI_KEY
});

// Step 1: Create a board
const board = await client.boards.create({
  name: "Website Redesign Sprint Planning",
  organization_id: "your-org-id"
});

// Step 2: Generate initial tasks
const generation1 = await client.ai.generate({
  board_uuid: board.uuid,
  prompt: "Create 12 task cards for website redesign: wireframes, design system, responsive layouts, component library, accessibility, performance optimization, testing, deployment",
  options: {
    use_board_context: false,  // Fresh board, no context
    layout: "grid"
  }
});

console.log(`Created ${generation1.objects_created} task cards`);
console.log(`Quota remaining: ${generation1.quota_remaining}/${generation1.quota_limit}`);

// Step 3: Add team organization
await new Promise(resolve => setTimeout(resolve, 2000)); // Brief pause

const generation2 = await client.ai.generate({
  board_uuid: board.uuid,
  prompt: "Generate org chart nodes for the project team: Project Manager, UX Designer, Frontend Developer, Backend Developer, QA Engineer",
  options: {
    use_board_context: false,  // Different object type
    placement: "below"
  }
});

console.log(`Team org chart created with ${generation2.objects_created} nodes`);

// Step 4: Expand with context
const generation3 = await client.ai.generate({
  board_uuid: board.uuid,
  prompt: "Add 8 more tasks continuing the development theme",
  options: {
    use_board_context: true,  // Analyze existing tasks
    max_context_objects: 20,
    placement: "right"
  }
});

console.log(`Additional tasks added: ${generation3.objects_created} cards`);
console.log(`Themes detected: ${generation3.context_used.themes_detected.join(', ')}`);

// Step 5: Check quota
console.log(`\nTotal quota used: ${50 - generation3.quota_remaining} / 50`);

Output:

Created 12 task cards
Quota remaining: 49/50

Team org chart created with 5 nodes

Additional tasks added: 8 cards
Themes detected: development, project-management

Total quota used: 3 / 50

Performance Tips

Response Time Optimization

Factor	Impact	Recommendation
Context depth	High	Use max_context_objects: 20 for faster generation
Board size	Medium	Disable context for boards >50 objects
Prompt complexity	Low	Keep prompts under 500 characters
Object count	Medium	Generate 10 objects at a time, not 50

Typical Response Times:

Simple generation (context OFF):  2-4 seconds
With context (10 objects):        3-6 seconds
With context (50 objects):        5-10 seconds
Complex generation:               8-15 seconds
Timeout threshold:                30 seconds

Token Economy

Save costs by minimizing token usage:

// Expensive: Full context every time
{
  use_board_context: true,
  max_context_objects: 50  // ~5000 tokens
}

// Cost: ~$0.05 per generation

// Economical: Targeted context
{
  use_board_context: true,
  max_context_objects: 10  // ~1000 tokens
}

// Cost: ~$0.01 per generation

Cost Breakdown:

• Intent classification: ~$0.0003 (100 tokens)
• Context analysis: ~$0.001-0.01 (varies by depth)
• Content generation: ~$0.005-0.03 (depends on complexity)
• Total: ~$0.006-0.04 per generation

Quota Management

Tracking Usage

Every generation response includes quota information:

{
  "credits_used": 1,
  "quota_remaining": 45,
  "quota_limit": 50,
  "quota_warning": "You've used 5 of 50 AI requests this month (10%)"
}

Response Headers:

X-AI-Quota-Limit: 50
X-AI-Quota-Remaining: 45
X-AI-Quota-Reset: 2025-12-01T00:00:00.000Z

Quota Warnings

At 80% usage, automatic warnings appear:

{
  "quota_warning": "You've used 40 of 50 AI requests this month (80%)"
}

At 100% usage, requests fail with 402 Payment Required:

{
  "statusCode": 402,
  "message": "AI request limit reached (50/month). Resets Dec 1",
  "upgradeRequired": true,
  "current": 50,
  "limit": 50,
  "resetAt": "2025-12-01T00:00:00.000Z"
}

Reset Schedule

Quotas reset on the 1st day of each month at 00:00:00 UTC.

Check reset time via:

• Response header: X-AI-Quota-Reset
• Response body: quota_reset_at (if approaching limit)

API Reference

For complete API documentation including:

• Request/response schemas
• Error codes and handling
• Authentication methods
• Rate limits

See AI Generation API Reference.

Related Features

• Custom Objects - Define schemas for AI-generated objects
• Object Types API - Register and manage object types
• Quota API - Check and monitor quota usage
• Webhooks - Receive events when AI generates content

Support

Need help with AI Generation?

• Documentation: docs.boardapi.io
• API Reference: AI Generation API
• Examples: GitHub Examples Repository
• Email Support: support@boardapi.io (Professional tier+)
• Community Forum: forum.boardapi.io

---

Last Updated: 2025-11-28 Feature Status: Production-Ready