AI Generation API Reference

The AI Generation API allows you to create board content automatically using natural language prompts. The AI analyzes existing board context and generates contextually relevant objects.

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.

Authentication

AI Generation endpoints require API key authentication:

bash

curl -H "X-API-Key: your-api-key" \
  https://api.boardapi.io/api/v1/ai/generate

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

Setup Requirements

1. Configure AI Provider

AI Generation requires an OpenAI-compatible API key configured in your organization settings:

Via Environment Variables (Backend):

bash

GPTPROXY_API_KEY=your-openai-api-key
GPTPROXY_API_URL=https://gptproxy.ru/api/index.php?p=v1/chat/completions
GPTPROXY_MODEL=gpt-5-mini

Supported Providers:

OpenAI (GPT-4o, GPT-4o-mini)
GPT Proxy (gpt-5-mini)
Any OpenAI-compatible endpoint

Configuration Required

AI Generation will return 500 Internal Server Error if no API key is configured. Contact your administrator to set up AI provider credentials.

2. Register Object Types

Before generating content, you must have registered object types in your organization. The AI will generate objects matching your custom schemas.

See Object Types API for details on registering custom object types.

Generate Content

Creates objects on a board using AI based on natural language prompts.

Request

http

POST /ai/generate
X-API-Key: your-api-key
Content-Type: application/json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "prompt": "Create 10 task cards for website redesign project with title, description, status, and priority",
  "options": {
    "use_board_context": true,
    "layout": "grid",
    "language": "en",
    "placement": "auto",
    "max_context_objects": 50
  }
}

Request Body Parameters

Parameter	Type	Required	Description
`board_uuid`	string	Yes	UUID of the target board
`prompt`	string	Yes	Natural language description (10-2000 characters)
`options`	object	No	Advanced generation options

Options Object

Parameter	Type	Default	Description
`use_board_context`	boolean	`true`	Include existing board objects as context
`layout`	string	`"grid"`	Layout strategy: `grid`, `linear`, `freeform`
`language`	string	`"en"`	Language for generated content
`placement`	string	`"auto"`	Placement strategy: `auto`, `below`, `right`, `position`
`start_position`	object	-	Starting position `{x, y}` (only with `placement: "position"`)
`max_context_objects`	number	`50`	Maximum board objects to analyze (1-50)

Example Prompts

SaaS Project Management:

json

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

Business Organization:

json

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

Contextual Expansion:

json

{
  "prompt": "Add 5 more tasks continuing the current development theme",
  "options": {
    "use_board_context": true
  }
}

Response

Status Code: 200 OK

json

{
  "generation_id": "gen_1637256780000",
  "objects_created": 5,
  "objects": [
    {
      "id": "obj_new_1",
      "type": "task-card",
      "data": {
        "title": "Create high-fidelity design mockups",
        "description": "Finalize desktop and mobile mockups for key pages",
        "status": "In Progress",
        "priority": "High"
      },
      "position": { "x": 300, "y": 500 },
      "dimensions": { "width": 220, "height": 180 }
    }
  ],
  "context_used": {
    "objects_analyzed": 12,
    "themes_detected": ["development", "project-management"],
    "difficulty_level": "intermediate"
  },
  "credits_used": 1,
  "generation_time_ms": 3240,
  "quota_remaining": 45,
  "quota_limit": 50,
  "quota_warning": "You've used 5 of 50 AI requests this month (10%)"
}

Response Fields

Field	Type	Description
`generation_id`	string	Unique identifier for this generation
`objects_created`	number	Number of objects successfully created
`objects`	array	Array of generated objects with full details
`context_used`	object	Information about board context analyzed (null if disabled)
`credits_used`	number	Number of credits consumed (typically 1 per generation)
`generation_time_ms`	number	Total generation time in milliseconds
`quota_remaining`	number	Remaining AI requests this month (-1 for unlimited)
`quota_limit`	number	Total AI request limit per month (-1 for unlimited)
`quota_warning`	string	Warning message if approaching quota limit (at 80%+ usage)

Quota Headers

The response includes quota information in headers:

http

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

Header	Description
`X-AI-Quota-Limit`	Total AI request limit per month
`X-AI-Quota-Remaining`	Remaining AI requests this month
`X-AI-Quota-Reset`	ISO 8601 timestamp when quota resets (start of next month)

How It Works

1. Context Analysis

