Boards API Reference

The Boards API provides endpoints for creating, retrieving, updating, and deleting collaborative whiteboards. All board operations require API key authentication.

Authentication

All Boards API endpoints require API key authentication:

bash

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

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`	Create a new board
`GET`	`/boards`	List all boards for organization
`GET`	`/boards/by-owner`	Get boards by external owner ID
`GET`	`/boards/:uuid`	Retrieve board details
`GET`	`/boards/:uuid/access-links`	Get board access links
`PATCH`	`/boards/:uuid`	Update board metadata
`DELETE`	`/boards/:uuid`	Delete a board
`POST`	`/boards/:uuid/end-session`	End active board session
`POST`	`/boards/:uuid/duplicate`	Duplicate a board
`PATCH`	`/boards/:uuid/archive`	Archive or restore a board

Create Board

Creates a new collaborative whiteboard with optional initial objects and webhook configuration.

Request

http

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

{
  "title": "English Lesson",
  "external_id": "lesson_123",
  "expires_in_hours": 48,
  "config": {
    "max_participants": 30,
    "allow_anonymous": true
  },
  "initial_objects": [
    {
      "type": "vocabulary-card",
      "data": {
        "word": "apple",
        "translation": "яблоко"
      },
      "position": { "x": 100, "y": 100 }
    }
  ],
  "webhook_url": "https://api.client.com/webhooks"
}

Request Body Parameters

Parameter	Type	Required	Description
`title`	string	Yes	Board title (max 255 characters)
`external_id`	string	No	Your system's reference ID for this board
`expires_in_hours`	number	No	Board expiration time in hours (default: 72)
`config`	object	No	Board configuration options
`config.max_participants`	number	No	Maximum allowed participants (default: 50)
`config.allow_anonymous`	boolean	No	Allow access without registration (default: true)
`initial_objects`	array	No	Array of objects to create on the board
`webhook_url`	string	No	Webhook URL for board events

Initial Objects Structure

Each object in initial_objects array:

json

{
  "type": "vocabulary-card",
  "data": {
    "word": "apple",
    "translation": "яблоко",
    "image_url": "https://cdn.example.com/apple.jpg"
  },
  "position": {
    "x": 100,
    "y": 100
  }
}

Field	Type	Required	Description
`type`	string	Yes	Object type (e.g., `vocabulary-card`, `shape`, `text`)
`data`	object	Yes	Object data (validated against object type schema)
`position`	object	Yes	Position on canvas
`position.x`	number	Yes	X coordinate (pixels)
`position.y`	number	Yes	Y coordinate (pixels)

Response

Status Code: 201 Created

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "English Lesson",
  "external_id": "lesson_123",
  "status": "active",
  "created_at": "2025-11-14T10:00:00Z",
  "expires_at": "2025-11-16T10:00:00Z",
  "access_links": {
    "host": "https://app.boardapi.io/board/a1b2c3d4?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "guest": "https://app.boardapi.io/board/a1b2c3d4?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Response Fields

Field	Type	Description
`board_uuid`	string	Unique board identifier (UUID)
`title`	string	Board title
`external_id`	string	Your system's reference ID
`status`	string	Board status (`active`, `archived`, `expired`)
`created_at`	string	ISO 8601 creation timestamp
`expires_at`	string	ISO 8601 expiration timestamp
`access_links.host`	string	URL with host token (full control)
`access_links.guest`	string	URL with guest token (read/write)

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch('https://api.boardapi.io/api/v1/boards', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'English Lesson',
    external_id: 'lesson_123',
    expires_in_hours: 48,
    initial_objects: [
      {
        type: 'vocabulary-card',
        data: {
          word: 'apple',
          translation: 'яблоко'
        },
        position: { x: 100, y: 100 }
      }
    ],
    webhook_url: 'https://api.client.com/webhooks'
  })
});

const board = await response.json();
console.log(board.access_links.host); // Share with teacher
console.log(board.access_links.guest); // Share with students

cURL:

bash

curl -X POST https://api.boardapi.io/api/v1/boards \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "English Lesson",
    "external_id": "lesson_123",
    "expires_in_hours": 48,
    "initial_objects": [
      {
        "type": "vocabulary-card",
        "data": {
          "word": "apple",
          "translation": "яблоко"
        },
        "position": {"x": 100, "y": 100}
      }
    ],
    "webhook_url": "https://api.client.com/webhooks"
  }'

PHP:

php

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

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: your-api-key',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'title' => 'English Lesson',
        'external_id' => 'lesson_123',
        'expires_in_hours' => 48,
        'initial_objects' => [
            [
                'type' => 'vocabulary-card',
                'data' => [
                    'word' => 'apple',
                    'translation' => 'яблоко'
                ],
                'position' => ['x' => 100, 'y' => 100]
            ]
        ],
        'webhook_url' => 'https://api.client.com/webhooks'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$board = json_decode(curl_exec($ch), true);
echo $board['access_links']['host'];

Possible Errors

Status Code	Error	Description
`400`	`Bad Request`	Missing required fields or invalid data format
`401`	`Unauthorized`	Invalid or missing API key
`413`	`Payload Too Large`	Request body exceeds size limit
`429`	`Too Many Requests`	Rate limit exceeded
`500`	`Internal Server Error`	Server error occurred

Get Board

Retrieves board metadata and current state.

Request

http

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

URL Parameters

Parameter	Type	Description
`id`	string	Board UUID

Query Parameters

Parameter	Type	Description
`includeObjects`	boolean	Include canvas objects in response (default: true)
`includeParticipants`	boolean	Include current participants list (default: false)

Response

Status Code: 200 OK

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "English Lesson",
  "external_id": "lesson_123",
  "status": "active",
  "created_at": "2025-11-14T10:00:00Z",
  "updated_at": "2025-11-14T12:30:45Z",
  "expires_at": "2025-11-16T10:00:00Z",
  "state": {
    "version": 42,
    "objects": [
      {
        "id": "obj_1",
        "type": "vocabulary-card",
        "data": {
          "word": "apple",
          "translation": "яблоко"
        },
        "position": {
          "x": 100,
          "y": 100
        },
        "created_at": "2025-11-14T10:00:00Z",
        "created_by": "user_123"
      }
    ]
  },
  "participants": [
    {
      "user_id": "user_1",
      "role": "host",
      "joined_at": "2025-11-14T10:00:00Z",
      "color": "#FF6B6B"
    },
    {
      "user_id": "user_2",
      "role": "guest",
      "joined_at": "2025-11-14T10:05:00Z",
      "color": "#4ECDC4"
    }
  ],
  "participants_count": 2,
  "objects_count": 1
}

Response Fields

Field	Type	Description
`board_uuid`	string	Board identifier
`title`	string	Board title
`status`	string	Board status
`state`	object	Current board state (canvas objects)
`state.version`	number	State version for conflict resolution
`state.objects`	array	Array of objects on canvas
`participants`	array	Active participants (if requested)
`participants_count`	number	Total active participants
`objects_count`	number	Total objects on board

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4?includeObjects=true&includeParticipants=true',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const board = await response.json();
console.log(`Board: ${board.title}`);
console.log(`Participants: ${board.participants_count}`);
console.log(`Objects: ${board.objects_count}`);

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4?includeObjects=true'

PHP:

php

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

echo "Board: {$board['title']}\n";
echo "Participants: {$board['participants_count']}\n";

Possible Errors

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

Update Board

Updates board metadata such as title, expiration, or webhook URL.

Request

http

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

{
  "title": "Updated Lesson Title",
  "expires_in_hours": 72,
  "webhook_url": "https://api.client.com/webhooks-v2"
}

URL Parameters

Parameter	Type	Description
`id`	string	Board UUID

Request Body Parameters

Parameter	Type	Required	Description
`title`	string	No	New board title
`expires_in_hours`	number	No	New expiration time
`webhook_url`	string	No	New webhook URL for events
`config`	object	No	Updated board configuration

Response

Status Code: 200 OK

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Updated Lesson Title",
  "updated_at": "2025-11-14T13:00:00Z",
  "expires_at": "2025-11-17T10:00:00Z"
}

Example Requests

JavaScript/TypeScript:

javascript

const response = await fetch('https://api.boardapi.io/api/v1/boards/a1b2c3d4', {
  method: 'PATCH',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Updated Lesson Title',
    expires_in_hours: 72
  })
});

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

cURL:

bash

curl -X PATCH https://api.boardapi.io/api/v1/boards/a1b2c3d4 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Lesson Title",
    "expires_in_hours": 72
  }'

Possible Errors

Status Code	Error	Description
`400`	`Bad Request`	Invalid update data
`404`	`Not Found`	Board does not exist
`401`	`Unauthorized`	Invalid API key

Delete Board

Deletes a board and all associated data. This operation is permanent and cannot be undone.

Request

http

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

URL Parameters

Parameter	Type	Description
`id`	string	Board 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/a1b2c3d4', {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

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

cURL:

bash

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

PHP:

php

<?php
$ch = curl_init('https://api.boardapi.io/api/v1/boards/a1b2c3d4');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => ['X-API-Key: your-api-key'],
    CURLOPT_RETURNTRANSFER => true
]);

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 204) {
    echo "Board deleted successfully";
}

Possible Errors

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

List All Boards

Retrieves a list of all boards for the authenticated organization, with optional status filtering.

Request

http

GET /boards?status=active
X-API-Key: your-api-key

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by board status: `active`, `archived`, `expired`

Response

Status Code: 200 OK

json

[
  {
    "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "English Lesson",
    "external_id": "lesson_123",
    "status": "active",
    "created_at": "2025-11-14T10:00:00Z",
    "updated_at": "2025-11-14T12:30:45Z",
    "expires_at": "2025-11-16T10:00:00Z",
    "participants_count": 5,
    "objects_count": 12
  },
  {
    "board_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "title": "Math Practice",
    "external_id": "lesson_124",
    "status": "active",
    "created_at": "2025-11-14T11:00:00Z",
    "updated_at": "2025-11-14T11:15:00Z",
    "expires_at": "2025-11-16T11:00:00Z",
    "participants_count": 3,
    "objects_count": 8
  }
]

Example Requests

JavaScript/TypeScript:

javascript

// Get all active boards
const response = await fetch('https://api.boardapi.io/api/v1/boards?status=active', {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

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

cURL:

bash

# Get all boards
curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards'

# Get only active boards
curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards?status=active'

# Get only archived boards
curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards?status=archived'

PHP:

php

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

echo "Total boards: " . count($boards) . "\n";
foreach ($boards as $board) {
    echo "- {$board['title']} ({$board['participants_count']} participants)\n";
}

Possible Errors

Status Code	Error	Description
`401`	`Unauthorized`	Invalid API key
`400`	`Bad Request`	Invalid status value

Get Boards by Owner

Retrieves all boards associated with a specific external owner ID.

Request

http

GET /boards/by-owner?externalId=user_12345
X-API-Key: your-api-key

Query Parameters

Parameter	Type	Required	Description
`externalId`	string	Yes	External owner ID from your system

Response

Status Code: 200 OK

json

[
  {
    "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "User's Board 1",
    "external_id": "lesson_123",
    "owner_external_id": "user_12345",
    "status": "active",
    "created_at": "2025-11-14T10:00:00Z",
    "expires_at": "2025-11-16T10:00:00Z"
  },
  {
    "board_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "title": "User's Board 2",
    "external_id": "lesson_124",
    "owner_external_id": "user_12345",
    "status": "active",
    "created_at": "2025-11-14T11:00:00Z",
    "expires_at": "2025-11-16T11:00:00Z"
  }
]

Example Requests

JavaScript/TypeScript:

javascript

// Get all boards owned by a specific user
const userId = 'teacher_456';
const response = await fetch(
  `https://api.boardapi.io/api/v1/boards/by-owner?externalId=${userId}`,
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const userBoards = await response.json();
console.log(`Teacher has ${userBoards.length} boards`);

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/by-owner?externalId=teacher_456'

