Templates API

The Templates API allows you to create, manage, and apply board templates.

Create Template

Creates a new template based on an existing board. The template will contain all the content and configuration of the original board.

• URL: /templates
• Method: POST
• Headers:
  • X-API-Key: Organization API key (Required)
• Body:

{
  "board_id": "board-uuid-string",
  "name": "Vocabulary Practice Template",
  "description": "Template for vocabulary practice", // Optional
  "thumbnail_url": "https://example.com/thumb.jpg", // Optional
  "config": { // Optional
    "permissions": {
      "allow_guest_access": true
    }
  }
}

Response (201 Created)

{
  "id": "template-uuid",
  "name": "Vocabulary Practice Template",
  "description": "Template for vocabulary practice",
  "is_public": false,
  "organization_id": "org-uuid",
  "created_at": "2025-11-17T10:00:00.000Z"
}

List Templates

Retrieves all templates for the organization as well as public templates from other organizations.

• URL: /templates
• Method: GET
• Headers:
  • X-API-Key: Organization API key (Required)
• Query Parameters:
  • is_public: Filter by public status (true/false)

Response

[
  {
    "id": "template-uuid",
    "name": "Vocabulary Practice Template",
    "is_public": false,
    "organization_id": "org-uuid",
    "created_at": "2025-11-17T10:00:00.000Z"
  }
]

Get Template

Retrieves a specific template by its ID.

• URL: /templates/:id
• Method: GET
• Headers:
  • X-API-Key: Organization API key (Required)

Response

{
  "id": "template-uuid",
  "name": "Vocabulary Practice Template",
  "state": { ... }, // Full board state
  "organization_id": "org-uuid",
  "created_at": "2025-11-17T10:00:00.000Z"
}

Apply Template

Creates a new board based on the specified template.

• URL: /templates/:id/apply
• Method: POST
• Headers:
  • X-API-Key: Organization API key (Required)
• Body:

{
  "title": "New Board from Template", // Optional
  "external_id": "lesson_12345", // Optional
  "webhook_url": "https://your-app.com/webhooks", // Optional
  "config": { ... } // Optional overrides
}

Response (201 Created)

{
  "id": "board-uuid",
  "title": "New Board from Template",
  "board_uuid": "board-uuid",
  "access_links": {
    "host": "http://localhost:4000/board/board-uuid?token=...",
    "guest": "http://localhost:4000/board/board-uuid?token=..."
  },
  "created_at": "2025-11-17T10:00:00.000Z"
}

Manage Visibility

Make Public

Makes a template public so it can be used by other organizations.

• URL: /templates/:id/public
• Method: PATCH
• Headers:
  • X-API-Key: Organization API key (Required)

Make Private

Makes a template private so it can only be used by the owning organization.

• URL: /templates/:id/private
• Method: PATCH
• Headers:
  • X-API-Key: Organization API key (Required)

Delete Template

Deletes a template by its ID.

• URL: /templates/:id
• Method: DELETE
• Headers:
  • X-API-Key: Organization API key (Required)