Documentation | Codiris

REST API endpoint reference with request/response formats, authentication, and rate limits.

Base URL

All API requests should be made to:

https://app.codiris.ai/api

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer brb_live_xxxxxxxxxxxxxxxxxxxx

Get your API key from Settings & Members → API Keys in your Codiris dashboard. SDK keys have the format brb_live_ or brb_test_.

User Isolation (Multi-tenancy)

For multi-tenant applications, you can isolate boards per user using the X-External-User-Id header. Boards created with this header will be tagged with your user's ID and only visible when querying with the same external user ID.

X-External-User-Id: your-user-123

Alternatively, you can use the externalUserId query parameter:

GET /brainboard/boards?externalUserId=your-user-123

How It Works

Include the X-External-User-Id header in your requests
When creating boards, they are automatically tagged with this external user ID
When listing boards, only boards belonging to that user are returned
Other users cannot see or access boards with different external user IDs

Example Request

curl -X GET "https://app.codiris.ai/api/brainboard/boards" \
  -H "Authorization: Bearer brb_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-External-User-Id: user_alice_123"

Boards

GET/brainboard/boards

List all boards with optional filtering and pagination.

Parameter	Type	Description
page	integer	Page number (default: 1)
pageSize	integer	Items per page (default: 20, max: 100)
status	string	Filter: 'active' or 'archived'
search	string	Search by name
workspaceId	string	Filter by workspace
externalUserId	string	Filter by external user ID (multi-tenancy)

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "board_xxxxx",
        "name": "My Board",
        "description": "Board description",
        "isPublic": false,
        "status": "active",
        "thumbnail": "https://...",
        "externalUserId": "your-user-123",
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

GET/brainboard/boards/{boardId}

Get a specific board by ID with full details.