PHP:

php

<?php
$teacherId = 'teacher_456';
$url = 'https://api.boardapi.io/api/v1/boards/by-owner?externalId=' . urlencode($teacherId);
$boards = json_decode(
  file_get_contents($url, false, stream_context_create([
    'http' => ['header' => 'X-API-Key: your-api-key']
  ])),
  true
);

echo "Teacher has " . count($boards) . " boards\n";

Use Cases

Display all boards created by a teacher in your LMS
Show student's personal boards in their dashboard
Filter boards by organization department or team

Possible Errors

Status Code	Error	Description
`401`	`Unauthorized`	Invalid API key
`400`	`Bad Request`	Missing externalId parameter

Get Board Access Links

Retrieves the host and guest access links for an existing board. Useful for re-sharing board URLs or integrating into your UI.

Request

http

GET /boards/:uuid/access-links
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`uuid`	string	Board UUID

Response

Status Code: 200 OK

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "access_links": {
    "host": "https://app.boardapi.io/board/a1b2c3d4?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJib2FyZFV1aWQiOiJhMWIyYzNkNCIsInJvbGUiOiJob3N0In0...",
    "guest": "https://app.boardapi.io/board/a1b2c3d4?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJib2FyZFV1aWQiOiJhMWIyYzNkNCIsInJvbGUiOiJndWVzdCJ9..."
  }
}

