Skip to Content
Pindown.ai is in early alpha - features may change
Client SDKPinboards API

Pinboards API

The Pinboards API provides methods to create and manage pinboards for organizing your pins.

Getting Started

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Access pinboards API
const pinboards = client.pinboards

Create Pinboard

Create a new pinboard to organize your pins:

const pinboard = await client.pinboards.create({
  title: 'Sales Dashboard',
  tags: ['sales', 'metrics', 'dashboard']
})
 
console.log(`Pinboard created: ${pinboard.id}`)
console.log(`Share URL: ${pinboard.shareable_url}`)

Get Pinboard

Retrieve a pinboard with all its pins:

const pinboard = await client.pinboards.get('pb-abc123')
 
console.log(`Title: ${pinboard.title}`)
console.log(`Pins: ${pinboard.pins.length}`)
console.log(`Layout:`, pinboard.layout)

List Pinboards

Get all your pinboards:

const pinboards = await client.pinboards.list()
 
pinboards.forEach(pb => {
  console.log(`- ${pb.title} (${pb.pin_count} pins)`)
})

Update Pinboard

Update pinboard title, tags, or settings:

await client.pinboards.update('pb-abc123', {
  title: 'Updated Sales Dashboard',
  tags: ['sales', 'q4', '2024'],
  is_public: true
})
 
console.log('Pinboard updated')

Delete Pinboard

Delete a pinboard (pins are not deleted, only removed from board):

try {
  await client.pinboards.delete('pb-abc123')
  console.log('Pinboard deleted')
} catch (error) {
  console.error('Failed to delete:', error.message)
}

Add Pin to Pinboard

Add an existing pin to a pinboard with layout position:

await client.pinboards.addPin('pb-abc123', {
  pin_id: 'p-xyz789',
  position: {
    x: 0,  // Grid position X
    y: 0,  // Grid position Y
    w: 2,  // Width (grid units)
    h: 1   // Height (grid units)
  }
})
 
console.log('Pin added to pinboard')

Remove Pin from Pinboard

Remove a pin from a pinboard:

await client.pinboards.removePin('pb-abc123', 'p-xyz789')
 
console.log('Pin removed from pinboard')

Update Layout

Update the layout/positioning of pins:

await client.pinboards.updateLayout('pb-abc123', {
  layout: {
    'p-pin1': { x: 0, y: 0, w: 2, h: 1 },
    'p-pin2': { x: 2, y: 0, w: 2, h: 2 },
    'p-pin3': { x: 0, y: 1, w: 2, h: 1 }
  }
})
 
console.log('Layout updated')

Complete Example

Create a pinboard and add multiple pins:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY!
})
 
async function createDashboard() {
  // 1. Create pinboard
  const pinboard = await client.pinboards.create({
    title: 'Sales Dashboard Q4 2024',
    tags: ['sales', 'dashboard']
  })
 
  // 2. Create pins
  const revenuePin = await client.pins.create({
    pin_type: 'stat-cards',
    pin_config: {
      cards: [{ title: 'Revenue', value: '$125k', change: '+18%', trend: 'up' }]
    },
    pin_layout: '1x1',
    metadata: {
      title: 'Revenue'
    }
  })
 
  const usersPin = await client.pins.create({
    pin_type: 'stat-cards',
    pin_config: {
      cards: [{ title: 'Users', value: '1,234', change: '+5%', trend: 'up' }]
    },
    pin_layout: '1x1',
    metadata: {
      title: 'Users'
    }
  })
 
  // 3. Add pins to pinboard
  await client.pinboards.addPin(pinboard.id, {
    pin_id: revenuePin.id,
    position: { x: 0, y: 0, w: 2, h: 1 }
  })
 
  await client.pinboards.addPin(pinboard.id, {
    pin_id: usersPin.id,
    position: { x: 2, y: 0, w: 2, h: 1 }
  })
 
  console.log(`✅ Dashboard created: ${pinboard.shareable_url}`)
}
 
createDashboard()

Custom Roles (Advanced RBAC)

Control which users can see specific pins using custom roles. This is an advanced feature for role-based access control.

Creating and Managing Roles

Custom roles require direct API calls (not yet in Client-JS SDK):

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({ apiKey: 'YOUR_API_KEY' })
 
// Create pinboard
const board = await client.pinboards.create({
  metadata: { title: 'VIP Dashboard' }
})
 
// Create custom role
const roleRes = await fetch(`https://api.pindown.ai/api/pinboards/${board.pinboard_id}/roles`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${client.config.apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'VIP Members',
    color: '#FFD700'
  })
})
const { roleId } = await roleRes.json()
 
// Create VIP-only pin
const vipPin = await client.pins.create({
  metadata: { title: 'Exclusive Content' }
})
 
await client.pinboards.addPin(board.pinboard_id, vipPin.pin_id)
 
// Make pin visible only to VIP role
await fetch(`https://api.pindown.ai/api/pinboards/${board.pinboard_id}/pins/${vipPin.pin_id}/required-roles`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${client.config.apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    roleIds: [roleId]
  })
})
 
// Invite VIP user
await client.pinboards.share(board.pinboard_id, {
  email: 'vip@example.com',
  role: 'viewer'
})
 
// Assign VIP role to user (after they accept)
const vipUserId = 'user-123'
await fetch(`https://api.pindown.ai/api/pinboards/${board.pinboard_id}/users/${vipUserId}/custom-roles`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${client.config.apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    roleIds: [roleId]
  })
})
 
console.log('✅ VIP user can now see VIP-only pins!')

Key Features

  • Up to 5 custom roles per pinboard
  • Role-based pin visibility - Only users with assigned roles see protected pins
  • Multiple roles per user - Assign multiple roles to each collaborator
  • Owner sees all - Board owner always sees all pins regardless of requirements
  • AND logic - Pins requiring multiple roles need ALL roles to be visible

See Also

Next Steps

Pages APICreate a Pin