When use_board_context: true, the AI analyzes existing board content:

Objects Analyzed: Up to 50 most recent objects (configurable via max_context_objects)
Theme Detection: Identifies topics, difficulty level, language
Pattern Recognition: Understands object structure and data schemas
Space Detection: Finds optimal placement to avoid collisions

2. Content Generation

The AI generates content based on:

Your Prompt: Natural language description of what you want
Board Context: Existing objects for consistency
Object Type Schemas: Your registered custom object types
Layout Preferences: Specified layout and placement strategy

3. Smart Placement

Objects are automatically positioned to avoid overlaps:

Auto: System detects free space intelligently
Below: Places objects below existing content
Right: Places objects to the right of existing content
Position: Uses specified start_position coordinates

4. Layout Strategies

Layout	Description	Best For
`grid`	Evenly spaced grid arrangement	Flashcards, vocabulary
`linear`	Vertical or horizontal list	Timelines, sequences
`freeform`	Natural scattered placement	Mind maps, brainstorms

Error Handling

400 Bad Request

Invalid Prompt Length:

json

{
  "statusCode": 400,
  "message": "Prompt is too short (minimum 10 characters)",
  "error": "Bad Request"
}

Validation Errors:

Prompt must be 10-2000 characters
board_uuid must be a valid UUID
max_context_objects must be 1-50

404 Not Found

Board Not Found:

json

{
  "statusCode": 404,
  "message": "Board with UUID a1b2c3d4... not found",
  "error": "Not Found"
}

413 Payload Too Large

Too Many Context Objects:

json

{
  "statusCode": 413,
  "message": "Board has too many objects (120). Maximum: 50",
  "error": "Payload Too Large",
  "suggestion": "Disable 'use_board_context' or reduce max_context_objects"
}

The AI cannot process boards with more than 50 objects in context. Solutions:

Set use_board_context: false to disable context analysis
Reduce max_context_objects to a lower value
Create a new board with fewer objects

402 Payment Required

Quota Exceeded:

json

{
  "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"
}

Quota resets on the 1st day of each month at midnight UTC. To increase your quota, upgrade your plan:

Professional: 50 requests/month
Business: 200 requests/month
Enterprise: 1000 requests/month

429 Too Many Requests

Rate Limit Exceeded:

json

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Daily limit: 20 generations",
  "error": "Too Many Requests",
  "retry_after": 3600
}

Rate limits by tier:

Free tier: 5 generations/hour, 20/day
Premium: 50/hour, 200/day
Enterprise: Unlimited

The retry_after field indicates seconds until you can retry.

500 Internal Server Error

AI Provider Error:

json

{
  "statusCode": 500,
  "message": "AI provider error: timeout",
  "error": "Internal Server Error"
}

Common causes:

AI provider API key not configured
AI provider service unavailable
Network timeout (>30 seconds)

501 Not Implemented

Missing Dependencies:

json

{
  "statusCode": 501,
  "message": "GptProxyProvider not yet implemented. Waiting for Agent 2 to complete.",
  "error": "Not Implemented"
}

This error occurs if the AI provider integration is not fully configured on the backend.

Usage Quotas

Monthly Quotas by Tier

Tier	AI Requests/Month	Cost per Request
Starter	Not available	-
Professional	50	~$0.01
Business	200	~$0.01
Enterprise	1000	~$0.01

Quota Tracking

Monitor your usage via:

Response Headers: Every generation includes quota headers
Response Body: quota_remaining and quota_limit fields
Warning Messages: Automatic warnings at 80%+ usage

Quota Soft Limits

At 80% usage, you'll receive warnings:

json

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

At 100% usage, requests will fail with 402 Payment Required.

Quota Reset Schedule

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

The X-AI-Quota-Reset header provides the exact reset timestamp.

Best Practices

1. Optimize Token Usage

Enable Context Only When Needed:

json

{
  "options": {
    "use_board_context": false  // Saves tokens for simple generations
  }
}

Limit Context Objects:

json

{
  "options": {
    "max_context_objects": 20  // Analyze fewer objects to reduce cost
  }
}

2. Write Clear Prompts

Good Prompts:

✅ "Create 10 vocabulary cards about animals. Include word, Spanish translation, and example sentence. Difficulty: beginner"
✅ "Generate 5 quiz questions based on existing cards. Multiple choice format with 4 options each"
✅ "Add 3 more cards continuing the current theme at intermediate difficulty"