Response Fields

Field	Type	Description
`board_uuid`	string	Board identifier
`access_links.host`	string	Host access link (full permissions)
`access_links.guest`	string	Guest access link (read/write)

Example Requests

JavaScript/TypeScript:

javascript

// Get access links for a board
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/access-links',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const { access_links } = await response.json();

// Display in your UI
document.getElementById('host-link').value = access_links.host;
document.getElementById('guest-link').value = access_links.guest;

cURL:

bash

curl -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/access-links'

PHP:

php

<?php
$boardId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
$result = json_decode(
  file_get_contents(
    "https://api.boardapi.io/api/v1/boards/{$boardId}/access-links",
    false,
    stream_context_create(['http' => ['header' => 'X-API-Key: your-api-key']])
  ),
  true
);

echo "Host link: {$result['access_links']['host']}\n";
echo "Guest link: {$result['access_links']['guest']}\n";

Use Cases

Display board links in your application UI
Send invitation emails with board access
Regenerate links for existing boards
Implement "Copy Link" functionality

Possible Errors

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

End Board Session

Ends the active session for a board, disconnecting all participants and marking the session as completed. The board itself is not deleted and can be accessed again later.

Request

http

POST /boards/:uuid/end-session
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`uuid`	string	Board UUID

Response

Status Code: 200 OK

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_ended_at": "2025-11-14T15:30:00Z",
  "status": "active",
  "message": "Session ended successfully. All participants have been disconnected."
}