{
  "success": true,
  "data": {
    "id": "board_xxxxx",
    "name": "My Board",
    "description": "Board description",
    "workspaceId": "ws_xxxxx",
    "isPublic": false,
    "status": "active",
    "externalUserId": "your-user-123",
    "settings": {
      "allowComments": true,
      "gridEnabled": true,
      "snapToGrid": true,
      "gridSize": 20,
      "backgroundColor": "#ffffff"
    },
    "cameraX": 0,
    "cameraY": 0,
    "cameraZoom": 1,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

POST/brainboard/boards

Create a new board.

Request body:

{
  "name": "New Board",
  "description": "Optional description",
  "workspaceId": "ws_xxxxx",
  "templateId": "template_xxxxx",
  "isPublic": false,
  "settings": {
    "gridEnabled": true,
    "snapToGrid": true,
    "allowComments": true
  }
}

PUT/brainboard/boards/{boardId}

Update an existing board.

{
  "name": "Updated Name",
  "description": "Updated description",
  "isPublic": true,
  "status": "active",
  "settings": {
    "backgroundColor": "#f5f5f5"
  }
}

DELETE/brainboard/boards/{boardId}

Delete a board permanently.

POST/brainboard/boards/{boardId}/duplicate

Create a copy of an existing board.

{ "name": "Copy of Board" }

Objects

GET/brainboard/boards/{boardId}/objects

Get all objects on a board.

{
  "success": true,
  "data": [
    {
      "id": "obj_xxxxx",
      "boardId": "board_xxxxx",
      "type": "sticky",
      "x": 100,
      "y": 100,
      "width": 200,
      "height": 200,
      "rotation": 0,
      "zIndex": 1,
      "text": "Hello World",
      "fill": "#ffeb3b",
      "fontSize": 16,
      "isLocked": false,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

POST/brainboard/boards/{boardId}/objects

Create a new object on a board.

{
  "type": "sticky",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 200,
  "text": "New note",
  "fill": "#ffeb3b"
}

POST/brainboard/boards/{boardId}/objects/batch

Create multiple objects at once.

{
  "objects": [
    { "type": "sticky", "x": 100, "y": 100, "text": "Note 1" },
    { "type": "sticky", "x": 320, "y": 100, "text": "Note 2" }
  ]
}

PUT/brainboard/boards/{boardId}/objects/{objectId}

Update an existing object.

{
  "x": 200,
  "y": 200,
  "text": "Updated text",
  "fill": "#90caf9"
}

PUT/brainboard/boards/{boardId}/objects/batch

Update multiple objects at once.

{
  "objects": [
    { "id": "obj_1", "x": 100, "fill": "#ff0000" },
    { "id": "obj_2", "x": 200, "fill": "#00ff00" }
  ]
}

DELETE/brainboard/boards/{boardId}/objects/{objectId}

Delete an object from a board.

DELETE/brainboard/boards/{boardId}/objects/batch

Delete multiple objects at once.

{ "objectIds": ["obj_1", "obj_2", "obj_3"] }

Members

GET/brainboard/boards/{boardId}/members

Get all members of a board.

{
  "success": true,
  "data": [
    {
      "id": "member_xxxxx",
      "boardId": "board_xxxxx",
      "userId": "user_xxxxx",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "editor",
      "joinedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

POST/brainboard/boards/{boardId}/members

Invite a member to a board.

{ "email": "newuser@example.com", "role": "editor" }

Roles: owner, admin, editor, commenter, viewer

PUT/brainboard/boards/{boardId}/members/{memberId}

Update a member's role.

{ "role": "admin" }

DELETE/brainboard/boards/{boardId}/members/{memberId}

Remove a member from a board.

Comments

GET/brainboard/boards/{boardId}/comments

Get all comments on a board. Optionally filter by objectId.

Parameter	Type	Description
objectId	string	Filter comments by object

POST/brainboard/boards/{boardId}/comments

Add a comment to a board or object.

{
  "content": "This is a comment",
  "objectId": "obj_xxxxx",
  "parentId": "comment_xxxxx"
}

PUT/brainboard/boards/{boardId}/comments/{commentId}

Update a comment.

{ "content": "Updated comment text" }

DELETE/brainboard/boards/{boardId}/comments/{commentId}

Delete a comment.

POST/brainboard/boards/{boardId}/comments/{commentId}/resolve

Mark a comment as resolved.

Templates

GET/brainboard/templates

List available templates.

Parameter	Type	Description
category	string	Filter by category

Categories: brainstorming, planning, mapping, retrospective, design, research

GET/brainboard/templates/{templateId}

Get a specific template.

POST/brainboard/templates

Save a board as a template.

{
  "boardId": "board_xxxxx",
  "name": "My Template",
  "description": "Reusable template",
  "isPublic": false
}

AI Features

POST/brainboard/generate

Generate content using AI.

{
  "prompt": "Create a user journey map for e-commerce checkout",
  "boardId": "board_xxxxx",
  "context": "Additional context",
  "type": "diagram"
}

Types: content, diagram, brainstorm, summary

Response:

{
  "success": true,
  "data": {
    "content": "Generated text content...",
    "objects": [
      { "type": "sticky", "x": 100, "y": 100, "text": "Step 1" }
    ],
    "suggestions": [
      "Add more detail to step 3",
      "Consider edge cases"
    ]
  }
}

POST/brainboard/source-chat

Chat with AI about board content with source citations.

{
  "boardId": "board_xxxxx",
  "messages": [
    { "role": "user", "content": "What are the main themes?" }
  ]
}

Response:

{
  "success": true,
  "data": {
    "role": "assistant",
    "content": "Based on the board content...",
    "sources": [
      {
        "objectId": "obj_xxxxx",
        "text": "User onboarding improvements",
        "type": "sticky"
      }
    ]
  }
}

POST/brainboard/chat

Simple chat without source citations.

POST/brainboard/command

Execute natural language commands on the board.

{
  "boardId": "board_xxxxx",
  "command": "make all sticky notes blue",
  "selectedObjectIds": ["obj_1", "obj_2"]
}

Response:

{
  "success": true,
  "data": {
    "operations": [
      { "type": "update", "objectId": "obj_1", "data": { "fill": "#3b82f6" } },
      { "type": "update", "objectId": "obj_2", "data": { "fill": "#3b82f6" } }
    ]
  }
}

POST/brainboard/audio-overview

Generate an audio overview of a board.

{
  "boardId": "board_xxxxx",
  "style": "podcast"
}

Styles: summary (2-3 min), podcast (5-7 min), deep-dive (8-10 min)

Response:

{
  "success": true,
  "data": {
    "id": "audio_xxxxx",
    "audioUrl": "https://...",
    "script": "Welcome to this overview...",
    "duration": 320
  }
}

Import/Export

POST/brainboard/import-url

Import content from a URL onto a board.

{
  "boardId": "board_xxxxx",
  "url": "https://example.com/article",
  "position": { "x": 100, "y": 100 }
}

POST/brainboard/extract-pdf

Extract content from a PDF onto a board.

{
  "boardId": "board_xxxxx",
  "pdfUrl": "https://example.com/document.pdf",
  "position": { "x": 100, "y": 100 }
}

POST/brainboard/create-from-interview

Create a board from an interview summary.

{
  "interviewId": "interview_xxxxx",
  "name": "Interview Summary Board"
}

GET/brainboard/boards/{boardId}/export?format=json

Export board as JSON.

{
  "success": true,
  "data": {
    "board": { ... },
    "objects": [ ... ],
    "frames": [ ... ]
  }
}

POST/brainboard/boards/{boardId}/export

Export board as image or PDF.

Export as PNG:

{
  "format": "png",
  "scale": 2,
  "backgroundColor": "#ffffff",
  "frameId": "frame_xxxxx"
}

Export as PDF:

{
  "format": "pdf",
  "includeFrames": true,
  "pageSize": "a4",
  "orientation": "landscape"
}

POST/brainboard/boards/{boardId}/share

Generate a share link for a board.

{
  "canEdit": false,
  "expiresAt": "2024-12-31T23:59:59Z",
  "password": "optional-password"
}

Response:

{
  "success": true,
  "data": {
    "shareUrl": "https://app.codiris.ai/brainboard/board_xxxxx?token=abc123",
    "shareToken": "abc123"
  }
}

DELETE/brainboard/boards/{boardId}/share

Revoke a share link.

POST/brainboard/shared/{shareToken}

Access a shared board as a guest.

{
  "name": "Guest User",
  "email": "guest@example.com"
}

Error Handling

All endpoints return errors in this format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

Tier	Requests/min	Requests/day
Free	60	1,000
Pro	300	10,000
Enterprise	1,000	Unlimited

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312200

Validate API Key

GET/brainboard/validate

Validate your API key and check permissions.

{
  "success": true,
  "data": {
    "valid": true,
    "userId": "user_xxxxx",
    "workspaceId": "ws_xxxxx",
    "permissions": ["read", "write", "admin"]
  }
}

Next Steps

Getting Started

Quick start guide with SDK setup

API Reference

SDK method documentation

Examples

Code examples and recipes

Object Types

All 14 canvas element types

API Endpoints

Base URL

Authentication

User Isolation (Multi-tenancy)

How It Works

Example Request

Boards

Objects

Members

Comments

Templates

AI Features

Import/Export

Sharing

Error Handling

HTTP Status Codes

Rate Limits

Validate API Key

Next Steps

Getting Started

API Reference

Examples

Object Types