Bad Prompts:

❌ "Make some cards" (too vague)
❌ "x" (too short, <10 characters)
❌ A 3000-character essay (exceeds 2000 limit)

3. Handle Errors Gracefully

javascript

try {
  const response = await fetch('/api/v1/ai/generate', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(request)
  });

  if (!response.ok) {
    const error = await response.json();

    if (response.status === 402) {
      // Quota exceeded - show upgrade prompt
      showUpgradeModal(error.current, error.limit, error.resetAt);
    } else if (response.status === 429) {
      // Rate limit - show retry countdown
      showRetryMessage(error.retry_after);
    } else {
      // Other errors
      showError(error.message);
    }
    return;
  }

  const result = await response.json();

  // Check quota warning
  if (result.quota_warning) {
    showWarningBanner(result.quota_warning);
  }

  // Process generated objects
  addObjectsToBoard(result.objects);

} catch (error) {
  showError('Network error. Please try again.');
}

4. Monitor Performance

Track Generation Times:

javascript

const result = await generateContent(request);
console.log(`Generated ${result.objects_created} objects in ${result.generation_time_ms}ms`);

// Typical ranges:
// - Simple generation: 2-5 seconds
// - With context: 3-8 seconds
// - Complex prompts: 5-15 seconds

5. Use Context Effectively

When to Enable Context:

✅ "Add more cards to the existing theme"
✅ "Generate quiz based on current board"
✅ "Create objects matching the difficulty level"

When to Disable Context:

✅ Creating a brand new board from scratch
✅ Simple, self-contained generations
✅ When you want to save tokens/cost

Code Examples

Node.js / JavaScript

javascript

const API_BASE = 'https://api.boardapi.io/api/v1';
const API_KEY = process.env.BOARDAPI_KEY;

async function generateContent(boardUuid, prompt) {
  const response = await fetch(`${API_BASE}/ai/generate`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      board_uuid: boardUuid,
      prompt: prompt,
      options: {
        use_board_context: true,
        layout: 'grid',
        language: 'en'
      }
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const result = await response.json();

  console.log(`Generated ${result.objects_created} objects`);
  console.log(`Quota remaining: ${result.quota_remaining}/${result.quota_limit}`);

  return result;
}

// Usage
generateContent(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  'Create 10 vocabulary cards about food and drinks'
).then(result => {
  console.log('Objects:', result.objects);
}).catch(error => {
  console.error('Generation failed:', error);
});

Python

python

import requests
import os

API_BASE = 'https://api.boardapi.io/api/v1'
API_KEY = os.getenv('BOARDAPI_KEY')

def generate_content(board_uuid: str, prompt: str):
    response = requests.post(
        f'{API_BASE}/ai/generate',
        headers={
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json'
        },
        json={
            'board_uuid': board_uuid,
            'prompt': prompt,
            'options': {
                'use_board_context': True,
                'layout': 'grid',
                'language': 'en'
            }
        }
    )

    response.raise_for_status()
    result = response.json()

    print(f"Generated {result['objects_created']} objects")
    print(f"Quota: {result['quota_remaining']}/{result['quota_limit']}")

    return result

# Usage
try:
    result = generate_content(
        'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        'Create 10 vocabulary cards about food and drinks'
    )
    print('Objects:', result['objects'])
except requests.exceptions.HTTPError as error:
    print(f'Generation failed: {error.response.json()["message"]}')

cURL

bash

#!/bin/bash

API_KEY="your-api-key"
BOARD_UUID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

curl -X POST "https://api.boardapi.io/api/v1/ai/generate" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "board_uuid": "'$BOARD_UUID'",
    "prompt": "Create 10 vocabulary cards about food and drinks with Spanish translations",
    "options": {
      "use_board_context": true,
      "layout": "grid",
      "language": "en",
      "placement": "auto"
    }
  }'

Rate Limits

Request Limits

Limit Type	Free Tier	Premium	Enterprise
Requests per hour	5	50	Unlimited
Requests per day	20	200	Unlimited
Concurrent requests	1	3	10

Time Limits

Request Timeout: 30 seconds
Typical Response Time: 3-8 seconds
Maximum Generation Time: 30 seconds (then timeout)

Size Limits