Response Fields

Field	Type	Description
`board_uuid`	string	Board identifier
`session_ended_at`	string	ISO 8601 timestamp of session end
`status`	string	Board status (remains `active`)
`message`	string	Confirmation message

Example Requests

JavaScript/TypeScript:

javascript

// End board session (e.g., when lesson is finished)
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/end-session',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const result = await response.json();
console.log(result.message);
// "Session ended successfully. All participants have been disconnected."

cURL:

bash

curl -X POST \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/end-session'

PHP:

php

<?php
$ch = curl_init('https://api.boardapi.io/api/v1/boards/a1b2c3d4/end-session');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your-api-key'],
    CURLOPT_RETURNTRANSFER => true
]);

$result = json_decode(curl_exec($ch), true);
echo $result['message'];

Use Cases

End online lesson/class session
Force disconnect all participants for maintenance
Complete collaborative work session
Trigger end-of-session webhooks

Behavior

All connected WebSocket clients are disconnected
Session metadata is updated with end timestamp
Board state is preserved and can be accessed later
Board status remains active (not archived)
New participants can still join after session ends

Possible Errors

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

Duplicate Board

Creates an exact copy of an existing board, including all objects and configuration. The new board gets a new UUID and fresh access links.

Request

http

POST /boards/:uuid/duplicate
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`uuid`	string	Board UUID to duplicate

Response

Status Code: 201 Created

json

{
  "board_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "title": "English Lesson (Copy)",
  "external_id": "lesson_123_copy",
  "status": "active",
  "created_at": "2025-11-14T16:00:00Z",
  "expires_at": "2025-11-16T16:00:00Z",
  "access_links": {
    "host": "https://app.boardapi.io/board/c3d4e5f6?token=...",
    "guest": "https://app.boardapi.io/board/c3d4e5f6?token=..."
  },
  "source_board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields

Field	Type	Description
`board_uuid`	string	New board UUID
`title`	string	New board title (original + " (Copy)")
`external_id`	string	New external ID (original + "_copy")
`status`	string	Board status (always `active`)
`access_links`	object	New access links for the duplicated board
`source_board_uuid`	string	Original board UUID

What Gets Duplicated

✅ Copied:

All objects on the canvas (with positions)
Board title (with " (Copy)" suffix)
Board configuration (max_participants, allow_anonymous, etc.)
External ID (with "_copy" suffix)
Webhook URL

❌ Not Copied:

Board UUID (new UUID is generated)
Access tokens (new tokens are generated)
Participant history
Session history
Creation/update timestamps

Example Requests

JavaScript/TypeScript:

javascript

// Duplicate a board (e.g., reuse lesson template)
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/duplicate',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const newBoard = await response.json();
console.log(`Duplicated board: ${newBoard.board_uuid}`);
console.log(`New host link: ${newBoard.access_links.host}`);

cURL:

bash

curl -X POST \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/duplicate'

PHP:

php

<?php
$ch = curl_init('https://api.boardapi.io/api/v1/boards/a1b2c3d4/duplicate');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your-api-key'],
    CURLOPT_RETURNTRANSFER => true
]);

$newBoard = json_decode(curl_exec($ch), true);
echo "New board: {$newBoard['board_uuid']}\n";
echo "Host link: {$newBoard['access_links']['host']}\n";

Use Cases

Reuse lesson templates for multiple classes
Create backup copies before major changes
Fork boards for different student groups
Create variations of successful board layouts

Possible Errors

Status Code	Error	Description
`404`	`Not Found`	Source board does not exist
`401`	`Unauthorized`	Invalid API key
`410`	`Gone`	Source board has expired

Archive Board

Archives or restores a board. Archived boards are hidden from the default board list but can still be accessed and unarchived later.

Request

http

PATCH /boards/:uuid/archive
X-API-Key: your-api-key

URL Parameters

Parameter	Type	Description
`uuid`	string	Board UUID

Response

Status Code: 200 OK

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "English Lesson",
  "status": "archived",
  "archived_at": "2025-11-14T17:00:00Z",
  "message": "Board archived successfully"
}

Or when unarchiving:

json

{
  "board_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "English Lesson",
  "status": "active",
  "restored_at": "2025-11-14T17:30:00Z",
  "message": "Board restored successfully"
}

Response Fields

Field	Type	Description
`board_uuid`	string	Board identifier
`title`	string	Board title
`status`	string	New status (`archived` or `active`)
`archived_at`	string	Timestamp when archived (if archiving)
`restored_at`	string	Timestamp when restored (if unarchiving)
`message`	string	Confirmation message

Behavior

When archiving:

Board status changes from active to archived
Board is hidden from GET /boards (unless ?status=archived)
Existing access links continue to work
Active sessions are not disconnected
Board data is preserved

When unarchiving:

Board status changes from archived to active
Board appears in GET /boards again
All data and access links remain unchanged

Example Requests

JavaScript/TypeScript:

javascript

// Archive a board
const response = await fetch(
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/archive',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const result = await response.json();
console.log(result.message); // "Board archived successfully"

// To unarchive, call the same endpoint again
const restoreResponse = await fetch(
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/archive',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const restored = await restoreResponse.json();
console.log(restored.message); // "Board restored successfully"

cURL:

bash

# Archive board
curl -X PATCH \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/archive'

# Unarchive board (call same endpoint again)
curl -X PATCH \
  -H "X-API-Key: your-api-key" \
  'https://api.boardapi.io/api/v1/boards/a1b2c3d4/archive'

PHP:

php

<?php
// Archive board
$ch = curl_init('https://api.boardapi.io/api/v1/boards/a1b2c3d4/archive');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => ['X-API-Key: your-api-key'],
    CURLOPT_RETURNTRANSFER => true
]);

$result = json_decode(curl_exec($ch), true);
echo $result['message'];

// The endpoint toggles status, so calling it again will restore

Use Cases

Archive completed lessons/sessions
Clean up board list without deleting
Preserve historical boards for review
Temporarily hide inactive boards

Archive vs Delete

Operation	Status	Data	Access Links	Reversible
Archive	`archived`	Preserved	Work	Yes (toggle)
Delete	N/A	Deleted	Broken	No

Possible Errors

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

Response Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Request succeeded with no response body
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Resource not found
`410`	Gone	Resource has expired
`413`	Payload Too Large	Request body too large
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred

Rate Limiting

All API endpoints are rate-limited based on your plan:

Standard: 1,000 requests/hour
Premium: 10,000 requests/hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642512000

Common Use Cases

Create a Board for a Lesson

javascript