Prompt Length: 10-2000 characters
Context Objects: 1-50 objects (when context enabled)
Generated Objects: 1-50 per request (determined by AI based on prompt)

Troubleshooting

Generation Takes Too Long

Symptoms: Request times out after 30 seconds

Solutions:

Reduce max_context_objects to analyze fewer objects
Disable context with use_board_context: false
Use simpler prompts requiring fewer objects
Check AI provider status

Objects Overlap on Board

Symptoms: Generated objects placed on top of each other

Solutions:

Ensure use_board_context: true for smart placement
Try different placement strategies: below, right, position
Manually specify start_position in empty board area
Use layout: "grid" for predictable spacing

Wrong Object Types Generated

Symptoms: AI creates generic objects instead of custom types

Solutions:

Verify your object types are registered in the organization
Be specific in your prompt: "Create vocabulary-card objects..."
Include example field names in prompt: "Include word, translation, example"
Check object type schemas are properly configured

Quota Exhausted Too Quickly

Symptoms: Hitting quota limits faster than expected

Solutions:

Disable context when not needed to reduce token usage
Generate fewer objects per request
Use caching by making similar requests
Upgrade to higher tier plan
Monitor quota headers in responses

AI Provider Not Configured

Symptoms: 500 Internal Server Error or 501 Not Implemented

Solutions:

Verify GPTPROXY_API_KEY is configured in backend environment
Check AI provider URL is accessible
Test API key validity with provider
Contact administrator for configuration

Object Types API - Register custom object types
Boards API - Create and manage boards
Webhooks - Receive AI generation events
Authentication - API key setup and management

Support

Need help with AI Generation?

Documentation: docs.boardapi.io
Community Forum: forum.boardapi.io
Email Support: support@boardapi.io (Professional tier+)
Priority Support: 24h response (Business tier+)

Last Updated: 2025-11-26 API Version: 1.0 Status: Production-Ready

AI Generation API Reference ​

Authentication ​

Base URL ​

Setup Requirements ​

1. Configure AI Provider ​

2. Register Object Types ​

Generate Content ​

Request ​

Request Body Parameters ​

Options Object ​

Example Prompts ​

Response ​

Response Fields ​

Quota Headers ​

How It Works ​

1. Context Analysis ​

2. Content Generation ​

3. Smart Placement ​

4. Layout Strategies ​

Error Handling ​

400 Bad Request ​

404 Not Found ​

413 Payload Too Large ​

402 Payment Required ​

429 Too Many Requests ​

500 Internal Server Error ​

501 Not Implemented ​

Usage Quotas ​

Monthly Quotas by Tier ​

Quota Tracking ​

Quota Soft Limits ​

Quota Reset Schedule ​

Best Practices ​

1. Optimize Token Usage ​

2. Write Clear Prompts ​

3. Handle Errors Gracefully ​

4. Monitor Performance ​

5. Use Context Effectively ​

Code Examples ​

Node.js / JavaScript ​

Python ​

cURL ​

Rate Limits ​

Request Limits ​

Time Limits ​

Size Limits ​

Troubleshooting ​

Generation Takes Too Long ​

Objects Overlap on Board ​

Wrong Object Types Generated ​

Quota Exhausted Too Quickly ​

AI Provider Not Configured ​

Related Documentation ​

Support ​

AI Generation API Reference

Authentication

Base URL

Setup Requirements

1. Configure AI Provider

2. Register Object Types

Generate Content

Request

Request Body Parameters

Options Object

Example Prompts

Response

Response Fields

Quota Headers

How It Works

1. Context Analysis

2. Content Generation

3. Smart Placement

4. Layout Strategies

Error Handling

400 Bad Request

404 Not Found

413 Payload Too Large

402 Payment Required

429 Too Many Requests

500 Internal Server Error

501 Not Implemented

Usage Quotas

Monthly Quotas by Tier

Quota Tracking

Quota Soft Limits

Quota Reset Schedule

Best Practices

1. Optimize Token Usage

2. Write Clear Prompts

3. Handle Errors Gracefully

4. Monitor Performance

5. Use Context Effectively

Code Examples

Node.js / JavaScript

Python

cURL

Rate Limits

Request Limits

Time Limits

Size Limits

Troubleshooting

Generation Takes Too Long

Objects Overlap on Board

Wrong Object Types Generated

Quota Exhausted Too Quickly

AI Provider Not Configured

Related Documentation

Support