const lesson = {
  title: 'English Lesson: Animals',
  lesson_id: 12345,
  vocabulary: [
    { word: 'cat', translation: 'кот' },
    { word: 'dog', translation: 'собака' }
  ]
};

const board = await createBoard({
  title: lesson.title,
  external_id: `lesson_${lesson.lesson_id}`,
  expires_in_hours: 24,
  initial_objects: lesson.vocabulary.map((word, i) => ({
    type: 'vocabulary-card',
    data: word,
    position: { x: 100 + (i * 220), y: 100 }
  })),
  webhook_url: 'https://api.myschool.com/webhooks'
});

// Share URLs with teacher and students
teacher.board_url = board.access_links.host;
students.board_url = board.access_links.guest;

Monitor Board Activity

javascript

// Periodically check board state
setInterval(async () => {
  const board = await fetch(`/api/v1/boards/${boardId}`, {
    headers: { 'X-API-Key': apiKey }
  }).then(r => r.json());

  console.log(`Active participants: ${board.participants_count}`);
  console.log(`Objects on board: ${board.objects_count}`);
}, 30000); // Every 30 seconds

Clean Up Expired Boards

javascript

// Delete boards when they're no longer needed
async function cleanup() {
  const boards = await listBoards();

  for (const board of boards) {
    if (new Date(board.expires_at) < new Date()) {
      await fetch(`/api/v1/boards/${board.board_uuid}`, {
        method: 'DELETE',
        headers: { 'X-API-Key': apiKey }
      });
    }
  }
}

Next Steps

WebSocket Events - Real-time board updates
Object Types - Custom object registration
Webhooks - Event notifications
Integration Guide - Complete integration examples

Boards API Reference ​

Authentication ​

Base URL ​

Endpoints Overview ​

Create Board ​

Request ​

Request Body Parameters ​

Initial Objects Structure ​

Response ​

Response Fields ​

Example Requests ​

Possible Errors ​

Get Board ​

Request ​

URL Parameters ​

Query Parameters ​

Response ​

Response Fields ​

Example Requests ​

Possible Errors ​

Update Board ​

Request ​

URL Parameters ​

Request Body Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Delete Board ​

Request ​

URL Parameters ​

Response ​

Example Requests ​

Possible Errors ​

List All Boards ​

Request ​

Query Parameters ​

Response ​

Example Requests ​

Possible Errors ​

Get Boards by Owner ​

Request ​

Query Parameters ​

Response ​

Example Requests ​

Use Cases ​

Possible Errors ​

Get Board Access Links ​

Request ​

URL Parameters ​

Response ​

Response Fields ​

Example Requests ​

Use Cases ​

Possible Errors ​

End Board Session ​

Request ​

URL Parameters ​

Response ​

Response Fields ​

Example Requests ​

Use Cases ​

Behavior ​

Possible Errors ​

Duplicate Board ​

Request ​

URL Parameters ​

Response ​

Response Fields ​

What Gets Duplicated ​

Example Requests ​

Use Cases ​

Possible Errors ​

Archive Board ​

Request ​

URL Parameters ​

Response ​

Response Fields ​

Behavior ​

Example Requests ​

Use Cases ​

Boards API Reference

Authentication

Base URL

Endpoints Overview

Create Board

Request

Request Body Parameters

Initial Objects Structure

Response

Response Fields

Example Requests

Possible Errors

Get Board

Request

URL Parameters

Query Parameters

Response

Response Fields

Example Requests

Possible Errors

Update Board

Request

URL Parameters

Request Body Parameters

Response

Example Requests

Possible Errors

Delete Board

Request

URL Parameters

Response

Example Requests

Possible Errors

List All Boards

Request

Query Parameters

Response

Example Requests

Possible Errors

Get Boards by Owner

Request

Query Parameters

Response

Example Requests

Use Cases

Possible Errors

Get Board Access Links

Request

URL Parameters

Response

Response Fields

Example Requests

Use Cases

Possible Errors

End Board Session

Request

URL Parameters

Response

Response Fields

Example Requests

Use Cases

Behavior

Possible Errors

Duplicate Board

Request

URL Parameters

Response

Response Fields

What Gets Duplicated

Example Requests

Use Cases

Possible Errors

Archive Board

Request

URL Parameters

Response

Response Fields

Behavior

Example Requests

Use Cases